Spec‑Driven Development 工作流：从需求到代码实现

需求写得像一句口号，AI Coding Agent 却直接开始改仓库，最后没人能判断它到底完成了什么。

最快解法：采用双轨工作流——规格轨管理需求、约束和验收标准，代码轨按可验证任务产生变更；两条轨道通过版本、任务编号和测试结果关联，不让 Agent 从一句需求直接生成整套代码。

这篇文章适合准备在真实仓库引入 Spec‑Driven Development 的团队，也适合需要多人审查 AI 生成代码的研发负责人。如果你希望让远程 Coding Agent 长时间执行任务，同时保留过程记录、失败恢复和审查入口，下面的交接条件比单纯学习几个提示词更重要。

先建立规格轨与代码轨

Spec‑Driven Development 工作流最容易被误解成“先写一份文档，再让 AI 照着写代码”。在团队环境中，更可靠的做法是把研发过程拆成两条互相校验的轨道。

规格轨回答：

• 为什么做这个功能；
• 哪些用户行为必须支持；
• 哪些异常必须处理；
• 哪些范围明确不做；
• 什么结果可以判定为完成。

代码轨回答：

• 哪些仓库文件需要变化；
• 依赖、接口和数据迁移如何调整；
• 每个任务由谁或哪个 Agent 执行；
• 用什么命令验证；
• 当前变更是否可以合并。

这两条轨道不能只靠口头同步。你至少需要让 Specification、技术计划、任务文件、代码提交和测试结果共享一个需求编号或特性编号。这样，审查者才能从代码差异反查规格，也能从规格确认测试是否覆盖了真正的业务行为。

当前公开的 Spec Kit 流程已经把 specify、plan、tasks 和 implement 分成独立阶段，并提供 clarify、analyze 等质量检查步骤。官方流程说明 (github.github.com)

需求评审：先把模糊目标变成可判定边界

需求评审不是让产品负责人把背景讲得更长，而是判断这项需求是否已经具备进入 Specification 的条件。

以“增加团队邀请功能”为例，不能直接交给 Agent。你需要先补齐：

• 目标用户：团队管理员、普通成员，还是外部协作者；
• 核心行为：邀请、接受、拒绝、重复邀请分别如何表现；
• 权限边界：谁可以发起邀请，谁可以查看邀请状态；
• 异常路径：邮箱已存在、邀请过期、用户没有权限时怎么办；
• 明确不做：本次是否不处理批量邀请、邮件模板编辑或跨组织邀请；
• 验收结果：什么状态、接口响应或页面行为能够证明需求完成。

需求进入规格阶段前，必须先完成一次“可判定性检查”。如果团队只能说“希望体验更好”或“后续再看异常情况”，说明目标仍然缺少边界，Agent 不应继续向下执行。

一个适合团队协作的需求条目可以包含：

• REQ-021：管理员可邀请尚未加入组织的用户；
• 前置条件：管理员已登录，且拥有成员管理权限；
• 正常行为：提交有效地址后生成待接受邀请；
• 异常行为：重复邀请时返回已有邀请状态；
• 不做范围：本任务不修改邮件模板系统；
• 验收方式：接口测试、权限测试和页面状态检查。

⚠️ 经验提醒：如果评审者无法用“通过”或“不通过”回答验收条件，需求就还没有准备好进入 Specification。过早进入下一阶段，通常只会把争议转移到代码审查时。

Specification 与技术设计分别解决什么问题

Specification 是业务行为与验收标准的单一事实来源，但它不是技术设计文档。

你可以这样区分：

✅ Specification 负责“应该发生什么”

• 用户执行某个动作后看到什么；
• 数据必须满足哪些约束；
• 接口在不同条件下返回什么；
• 错误、权限和边界情况如何处理；
• 哪些内容属于明确排除范围。

✅ 技术设计负责“准备怎么实现”

• 复用哪个现有组件；
• 是否新增服务、表或接口；
• 哪些模块会受到影响；
• 是否需要迁移旧数据；
• 使用哪些测试层级验证；
• 如何兼容现有部署和回滚方式。

在规格文件中，最好把内容明确分成三类：

1. 业务事实：已经确认的用户行为和规则；
2. 技术约束：必须兼容的接口、运行环境或安全要求；
3. 待确认项：尚未决定、不能由 Agent 自行拍板的内容。

这样做的价值在于，Agent 不会把“建议使用某种组件”误读成强制要求，也不会把未确认事项悄悄写进实现范围。

