在让 Claude Code 或 Codex 干活之前，先写好三个规格文件

用 AI 编程智能体超过一周之后，你大概率遇到过这种情况：同一个任务，周一跑出来干干净净，周二跑出来一塌糊涂。提示词几乎没变，代码库也没动，但结果天差地别。

我花了将近一年追这个问题。试过更精细的提示词，试过更详细的说明，换过不同的模型，全都没有从根本上解决。真正的问题在于我没有一套结构化的方式来传递意图。我完全依赖提示词来承载所有信息：项目规则、功能需求、任务步骤、编码规范。一个输入扛这么多东西，迟早垮掉。

解法其实很直接：把指令拆成三个文件，分布在三个层次上。做了这个调整之后，不同会话之间的质量差异基本上消失了。

为什么单个文件行不通

关于大语言模型指令跟随能力有一个有名的现象，叫”指令诅咒”（Curse of Instructions）。当单个上下文中的指令数量增加时，模型对每条单独指令的遵守率会急剧下降。我自己也直接验证过：把项目规则、功能规格、任务清单全塞进一个 CLAUDE.md，智能体大约会无视后半部分里将近一半的指令。

这在注意力机制的视角下很好理解。一份混杂了各种关切的长文档，会迫使模型在推理过程中实时判断什么最重要，而它做出的权衡往往很糟糕。解法是按职责分离信息，让每一层保持专注。

第一层：CLAUDE.md 作为项目宪法

CLAUDE.md（或者你用的智能体对应的配置文件）在每次会话启动时自动加载，这反而决定了它不适合放功能相关的指令。它只应该包含整个项目层面始终成立的事情：

• 构建命令和技术栈版本
• 目录结构与命名规范
• 三档行为规则：必须做、先确认再做、绝对不做

我吃过一个亏：一开始把能想到的所有东西全部预先写进去，效果反而差。后来改成观察智能体在哪里反复犯错，再针对性地增加规则，这种渐进式的方式比任何提前规划都管用。

有几类东西要坚决排出 CLAUDE.md：API 密钥（会过期）、代码片段（会和真实代码脱节）、已经有 linter 在管的代码风格规则，以及任何针对单个功能的内容。这些东西属于下一层。

第二层：SPEC.md 描述做什么和为什么做

规格文件描述一个功能。它回答五个问题：这个功能做什么、为什么要做、成功标准是什么、技术约束有哪些、边界在哪里。就这五部分。

和传统 PRD 的关键区别在于：规格文件是为智能体消费而设计的，不是给人开评审会用的。而且它故意不写”怎么做”。实现方式应该由智能体通过分析现有代码库来判断，而不是照着规格里的步骤一步步抄。

写出一份好规格有两条路。一是自己按五段结构起草。二是让智能体来采访你。采访这条路效果出奇地好，但要执行两条规则：每次只问一个问题，尽量用选择题而不是开放性问题。这样产出的规格，往往能覆盖我自己写时会漏掉的边界情况。

写完的规格存到 docs/specs/YYYY-MM-DD-topic.md 并提交到 Git。这样智能体可以用 git diff 追溯决策路径，代码审查时也能区分哪些是有意为之、哪些是误打误撞。

第三层：plan.md 作为可执行任务清单

计划文件是最细的那一层。它把规格拆解成每个耗时两到五分钟的任务，明确写出文件路径，固定执行顺序。我会把每个计划都锚定在 TDD 循环上：先写测试，再写刚好能让测试通过的实现代码，确认测试通过，然后提交。

明确写出文件路径比我预想的更重要。不写的话，智能体会猜文件该放哪里，而这些猜测在不同会话之间会漂移。把路径钉死就消除了这种随机性。

让整套方案真正生效的会话切割

有一点我摸索了好几个月才想明白。就算三个文件都写得很干净，如果在同一个会话里写完规格就直接开始实现，质量还是会下滑。原因很直接：写规格时的头脑风暴和问答过程会消耗大量上下文窗口。等到开始实现时，智能体已经开始遗忘前面的决定了。

解法也很简单。第一个会话：写 SPEC.md，保存。第二个会话：根据规格生成 plan.md。第三个会话起：逐条执行任务。上下文窗口用到大概一半时，我也会主动开新会话。准确度的提升是立竿见影的。

这条路通往哪里

敏捷宣言的核心成员发布过一份基于智能体的软件开发成熟度模型，和这套分层方式高度吻合：

• 第一级：写规格，实现功能，然后把规格扔掉。
• 第二级：把规格当作活文档，随着代码一起演进。
• 第三级：规格成为唯一事实来源，代码是生成产物。

我接触过的大多数开发者还没到第一级。他们仍在用提示词作为唯一输入、代码作为唯一输出的模式工作。这对小任务够用，但复杂度一上来就开始崩。

从第一级升到第二级，只需要一个习惯：把规格文件提交到 Git。从第二级升到第三级，是工作流的改变：需要改代码时，先更新规格，再重新生成。

现在就可以开始。给项目写一个 CLAUDE.md 记下基本信息，在动任何代码之前先给下一个功能写一份 SPEC.md，看看会发生什么。差距会叠加得很快。