Skip to main content
← All posts
作者：Sagasu

#02 - Specification 即协议——当文档成为代码的「事实来源」

📌 本文是「AI 时代的编码新范式」系列的第 2 篇。第 1 篇讲了「口喷需求的代价」——Agent 猜不对你脑子里没说的约束。本篇讲的是：那些约束写下来之后，到底发生了什么变化——不是多了一份文件，而是文档在整个工程流程中的身份变了。每篇可独立阅读。

两行命令。同一个意图。

# 盲飞——Agent 不知道你想干什么
claude "帮我重构这个 auth 模块"

# 航图——Agent 有一份明确的执行契约
# （示意，非 Claude Code 真实 CLI 语法）
claude --spec specs/refactor-auth.md

第一行让 Agent 盲飞。第二行给了它航图。

这中间的差距，不是你多写了一篇文档，而是一份 spec 的身份发生了三重转变——从给人看的说明书变成给 Agent 读的执行协议、从写完就过时的静态文件变成每次会话都重新加载的 living document、从人类阅读的散文变成机器解析的接口配置。

这三重转变加起来，等于一件事：在 AI Agent 成为你的主力编码者的时代，spec 不再是「开发过程中顺便产出的一份文件」。spec 是开发过程的第一道输入。

第一重转变：从说明书到执行协议

2025 年 9 月，GitHub 开源了 Spec Kit——一个专门面向 AI 编码 Agent 的工具包。它把开发流程重新组织成四个阶段：Specify → Plan → Tasks → Implement。

这看起来像是一个普通的流程重组。但它做了一件关键的事：把 spec 从「开发开始前要做完的事」变成了「开发本身的第一步」。

在传统流程里，写需求文档和写代码是两个阶段——由不同的人、在不同的时间、用不同的工具完成。交接点是一封邮件或一个 Jira ticket。文档一旦交出去，就和实现过程解耦了。代码可能在三个月后偏离 spec，但 spec 不会知道——它会安静地躺在 Confluence 里过期。

在 Spec Kit 的四阶段模型里，Specify 不是前置步骤。它就是管线本身的第一道工序。spec 写完之后直接流入 Plan（Agent 读取 spec 生成执行计划），Plan 流入 Tasks（拆解为可执行的子任务），Tasks 流入 Implement（Agent 逐项编码）。spec 是输入信号，代码是输出信号。中间没有人类翻译环节，没有「你把需求写成邮件、他把邮件理解成代码」的损耗。

Microsoft 把这套方法称为 spec-first——不仅是「先写 spec 再写代码」，而是 spec 驱动代码生成。他们的核心理念是：spec 应当作为业务意图与代码/测试之间的 shared source of truth。这是一句很容易被忽略的话，但它暗含了一个巨大的立场转变：source of truth 不再是代码，而是 spec。代码只是 spec 的一种表达形式。

GitHub Spec Kit 目前已支持 30+ AI 编程 Agent 的集成【^1】——Claude Code、Copilot、Codex、Cursor 都在列表里。这意味着同一份 spec 可以被不同的 Agent 读取和执行。spec 不再绑定到某一个工具、某一个 IDE、某一个团队的工作流程。它变成了一个跨 Agent 的执行协议，就像 REST API 不关心 consumer 是用 curl 还是用 Postman——spec 只定义「做什么」「怎么做」「做对的标准是什么」，谁来实现都可以。

Thoughtworks 在 2025 年的一篇行业分析中这样描述 SDD 的核心逻辑：用写好需求规范来驱动 AI Agent，本质上是用结构化自然语言替代模糊 prompt。这个定义本身就在说：spec 已经不再是文档了。它是 prompt。是给机器的指令。

第二重转变：从静态文档到 Living Document

传统的需求文档有一个半衰期。写完的那一刻就开始过期。Sprint 2 的需求调整不会自动回写到 Sprint 1 的 PRD 里。三个月后，文档和代码之间的关系已经无法信任——你不知道是文档没更新，还是代码写偏了。

但在 Agent 工作的方式里，这个关系被翻转了。

Claude Code 每次启动一个新会话时，会重新读取项目根目录下的 CLAUDE.md 文件。GitHub Copilot 会读取 .github/copilot-instructions.md。Codex 会读取它的 harness 配置。这意味着：你改一行 spec，Agent 下一次执行的输出立刻就变。 没有「上次的需求变更需要通知到实现方」的延迟。spec 本身就是通知。

这就是「living document」的真正含义。不是「有人定期维护所以它不过时」，而是「维护它有即时的、看得见的回报」。你更新 spec，Agent 就按新 spec 工作。维护的动力来自直接的反馈循环，而不是来自流程要求。

