AI 写代码太快，文档怎么才能跟上？

AI 写代码快，这事现在已经不新鲜了。

真正让人头疼的是另一件事：代码冲出去的速度，和文档更新的速度，根本不是一个量级。你一句“给列表加个筛选条件”，Agent 可能已经改完 Controller、Service、Mapper 了。看起来很爽。过几周你再回来，spec 是旧的，接口说明对不上，数据库字段也没人提，自己读自己的项目像在考古。

所以这篇文章想聊的重点，不是某个 skill 怎么装、某个命令怎么敲，而是一个更实际的问题：AI Coding 时代，文档流程到底该怎么改，才不至于写着写着把自己绕晕。

问题到底出在哪

很多人以为，AI Coding 的问题是“代码会写错”。

其实更常见的麻烦是：代码写得没那么错，但项目的上下文越来越乱。

比如这些场景：

• spec 里还写着“支持按状态筛选”，代码里其实已经支持了 8 个筛选条件。
• 数据库多了字段，接口文档一点没提。
• 当时明明讨论过两个方案，过一个月谁也想不起来为什么选了现在这个。
• Agent 理解错需求，已经改完一堆文件，你才发现“我根本不是这个意思”。

说白了，AI 最大的副作用不是“不会写”，而是太愿意立刻开干。

这件事放在小 demo 里问题不大，反正写完就扔。可一旦项目要持续迭代，文档掉队、需求跑偏、验收模糊，这些账迟早都得补，而且通常是你自己半夜来补。

更稳的思路，其实不复杂

如果把“文档生成”理解成“AI 帮我顺手写一份说明”，那大概率还是会失真。

更稳的做法，是把文档放回流程里，而不是放到流程后面。我的理解可以概括成四句话：

• 先整理现状，再改代码。
• 文档记录“现在是什么样”。
• 决策单独记录“为什么这样做”。
• 验收必须能执行，别只写“功能正常”。

这四句听起来很朴素，但其实已经够用了。

1. 先整理现状，再动代码

很多返工，不是因为 AI 能力不够，而是因为方向一开始就偏了。

所以在改代码之前，最好先让 AI 做一件没那么刺激、但很值钱的事：把这次改动会影响到什么先整理出来。

比如：

• 这次改的是哪个模块
• 接口现在长什么样
• 数据库字段有哪些
• 哪些方法会受影响
• 哪些地方改完之后必须重新验证

也是当前大多数模型支持的 Plan 模式，先做计划，再进入开发，心里会踏实很多。

2. 文档只写“现在是什么”

很多文档越写越难读，是因为它把现状、历史、争论、废案全塞进去了。

更好的做法是分成两块：

• spec 只写当前状态
• 决策日志单独写为什么这么设计

这样以后你打开 spec，不用先看半天历史剧情，直接就能知道现在该信什么。

3. 验收项别写成空气

“功能正常”“接口没问题”“导出成功”这种话，安慰作用大于实际作用。

验收项最好写成可以执行的东西。比如：

• 传什么参数
• 调哪个接口
• 预期返回什么字段
• 数据库里应该出现什么结果

这样改完之后，AI 也好，人也好，至少知道怎么证明“这次真改对了”，而不是靠感觉。

4. 跨服务需求，先画路线图

单模块需求还好说。最容易乱的是跨服务改动。

比如前端发起导出，后端创建任务，数据服务生成文件，最后前端展示进度。这个时候如果直接让 AI 同时改几边，很容易出现一种熟悉的灾难：大家都改了，链路还是不通。

更稳的做法是先把调用链画出来：

frontend → backend → data-service

先确认入口在哪，谁依赖谁，哪个服务应该先改。路线图有了，后面改代码才不会像边开车边画地图。

一个够用的文档流程，可以长这样

如果你不想把事情搞得太复杂，一个最小可用流程其实就够了：

1. 输入需求：先把这次要改什么说清楚。
2. 定位模块或服务：确认这次影响的是哪个模块，还是哪条跨服务链路。
3. 生成或更新当前 spec：把接口、字段、代码位置、受影响范围整理出来。
4. 人工确认：先确认方向，再让 AI 开始改代码。
5. AI 按任务执行：把改动拆成明确任务，不要一股脑“帮我全改了”。
6. 跑验收：至少有几条可以执行的断言，别靠“应该没问题”。
7. 记录决策：这次为什么这么改，顺手记下来。

听上去像多了一步，其实是在少走弯路。

你可以把它理解成给 AI 加一个“出发前检查”。麻烦一点，但能少掉很多“已经改完了才发现不是这个意思”的时刻。

举个最典型的小例子

假设你要给文章列表加一个作者筛选。

最省事的说法当然是：

给文章列表接口加一个 author 参数，支持模糊搜索

但更稳的说法应该是：

1. 先确认这是哪个模块的需求。
2. 看现在接口到底收哪些参数。
3. 看数据库和查询逻辑怎么对应。
4. 更新当前 spec。
5. 写好验收，比如“传 author=张三 时，返回结果都应该包含张三”。
6. 再让 AI 改代码。

这一步的核心不是“多写一份文档”，而是先把上下文对齐。

因为 AI 最怕的不是复杂，最怕的是你以为自己说清楚了，其实没有。

什么场景值得这么做

这套思路特别适合下面几种情况：

• 项目会持续迭代，不是写完就扔。
• 不止一个人维护，后面还有人要接手。
• 需求经常改，接口和字段经常变。
• 项目跨多个模块，甚至多个服务。
• 你已经开始感觉“代码跑得比文档快太多了”。

如果你正好处在这个阶段，那优化文档流程的收益通常很明显。

什么场景不用太认真

也别把它当成万能流程。

如果你只是：

• 写个一次性脚本
• 做个快速原型
• 周末试个小想法
• 这个项目过两天就不要了

那就别给自己上全套装备。

这就像你只是下楼买瓶水，没必要背登山包。流程是为复杂项目服务的，不是为了给简单事情增加仪式感。

文末放一个可参考实现

如果你懒得自己从零搭流程，可以看看 doc-first-dev 这个仓库。

我觉得它有参考价值，不是因为它是什么“终极方案”，而是因为它把上面这套思路拆成了几个更具体的动作：

• /spec-first：先更新 spec，再开发和验收
• /spec-multi：跨服务需求先追调用链，再安排改动顺序
• /whylog-record：把“为什么这么改”单独记下来

如果你想自己做一套内部规则、skills 或工作流，也完全可以参考它的拆法，而不是照着它原封不动搬过去。

最后补一句更实际的

doc-first-dev 目前本质上还是个人维护的 skills。它的完整性、稳定性、通用性，还有文档规范到底能不能长期扛住真实项目，坦白说，都还有待考验。

所以这篇文章的重点，不是推荐你立刻去用这个仓库本身。

我更想强调的是：它背后的思想值得借鉴。

也就是：

• 先把需求和现状写清楚
• 再让 AI 动代码
• 改完之后做可追踪的验收
• 最后把“为什么这么做”单独记下来

你可以先看看这个项目，再决定要不要用；也可以干脆自己写一套更适合自己团队的规则。

仓库能不能直接拿来用，因人而异；但这套思路，我觉得很难说没用。