CodeBook 开发工作流

铁律

没有走完流程，不准声称"完成"。
跳过任何一步 = 违规，不是效率。

违反规则的字面意思，就是违反规则的精神。

全流程概览

构思 → 计划 → TDD 实现 → 验证 → 多维度子代理审查 → 交付

每个阶段都有硬门禁，不可跳过。

Phase 1: 构思（Brainstorm）

何时用： 任何新功能、行为变更、非 trivial 重构。

1. 先了解上下文（读代码、git log、已有文档）
2. 提出 2-3 种方案，附带权衡分析和推荐
3. 与用户确认方案后，再进入 Phase 2

门禁： 未经确认的方案不得进入计划阶段。

Phase 2: 计划（Plan）

何时用： Phase 1 确认后，动手前。

1. 列出要创建/修改的文件精确路径
2. 每个 Task 拆到 2-5 分钟粒度
3. 每个 Task 必须包含：失败测试 → 实现 → 通过测试 → commit
4. 计划写入 docs/plans/YYYY-MM-DD-<topic>.md

门禁： 计划未写完、未确认，不得动生产代码。

Phase 3: TDD 实现

何时用： 计划确认后。

详见： codebook-tdd skill

核心循环：

RED   — 写一个最小失败测试，运行确认它以正确的原因失败
GREEN — 写最小代码让测试通过
REFACTOR — 清理，保持全绿

门禁：

• 没有失败测试，不写生产代码
• 先写了代码再补测试？删掉代码，从测试重来
• 一次只测一个行为

Phase 4: 验证（Verify）

何时用： 声称"完成"之前。

详见： 下方验证检查清单

门禁：

• 没有跑验证命令的输出，不准说"通过"
• 没有全量回归的结果，不准提交

Phase 5: 多维度子代理审查（Multi-Agent Review）

何时用： Phase 4 验证通过后、提交前。

设计原理：

• 审计师不做账（Greptile 原则）— 实现者和审查者共享上下文 = 自己检查自己的作业
• 多维度并行（Anthropic Code Review 架构）— 一个通才审查员容易漏审，多个专家各看一个维度互相补盲
• 行为验证（Qodo 思路）— 不只看"代码对不对"，还要问"有没有该测但没测的场景"

执行方式： 并行派出多个子代理（Agent tool），每个有独立角色和审查清单，最后由主代理汇总裁决。

#### 审查角色定义

角色 A：正确性审查员（Correctness Reviewer）

聚焦：逻辑 bug、边界情况、作用域/资源管理

你是 CodeBook 项目的正确性审查员。只关注逻辑正确性。

项目根目录：{mcp-server 的绝对路径}
第一步：读 CLAUDE.md 了解架构，特别是"关键设计决策"和"常见陷阱"。

## 变更信息
- 变更目标：{一句话}
- 涉及文件：{路径列表}

## 你的操作步骤
1. 读 CLAUDE.md
2. 读涉及文件完整代码
3. 用 Grep 搜索变更函数的所有调用方，确认上下游没有被破坏
4. 对照清单逐项检查

## 审查清单
- [ ] class_stack 等作用域管理：有 push 必有 pop？有 enter 必有 leave？
- [ ] 循环/递归的终止条件：能否无限循环？空输入怎么办？
- [ ] 资源对称性：打开的文件/连接是否关闭？
- [ ] 节点类型匹配：tree-sitter 节点字符串与 LANG_CONFIG 一致？
- [ ] 类型边界：None 返回值是否被调用方正确处理？
- [ ] 并发安全：共享可变状态是否在单次调用作用域内？

输出格式：Critical / Important / Minor 分级。
不要猜测实现意图——只从代码判断。读不懂的地方就是问题。

角色 B：工程规范审查员（Engineering Standards Reviewer）

聚焦：测试覆盖、错误处理、代码风格、配置兼容

你是 CodeBook 项目的工程规范审查员。只关注工程质量。

项目根目录：{mcp-server 的绝对路径}
第一步：读 CLAUDE.md 了解测试铁律和验证清单。

## 变更信息
- 变更目标：{一句话}
- 涉及文件：{路径列表}

## 你的操作步骤
1. 读 CLAUDE.md
2. 读涉及文件和对应的测试文件
3. 运行 `python -m pytest tests/ -v` 确认测试状态
4. 对照清单逐项检查

## 审查清单
- [ ] 每个新函数/方法都有测试？
- [ ] 测试覆盖了正常路径 + 至少一个异常路径？
- [ ] CLI round-trip：新配置格式有写入→读回→验证一致的测试？
- [ ] 错误处理完整：文件不存在、解析失败、网络超时、编码错误？
- [ ] 无硬编码路径或 magic number？
- [ ] 日志/错误消息对排查有帮助？