Anthropic 在它的长程 Agent 实践里进一步证实了这一点。在 Effective Harnesses for Long-Running Agents 一文中，他们描述了 Agent 跨会话推进任务的工作方式：初始化阶段先写出完整需求文档；编码 Agent 靠进度文件 + git 记录了解当前状态；每次新会话开始时，Agent 读取这些文档来重建上下文。文档在这里的角色不是「参考资料」，而是 Agent 的外部记忆系统。

Agent 没有长期记忆。重启会话即丢失全部上下文。文档填补了这个缺口——它不是给人看的记录，它是 Agent 的持久化状态层。

第三重转变：从人类阅读到机器执行

最直接的证据不是某篇行业报告，而是你硬盘上已经存在的文件。

CLAUDE.md. AGENTS.md..github/copilot-instructions.md。

这些文件不是写给同事看的。它们是写给 Agent 在运行时读取的。它们的内容不追求「人类阅读体验」——没有摘要、没有背景介绍、没有可读性优化。它们就是纯粹的上下文数据：项目名称、技术栈、编码规范、约束条件、仓库结构、测试命令、部署流程。Agent 逐行读取，按规则执行。

一篇 2025 年的 arxiv 论文分析了 242 个真实仓库中的 253 个 CLAUDE.md 文件。研究发现这些 manifest 文件正在成为 Agent 的运行时上下文——它们定义了项目的身份、操作的边界、允许做什么和不允许做什么。另一篇覆盖了 Claude Code、GitHub Copilot、Cursor、Gemini 和 Codex 五种工具的论文进一步确认：AGENTS.md 这种文件格式正在成为跨工具的行业标准。

这不是巧合。当五种主流 AI 编码工具都开始读取同一个文件格式时，这个格式就不再是某个工具的私有配置——它正在变成 Agent 开发环境的基础设施层。你的 AGENTS.md 不只是给 Claude Code 看的。将来 Cursor 也会读它。Codex 也会读它。你在今天写下的这份文件，实际上是在为一个还不存在的工具链预埋接口。

这意味着什么？意味着项目文档正在从「人类协作文档」变成「Agent 配置层」。你项目里的 CLAUDE.md 的受众不是下一个接手这个项目的开发者——虽然他会看。它的一号读者是 Agent，每次启动都会读。你不是在写文档，你是在编程——在给 Agent 编程。

你的项目里缺的不是代码

把这三重转变拼在一起，你看到的画面是这样的：一份 spec 文件，放在项目根目录。Agent 每次启动时读取它。它告诉 Agent 这个项目是什么、你应该做什么、你不应该做什么、做到什么程度算完成。Agent 按照这些规则生成代码。你 review 代码是否符合 spec。你更新 spec。Agent 下次按新 spec 执行。

这不是「多写了一份需求文档」。这是你给 Agent 编程的方式——不是用 Python，不是用 TypeScript，而是用结构化自然语言。

你的项目里缺的不是更多代码。Agent 可以写代码。你的项目里缺的是一份连 Agent 都能正确解读的 spec——清晰到没有误解空间，完整到没有自作主张的余地，每一行都在回答 Agent 执行时会问的那三个问题：做什么、怎么做、做对的标准是什么。

把 spec 想象成你和 Agent 之间的 API contract。接口写清楚了，Agent 就能对接。写得模糊，Agent 就乱接。

参考文献

  1. GitHub. (2025). Spec-driven development with AI: Get started with a new open source toolkit. GitHub Blog. — Spec Kit 的推出公告，定义了 Specify → Plan → Tasks → Implement 四阶段流程。

  2. Microsoft. (2025). Spec-Driven Development: A Spec-First Approach to AI-Native Engineering. Microsoft Developer Blog. — Spec-First 方法论，spec 作为 shared source of truth.

  3. GitHub. GitHub Spec Kit. GitHub 开源仓库。 — 支持 30+ AI 编程 Agent 集成。

  4. GitHub. What is Spec-Driven Development?. GitHub 官方文档。 — 规格作为可执行的开发输入。

  5. Anthropic. (2025). Effective harnesses for long-running agents. Anthropic Engineering Blog. — 文档作为 Agent 外部记忆与状态管理的实践。

  6. Thoughtworks. (2025). Spec-driven development: Unpacking one of 2025's key new AI-assisted engineering practices. Thoughtworks Insights. — SDD 定义为「用规范作为 Agent 提示词」。

  7. On the Use of Agentic Coding Manifests: An Empirical Study of Claude Code (arXiv:2509.14744). — 分析 242 个仓库中 253 个 CLAUDE.md 文件。

  8. Configuring Agentic AI Coding Tools: An Exploratory Study (arXiv:2602.14690). — AGENTS.md 成为跨工具标准（Claude Code、Copilot、Cursor、Gemini、Codex）。