公开的 Spec Kit 文档把 Specification 聚焦于要构建的行为，把 Plan 用于技术栈和架构选择。你可以据此建立团队内部的文档边界，但具体命令、目录结构和集成能力仍应以当前版本文档为准。规格与计划命令说明 (github.com)

仓库准备：在写代码前锁定影响范围

把工具安装到仓库里，不等于已经完成接入。真正需要准备的是一个能够被团队共同阅读、审查和恢复的工作区。

在现有 Git 仓库中，建议按以下步骤落地：

第 1 步：建立项目级原则。 记录代码质量、测试要求、兼容性、安全边界和审查规则。项目原则不应写成口号，而应能影响后续技术选择，例如“涉及权限的变更必须包含拒绝路径测试”。

第 2 步：为特性建立独立目录。 目录名可以按需求编号或特性名称组织，重点是让 spec.md、plan.md、tasks.md 和验证产物能够被一起追踪。具体目录名和 CLI 行为应以你当前安装版本的官方文档为准，不要照搬旧教程。

第 3 步：执行仓库侦察。 让 Agent 先只读检查入口、模块边界、测试命令、配置文件、数据库迁移方式和 CI 流程。此阶段禁止修改代码，否则后续技术计划会建立在不可追溯的隐性变更上。

第 4 步：生成影响清单。 技术计划至少需要说明组件影响、依赖变化、接口调整、数据迁移、测试策略和回滚方式。若 Agent 无法指出具体影响文件或原因，计划还不具备拆分任务的条件。

第 5 步：设置人工批准点。 涉及公共接口、认证授权、数据迁移、基础设施或跨模块重构时，先由人工批准技术计划，再生成执行任务。低风险的局部改动可以快速推进，但高风险变更不应让 Agent 自行决定架构。

公开文档还特别强调，现有项目在演进规格时，规格、计划、任务和实现都可能成为变更起点；关键是判断变化影响的是产品行为、实现策略、任务拆分，还是仅仅代码缺陷。现有项目规格演进指南 (github.github.com)

Agent 执行：把长任务改造成可恢复的小批量变更

AI Coding Agent 每次执行的任务，不应按“做一个大功能”描述，而应绑定 4 类信息：

• 对应的规格条目；
• 允许修改的目标文件或模块；
• 必须执行的验证命令；
• 完成后必须满足的退出条件。

例如，不要写“完成团队邀请功能”，而要拆成：

• 为邀请记录增加状态字段，并完成迁移测试；
• 实现创建邀请接口，覆盖权限和重复邀请；
• 增加接受邀请流程，验证过期状态；
• 补齐页面状态展示和错误提示；
• 运行接口、权限和回归测试。

每个任务都应该产生一个可审查的结果。如果任务横跨多个模块，既要改数据层，又要改接口层，还要更新页面，但中间没有任何可验证节点，就应该继续拆分。

远程执行时，还要为长任务设置检查点。一个有效的检查点至少保存：

• 当前任务编号；
• 已修改文件；
• 已执行命令及结果；
• 未完成事项；
• 下一步允许执行的范围；
• 最近一次可恢复的提交或快照。

如果任务失败，Agent 应从最近一次验证通过的检查点继续，而不是重新扫描整个仓库，更不能在已有失败变更上继续堆叠。

公开参考实现中的 /speckit.tasks 用于从技术计划生成可执行任务，/speckit.implement 则根据任务清单执行实现；实施阶段还会检查前置产物是否存在，并依据任务依赖推进。核心命令参考 (github.github.com)

决策条件：你的团队应该采用哪种执行粒度

• 若任务能绑定单一行为、明确文件范围和验证命令，就可以交给 Agent 执行。
• 若任务只有功能目标，没有退出条件，先回到 Specification 或技术计划。
• 若任务涉及公共接口、权限、迁移或跨服务依赖，先人工批准计划，再拆分执行。
• 若任务失败后无法判断哪些变更可信，说明缺少检查点，应先补齐提交、日志和测试产物。
• 若远程 Agent 需要长时间运行但团队无法实时跟进，必须启用仓库隔离、日志留存和可恢复快照，否则不适合无人值守执行。

代码审查：同时审实现质量与规格一致性

传统代码审查通常关注命名、复杂度、测试和安全问题。在 Spec‑Driven Development 工作流中，还要增加一条检查线：代码是否准确实现了 Specification，而不是擅自扩大或缩小范围。

审查者可以按以下顺序检查：

先看差异摘要。 Agent 应说明改了哪些文件、对应哪些需求编号、为什么需要这些变化。无法解释的新增文件或依赖，应先暂停合并。

