我用两个高效技巧解决AI开发文档记录难题

我用 AI 写了三个月代码，结果连自己写的东西都看不懂了

一个开发者的普遍困境

从去年开始，大量开发者涌入 Claude Code 进行 AI 辅助开发。效率提升令人振奋——过去需要两天的功能，现在一个下午就能搞定。但很快，一个尴尬的问题浮出水面：三个月前自己写的代码，如今竟然看不懂了。

问题不在于代码质量——代码本身还算可以。真正的症结出在文档上：更准确地说，是文档虽然存在，却和真实代码完全脱节。

列表接口的 spec 里写着"支持按状态筛选"，可实际代码里已经加了七八个筛选条件，文档却从未更新。数据库表多了三个字段，接口规范中却只字未提。当你想添加新功能时，根本不知道该相信 spec 还是相信代码。

这其实就是 AI 时代催生的新型技术债。AI 写代码的速度太快，文档的更新根本追不上。

两个核心症结

这种现象可以拆解为两个独立但又彼此关联的问题。

第一个问题：文档腐化。

传统项目中，文档腐化已经足够让人头疼。到了 AI 时代，这个问题被进一步放大——代码产出速度翻了几倍，但维护文档的习惯却没能同步跟上。更糟糕的是，很多人会在需求启动前写一份 spec，然后在开发中随着需求变化反复修改，最终项目里散落着三四个版本的"spec-v2-final.md"，没人知道哪一份才是最新的。

第二个问题：AI 的"即时行动"倾向。

这个问题更加隐蔽。AI 编程工具天然遵循这样的行为模式：理解需求 → 立刻写代码。它不会主动说"我先整理一下方案，等你确认再动手"，而是直接开始编码。需求明确时这当然很好，但当需求模糊或理解出现偏差时，方向错误的代码比没有代码更棘手——因为你得先清理掉错误的部分，再从头来过。

打造了一套解决方案

过去几个月，我一直在思考如何解决这两个痛点，最终开发了一套名为 doc-first-dev 的工具：一组可安装到 Claude Code 的 Agent Skills，将"文档先行"的工作流程强制固化下来。

核心是两个命令：

• /spec-first：管理从需求到交付的完整开发周期。每次有新需求或变更，先编写或更新文档，确认通过后再开发，开发完成后自动进行验收。
• /whylog-record：任务结束后，记录本次的决策背景——考虑过哪些方案、为什么选择当前方案、做过哪些取舍。

两个命令配合使用，才能回答开发中最重要的两个问题：现在的代码长什么样（spec），以及为什么长这样（决策日志）。

三个值得关注的设计思路

1. 确认门：分析与执行之间的强制停顿

/spec-first 的工作流中，有一个最关键的设计：在 AI 开始写代码之前，必须经过一次用户确认。

AI 会先分析需求、阅读代码，将受影响的接口、数据库结构、代码位置整理成文档，然后展示"改前什么样、改后什么样"的对比。只有你点击"确认通过，开始开发"，它才会真正动代码。

这个设计看似简单，背后的逻辑却很重要：确认门将"理解"和"执行"强制解耦了。

没有这个机制时，AI 经常话还没说完就开始写代码。有时候方向正确，有时候不对。方向不对时，你得花时间解释"不是这个意思"，然后等它重写。有了确认门之后，先对齐"方向"，再谈"执行"。返工率明显降低了。

如果在确认环节发现方向有偏差，可以补充说明，AI 会重新分析；如果需求本身发生变化，也可以在这里调整范围。修改文档的成本远比修改代码低得多。

2. Spec 与决策日志分开存储

另一个思考了很久的问题：文档里应该放什么，不应该放什么。

我看到很多项目的 spec 越写越臃肿，里面夹杂着"2023年10月讨论过方案A，最终选了方案B，因为……"之类的历史记录。这些内容对新人有价值，但每次随机读取 spec 时都要费力跳过它们。

