Spec‑Driven Development：AI Coding Agent 开发指南

Spec‑Driven Development 的获胜者方案，是把需求依次变成项目约束、可判定的 Specification、可独立执行的任务和验收证据；只有在不可变边界明确、规格进入版本控制的条件下，AI Coding Agent 才适合持续修改真实项目。

这篇指南适合 3 类人：经常需要反复纠正 AI Coding Agent 的个人开发者；准备把 AI 编程引入团队流程的技术负责人；以及需要为 Agent 生成代码建立审计和验收依据的工程团队。

第 1 步：先固定项目约束，再让 Agent 接触需求

很多返工并不是 Agent 不会写代码，而是项目规则没有被固定下来。每次对话只补充一句“这里要遵循旧目录”“这个接口不能动”，规则很快会被上下文覆盖，后续任务又会重复犯同样的错误。

在开始 Spec‑Driven Development 之前，项目根目录应先形成一份稳定的约束文件，至少说明以下内容：

• 技术栈与运行方式，例如前端、后端、数据库、构建工具和测试入口；
• 目录职责，哪些目录存放业务代码、测试、脚本和生成文件；
• 命名、格式化、错误处理和日志要求；
• 安全边界，包括密钥、用户权限、外部接口和敏感数据处理；
• 禁止修改区域，例如数据库迁移历史、公共接口、部署配置或已有兼容层；
• 完成定义，包括必须通过的测试、静态检查、接口验证和人工检查。

如果采用 Spec Kit 这类工作流，项目原则通常先通过 constitution 阶段建立，并作为后续规格、设计和实现阶段的共同依据。官方工作流把这类原则定位为项目级指导规则，而不是某个单独任务的临时提示。项目约束与 constitution 说明

Spec‑Driven Development 应该从哪里切入？

可以从一个很小的功能开始，而不是一开始改造整个代码库。先选择一个边界清楚、可以独立测试的功能，记录“允许改什么、禁止改什么、完成后如何验证”，再让 Agent 生成第一版 Specification。若项目规则尚未稳定，应先整理约束，不要直接进入代码实现。

建议先完成这份检查清单：

• [ ] 已写明本地启动、构建和测试命令；
• [ ] 已列出不可修改的接口、目录或配置；
• [ ] 已说明权限、输入校验和敏感数据处理边界；
• [ ] 已定义成功条件，而不是只写“体验更好”；
• [ ] 已将约束文件提交到版本控制；
• [ ] 已确认后续任务都能引用同一份约束，而不是依赖聊天记录。

这里的隐性成本主要有 3 个。第一，规则没有版本化时，团队无法判断某次生成代码到底违反了哪一条约束。第二，权限与安全边界不清楚时，Agent 可能为了让测试通过而扩大接口权限。第三，禁止修改区域没有声明时，局部修复可能破坏历史兼容逻辑。

第 2 步：把自然语言需求改写成可判定的 Specification

Specification 不是“把 Prompt 写长”，而是把目标转化为能够被测试、检查或人工确认的行为描述。

一条合格的规格至少应回答：

1. 谁发起操作；
2. 在什么前置条件下操作；
3. 输入是什么；
4. 系统应产生什么输出或状态变化；
5. 失败、超时、重复提交和权限不足时如何处理；
6. 哪些非功能要求属于必须满足的边界；
7. 如何证明这条规格已经完成。

例如，“增加一个文件导入功能”无法直接驱动可靠实现。更适合执行的写法是：

已登录用户提交允许类型的文件后，系统创建一条待处理记录；重复提交同一文件时不得产生重复业务记录；文件类型不符合规则时返回可识别错误；没有权限的用户不能访问导入接口；成功与失败都必须写入可追踪日志。

这段 Specification 没有虚构性能数字，却已经包含了行为、异常、权限和验收方向。随后可以将每条要求映射到单元测试、接口测试、静态检查或人工操作步骤。

规格需要具体到什么层级，Agent 才不会自行猜测关键行为？