再看正常与异常路径。 不要只验证主流程。权限拒绝、重复提交、空数据、超时、旧数据兼容和回滚路径，往往才是规格遗漏最容易暴露的位置。

然后核对范围。 如果规格明确“不修改邮件模板”，但代码同时重构了通知系统，就属于范围扩大；如果规格要求记录审计事件，而代码只返回成功状态，则属于范围缺失。

最后检查验证产物。 Agent 输出至少应包含差异摘要、执行过的测试命令、测试结果和未解决项。测试失败不能用“后续再处理”替代，必须进入新的任务或获得明确的人工豁免。

公开的 Agentic SDD 参考流程也建议在任务生成后执行跨产物一致性分析；发现问题时，应回到拥有该问题的阶段修复，而不是直接在实现阶段绕过。一致性分析与恢复说明 (github.github.com)

接入 Git：让规格、提交与合并请求互相可追踪

接入现有 Git 流程时，不建议把 Specification 放在团队聊天记录或个人笔记中。它们应该进入与代码相同的版本管理体系，并通过需求编号与提交、分支和合并请求建立关系。

一种可执行的约定是：

• 分支名称包含特性编号；
• spec.md、plan.md 和 tasks.md 与特性一起提交；
• 提交信息引用需求或任务编号；
• 合并请求描述列出规格覆盖范围和测试结果；
• CI 检查规格文件是否存在、任务是否标记完成、关键验证命令是否通过；
• 合并前由人工确认代码、规格、任务和测试属于同一版本。

这里的重点不是增加文档数量，而是减少“代码已经变了，规格还停留在旧状态”的情况。上线后如果发现缺陷改变了既定行为，应先更新 Specification，再生成修复任务；如果只是实现错误而业务规则没有变化，则保留规格不动，并在任务中记录修复依据。

你还可以在 kvmboot 帮助中心 查看远程开发环境相关的基础操作说明；如果团队需要确认具体交付方式，可通过 kvmboot 联系页面 提前核对接入条件。

持续交付：规格必须随着代码一起演进

双轨流程不是“一次性写完规格后永久冻结”。产品需求、接口约束和运行环境都会变化，真正稳定的做法是让规格成为可演进的工程资产。

每次合并前，你都应该确认：

• 规格是否仍然描述当前产品行为；
• 技术计划是否仍然匹配仓库结构；
• 任务是否全部完成或明确关闭；
• 测试是否覆盖新增和变更后的异常路径；
• 代码版本与审查记录是否能够互相对应。

上线后的变化可以按三类处理：

✅ 行为变化：先更新 Specification，再创建实施任务。 ✅ 实现策略变化：更新技术计划，并重新检查任务依赖。 ✅ 单纯代码缺陷：保留原规格，新增修复任务和回归测试。

对于需要远程 Coding Agent 长时间执行的团队，仓库隔离、日志保留、快照恢复和安全审查入口应当被视为交付环境的一部分，而不是 Agent 工具之外的附加项。你可以先通过 kvmboot 关于远程环境的说明 了解服务定位，再判断现有方案是否满足团队的执行与审查要求。

常见问题

怎样把一条模糊需求整理成可执行规格？ 先拆出目标用户、核心行为、边界、异常和验收标准，再为每条需求建立编号。技术方案和待确认事项单独记录，不能让 Agent 用猜测填补空白。

业务规格与技术设计应当怎样分工？ 规格描述系统应该表现出什么行为，技术设计描述准备如何实现。前者决定验收标准，后者决定组件、接口、迁移和测试方案。

远程 Agent 的单次任务应当控制到什么范围？ 任务应小到可以绑定规格、目标文件、验证命令和退出条件，同时大到能形成一个完整、可审查的变更。无法独立验证的长任务应继续拆分。

怎样把这套方法接入已有 Git 仓库？ 把规格、计划和任务纳入版本管理，并用统一编号关联分支、提交、合并请求和测试结果。上线后的行为变化先回写规格，再生成新的实现任务。

如果你现在的流程是“本地机器临时运行、聊天窗口传递上下文、失败后人工猜测状态”，它通常会遇到环境不一致、日志不完整、权限边界模糊和无法恢复 4 个问题；直接使用普通云主机也可能缺少稳定的 Mac 工具链、图形化审查入口或团队熟悉的远程接入方式。对于需要临时算力、长时间 AI Coding Agent 执行和多人复核的场景，租赁 kvmboot 的 Mac 环境更适合先做隔离测试与流程验证；但如果你需要长期满负载运行，或必须连接特定物理设备，自购设备仍可能更合理。