#5 写好一份 Spec 的实战手册

📌 本文是「AI 时代的编码新范式」系列的第 5 篇。全系列共 9 篇，基于 43 篇行业文献、学术论文与一线实践报告，探讨 Spec-Driven Development 如何在 AI Agent 时代从边缘实践变为工程的基础设施。每篇可独立阅读。前四篇解决了「为什么需要 spec」（第 1 篇）、「spec 的角色变了」（第 2 篇）、「spec 让任务变快」（第 3 篇）、「spec 是 Agent 的外部记忆」（第 4 篇）。本篇回答最后一个问题：spec 到底怎么写。

你已经相信 spec 重要了。

你读完了前四篇。你被注册页面那个黄色警告框说服了——口喷需求会把理解成本后移到 debug 阶段。你知道了 spec 是 Agent 的执行协议，不是给人看的说明书。你甚至理解了 Anthropic 那套三文件记忆系统。

然后你打开了一个空的 Markdown 文件。

光标在闪烁。

你开始想：写多长？用什么格式？要不要画 UML 图？要不要写用户故事？要不要像公司里的 PRD 那样搞个模板？你翻了翻网上那些 spec 示例——有的像 RFC 长达几十页，有的只有三行。你不知道该学哪个。

于是你关掉了文件，决定「下次再写」。

这个「下次」通常不会来。

Spec 不是什么

在告诉你怎么写之前，先说清楚它不是什么。大多数人的「不会写 spec」，其实是「把 spec 当成了别的东西」。

它不是 PRD。 产品需求文档回答的问题是「用户想要什么」——目标用户是谁，使用场景是什么，业务价值在哪里。这些问题很重要，但它们是给人看的。Agent 不需要理解「用户痛点」——它需要理解「接口长什么样，输入什么，输出什么，什么不能做」。PRD 说「用户需要一个安全的注册流程」，spec 说「密码用 bcrypt 存储，cost factor ≥ 10，错误提示不区分用户不存在和密码错误」。前者是产品判断，后者是执行约束。

Thoughtworks 在 2025 年的行业分析里给了一个更精确的技术定义：spec 应当显式定义目标软件的外部行为——输入输出映射、前置条件与后置条件、不变量、约束、接口类型、集成契约、状态机。不是「描述业务需求」，是「定义软件行为」。

它不是技术设计文档。 技术设计回答的是「架构怎么搭」——用什么数据库，怎么分微服务，消息队列选 Kafka 还是 RabbitMQ。spec 不关心这些。spec 关心的是「功能怎么实现」——这个 API 接受什么参数，返回什么状态码，异常时怎么处理。Addy Osmani 在他的 spec 方法论里说了一句到位的话：高层 spec 应该聚焦于 what 和 why，而不是 how——至少在最初阶段如此。架构决策是 how，那是 Agent 在实现阶段自己会做的事。你只需要告诉它 what 和 why。

它不是用户故事。 用户故事的经典格式是「作为一个用户，我想要上传文件，以便分享给同事」。它只有意图。但 Agent 需要的不只是意图——它需要约束（文件大小限制、类型白名单）、边界（本期不做断点续传）、验收标准（上传成功后文件出现在列表中、超时返回明确错误）。用户故事是 spec 的起点，不是 spec 本身。

Amazon 有一个产品方法论叫 Working Backwards——在开始做任何东西之前，先写一份「如果这个产品已经做完了，新闻稿会长什么样」。这不是 spec，但它给了 spec 一个正确的起点：从结果倒推。先想清楚「做完了是什么样」，再想「需要满足什么条件才能做到那个样子」。第 1 篇里那份注册功能 spec 就是这个思路——它不是从「用户需要一个注册页面」开始的，是从「一个安全的注册流程应该满足什么条件」倒推出来的。

Spec 的五要素

澄清了误解之后，正面回答：一份合格的 spec 包含什么。

GitHub 官方博客上一篇被广泛引用的分析——作者 Matt Nigh 读取了超过 2500 个 agents.md 文件——发现最有效的 spec 都覆盖了六个领域：命令、测试、项目结构、代码风格、Git 工作流、边界。其中「永远不要提交密钥」是出现频率最高的一条单条约束。

把这个结论跟 Addy Osmani 的方法论、Thoughtworks 的技术定义、以及第 1 篇的注册页面 spec 交叉对照之后，可以提炼出五个核心要素。一、目标。 这个功能解决什么问题，为谁解决。不需要长篇大论——一两句话说清楚就够了。AWS 的 Prescriptive Guidance 把这个原则叫做「Start with why」：先说为什么做，再说做什么。Agent 需要知道目标才能在不偏离方向的前提下自己做细节决策。如果目标模糊——「优化一下这个页面」——Agent 没有方向锚点，它的每一个选择都是随机的。

