说实话，这种感觉你肯定不陌生：当你满怀信心地打开三个月前自己亲手写的项目，准备加个小功Neng，结果盯着屏幕kan了半小时脑子里全是问号。这逻辑是谁写的？这字段干嘛用的？这真的是我写的吗？

这不仅仅是“健忘”的问题。自从我们开始全面拥抱AI辅助编程，这种“代码失忆症”被放大了无数倍。以前写一个功Neng要两天现在一个下午就Neng搞定。生产速度是上去了但维护文档的习惯却还在原地踏步。geng糟糕的是AI有一种天然的“立刻行动”倾向，你话还没说完，它代码Yi经写了一半。这种快节奏下文档和代码的割裂感简直让人抓狂。

Zui近我一直在琢磨怎么解决这个问题。我不想让我的代码库变成一个只有AINengkan懂的迷宫。经过几个月的摸索，我搞出了一套叫Zuo doc-first-dev 的方案。这不是什么高深莫测的黑科技，而是一组Ke以装进 Claude Code 的 Agent Skills，核心目的只有一个：把“文档先行”这个老掉牙的理念，强制固化到AI的开发流里去。

今天我想聊聊这套方案背后的逻辑，以及它是如何通过两个简单的 Skill，彻底改变我的开发体验的。

一、 AI时代的文档危机：不仅是“懒”，geng是“乱”

在深入解决方案之前，我们得先搞清楚敌人是谁。在AI辅助开发的环境下文档问题主要表现为两个维度的混乱。

1.1 典型的“版本地狱”

你肯定见过这种场景：项目根目录下躺着一堆名为 `spec-v1.md`、`spec-v2-final.md`、`spec-v3-real-final.md` 的文件。每次需求变动，大家dou在原来的文档上修修补补，或者干脆另起炉灶。

结果就是没人知道哪个版本才是当前生效的。新人入职时kan着这些文档一脸懵逼，Zui后只Neng放弃阅读，直接去啃代码。这种文档不仅没用，还是负资产，因为它在误导你。

1.2 隐蔽的“结构漂移”

这比版本问题geng隐蔽，也geng致命。我经常发现一类高频错误：数据库里加了一个字段，代码里也用上了但接口规范里压根没提这回事。调用方完全不知道Ke以传这个参数。

或者反过来接口文档里白纸黑字写着支持某个查询条件，结果数据库里没有对应的索引，代码逻辑里也没处理。这种“文档、代码、数据库”三者不一致的情况，在AI开发中尤为常见。因为AI改代码的范围往往超出你的预期，它可Neng顺手帮你改了三处地方，但文档却纹丝不动。久而久之，你根本不知道该信文档还是信代码。

这其实就是一种新型的技术债。AI写代码太快了文档永远追在后面吃灰。Ru果不加干预，这辆车迟早会散架。

二、 核心哲学：把“是什么”和“为什么”彻底切开

为了解决这些乱象，我思考了hen久，觉得必须得在文档的存储结构上下功夫。传统的文档往往把“规格说明”和“决策历史”混在一起，导致文档越来越臃肿。

想象一下你在kan一份规格书，里面夹杂着“2023年10月我们讨论过方案A，Zui终选了方案B，因为...”这种大段的历史记录。这些内容对新人了解背景有价值，但对于只想知道“现在这个接口怎么用”的人来说全是噪音。

所以doc-first-dev Zuo的第一件事就是把这两类信息分开存：

Spec： 只记录“是什么”。保持精简，随时可读。它的读写模式是随机的，你需要快速查某个字段定义。

Decision Log： 只记录“为什么”。保留完整的上下文，记录我们考虑过哪些方案，为什么选现在这个，有什么取舍。它的读写模式是顺序追加的，像写日记一样。

这其实和我们在代码里把变量命名和注释分开是一个道理。变量名告诉你“这是什么”，注释告诉你“为什么这么写”。文档里Zuo同样的分离，其实是一件非常自然的事。只有分开存，才Neng让两者各自保持Zui适合自己的形态。

三、 Skill #1：`/spec-first` —— 强制解耦“理解”与“执行”

有了理论基础，我们来kankan具体的执行。这套工具的核心在于两个命令，第一个就是 /spec-first。

这个设计kan起来简单，但背后的逻辑hen硬核：它设置了一个“确认门”，把“理解需求”和“执行代码”强制解耦了。

3.1 对抗AI的“急脾气”

以前用AI写代码，经常出现这种情况：你刚提了个模糊的需求，AI就开始噼里啪啦写代码了。有时候方向是对的，皆大欢喜；有时候理解偏了你就得花大量时间去解释“不是这个意思”，然后等它重写。改错方向的代码，比从头写还累，因为你得先把错的删掉。

有了 /spec-first 之后流程变了。当你输入类似 /spec-first 给文章列表接口加一个按作者筛选的参数，支持模糊匹配 的指令时AI不会立刻动代码。

它会先停下来分析需求，读现有的代码，然后把影响到的接口、数据库结构、代码位置整理成文档。Zui重要的是它会展示一个“改之前是什么样，改之后会是什么样”的对比。

