From f041139ca8ced2be3e516f120754dcd5c7e9d0bc Mon Sep 17 00:00:00 2001 From: tupingr Date: Tue, 26 May 2026 15:40:36 +0800 Subject: [PATCH] =?UTF-8?q?refactor(principles):=20=E4=B8=8A=E4=B8=8B?= =?UTF-8?q?=E6=96=87=E8=B5=84=E6=BA=90=E7=AE=A1=E7=90=86=E8=A7=84=E5=88=99?= =?UTF-8?q?=E6=89=A9=E5=B1=95=E8=87=B3=E6=89=80=E6=9C=89=20AI=20=E8=A7=92?= =?UTF-8?q?=E8=89=B2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 从「Arch AI 专用」升级为「所有角色通用硬约束」 - 新增角色特定约束：Arch/Coder/Tester 各自的上下文风险+应对 - 更新过时引用：Token预算表、信息分层、阶段切换清单 - 补充信号识别：Coder AI 需同时改3个文件时触发收尾 Co-Authored-By: Claude Opus 4.7 --- .ai/principles.md | 68 ++++++++++++++++++++++++++++++++--------------- 1 file changed, 46 insertions(+), 22 deletions(-) diff --git a/.ai/principles.md b/.ai/principles.md index 243c973..eaa102f 100644 --- a/.ai/principles.md +++ b/.ai/principles.md @@ -2,24 +2,23 @@ ## 为什么这样设计 -AI 的上下文窗口有限（~200K tokens）。当前架构按人类认知模式设计——详尽文档、全局视角——但 AI 每个读入上下文的字都是成本。这套分层架构的核心思想：**每个角色只加载必要信息，按需展开细节。** +AI 的上下文窗口有限。每个读入上下文的字都是成本。这套分层架构的核心思想：**每个角色只加载必要信息，按需展开细节。** ## Token 预算 | 层级 | 预算 | 内容 | 加载时机 | |------|------|------|----------| -| 角色工作台 (card + today) | < 2K | 身份+今日任务 | 每次会话必读 | +| 入口（dashboard/card） | < 2K | 身份+全貌+任务 | 每次会话必读 | +| Task 文件 | < 1K | 单任务全部信息 | Coder/Tester 开工时 | +| 知识沉淀 (knowledge) | < 3K | 决策/模式/教训 | 按需加载 | | 阶段上下文 (phase) | < 5K | 目标+范围+架构 | 按需加载 | -| 专题文档 (knowledge) | < 3K | 决策/模式/教训 | 按需加载 | -| 路线图 (ROADMAP) | < 2K | 全局进度 | 需要全局视野时 | -## 信息分层 +## 信息分层（三层架构） ``` -Layer 0: 角色工作台 → AI 每天进来只读这个 -Layer 1: 路线图看板 → 人类 + AI 共享进度 -Layer 2: 阶段上下文 → 按当前阶段按需加载 -Layer 3: 知识沉淀 → 自动积累，永久沉淀 +指挥层: dashboard.md → 人类 + Arch AI 唯一入口 +决策层: DECISIONS.md → 待人类决策事项 +执行层: .ai/tasks/active/ → Coder/Tester 各自 task 文件 ``` ## 维护规则 @@ -30,38 +29,63 @@ Layer 3: 知识沉淀 → 自动积累，永久沉淀 4. **一文一答**：每个文件独立回答一个问题，不需要串联阅读 5. **角色无关设计**：任何 AI 模型都能通过读 card.md 快速接管角色 -## Arch AI 上下文资源管理（硬约束） +--- -**问题**：Arch AI 每次会话有上下文窗口限制。如果盲目冲刺大任务，到一半触发自动压缩，前面的讨论、决策细节、已排除的选项全部丢失——代价不是「重来」，是「用不完整的记忆做决策」。 +## AI 上下文资源管理（硬约束，适用于所有 AI 角色） -**规则**： +**问题**：每个 AI 每次会话有上下文窗口限制。如果盲目冲刺大任务，到一半触发自动压缩，前面的讨论、决策细节、已排除的选项全部丢失——代价不是「重来」，是「用不完整的记忆做决策」。 -1. **任务前评估**：开始一个复杂任务前，先判断能否在自己的有效上下文内完成。如果不能，拆分到多个独立会话 -2. **做完一件再开始下一件**：不积累未完成的工作。一个阶段收尾了（commit + push），再启动下一个 -3. **决策即记录**：每个重要判断产生后，立即写入对应的 knowledge/ 文件，不要留在对话里。对话是易失的，knowledge 是持久的 -4. **接近窗口上限时主动收尾**：感觉上下文开始吃力时，主动做 checkpoint——把已完成的写入文件、commit、告知人类当前进展和下一步。**宁可多开一个会话，不要带着残缺记忆继续** -5. **拆分策略**：大任务（如「重构整个架构」）拆成独立可提交的子任务。每个子任务结束后 git commit，确保即使后续会话压缩，已完成的部分不会丢失 +### 通用规则（所有角色遵守） + +1. **任务前评估**：开始一个复杂任务前，先判断能否在自己的有效上下文内完成。不能 → 拆分到多个独立会话 +2. **做完一件再开始下一件**：不积累未完成的工作。阶段收尾了（commit + push），再启动下一个 +3. **决策即记录**：每个重要判断产生后，立即写入对应文件，不要留在对话里。对话是易失的，文件是持久的 +4. **接近窗口上限时主动收尾**：感觉上下文开始吃力时，主动 checkpoint——已完成写入文件、commit、告知人类当前进展和下一步。**宁可多开一个会话，不要带着残缺记忆继续** +5. **拆分到可提交粒度**：大任务拆成独立子任务。每个子任务结束后 git commit，确保即使后续会话压缩，已完成的部分不会丢失 + +### 角色特定约束 + +| 角色 | 主要风险 | 应对策略 | +|------|---------|---------| +| Arch AI (Claude Code) | 长对话积累上下文，架构讨论容易收不住 | 每个 ADR 产出后立即写入 decisions.md；感知吃力时主动收尾 | +| Coder AI (Trae + GLM-4.6) | 上下文窗口更小，多文件任务容易超出 | 每个 session 只做 1 个 task 文件；不读其他 task，不读架构文档 | +| Tester AI (Coze CN) | 沙盒执行时间有限 | 1 个 session 只测 1 个 T01-XXX task；报告立即写回 repo | + +### 信号识别（何时应立即执行规则 4） -**信号识别**：当出现以下情况时，说明接近上下文上限，应立即执行规则 4： - 需要反复回看前面的讨论才能做判断 - 开始忘记用户几分钟前说过的话 -- Token 用量接近已知窗口限制 - 回复质量出现可感知的下降 +- 同一个问题被重复提出 +- （Coder AI）需要同时修改 3 个以上文件才能完成 task -**反模式**：「一口气做完再 commit」——做一半触发压缩，前面做的全丢。 +### 反模式 + +- 「一口气做完再 commit」——做一半触发压缩，前面做的全丢 +- 「这个 task 简单，我顺便把下一个也做了」——超边界 = 超上下文 +- 「先放着，等会儿一起处理」——对话不等人，放着 = 丢了 + +--- ## 文件约定 -- 角色工作台: `.ai/roles/{role}/` +- 控制面板: `dashboard.md` +- 决策入口: `DECISIONS.md` +- 角色工作台: `.ai/roles/{role}/card.md` +- 执行任务: `.ai/tasks/active/` - 阶段上下文: `.ai/phases/phase-NN-name/` - 知识沉淀: `.ai/knowledge/` - 提示词模板: `.ai/prompts/{domain}/` +- Skill 工具: `.trae/skills/` +- 框架边界: `SYNC.md` +- 模板变量: `TEMPLATE.yaml` ## 阶段切换检查清单 切换阶段时 Arch AI 必须： - [ ] 更新所有角色的 card.md（当前阶段字段） -- [ ] 更新 ROADMAP.md（阶段进度条） +- [ ] 更新 dashboard.md（进度条 + task 状态面板 + 最近事件） +- [ ] 更新 phases/INDEX.md - [ ] 生成上一阶段的 completion.md - [ ] 产出阶段复盘（docs/share/phase-NN/） - [ ] 审计 token 预算