二、约束。 绝对不能做什么，必须遵守什么规则。这是 spec 最区别于用户故事的部分。约束分两类：安全约束（密码哈希、输入验证、不暴露用户数据）和工程约束（不用某个已废弃的 API、遵循现有的错误处理模式、不引入新依赖）。GitHub 那个 2500 文件研究里，「不要碰什么」比「要做什么」更值得重视——「永远不要提交密钥」是出现频率最高的单条约束。

三、边界。 输入输出的范围、依赖关系、以及——同样重要的——明确不做什么。第 1 篇的注册 spec 里有一节叫「明确不做（本期）」：不发送验证邮件，不做社交登录，不做 CAPTCHA。这三条看起来像是「没什么可写了凑数的」，但它们的作用是防止 Agent 自作主张扩展功能。Agent 有一种天然的倾向：它看到「注册」就会联想到「邮箱验证」「密码强度检测」「登录频率限制」——这些都是训练数据里注册功能的常见配套。如果你不明确说「不做」，Agent 就会做。

四、验收标准。 怎么算「做对了」。这一条是整个 spec 的锚。Claude Code 的 Best Practices 文档里说得很直接：给 Agent 一种验证自己工作的方式。测试用例是最直接的验证方式。截图对比是 UI 开发的验证方式。Linting 结果是代码风格的验证方式。每一项验收标准都是一条「Agent 可以不依赖人类判断就推进」的许可。没有验收标准的任务，Agent 每走一步都要回头看你——这恰好是把 Agent 用慢了的方式。Thoughtworks 补充了一个有用的建议：用 Given/When/Then 的格式写验收标准——这个从 BDD 里继承来的结构在 AI 时代依然有效。

五、技术上下文。 项目结构、技术栈、相关文件位置。这部分你不需要手写——让 Agent 读一遍你的代码库，它自己就能生成。Addy Osmani 的第一条原则就是「先给高层愿景，让 AI 草拟细节」：你写两句话描述项目目标，让 Agent 扫描代码库生成一份包含技术栈、目录结构、命令清单的上下文文档，你 review 一下就行。这部分 spec 的价值在于让后续每一次 Agent 会话都能快速定位「相关代码在哪、怎么跑测试、用什么框架」。

同一个功能，两份 Spec

回到第 1 篇那个注册页面。口喷需求是一句话：「帮我做一个注册页面」。

Agent 听到这句话之后，它脑中的「注册页面」是训练数据里成千上万个注册页面的平均值。那个平均值有邮箱输入框、密码框、注册按钮——但没有「密码不能明文对比」「错误提示不能区分用户」「接口响应不能返回其他用户数据」。因为这些是安全约束，不是 UI 模板。

结果就是那个黄色警告框：「密码需要唯一。该密码已被用户 r***88 使用。」

现在对照第 1 篇里那份 spec，用五要素的镜头重新看一遍。

目标——「为平台提供邮箱注册入口」，一句话。不是「做一个注册页面」，是「提供注册入口」。措辞的差别决定了 Agent 的思考方向：前者让它想 UI，后者让它想流程。

约束——「密码使用 bcrypt 存储，cost factor ≥ 10，不可逆」「错误提示不附带任何关联账户信息」「接口响应中不返回其他用户的数据」。三条安全约束，每一条都是对那个黄色警告框的预防。

边界——「不发送验证邮件」「不做社交登录」「不做 CAPTCHA」。三条明确的「不做」，每一条都在堵住 Agent 自作主张的路。

验收标准——六条可测试的断言：「新邮箱 + 合规密码 → 201，数据库密码字段为 bcrypt 哈希」「已注册邮箱 → 409」「接口响应中不出现其他用户的标识信息」。每一条都可以写成自动化测试。Agent 做完之后能自己跑一遍验证，不需要你逐行检查。

技术上下文——API 路径（POST /api/auth/register）、数据字段（email、password、created_at）、前端路由（/register）。这些就是 Agent 需要的技术锚点。

同一份功能，口喷需求一句话 vs 五要素 spec 一页纸。Agent 在前者上产出了一个泄露用户密码的系统，在后者上一次通过安全审计。差异不在于 Agent 的能力——是同一个 Agent。差异在于你给了它什么。

Addy Osmani 在他的文章里引用了一个观察：「有经验的开发者会先写好文档，然后模型可能仅凭这份文档就能构建出匹配的实现。」spec 不是辅助材料——在足够好的 spec 面前，Agent 有可能仅凭它就构建出匹配的实现。

从三句话开始

说完了五要素，你可能会觉得写 spec 是一件需要认真准备的事。它确实是。但「认真准备」不等于「从完美的文档开始」。