## 行为验证（Qodo 思路）
在审查完已有测试后，回答：
- 有没有该测但没测的边界场景？列出 1-3 个缺失的测试用例建议。

输出格式：Critical / Important / Minor / 缺失测试建议。

角色 C：架构一致性审查员（Architecture Consistency Reviewer）

聚焦：设计决策一致性、模块边界、API 契约

你是 CodeBook 项目的架构一致性审查员。只关注架构层面。

项目根目录：{mcp-server 的绝对路径}
第一步：读 CLAUDE.md 了解所有"关键设计决策"。

## 变更信息
- 变更目标：{一句话}
- 涉及文件：{路径列表}
- 原始需求：{需求来源或计划文档路径}

## 你的操作步骤
1. 读 CLAUDE.md 的"关键设计决策"和"新增语言支持清单"
2. 读涉及文件，重点看公共接口（函数签名、返回类型）
3. 用 Grep 检查是否有新增的跨模块依赖
4. 对照清单逐项检查

## 审查清单
- [ ] 新代码与 CLAUDE.md 记录的设计决策一致？如果不一致，是有意的变更还是无意的偏离？
- [ ] 模块边界清晰？有没有本该在 A 模块的逻辑写到了 B 模块？
- [ ] 公共 API 向后兼容？已有调用方是否需要修改？
- [ ] 新增依赖是否必要？能否用已有工具实现？
- [ ] 命名与项目现有惯例一致？

输出格式：Critical / Important / Minor 分级。
如果发现设计决策需要更新，明确指出 CLAUDE.md 的哪一条需要修改。

#### 执行与汇总流程

Step 1 — 并行派出

# 伪代码示意，实际用 Agent tool 并行调用
Agent(description="Correctness review", prompt=角色A_prompt)
Agent(description="Engineering review", prompt=角色B_prompt)
Agent(description="Architecture review", prompt=角色C_prompt)
# 三个 Agent 同时启动，互不可见

Step 2 — 主代理汇总裁决

三个审查员返回后，主代理（即当前会话的我）负责：

1. 去重：多个审查员报同一个问题 → 合并，取最高严重级别
2. 交叉验证：只有一个审查员报的 Critical → 主代理亲自验证后定级
3. 生成终审报告：按 Critical → Important → Minor → 缺失测试建议 排序
4. 展示给用户：用户确认后执行修复

Step 3 — 修复与重审

• Critical：必须修复，修完重新走 Phase 4 + 重新派出报告该问题的审查角色
• Important：必须修复才能提交
• Minor：记录为 TODO，可后续处理
• 缺失测试建议：评估后补充测试
• 审查员说错了？ 用技术理由反驳，记录到终审报告中

#### 轻量模式（Small Change Fast Track）

当变更满足以下全部条件时，可以用单代理审查替代三代理并行：

• 涉及文件 ≤ 2 个
• 变更行数 ≤ 30 行
• 不涉及公共 API 签名变更
• 不涉及 tree-sitter 节点类型或 LANG_CONFIG

轻量模式使用角色 A（正确性审查员）的 prompt，追加角色 B 的"行为验证"段落。

门禁： 终审报告中有 Critical/Important 未修复，不得进入交付阶段。

Phase 6: 交付

1. git add 具体文件（不用 -A）
2. commit message 说 why 不说 what
3. 确认无遗留 TODO

验证检查清单

声称完成之前，逐项确认：

关键原则：证据先于断言。

✅ [跑命令] [看到 22 passed] "全部通过"
❌ "应该没问题" / "看起来对了"

红旗清单 — 看到这些立刻停下

• 没写测试就开始写代码
• 说"应该可以"但没跑验证
• 一次改了多个不相关的东西
• 测试通过了但不理解为什么
• "这次特殊，可以跳过"
• 修了 bug 但没写回归测试
• "改动太小，不需要审查"
• 自己审查自己的代码，没有派子代理
• 把会话历史传给审查子代理（= 泄露实现意图）
• 在审查 prompt 中暗示期望结果（"应该没问题，帮我确认一下"）

看到以上任何一条：停下，回到正确的阶段。

常见借口 vs 现实

关联 Skill

• TDD 实现 → codebook-tdd：Phase 3 的详细 RED-GREEN-REFACTOR 规范
• 系统化调试 → codebook-debugging：遇到 bug 或测试意外失败时，切换到调试流程而非盲目修复

CodeBook 特殊规则

1. Tree-sitter 相关改动：必须用真实源代码文件测试，不用 mock
2. 多语言支持：新增语言必须有完整的 LANG_CONFIG + 专用提取函数 + 测试用例
3. CLI 安装器：新增工具必须测试 round-trip（写入 → 读回 → 验证一致）
4. MCP Server：任何 tool/resource 变更必须验证 JSON-RPC 响应格式