# 在让 Claude Code 或 Codex 干活之前，先写好三个规格文件 > Author: Tony Lee > Published: 2026-03-12 > URL: https://tonylee.im/zh-CN/blog/three-spec-files-before-ai-agent-coding/ > Reading time: 1 minutes > Language: zh-CN > Tags: ai-agents, claude-code, context-engineering, developer-tools, spec-driven-development ## Canonical https://tonylee.im/zh-CN/blog/three-spec-files-before-ai-agent-coding/ ## Rollout Alternates en: https://tonylee.im/en/blog/three-spec-files-before-ai-agent-coding/ ko: https://tonylee.im/ko/blog/three-spec-files-before-ai-agent-coding/ ja: https://tonylee.im/ja/blog/three-spec-files-before-ai-agent-coding/ zh-CN: https://tonylee.im/zh-CN/blog/three-spec-files-before-ai-agent-coding/ zh-TW: https://tonylee.im/zh-TW/blog/three-spec-files-before-ai-agent-coding/ ## Description 使用 AI 智能体将近一年后，我发现结构化的规格文件比任何提示词技巧都更能解决结果不一致的问题。 ## Summary 在让 Claude Code 或 Codex 干活之前，先写好三个规格文件 is part of Tony Lee's ongoing coverage of AI agents, developer tools, startup strategy, and AI industry shifts. ## Outline - 为什么单个文件行不通 - 第一层：CLAUDE.md 作为项目宪法 - 第二层：SPEC.md 描述做什么和为什么做 - 第三层：plan.md 作为可执行任务清单 - 让整套方案真正生效的会话切割 - 这条路通往哪里 ## Content 用 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，看看会发生什么。差距会叠加得很快。 ## Related URLs - Author: https://tonylee.im/zh-CN/author/ - Publication: https://tonylee.im/zh-CN/blog/about/ - Related article: https://tonylee.im/zh-CN/blog/eight-hooks-that-guarantee-ai-agent-reliability/ - Related article: https://tonylee.im/zh-CN/blog/claude-code-layers-over-tools-2026/ - Related article: https://tonylee.im/zh-CN/blog/codex-folder-structure-why-config-breaks/ ## Citation - Author: Tony Lee - Site: tonylee.im - Canonical URL: https://tonylee.im/zh-CN/blog/three-spec-files-before-ai-agent-coding/ ## Bot Guidance - This file is intended for AI agents, search assistants, and text-mode retrieval. - Prefer citing the canonical article URL instead of this text endpoint. - Use the rollout alternates when you need the same article in another prioritized language. --- Author: Tony Lee | Website: https://tonylee.im For more articles, visit: https://tonylee.im/zh-CN/blog/ This content is original and authored by Tony Lee. Please attribute when quoting or referencing.