写到 Agent 不需要自行猜测关键决策，但仍然保留合理实现空间。规格应明确业务行为和不可变边界，却不必提前规定每一个函数名、循环写法或组件内部结构。

可以用“必须明确”和“可以留给 Agent”来区分：

• 必须明确：用户流程、输入输出、异常行为、权限边界、兼容要求和验收方式；
• 可以留给 Agent：内部函数拆分、局部变量命名、非关键依赖选择和重复代码消除方式；
• 不应含糊：如“高性能”“友好”“适配所有情况”等无法直接验收的表达；
• 不应越界：规格阶段不要把尚未确认的技术方案伪装成业务事实。

规格最好拆成用户场景、功能要求、异常要求和验收场景 4 个层次。这样做的价值在于，后续发现问题时，可以定位是需求不完整、设计不合理，还是实现没有满足规格，而不是继续追加一段临时提示。

第 3 步：让 Agent 先产出设计，再生成任务

需求规格确认后，不应立即要求 Agent “开始写全部代码”。更稳妥的时间线是先生成设计方案，再拆分任务。

设计阶段应要求 Agent 输出：

• 受影响的模块与文件；
• 数据流和调用链；
• 接口、数据结构或状态变化；
• 依赖变化及其风险；
• 测试策略；
• 不修改的区域；
• 仍然存在的不确定项。

如果方案中出现与项目约束冲突的内容，应在设计阶段退回，而不是等代码已经生成后再修补。官方流程将规格、计划、任务和实现作为相互衔接的产物；其中任务列表由设计方案进一步拆分，目的不是增加文档，而是让实现具备依赖顺序和可检查边界。官方快速开始流程

怎样把一份规格拆成 Agent 能独立完成的任务？

任务拆分应遵循“单一结果、有限范围、可独立验证”三个条件。一个任务最好只完成一种明确变化，例如新增数据模型、实现接口校验、补充异常测试，而不是同时改数据库、后端、前端和部署脚本。

可以按以下顺序拆分：

• 先处理数据结构和接口契约；
• 再实现核心业务逻辑；
• 然后补充错误处理和权限校验；
• 接着加入自动化测试；
• 最后处理界面、文档和集成验证。

每个任务都应包含 5 项信息：任务目的、涉及范围、依赖任务、修改限制、验证命令或验收动作。任务完成后，Agent 需要返回实际修改文件、关键差异、测试结果以及未解决问题。

对于跨模块的大功能，可以采用“规格中的规格”方式，将整体目标拆成多个独立子功能；每个子功能分别拥有自己的规格、设计和任务，避免一次实现让 Agent 在长上下文中丢失边界。大型功能拆分说明

第 4 步：按任务执行代码，并设置人工停点

代码执行阶段的关键不是让 Agent 一次完成更多内容，而是控制每轮上下文范围。

每轮输入只保留当前任务所需的 4 类材料：

• 当前任务及其验收条件；
• 相关 Specification 片段；
• 需要阅读的代码文件；
• 明确的测试或验证命令。

在修改前，要求 Agent 先陈述实现计划，并指出可能触碰的边界；如果它发现规格之间存在冲突，应先暂停并报告，不应自行选择一个未确认的解释。

在修改后，至少检查以下内容：

• 实际改动是否仅落在任务范围内；
• 是否新增了未批准的依赖；
• 是否覆盖了成功、失败、重复和权限场景；
• 测试是否验证原始规格，而不只是验证代码能运行；
• 是否留下临时日志、调试代码或未处理的异常。

官方流程中的 implement 会依据任务清单按依赖顺序执行；对于较大的功能，也可以按阶段运行，而不是一次执行全部任务。实现阶段说明

⚠️ 经验提醒：如果 Agent 连续两轮都在“修复上一次修复造成的问题”，通常不应继续增加提示词。应回到原始 Specification，检查需求、设计和任务之间是否已经出现冲突。

第 5 步：把验收证据映射回规格

验收不能只看“测试通过”或“页面能打开”。每条关键规格都应有对应证据：

