这份文档记录我当前的 AI coding 心得。它不是项目规范的替代品，而是帮助我在使用 Codex、DeepSeek、Claude Code 时保持稳定产出的个人操作手册。
核心目标：
- 用强模型做判断，而不是堆代码。
- 用便宜模型做实现，但必须框在小合同里。
- 用文档约束 AI，而不是依赖聊天记忆。
- 用测试、diff 和 review 做最终裁判。
你的 AI coding 流程应该围绕一句话展开：
Codex 把需求变成边界清晰的小合同，DeepSeek 负责挑刺和减复杂度，Claude Code 在合同内实现，Codex 最后只按 code review 查风险。
关键不是多找几个模型，而是让每个模型有固定职责：
- Codex / 强模型：理解系统、拆需求、做方案、框定范围、最终审查。
- DeepSeek：交叉评审，主要找阻塞问题、漏测、范围膨胀。
- Claude Code：在明确合同内改代码、补测试、跑验证。
- 测试和 diff：最终裁判。
项目里长期维护三份核心文档：CLAUDE.md、DESIGN.md、TODO.md。三者各管一层，不互相替代。
定位：给 AI 协作者看的入口文件。
它应该回答：
- 这个项目是什么，不是什么。
- 开始任务前应该读哪些文档。
- 哪些规则永远不能绕过。
- Codex、DeepSeek、Claude Code 如何分工。
- 什么时候必须停止并报告。
适合放：
- AI 协作流程。
- 多模型分工。
- 强规则。
- 项目边界。
- 文档读取入口。
不适合放：
- 详细接口设计。
- 长篇技术方案。
- 大量任务列表。
- 某个 PR 的临时决策。
判断标准：如果这条规则是所有 AI 协作者进入项目时必须先知道的，就放 CLAUDE.md。
定位：项目的工程设计规范。
它应该回答：
- 模块边界是什么。
- 接口应该怎么设计。
- 权限、审计、测试、Provider、工具系统有什么稳定原则。
- code review 先看什么。
- 重构应该怎么做才不破坏行为。
适合放：
- 模块职责。
- 依赖方向。
- 命名和接口原则。
- 工具与权限规范。
- 测试规范。
- 代码审查标准。
- 重构流程。
不适合放：
- 某个需求的长方案。
- 临时 TODO。
- 一次性调研结论。
- 当前进度状态。
判断标准：如果它是未来多个任务都要遵守的稳定工程约束，就放 DESIGN.md。
定位：项目当前要做什么、按什么顺序做、做到什么程度算完成。
它应该回答：
- 当前优先级是什么。
- 每个任务的边界是什么。
- 前置条件是什么。
- 验收标准是什么。
- 评审发现的问题是否已经变成可跟踪任务。
适合放：
[ ]/[x]任务。- 阶段顺序。
- 前置条件。
- 验收标准。
- 评审遗留项。
- 暂不优先事项。
不适合放：
- 长篇方案论证。
- 详细接口草图。
- 个人心得。
- 与路线无关的想法。
判断标准：如果它需要被执行、跟踪或验收，就放 TODO.md。
docs/ 用来承接三份核心文档不该承载的长内容。
适合放：
- 技术调研。
- 完整实施方案。
- 方案评审记录。
- PR 实施合同。
- AI coding 心得。
- 模板和复盘。
不适合放：
- 必须被所有 AI 进入项目时立即读取的硬规则。
- 需要每日更新的任务状态。
判断标准：如果内容太长，但又值得沉淀，就放 docs/，再由 TODO.md 或 CLAUDE.md 引用。
| 内容 | 写入位置 |
|---|---|
| AI 协作流程、多模型分工、强约束 | CLAUDE.md |
| 项目定位、做什么、不做什么 | CLAUDE.md |
| 模块边界、依赖方向 | DESIGN.md |
| 工具契约、权限、审计、Provider 原则 | DESIGN.md |
| 测试规范、代码审查规范 | DESIGN.md |
| 当前路线、优先级、任务状态 | TODO.md |
| 评审发现的待办 | TODO.md |
| 长篇技术调研 | docs/*-technical-research.md |
| 完整实现方案和评审 | docs/*-implementation-plan-review.md |
| 单 PR 实施合同 | docs/*-pr-contract.md 或任务消息中 |
| 个人方法论和复盘 | docs/ai-coding-self-improvement.md |
必须更新 CLAUDE.md：
- AI 协作流程变化。
- Codex / DeepSeek / Claude Code 分工变化。
- 项目边界变化。
- 新增所有 AI 都必须遵守的强规则。
必须更新 DESIGN.md：
- 模块依赖变化。
- 公共接口或工具契约变化。
- 权限、审计、测试、Provider 原则变化。
- code review 标准变化。
必须更新 TODO.md：
- 新增任务。
- 完成任务。
- 调整优先级。
- 方案评审发现新风险。
- 某个验收标准变化。
应该写到 docs/：
- 技术调研超过几段。
- 方案需要代码锚点和 PR 切分。
- 评审内容太长。
- 模板或心得需要复用。
不要把自然语言需求直接交给实现模型。先把需求压成合同：
- 目标：这次到底要完成什么。
- 非目标：这次明确不做什么。
- 修改范围：允许改哪些模块、哪些文件。
- 禁止事项：不能顺手重构、不能改公共接口、不能碰无关文件。
- 验收标准：什么叫完成。
- 验证命令：必须跑哪些测试。
- 停止条件：发现方案不成立时先报告，不自行扩大范围。
你写得越像合同，AI 越不容易飘。
方案必须从代码出发，不从想象出发。
每个关键设计决策都要带：
- 文件路径
- 行号或方法名
- 当前行为
- 为什么这里需要改
- 改完如何验证
这对应 CLAUDE.md 里的规则：方案评审必须做代码对照，评审发现要回写 TODO.md。
多模型评审最大的风险是越审越复杂。你要强制 DeepSeek 只输出四类内容：
Blocking:
- 会导致编译失败、行为回归、模块边界破坏、安全/权限问题的点。
Missing Tests:
- 哪些关键路径没有测试兜住。
Scope Cuts:
- 哪些设计可以砍掉、延后、改成更小实现。
Conclusion:
- 可实现 / 修正后可实现 / 不建议实现。禁止 DeepSeek 重设架构、扩展需求、提出非必要抽象。
Codex 的方案要详细，但详细的是边界，不是抽象。
好的详细：
- 修改范围详细。
- 验收标准详细。
- 测试矩阵详细。
- 风险和回滚详细。
坏的详细：
- 提前设计一堆未来接口。
- 为了“优雅”拆过多类。
- 给每个小变化都加框架。
- 一个 PR 同时改契约、行为、展示、测试、格式化。
你的目标是：方案严密，代码朴素。
适用：小 bug、文案、单文件工具修复、测试补充。
流程：
- Claude Code 直接实现。
- 跑目标测试。
- Codex 做 code review。
- 修复 review findings。
不需要完整技术调研，不需要 DeepSeek 方案评审。
适用：跨 2-3 个文件、小功能、局部重构。
流程：
- Codex 读
CLAUDE.md、DESIGN.md、相关代码，写单 PR 合同。 - DeepSeek 按
Blocking / Missing Tests / Scope Cuts / Conclusion挑刺。 - Codex 根据评审收敛合同。
- Claude Code 在合同内实现。
- Codex 做实现后 code review。
适用：AgentEngine、工具契约、Provider、CLI、MCP、安全权限、观测链路。
流程：
- Codex 做技术调研，写
docs/*-technical-research.md。 - Codex 写完整可实现方案和方案评审，关键设计决策带代码锚点。
- 评审发现回写
TODO.md。 - Codex 拆成多个单 PR 合同。
- DeepSeek 每次只评一个 PR 合同。
- Claude Code 每次只实现一个 PR。
- Codex 对每个 PR 做 code review。
- 所有阶段测试通过后再进入下一阶段。
大重构的顺序必须先护栏测试，再移动代码。
# PR-X 实施合同：<任务名>
## 背景
- 需求来源：
- 对应 TODO：
- 对应方案文档：
- 相关代码锚点：
## 目标
- 本 PR 完成什么：
## 非目标
- 本 PR 不做什么：
## 允许修改范围
- path/to/module/...
- path/to/test/...
## 禁止事项
- 不改公共接口，除非本合同明确要求。
- 不修改无关文件。
- 不做格式化 churn。
- 不新增抽象，除非本合同明确列出。
- 发现方案问题先停止报告，不自行扩大范围。
## 必须实现
- [ ] ...
- [ ] ...
## 必须测试
- [ ] 成功路径
- [ ] 失败路径
- [ ] 权限/安全边界
- [ ] 回归路径
## 验证命令
```bash
mvn -pl <module> -am test
mvn -q -DskipTests compile
git diff --check
```
## 完成定义
- 代码在允许范围内。
- 测试通过或说明无法运行原因。
- diff 无无关改动。
- TODO / DESIGN / CLAUDE.md 需要同步时已同步。你是方案评审者，不是重新设计者。
请只基于以下材料评审：
- CLAUDE.md
- DESIGN.md
- TODO.md
- 方案文档
- 相关代码
只输出四类内容：
## Blocking
会导致编译失败、行为回归、模块边界破坏、安全/权限问题的点。
## Missing Tests
哪些关键路径没有测试兜住。
## Scope Cuts
哪些设计可以砍掉、延后，或改成更小实现。
## Conclusion
可实现 / 修正后可实现 / 不建议实现。
禁止：
- 重设架构。
- 扩展需求。
- 提出非必要抽象。
- 建议无关重构。你是实现者，只能在本 PR 合同范围内工作。
要求：
- 先读 CLAUDE.md、DESIGN.md、TODO.md 和本 PR 合同。
- 只修改允许范围内的文件。
- 不顺手重构。
- 不扩大需求。
- 不删除旧入口，除非合同明确要求。
- 发现方案无法实现、测试无法通过或需要扩大范围时，停止并报告。
交付时必须说明：
- 修改了什么。
- 新增/修改了哪些测试。
- 跑了哪些命令。
- 哪些验证没跑，原因是什么。
- 是否存在剩余风险。请用 code review 视角审查本次实现。
只找：
- bug
- 行为回归
- 漏测
- 安全/权限绕过
- 模块边界破坏
- 无关改动
不要提出：
- 非必要重构
- 架构美化
- 未来扩展建议
- 风格偏好
输出顺序：
1. Blocking / High / Medium findings
2. Missing tests
3. Scope issues
4. Conclusion每次看到 AI 提出新抽象，先问 5 个问题：
- 这个抽象是不是当前验收必须？
- 不加这个抽象，代码是否真的难以测试？
- 是否已有本地模式可以复用？
- 这个抽象是否会扩大修改范围？
- 这个抽象是否让回滚更难？
只要有 2 个答案偏否，就先不要加。
来自 CLAUDE.md：
- 方案从代码出发。
- 方案评审必须做代码对照。
- 评审发现必须回写
TODO.md。 - Codex 方案详细的是边界，不是堆抽象。
- DeepSeek 只负责挑刺和减复杂度。
- Claude Code 只在单 PR 合同内实现。
- Codex review 只查 bug、回归、漏测、边界破坏。
来自 TODO.md：
- 每个任务必须有边界、前置条件和验收标准。
- 大重构先做护栏测试。
- 没有 metrics 和 benchmark，就很难证明重构变好了。
- P0-R 的推荐顺序是：护栏测试 ->
ToolCallExecutor->ContextPipeline-> MCP 风险和审计 -> BashTool -> CLI -> Provider 协议。
来自 DESIGN.md：
tools不能依赖engine、cli或im。engine只依赖抽象 provider/tool，不绑定具体 Provider JSON。cli和im只做入口适配，不拥有核心状态机。- 权限先于能力。
- 审计日志必须是合法 JSONL，不手拼 JSON。
- 测试覆盖真实风险，不追求数量。
- 代码审查先看风险，再看风格。
健康的 CLAUDE.md：
- 短而硬。
- 入口清晰。
- AI 读完知道先读什么、不能做什么。
- 不塞长方案。
健康的 DESIGN.md：
- 稳定。
- 原则清晰。
- 能指导不同任务的一致设计。
- 不记录临时进度。
健康的 TODO.md：
- 可执行。
- 每个任务有验收。
- 评审发现能落成
[ ]。 - 不展开长篇论证。
不健康信号：
- 同一条规则在三份文档里重复出现，但说法不一致。
TODO.md里出现长篇设计方案。DESIGN.md里出现一次性任务状态。CLAUDE.md变成所有细节的大杂烩。- AI 需要翻很多文档才能知道当前任务到底要做什么。
开始前问自己：
- 这是小、中、大哪类需求？
- 是否真的需要完整方案？
- 是否已经读了该读的文档？
- 是否知道当前代码入口？
- 是否知道哪些文件不能改？
- 是否有明确验收标准？
- 是否有测试可以证明没回归？
- 是否需要先补护栏测试？
如果这些问题答不上来，不要进入实现。
结束后记录：
- 原计划是否过大？
- 实现是否超范围？
- DeepSeek 是否提出了有价值的 Scope Cuts？
- Claude Code 是否顺手改了无关文件？
- Codex review 是否只查风险，还是又开始加设计？
- 测试是否真的覆盖失败路径？
- 哪个环节最浪费时间？
- 下次合同应该怎么写得更窄？
目标：每个中等需求都先写单 PR 合同。
重点训练：
- 写清楚非目标。
- 写清楚禁止事项。
- 写清楚验收标准。
- 控制修改范围。
目标：让 DeepSeek 的评审输出必须包含 Scope Cuts。
重点训练：
- 识别不必要抽象。
- 识别可延后的设计。
- 把大 PR 切小。
目标：重构前先补行为测试。
重点训练：
- 成功路径测试。
- 失败路径测试。
- 权限边界测试。
- 回归测试。
目标：Codex review 只报工程风险，不做架构美化。
重点训练：
- bug 优先。
- 漏测优先。
- 模块边界优先。
- 安全和审计优先。
每周看这些指标：
- 需求从开始到可验证完成的时间是否缩短。
- AI 实现超范围次数是否减少。
- review 后返工次数是否减少。
- 无关 diff 是否减少。
- 测试失败是否更早暴露。
- TODO 遗留项是否更具体。
- 你是否能更快判断“这不该现在做”。
最终目标不是让 AI 写更多代码，而是让你更稳定地交付：
范围更小，验证更硬，设计更少，质量更稳。