最近我注意到一个反常现象：PR 提交量越来越多，代码行数飞涨，但我真正花得最多时间的，其实不是写代码——而是写文档。
更具体地说，是和 AI 一起写文档，并以文档驱动代码执行。
这不是“文档驱动开发”的复古回潮，而是一种全新的工作范式：文档是上下文，是计划，是 Agent 之间的共识契约。你要想让多个 AI Agent 长期、稳定、低成本地产出高质量代码，文档不是附属品，而是主心骨。
文档，是 AI 协作的基础设施
AI Agent 没有长期记忆，没有自我意识。每次调用，它都是从 0 开始。如果你不给它上下文、不给它计划，它就像一个醒来就忘了昨天干了啥的程序员。
我们常说“上下文很重要”，而文档，就是上下文最好的载体。你写清楚了当前目标、任务拆解、模块说明、依赖关系、下一步计划，AI 才能知道该怎么配合你干活。
我现在的习惯是这样的：
文档 checkin，任务才开始。
我不再先写代码、事后补文档，而是先写文档、和 AI 对齐意图，然后才开始执行。甚至我会显式地告诉 AI：“你先读一遍文档，再干活”。
哪怕是 Claude 4 Sonnet 这种性价比高但容易走神的模型，读完结构化文档之后再执行，也比直接上手靠谱得多。
为什么要在代码库里写文档？
现在我越来越多地把文档写进代码仓库里，以 Markdown 格式 commit 到项目中。文档不再是项目之外的附件，而是和代码一样被版本控制、review、演进的第一等公民。
更重要的是，这样写文档可以直接利用 AI Agent 的代码理解能力。比如在 Cloud Code 里，我用 CLI Agent 帮我写文档，它可以无缝读取当前分支的代码变更、函数定义、依赖模块，并基于这些生成结构化的说明和计划。
这样带来的好处有三点：
- 上下文充足：AI 能直接从代码中提取语义，不需要我复述；
- 过程无损：省去 prompt 冗余，避免语义遗失；
- 同步演进：每次代码更新，文档也一并更新，保持计划与现实一致。
更重要的是，写文档阶段就让 AI 研究透彻代码，预先生成“搜索策略”，比如：
- 说明这个问题的解决方向应该去搜索什么关键字；
- 如果某个模块调用不明，AI 可以主动列出“建议查询哪些路径或接口说明”；
- 哪些 StackOverflow 问题值得一查、哪些官方文档段落可能含答案。
这一步可以极大节省后续执行阶段的 token 消耗，因为弱模型只需要按图索骥，不再反复试探和试错。
分工协作：用强 AI 控制弱 AI
AI 是可以组队干活的，关键是分清谁擅长什么。
我的实际策略是：
- 用强模型写文档、拆任务、制定策略：
- Gemini 2.5 Pro、Claude 4 Opus、GPT-4o在结构、组织、规划能力上更胜一筹，适合用来制定长期计划、生成可读性强的项目文档；
- 用弱模型执行具体任务：
- Claude 4 Sonnet、DeepSeek、SWE等价格便宜、速度快，用来根据计划批量生成代码、处理重复性修改、跑测试、写 UT 非常高效。
这就像一个经验丰富的架构师 + 项目经理，写好任务说明，分发给熟练工去执行。中间如果出现偏差，再用强模型回头 review 和调整。
文档不是交差，而是不断演化的“意图体”
AI 写代码的速度可以非常快，但如果没有文档支撑，那就是快着快着就撞墙。更大的问题是：你根本没法复盘，不知道它为啥这么写，下次也很难继续。
所以我现在要求自己做到三件事：
- 每一个任务都有文档起点（哪怕只有几行，也是意图的表达）；
- 任务执行过程中，文档不断被更新（补充进展、遇到的问题、下一步）；
- 所有文档都 checkin 到代码库里（作为语义的一部分，与代码一起演化）。
这不只是好习惯，而是面向 AI 协作时代的生存法则。
结语：文档是新的主函数
你可以不写文档，也能用 AI 生成很多代码。但你会发现，做着做着就失控了。哪段代码干嘛的、改了谁、影响了啥，全都混成一团。
真正能长期跑下去的 AI Coding 流水线，都有一个共同点：文档清晰、上下文稳定、计划持续演进。
我现在越来越觉得：在 AI 协作里，文档才是真正的“主函数”。
它不直接执行，但决定执行的方向；
它不产生代码，但决定代码的结构；
它不炫技，但撑起了一整个工程系统的灵魂。
把写文档当成工作本身，不是退回旧时代的繁琐，而是进入 AI 协作时代的唯一入口。