• 行为要求对应自动化测试或可复现操作；
• 输入输出要求对应接口示例或断言；
• 权限要求对应不同角色的访问结果；
• 异常要求对应错误码、提示信息和日志；
• 非功能要求对应静态检查、构建检查或人工审查；
• 禁止修改区域对应差异检查。

当某项验收失败时，先判断问题属于哪一层：

• 规格不完整：回到 Specification 补充行为或边界；
• 设计不合理：回到计划阶段重新评估依赖和模块影响；
• 任务拆分错误：拆小任务，补充缺失的前置条件；
• 实现错误：只回退到对应任务，不要让 Agent 对整个项目重新生成。

这一步能减少验收争议，因为团队讨论的不是“这段代码看起来对不对”，而是“它是否满足第几条规格，以及证据在哪里”。

可以使用如下验收清单：

• [ ] 每条关键 Specification 都有测试、检查或人工验收证据；
• [ ] 成功路径与失败路径都已验证；
• [ ] 权限、重复提交和边界输入已覆盖；
• [ ] 代码差异没有超出任务声明的范围；
• [ ] 构建、静态检查和测试结果已记录；
• [ ] 未通过项已关联到具体规格或任务；
• [ ] 未使用临时 Prompt 掩盖规格层面的缺陷。

第 6 步：让规格、实现和测试一起版本化

规格变更是 AI 编程项目最容易失控的阶段。常见错误是直接对 Agent 说“顺便把新需求改进去”，却不更新原规格、任务列表和测试，最终形成代码已经变化、文档仍停留在旧状态的分叉。

更可靠的变更流程是：

1. 先修改 Specification，并标记变更原因；
2. 列出受影响的接口、数据、权限和测试；
3. 重新检查设计方案与项目约束；
4. 更新任务列表，明确新增、删除和废弃任务；
5. 让 Agent 只实现变更后的任务；
6. 重新执行验收，并保留变更前后的差异。

如果使用相关工具链，可在实现前运行一致性分析，检查 spec.md、plan.md 和 tasks.md 之间的冲突、缺口与歧义；这类分析的价值是尽早发现源文件问题，而不是等实现完成后才依靠人工猜测。一致性分析命令说明

规格版本化还应配合可重置的运行环境。AI Coding Agent 可能修改依赖、生成缓存或改变本地状态，因此团队需要准备固定的启动命令、测试数据、环境变量模板和清理步骤。若开发环境无法快速恢复，失败任务就很难区分是代码问题、环境污染还是数据残留。

对于需要反复运行测试的项目，远程 Mac 自动化测试环境可以作为隔离执行节点，尤其适合涉及 Apple 平台构建、真机相关工具或多人共享测试环境的团队；但环境租赁不能替代规格、测试和版本控制本身。关于远程开发环境的准备，可以先参考 Zutcloud 帮助中心，再根据项目是否需要持续运行和多人协作决定部署方式。

当前开发环境与 Mac 方案的取舍

如果当前方案是开发者本地临时运行，常见缺点是环境差异难以复现、测试节点被个人工作占用，而且 Agent 修改失败后不容易恢复到干净状态；如果改用普通云主机，又可能遇到 Apple 平台工具链不可用、图形化调试不完整或远程交互体验不稳定的问题。

当任务涉及 Apple 平台构建、远程自动化测试、短期并行验证，或团队需要一个可重置的独立节点时，租赁 Zutcloud 的 Mac 环境通常比反复改造现有机器更直接。若项目是长期稳定的高负载开发、必须连接特定物理设备，或者已有成熟本地机房运维能力，自购设备仍可能更合适；若只是临时算力、测试环境或阶段性协作，则应优先比较 Mac mini 租用方案 与当前环境的恢复速度、权限管理和使用周期，而不是只看单次价格。

真正值得迁移到 Mac 环境的，不是“让 Agent 写得更多”，而是让规格、任务、测试和代码拥有一个能够重复执行、容易回退的运行位置。