基于规范的AI编程智能体开发：实用指南
基于规范的开发与AI编码智能体：四阶段工作流程、AGENTS.md与SPEC.md文件、多智能体角色、成熟度等级以及如何发现偏差。
来源: Spec-Driven Development with AI Coding Agents: The Definitive Guide
Claude Code、GitHub Copilot、Cursor 和 Windsurf 等工具生成、重构和测试代码的速度远超人类能力。然而，仅有速度而缺乏精确性往往会成为弊端。许多使用这些工具的团队都陷入不断提示、接收输出、修复错误后再再次提示的循环中，而且随着代码库规模的扩大，这种循环会愈发严重。问题通常不在于模型本身，而在于没有人能以规范的方式告诉智能体所需的内容。
基于规范的开发（SDD）便是其中一个解决方案。它将结构化的规范视为交付过程的核心产物——即用于生成、检查和管理代码的文档。
概念基础
vibe coding 为何行不通
“氛围编码”指的是用口语化的方式描述期望的结果，并通过非正式的后续提示来引导输出。这种方法适用于独立的任务、快速原型设计以及单次会话的实验。但在大规模应用中效果极差，其原因值得了解。
上下文衰减
每次会话都在一个上下文窗口内进行，即智能体一次能够处理的有限信息量。在氛围编码过程中，项目的状态仅存在于聊天记录中。随着对话的延长，早期的架构决策、安全限制以及库的选择都会逐渐被忽略。此时智能体会悄悄用看似合理的替代方案取而代之，而往往不会明确说明。这就是上下文衰减。
其典型症状是实现偏差：代理程序自认为正在构建的内容与业务方最初的要求逐渐脱节。代码虽然能通过测试、独立运行且表面上看似正常，却会违反之前设定的结构规则或业务规则。在企业系统中，这类缺陷是最难诊断且修复成本最高的。
核心理念
SDD基于一个架构原则：规范是核心文档，实现则是由此衍生而来。这不仅仅是工作流程上的微调，而是彻底颠覆了传统模式——在传统模式下代码优先，文档则滞后跟进。
在这种方法中，规范是机器可读的、受版本控制的、动态更新的且可执行的。它充当了人类意图与智能体执行行为之间的契约，智能体会在该契约的约束范围内工作，而非凭猜测行事。明确的契约能产生可预测的结果，而模糊的契约则会导致结果差异。简而言之，只有在明确定义了希望构建的内容之后，才能控制智能体最终生成什么。
机器可读规范的六个要素
用于智能体的规范必须克服自然语言的模糊性。为避免智能体做出不必要的假设，通常认为必要的六个要素包括：
- 结果，即工作应实现的目标。
- 范围，包括明确排除在外的内容。
SDD工作流程
包含人工审核的四个阶段
该工作流程包含四个依次进行的阶段，每个阶段都有需要人工介入的环节。这些人工审核点并非形式主义，其作用是防止错误在后续环节进一步累积，而为了“加快速度”跳过这些审核往往会产生相反的效果。
第一阶段：明确需求。开发人员首先从高层次上阐述目标，随后由智能体或开发人员自行将其细化为结构化的功能规范，包括用户流程、业务成果、验收标准以及明确的范围边界。此阶段的工作是进行架构审查，在任何规划开始之前检查其中是否存在错误设想、遗漏或误解。只有在第一阶段完全消除歧义后才能进入第二阶段：模糊的规范很少会导致实现结果也模糊不清，反而会造就一种自以为正确实则错误的实现方案。
第二阶段：规划。一旦需求规格得到批准，工程师就会起草一份技术计划，内容包括架构决策、数据模型、API契约以及技术选型。该计划还会明确各种组织层面的约束条件，例如“数据需存储在PostgreSQL中”或“每个API接口都必须进行JWT身份验证”。在此阶段进行人工审核，可以在错误被写入成千上万的代码行之前及时发现架构上的问题。
第三阶段：任务分解。已获批的计划会被拆分成多个小型任务，这些任务均可独立进行测试。粒度或许是软件驱动开发中最容易被忽视的要素。一个任务应在单次智能体运行中即可实现并验证，如果它要求智能体同时处理超过三个独立的问题，那就显得过于复杂了。合理拆分后的任务列表还能为测试驱动开发提供框架，因为每个任务在开始执行前都有明确的成功标准，从而使项目能频繁获得验证节点。
第四阶段：实现与验证。智能体会逐个任务编写代码，其输出结果具有针对性，便于审核并追溯到具体的需求。这一阶段会采用验证器模式，即一个智能体负责生成代码，另一个智能体或自动化测试套件则根据验收标准对其进行检查。
双向更新规范
最重要的实践之一，却也最常被违反的，就是双向更新。假设在第四阶段，智能体做出了规范中未涵盖的决策，比如出于性能考虑选择某个库，或以一种不那么显而易见的方式处理某个边缘情况。这样的决策应立即被写回规范中。
如果做不到这一点，就会产生“规范债务”：文档中记载的意图与实际行为逐渐脱节。这种差异会让原本有效的规范变成没人信任、最终也没人再阅读的过时文件，而在最需要它的时候——即后续的AI辅助修改过程中——它就变得毫无用处。规则很简单：当实现内容偏离规范时，就要立即更新规范，而非等到下一次迭代。规范债务的增长速度比技术债务更快，因为它会污染后续所有版本的起始基础。
持久化工件与项目章程
为什么智能体需要章程
编码代理在各个会话之间没有记忆功能。每个新会话仅以你放入其上下文中的内容作为起点。由于缺乏持久化机制，每个会话都是一张白纸，它不会知晓你的安全标准、命名规范、被禁用的库或架构决策。
“项目章程”是一组用于解决此问题的持久化文档。这些结构化的文件会与源代码一同存储在代码仓库中，从而使代理具备必要的机构知识，能够像团队内部成员一样工作，而非外人。
核心文档
AGENTS.md 或 CLAUDE.md，即操作手册。这是最重要的文件：作为智能体的README，在每次会话开始时阅读它即可了解该特定项目的运行方式。它应优先考虑机器解析的便利性而非人类可读性。一份有效的文件应包含三类信息：
- 智能体无法自行推断的操作细节：包含参数的完整构建命令、测试的运行方式、代码检查工具的配置以及环境变量名称。
- 命名与结构规范：每个目录的用途、文件的命名规则以及模块的组织方式。
.env 文件或更改认证逻辑。SPEC.md，即动态更新的规范文档。它是系统应执行功能的权威描述，而非历史记录。该文档反映了当前的预期行为，包括实现过程中所做的每一个决策。如果代码与 SPEC.md 不一致，则需更新该文档；而当需求发生变化时，首先编辑 SPEC.md，再相应调整实现代码。
PLAN.md，即架构记录文件。它记载了架构决策、技术选型以及全系统的约束条件。它能回答“为何要这样设计？”的问题，通过提供相应的理由来防止后续的自动化工具或工程师推翻那些经过深思熟虑后的决策。
针对特定工具的配置文件。每种工具都有自己约定的规则文件格式。Cursor的.mdc格式值得特别提及，因为它将Markdown与YAML前置内容结合使用，从而能够将规则与文件通配符模式关联起来。这样一来，诸如身份验证要求及数据库访问规则之类的后端规则，只有在自动化工具处理后端文件时才会生效，从而避免在处理前端文件时让无关信息占用其工作内存。
多智能体协调
为何单个智能体不够用
负责整个企业代码库的单一智能体存在一个根本限制：上下文窗口大小。一个拥有10万多个文件、多个服务、复杂的数据流以及完整测试套件的庞大系统，无法全部容纳在单个智能体的上下文中。智能体必须自行决定要处理哪些内容，而这些选择就会带来视野盲区。
多智能体协调机制的理念是借鉴高效人类团队的运作方式，明确各角色的职责，实现有序的任务交接，并以统一的规范作为所有人的行为准则。
三种角色
协调员。该角色承担项目管理员和架构师的功能。它掌握整体情况，包括完整的规范、任务列表以及架构约束条件。它会将整体规范拆分为若干子规范，分配给执行者，同时监控并行工作流之间的冲突，确保完成某项任务不会破坏整个架构。
执行者。执行者是各领域的专家。每人负责一个子规范，涵盖一项任务或一小组相关任务，并在独立的Git工作目录中开展工作，以避免与同时运行的其他执行者在文件层面产生冲突。他们不了解自己职责范围之外的工作，也不对其负责。这种隔离并非限制，反而使得输出结果具有确定性、可测试性和可审查性。
验证器。验证器的目标与实现者相反。实现者试图完成任务，而验证器则试图找出结果在哪些方面不符合规范。这种对抗式设计借鉴自形式化验证与安全研究领域，是SDD所提供的最强大的质量保障机制之一。验证器会根据验收标准检测输出结果，查找功能缺陷、安全策略违规、性能约束违反以及与规范的偏差。一旦发现差异，它不会直接修复代码，而是向协调器提交结构化的描述，将故障追溯到具体的需求上。
对于生产系统而言，这种对抗性验证器绝不能是可选的。能够自行编写并检查代码的智能体几乎总会认为自己的工作合格，而验证器的价值恰恰在于它独立于实现者且与实现者相对立。
基于工作树的并行执行
多智能体SDD最宝贵的能力之一就是并行性：多个智能体可以同时处理不同的功能或服务，每个都在自己的工作树中操作。对于任务间依赖性较少的庞大项目，交付时间可以大幅缩短。
Git工作树实现了这一点。每个智能体都有连接到同一仓库的独立工作目录，从而避免了文件冲突，同时协调器可以从一个地方监控所有工作流的进展。在验证器批准后，协调器会合并已完成的工作树，保持主分支的整洁。
用代码表示图表
为何图表应包含在规范中
传统上，架构图表是在代码编写完成后作为文档而绘制的。在SDD模式下，它们则处于设计阶段，作为规范和计划的一部分，在任何实现之前就确定下来。
这样做的目的是为了便于诊断。要求智能体根据规范生成有效的Mermaid图表，能迫使它在编写代码之前明确思考数据流、服务依赖关系以及状态转换。如果在这一阶段图表就显得混乱或逻辑不清，那很可能是规范存在歧义或结构缺陷的迹象，而通过修改图表来解决这些问题，其成本远低于在已部署的代码中修复这些问题。
格式
对于此用途而言，基于文本的格式，尤其是 Mermaid 和 D2，比二进制图像更优。它们可以进行版本控制和差异对比，同时自动化工具也能直接读取。随着规范的演进，这些格式还可以随时更新，从而确保结构文档与实现代码保持同步。
三种成熟度等级
业界已确定了 SDD 的三种等级。这些等级并非所有团队都必须按顺序遵循的阶梯，而是针对不同场景设计的不同权衡方案；在开始应用之前，首先要明确哪种等级适合自身的情况。
第一级：以规范为先。为某项任务编写详尽的规范。一旦实现完成并经过验证，该规范即被视为可丢弃的文件：可保留以供参考，但无需继续维护。它适用于独立的特性、一次性迁移以及那些无需第二级维护的实验场景。支持者认为，这一层级仅需少量成本即可实现SDD约60%的价值，因此是新手较为合理的起点。适用于那些有明确验收标准、无跨服务依赖、交付周期以天计的有限新特性。
第二级：以规范为依据（推荐默认设置）。在整个项目生命周期中，规范与代码处于平等地位，两者都会被持续维护。当需求发生变化时，首先修改规范；当实现方式出现偏差时，会立即更新规范以记录实际行为及背后的原因。这看似需要双重维护，但实际上能降低总体成本：它可避免不同阶段之间的上下文丢失，帮助新成员（无论是人类还是人工智能）顺利上手，还能让后续由人工智能辅助进行的修改更加可靠。这是生产系统、团队项目以及任何需要持续发展的项目的基准做法。
3级，以规范为源码（实验性）。规范是唯一的原始文档。代码被视为编译后的输出，按需重新生成，从不手动编辑。这是SDD的理论终极形态，由工程师负责维护规范，由AI负责实现代码。该模式存在一个尚未解决的问题——确定性。相同的规范在不同运行中可能会生成语法上不同但功能上等价的代码，这使得差异对比、调试和审查变得极为困难。请将其视为实验性方案。它可能适用于那些规范极为完善、AI治理机制健全且能够容忍不成熟工具的新项目，但截至2026年，不建议用于关键的生产系统。
按角色划分的操作指南
工程师与架构师
工程师的核心技能转向了上下文工程。编写正确的语法是智能体能够以机器速度完成的任务，因此工程师的价值在于界定精确的架构上下文，筛选智能体可查看的内容，并确保其输出符合系统的结构意图。这包括编写优质的AGENTS.md和SPEC.md文件，设定库管理规则（明确列出允许和禁止的依赖项），以机器可读的形式说明安全与合规要求，以及合理规划任务结构以区分不同关注点。
工程师的入门流程如下：
- 在开发任何基于人工智能的功能之前，创建或更新SPEC.md文件，确保其中包含前文所述的六个要素。
- 审查AGENTS.md文件，确认构建命令、测试模式、命名规则以及严重程度分级依然符合实际情况。
约束条件模块是任何需求规格中都很有用的模板，其中会列出技术栈（所有必需的技术）、禁止使用的库（需明确写出）、安全要求（用户如何认证、期望采用何种加密方式、数据如何处理）、性能限制（目标延迟和吞吐量）、测试要求（测试覆盖率阈值及所需测试类型），以及架构模式（必须采用的架构与应避免的架构）。
技术产品经理
从产品需求文档到行为描述文档。传统的产品需求文档假定会有人类工程师来阅读、讨论并凭借自身判断来实施这些需求。而在SDD模式下，产品任务管理器的输出必须是行为描述文档：一种机器可读的说明，详细阐述产品应如何响应特定的用户需求，同时明确智能体执行时的精确要求。
两者的区别不仅仅在于风格。产品需求文档可能只写“改善结账体验”。而行为描述文档则必须说明当前的结账流程是怎样的、它引发了哪些用户痛点、哪些行为变化才算得上改进、如何衡量成功、必须处理哪些边缘情况，以及系统绝不能做什么。
原型循环。SDD使TPM能够缩短从设计到工程实现的常规流程。无需等待设计师制作出原型再由工程师进行开发，TPM可以直接根据行为描述生成交互式原型，并通过实际运行效果而非静态界面来评估功能表现。如果原型未能符合预期，相关规格会立即更新，系统会重新生成实现代码，如此一来反馈循环便基于规格而非代码展开。这省去了多个可能导致需求偏差的环节（如PRD制定、设计交接、工程交接）。
首席技术官与工程团队负责人
治理机制。在以智能体为核心的组织中，CTO的首要任务是建立一套治理框架，让人工智能在提升交付效率的同时，不损害质量、安全或合规性。SDD提供了控制层，但前提是必须具备严格的组织纪律。在大规模应用中，有三项机制至关重要：
- 规格版本的管控。SPEC.md、PLAN.md和AGENTS.md与代码存储在同一个代码库中，并需经过相同的审核与批准流程。
- 审计追踪。每一个由人工智能生成的变更都应能追溯到具体的规格要求，在受监管的行业里这并非可选项。
- 各阶段转换时的人为审核。从规划到实施，任何内容都必须在每一步都获得批准后才能自动推进。
首席技术官也应依据该框架来评估人工智能编程工具，考察它们在支持持久化规则文件、审查机制、可追溯性以及多智能体工作流方面的表现。
衡量回报。采用SDD的组织常常反馈，在最初的二到四周内开发进度似乎会变慢，因为工程师们将时间花在需求规格制定上，而非直接编写代码。这一观察是正确的，但其解读具有误导性。需求规格制定并非新的额外工作，它原本就是以非正式、不一致的方式在实现之后才进行的，而那时成本已最高。真正反映回报的指标体现在后续环节：
- 从需求提出到生成可投入生产的代码所需的时间，即经过验证、审查并部署的代码，而不仅仅是写出来的代码。
- 返工比例，即因需求理解有误而需要重新开发的已完成功能所占的比例；
- 上下文恢复时间，指开发人员或客服在30天未接触过代码后重新开始高效工作所需的时间；
- 缺陷漏检率，即在需求评审阶段发现的缺陷与部署后发现的缺陷之间的比例。
据称，那些拥有成熟SDD实践的团队，其返工比例可降低40-60%，上下文恢复时间也能大幅缩短，因为规范文档提供了原本需要数小时通过代码分析才能获得的上下文信息。这些数据来自实际从业者的报告，并非经过控制的科学研究，因此请自行测量基准值。
意图偏移
什么是意图偏移
意图偏移指的是企业的初始需求与实际生产环境中的代码行为之间逐渐产生的差距。这种现象在人工智能辅助工作中并非新鲜事，也是软件工程中最古老的问题之一，但编码智能体却加剧了这一趋势。它们追求代码的合理性与测试通过率，而非与业务目标的契合度。如果让这类智能体负责开发支付处理功能，它编写的代码虽然能通过所有测试并覆盖所有指定场景。但如果需求规格不完整或过时，智能体就会利用训练数据中统计上最可能的默认值来填补空白。这些默认值对通用系统或许没问题，但对于特定企业的业务规则却可能带来灾难性后果。最糟糕的偏移情况是，直到给客户带来损失、引发合规审计或生产事故时才被发现，因为智能体非常擅长编写表面上看似正确但实际上存在细微偏差的代码。
防御机制
- 动态规范。首要的防御手段是随着决策的制定而实时更新的规范。任何对SPEC.md的偏离，无论多么微小或理由多么充分，都会立即被记录下来，因此该文件始终描述的是当前的实际行为，而非最初的设计意图。
- 对抗性验证。验证机制同时具备偏差检测功能。在每个任务中都将输出结果与规范进行比对，从而在偏差积累到多个实现周期之后之前，以最精细的粒度捕捉到偏差。
- 规范覆盖率跟踪。更高级的方案会追踪那些已有自动化、可验证测试的需求所占的比例。没有测试的需求可能会在未被察觉的情况下出现偏差，而致力于实现全面覆盖则是将测试驱动开发理念应用到需求层面。
最简版的AGENTS.md
可用于实际项目的 AGENTS.md 文件可以很简短。至少应包含一段关于项目的描述、构建、测试和代码检查的具体命令、命名与目录结构的规范、“必须”“建议先询问”以及“绝不可”事项的列表、对 SPEC.md 和 PLAN.md 的引用，以及代码库管理规则。需根据所使用的技术栈及组织要求调整各部分内容。
这会为你带来什么
基于规范的开发并非一时潮流，也不是对现有习惯的微小改进。它改变了工程工作的本质。借助编程智能体，交付过程中的瓶颈不再是语法生成的速度，而是需求定义的精确度。规范本身就是产品，代码则是实现它的手段，在基于智能体的软件开发中，规范是工程师最重要的交付物。
相关阅读
- 实用笔记：我在本地运行 AI 编码代理，效率几乎提升一倍 — 详细指导如何应用该实用笔记：包括合同条款、检查清单以及供采用此模式的团队直接使用的代码模板。
- 分层式代理工程：从需求规格与并行代理到规则设定与监督机制 — Karpathy 指出了开发方式从传统编码模式向代理模式转变的趋势。本文介绍了代理工程的五层结构：需求规格、任务协调、编码规则、人工审核与可观测性，同时还提供了为期一周的实施计划。