doc-first-dev 的做法是将两类信息分开存储：

• docs/plans/<模块>/ 中的 spec 只回答"现在是什么样"——当前的接口规范、数据库设计、代码结构。就地更新，始终只保留一份，历史版本交给 git 管理。
• docs/decisions/log.md 只回答"为什么是现在这样"——方案选择、取舍背景、考虑过但放弃的替代方案。顺序追加，不覆盖。

这种分离的好处：spec 保持精简，可以快速读完；决策日志保留完整的上下文，需要回溯历史时再去查阅。两者的读写模式本来就不同——spec 是随机读写，决策日志是顺序追加——分开存储才能让各自保持最适合的形态。

代码中已经很自然地把变量命名（what）和注释（why）分开了。文档中做同样的分离，其实是顺理成章的事。

3. 三角一致性：接口 ↔ 数据库 ↔ 代码，三方对齐

最后一个设计是在 spec 更新完成后自动进行检查。

我发现了一类高频错误：数据库加了一个字段，接口规范里却没有更新，然后代码里用了这个字段，但调用方根本不知道可以传这个参数。或者反过来，接口文档里写了某个查询条件，但数据库里没有对应的索引，代码里也没有做相应处理。

doc-first-dev 在每次分析完成后会进行三角校验：接口规范中的字段、数据库设计中的字段、代码地图中的方法签名，三者必须严格对齐。发现不一致时会立即暴露，并提问"以代码为准还是以 spec 为准"，由你来做出决定。

这个机制解决的并不是什么高深问题，而是那种"以为全都改完了，其实漏了一处"的低级错误。但这类错误在 AI 开发中尤其容易出现，因为 AI 修改代码的范围有时会超出预期，而缺少一个系统化检查全貌的方法。

一次完整的使用流程

举个具体例子。假设要给一个列表接口增加"按作者筛选"的功能：

/spec-first 给文章列表接口加一个按作者筛选的参数，支持模糊匹配

接下来会发生这些步骤：

1. AI 读取当前 spec，定位相关接口和数据库表，分析影响范围。
2. 它将需要修改的内容整理出来：接口规范添加 author 参数、数据库查询逻辑说明、受影响的 Mapper 方法。展示改前与改后的对比。
3. 你检查一遍，确认没有问题，点击"确认通过，开始开发"。
4. AI 开始修改代码——Mapper、Service、Controller，按顺序依次进行。
5. 改完后进行构建，然后自动进入验收环节：实际调用 POST /article/list 传入 author=张三，检查返回结果中所有文章是否都包含"张三"。
6. 验收通过后，输出简报：改了哪些文件，验收结果如何。

整个过程只需要在确认门那里介入一次，其余全部由工具自动完成。

适合谁用，不适合谁用

说实话，这套工具并非适用于所有场景。

适合的场景：

• 你在维护一个需要持续迭代的项目，而非一次性脚本
• 你（或团队）用 AI 写了大量代码，但文档状态已经混乱不堪
• 你希望 AI 的每次修改都有迹可循，能够方便地回溯

不太适合的场景：

• 纯探索性的原型开发，只是想快速验证一个想法
• 完全不在意文档的快速实验
• 项目生命周期很短，文档方面的投入回报不合算

一个推荐的使用方式：新项目在早期探索阶段先不用，等方向确定、开始认真迭代时，再引入这套工作流。

安装方式

如果你感兴趣，可以尝试安装：

npx skills add zzusp/doc-first-dev

安装完成后，在你的项目中运行 /spec-first 加上一句需求描述，它会自动检测是否需要初始化，然后进入流程。

项目地址：github.com/zzusp/doc-f…

开发这个工具的初衷很简单：不想在三个月后看不懂自己写的代码。目前使用下来，文档腐化的问题确实改善了很多。如果你也有类似的困扰，不妨试试看。有任何问题或想法，欢迎在评论区交流。