Addy Osmani 的方法论第一条就是：「先给一个简洁的高层 spec，然后让 AI 把它扩展成详细计划。」你不是在写一份巨著——你是在种一颗种子。

现在就可以做的事：在你的项目根目录下创建一个 CLAUDE.md 文件（如果你用的是 Copilot 或 Cursor，创建 AGENTS.md——内容一样，文件名不同）。写下三行：

# 项目说明

这是一个 [一句话描述你的项目做什么]。
技术栈：[列出主要框架和语言]。
Agent 必须遵守：[写 1-3 条最重要的约束]。

三行。写完了。这就是你的第一份 spec。

它不完美。它不完整。但它做到了最重要的一件事：从零到一。Agent 下次启动时，它读到的不再是一个空目录——它读到了项目的身份、技术栈和底线。这三条信息足以让 Agent 的产出质量产生质变。

然后你让它扩展。打开 Claude Code，对它说：「读一下这个项目的代码库和 CLAUDE.md，帮我补充：常用命令、项目结构说明、测试方式、代码风格示例。」Agent 会扫描你的代码库，生成一份更完整的上下文文档。你花两分钟 review 一下，改掉它猜错的地方，补上它漏掉的约束。

这就是 Addy Osmani 说的「让 AI 草拟细节」。你提供方向，Agent 填充细节，你 review 结果。这个循环比你自己从零写一份完整 spec 快得多。

Claude Code 的 Plan Mode 把这个循环产品化了。你在 Plan Mode 里描述你想做什么，Agent 只读不改——它分析代码库、理解约束、输出一份执行计划。你审查计划，觉得方向对就通过，不对就改。通过之后才退出 Plan Mode，让 Agent 开始写代码。Plan Mode 的本质就是：先在文档层对齐，再在代码层执行。在文档层解决一次理解偏差的成本，远低于在代码层解决同一个偏差。

Spec 是活文档

Thoughtworks 在那篇行业分析里传达了一个意思：行业对规范该是什么还没有形成共识——方法论仍在形成中。

这句话的意思不是「等标准出来了再开始」。它的意思是：没有人能告诉你「正确的 spec 长什么样」，因为所有人都还在摸索。

这反而给了你一个优势：你不需要学一套标准流程。你不需要买工具。你不需要安装框架。你需要的只是一个 Markdown 文件和三句话。

第一天：三行 CLAUDE.md。第一周：补充项目结构和常用命令。第一个月：为每个新功能写一份五要素 spec。第二个月：你回头看初版 CLAUDE.md，发现它已经长到了两页——但你没有哪一天是「专门坐下来写文档」的。它是随着开发自然生长出来的。

这就是 spec 作为 living document 的真正含义。它不是在项目开始时写完、然后在 Confluence 里过期的文档。它是你每次跟 Agent 交互时都在更新的工作文件——你改了 spec，Agent 下次执行立刻就变。spec 和代码之间形成了一个实时反馈循环：代码变了，你更新 spec；spec 变了，Agent 重新执行。

Ubuntu 的工程团队在 2026 年初发表的一篇回顾文章里写了一句话，放在 AI 时代依然精确：「文档是开发过程的一部分，而不是事后补充。」他们不是在说 SDD——他们是在说一个更朴素的道理：文档只有跟开发同步呼吸，才有生命力。

你不需要写一份完美的 spec。你需要的是开始写。

三句话就够了。

参考文献

1. Osmani, A. (2025). How to write a good spec for AI agents. Five principles for spec-writing: high-level vision first, PRD-like structure, task decomposition, Plan Mode, living document.

2. Thoughtworks. (2025). Spec-driven development: Unpacking one of 2025's key new AI-assisted engineering practices. Spec defines external behavior (I/O mappings, preconditions, invariants); industry consensus on spec format still forming.

3. GitHub. (2025). How to write a great AGENTS.md: Lessons from over 2,500 repositories. Six core areas of effective agent configs; "never commit secrets" as the most common constraint.

4. Anthropic. (2025). Claude Code: Best Practices for Agentic Coding. CLAUDE.md configuration, Plan Mode (explore → plan → code), verification criteria.

5. Working Backwards. The Amazon Working Backwards PR/FAQ Process. Start from customer outcome; write the press release before the implementation.

6. AWS. Start with why — Prescriptive Guidance. Press release and FAQ to define scope, customer value, and business outcomes.

7. Microsoft. (2025). Diving Into Spec-Driven Development With GitHub Spec Kit. Spec Kit: list requirements, motivations, and technical context before handing to AI agents.

8. Ubuntu. (2026). A year of documentation-driven development. Documentation as part of the development process, not an afterthought.