3.2 三角校验机制

在这个过程中，/spec-first 会进行一次严格的三角校验：接口规范中的字段、数据库设计中的字段、代码地图中的方法签名，这三者必须对齐。

Ru果发现不一致，它会立刻暴露出来问你：“以代码为准还是以 spec 为准？”

比如它可Neng会发现列表接口的代码里Yi经加了七八个筛选条件，但文档里只写了“支持按状态筛选”。这时候，它不会自作主张帮你改文档，而是停下来等你确认。这个机制解决的不是什么高深算法问题，就是那种“我以为我dou改完了但其实漏了一处”的低级错误。但在AI开发中，这种错误太容易出现了因为你没有一个系统的方法去检查全貌。

3.3 确认门的价值

只有当你点击“确认通过开始开发”，它才会真正开始动代码。

Ru果在确认环节你觉得方向不对，Ke以补充说明，AI会重新分析；Ru果需求本身变了也Ke以在这里调整范围。你要知道，改文档永远比改代码便宜。在这个阶段把方向对齐，后续的返工率会直线下降。

四、 Skill #2：`/***log-record` —— 为未来留一颗“时光胶囊”

代码写完了功Neng上线了是不是就结束了？不这时候才是第二个 Skill 登场的时候。

这就是 /***log-record。它的作用是在任务结束后把这次的决策背景记录下来。

4.1 记录那些“稍纵即逝”的想法

hen多时候，我们在开发过程中Zuo了hen多取舍。比如为了性Neng牺牲了一部分 性，或者因为时间紧迫暂时用了一个临时的方案。这些决策在当时是显而易见的，但三个月后你绝对想不起来当时为什么这么干。

/***log-record 会引导你记录：考虑过哪些方案？为什么选现在这个？有什么潜在的隐患？

这些内容不适合放在 Spec 里因为 Spec 是给“现在”用的，而这些记录是给“未来”用的。它们被顺序追加到决策日志里形成一条完整的时间线。

4.2 新人的救生圈

这种记录对团队新成员来说简直是救生圈。当他们kan到一段奇怪的代码时不需要去猜，也不需要到处问老员工，直接去查决策日志。日志里会清清楚楚地写着：“2023年10月我们讨论过方案A，Zui终选了方案B，因为...”。

这种上下文的保留，Neng极大地降低团队的沟通成本，也是知识沉淀Zui真实的方式。

五、 实战演练：如何在工作流中落地？

说了这么多理论，这套东西到底怎么用？其实安装和使用dou非常简单。

你需要安装这套工具。Ru果你用的是 Node 环境，直接运行：

npx skills add zzusp/doc-first-dev

安装完之后在你的项目根目录下运行 /spec-first 加上你的需求描述。它会自动检测是否需要初始化，然后开始走流程。

举个具体的例子。假设我要给一个列表接口加“按作者筛选”的功Neng：

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

AI分析： 它扫描代码库，发现目前的接口定义、数据库表结构。

生成文档： 它生成了一份geng新后的 Spec，标出了新增的 `author_name` 字段，以及对应的 SQL 变geng。

三角校验： 它发现代码里其实Yi经有一个类似的字段但没启用，于是停下来问我：“是复用这个字段还是新建？”

确认： 我选择了复用。AI geng新了 Spec。

执行： 我点击确认，AI 开始修改代码。

归档： 开发结束后我运行 /***log-record，记录下为什么选择复用字段而不是新建。

整个过程，我只需要在“确认门”和Zui后的“归档”处介入。其余的脏活累活，AIdou帮你处理了。

六、 这套方案适合你吗？

虽然这套工具我hen想安利给所有人，但说实话，它不是适合所有场景的。

Ru果你是在Zuo早期的技术验证，或者是在写一个一次性脚本，那这套流程可Neng太重了。我自己也是这么用的：新项目的早期探索阶段先不用，等方向确定了、开始认真迭代了再引入这套工作流。

它Zui适合的场景是：中长期的迭代项目、多人协作的项目，或者那些逻辑复杂、维护周期长的系统。文档的腐化成本极高，花一点时间在规范上，回报是巨大的。

七、 ：别让代码成为“孤岛”

写这个工具的出发点真的hen简单：我不想三个月后kan不懂自己写的代码。目前用下来文档腐化的问题确实好了hen多。那种“不知道该信文档还是信代码”的焦虑感少了hen多。

AI 时代的开发，速度是红利，但也是陷阱。Ru果我们只顾着踩油门，不管方向盘和后视镜，翻车是迟早的事。文档就是我们的后视镜，记录着我们为什么在这里又要去哪里。

通过这两个 Skill —— /spec-first 锁定当下的正确，/***log-record 保存过去的智慧 —— 我们终于Ke以在享受 AI 带来的极速的同时找回对代码库的掌控感。

Ru果你也有类似的困扰，不妨试试这套方法。当然任何工具dou不Neng解决所有问题，Zui重要的是养成“先思考，后执行；先文档，后代码”的习惯。Ru果你有什么问题或者想法，欢迎在评论区聊，我们一起把这套工作流打磨得geng好。

---