三个月前我开始用 AI 写项目，以为能解放双手。结果前两周爽完，后面每天都在擦屁股。
先说说我是怎么翻车的
我接了一个电商后台项目，用 Claude Code 撸代码。开始挺顺，让它写个订单模块，唰唰唰就出了。
第一次翻车：我让 AI "加个取消订单功能"。它顺手给订单表加了个 cancel_reason 字段，还给用户表加了个 cancel_count——我根本没要这个。问它为啥加，它说"考虑到用户频繁取消可能需要风控"。我谢谢你啊，我自己都不知道我要做风控。
第二次翻车：过了两天我发现订单状态流转不对，去改 PRD。改完让 AI 按新逻辑重写代码，它确实改了。但交互文档里的状态图还是旧的，测试用例也没更新。三份文档三个版本，我根本不知道哪个是对的。
第三次翻车：项目做到一半换了个需求，加了个"部分退款"。AI 很积极地改了代码，但忘了改接口文档里的返回字段。前端调接口一脸懵，我这头排查半天发现 AI 偷偷改了数据结构但没吭声。
我就发现一个问题：AI 就像一个记性不好的外包程序员。你这次跟它说清楚了，下次再聊它就忘了。更坑的是，它还会"善意地帮你补全"——加一些你根本没要的功能、字段、校验规则。
核心问题：AI 没有"上下文记忆"
我们跟 AI 聊天，感觉它好像记得之前说了啥。但真相是——
每次对话对 AI 来说都是一次全新的开始。
它靠的是你塞给它的那几页上下文。上下文一多，它就开始丢三落四。你让它看 PRD、看交互稿、看技术方案、看代码，它看着看着就晕了，最后凭"感觉"写。
就像你同时扔给一个人十份文档说"按这个写"，他大概率会漏掉其中三份里的约束条件。
那怎么办？
我试过各种 prompt 技巧："请严格按文档执行"、"不要添加未定义的功能"、"修改前先列出影响范围"……效果都有，但不稳定。AI 心情好的时候很乖，心情不好照样瞎改。
后来我换了个思路：不跟 AI 扯皮，直接给它画个跑道。
文档链：给 AI 画跑道
传统的开发流程是：人写文档 → 人写代码 → 人写测试。
AI 时代的开发流程变成了：人跟 AI 聊天 → AI 写代码 → 人修 bug。
doc-chain 的做法是：人定规则，AI 按规则跑。
具体来说，就是把开发拆成 6 个步骤，每一步产出一篇带编号的文档：
PRD（需求文档）→ 交互设计 → UI 设计 → 技术方案 → 测试用例 → 代码审计
每一篇文档的开头都要写清楚：我这篇东西是基于哪些上游文档写的，引用了里面的哪些内容。
比如技术方案开头长这样：
| 上游文档 | 路径 | 引用范围 |
|---------|------|---------|
| 订单模块 PRD | ../prd/order-prd.md | F001-F005 |
| 交互设计 | ../interaction/order-flow.md | P001-P003 |
| 全局错误码规范 | ../global/error-code.md | E01-E20 |
这个表格就是锁。
AI 写技术方案之前，必须先读 PRD 里的 F001-F005。它想加一个 F006 的功能？不行，PRD 里没定义。它想改错误码格式？不行，全局规范定死了必须用 E01 这种格式。
文档成了唯一的事实来源。AI 不再是"自由创作"，而是"按图施工"。
编号系统：防丢三落四的保险
文档链里每个功能点、每个页面、每个接口都有固定编号。
PRD 里：
- F001 = 创建订单
- F002 = 取消订单
- F003 = 支付订单
交互设计里：
- P001 = 订单列表页
- P002 = 订单详情页
技术方案里：
- API001 = POST /api/orders（对应 F001）
测试用例里：
- TC-F001 = 创建订单的正向流程
- TC-F001-001 = 创建订单的参数缺失场景
编号就是 DNA。
你改 PRD 里的 F002（取消订单），所有下游文档里引用 F002 的地方都必须同步改。不改？审计工具会报红。
审计工具：不用人眼逐行对
人工对文档一致性太痛苦了。doc-chain 配了一个 doc-audit.py，纯标准库写的，零依赖。
它能干这些事：
1. 查编号连续性
PRD 里有 F001、F002、F004，缺了 F003？报错。
2. 查上下游引用是否有效
技术方案引用了 PRD 的 F007，但 PRD 里根本没有 F007？报错。
3. 查接口一致性
技术方案 §6（接口定义）列了 5 个接口，§10（接口清单）只列了 4 个？报错。
4. 增量审计
我只改了 F003，没必要全量跑。doc-audit.py --delta F003 只检查 F003 相关的上下游。
5. 扫描下游影响
改 PRD 之前，先跑 doc-audit.py --scan-downstream 看看哪些文档引用了我要改的内容，一次性列出影响范围。
以前我对文档是靠人眼，现在交给脚本。它比我细心多了。
上下文预算：别让 AI 看太多
还有一个坑：你给 AI 的上下文太多，它会"看懵"。
我试过把整个项目的文档全塞给 AI，让它做一次全量审计。结果它开始 hallucinate——凭空发明一些不存在的编号，或者把 A 文档的内容张冠李戴到 B 文档上。
所以 doc-chain 定了条规矩：单次给 AI 的上下文不超过 12k token，超出就分段加载。
就像你不能让一个人一次性读完十本书然后马上写报告。分章节看，看完一章写一章的笔记，最后汇总。
改了需求怎么办？
这是我最关心的问题。业务方改需求是常态，怎么保证文档链不崩？
doc-chain 规定了两种改法：
改上游（比如改 PRD）
- 先扫描下游：哪些文档引用了我要改的功能点？
- 列出影响范围，问业务方：这些全都要改吗？
- 改的话，级联修改所有下游文档
- 不改的话，在下游文档里标注
[待同步]，写明哪里和上游不一致
改下游（比如改技术方案）
- 先读上游文档
- 逐条比对：我的修改在上游定义范围内吗？
- 超出了？立刻停手，先去改上游 PRD
- 没超出？直接改
红线就一条：不能出现"上游说 A，下游说 B，两边都假装没发现问题"。
这玩意儿适合谁？
说实话，不是所有人都需要文档链。
适合用的场景：
- 项目周期超过两周，文档会不断迭代
- 多人协作，AI 生成的内容需要给人 review
- 需求复杂，涉及多个模块的状态流转和数据一致性
- 你受够了 AI 每次都"顺手帮你优化"一些东西
不适合的场景：
- 一次性脚本、临时工具，写完就跑
- 个人 side project，怎么快怎么来
- 探索性项目，需求每天都在变，连你自己都不知道要什么
文档链是有成本的。写编号、维护上下游引用、跑审计脚本，这些都需要时间。它的价值在长周期、多人协作、需要可维护性的项目里才能体现出来。
怎么开始用
如果你用的是 Kimi Code CLI / Claude Code / Codex，把 doc-chain 装到 skills 目录就行：
git clone https://github.com/HKweiguang/doc-chain.git ~/.config/agents/skills/doc-chain
然后在对话里输入：
/skill:doc-chain 帮我写订单模块的 PRD
AI 就会按文档链的流程，先检查有没有已有文档，再按模板生成，自动维护编号和上下游引用。
当然你也可以不用 AI，自己手动写文档链。核心不是工具，是把约束写进文档，让变更可追溯这个思路。
最后说一句
AI 写代码最大的风险不是它写得慢，而是它太有想法了。
你不给它画跑道，它就自己跑出地球。doc-chain 不是什么高深的技术，就是一套"给 AI 定规矩"的土办法。规矩定清楚了，AI 才能从"创意发散型选手"变成"靠谱执行型选手"。
你平时用 AI 写代码遇到过啥离谱的翻车现场？评论区聊聊。
