应用 SDD 研发模式：让需求、AI 实现和交付结果保持一致

日期：2026-10-29 · 主题：AI Coding、软件工程、团队协作

一个团队让 AI Coding Agent 为项目增加任务筛选功能。几分钟后，Agent 修改了前端、添加了接口参数，测试通过，页面也能打开。

但上线后，用户发现筛选只作用于当前页面的二十条数据，而不是整个任务列表。更换筛选条件时，分页没有重置；浏览器后退时，筛选状态也没有恢复。

代码完成了，需求却没有真正完成。

这不是 AI 独有的问题。人类开发者在面对模糊需求时也会做出不同假设。AI 的特殊之处在于：它可以非常快地把未被发现的假设变成大量代码。实现越快，团队越需要明确自己究竟要交付什么。

SDD，即 Spec-Driven Development，通常译为规格驱动开发，是一种把需求、约束和验收条件明确表达出来，并用它们持续指导实现与验证的研发方式。它并不要求所有任务都经过同一套繁琐流程。它要解决的问题是：当人和 Agent 持续做决策时，如何让实现与真实意图保持一致。

本文通过一个具体功能展示从需求到验证的全过程。示例中的项目、接口和数据均为虚构教学案例，不代表已有系统的真实实现或测量结果。

一、规格到底是什么？

规格（Spec）是对系统预期行为的可检查描述。它应当回答：

• 谁遇到了什么问题？
• 用户要完成什么事？
• 系统在不同条件下应该怎样表现？
• 什么不属于这次需求？
• 哪些边界和约束必须满足？
• 如何判断完成？

一个有用的规格不一定很长。对于按钮文案调整，一条带目标文件和验收条件的任务描述就可能足够；对于支付、数据迁移或跨系统功能，则可能需要状态图、接口契约和故障处理方案。

GitHub 的 Spec Kit 将规格、计划、任务拆解和实现组织为一套流程；其当前文档还提供实现后的收敛检查。它是 SDD 的一种工具实现，不是采用 SDD 的唯一方式。GitHub Spec Kit

需求、规格、计划和测试有什么不同？

它们相互关联，但不应混为一谈。技术方案可能改变，用户想完成的目标不一定改变；测试通过，只能说明测试覆盖的条件成立，不自动证明产品满足需求。

二、SDD 与 AI Coding 为什么天然契合？

传统开发中，许多信息隐藏在团队默契里。长期参与项目的工程师知道“列表筛选”通常意味着什么，知道哪些 URL 参数需要保留，也知道历史上的某些边界条件。

Agent 没有天然继承这些默契。它只能根据任务描述、仓库、工具结果和可获取的上下文推断。缺失信息时，它可能选一个看似合理的答案继续实现。

规格的价值，是把最重要的隐含前提变成共享、可检查的上下文：

模糊目标
  ↓
预期行为与边界
  ↓
技术方案和可交付任务
  ↓
实现
  ↓
用证据检查预期与实际是否一致
  ↓
根据发现修订规格或实现

人负责决定真实需求、权衡成本与风险，并对结果承担责任。Agent 可以帮助发现歧义、起草方案、实现代码、编写检查和解释结果；它的产物仍然需要与项目事实、用户目标及实际运行情况核对。

规格不是冻结未来的合同。开发中发现原需求不可行或用户需要发生变化，团队可以修改规格。但修改要被明确记录，不能因为当前代码已经这样写，就悄悄把规格改成一样，假装从一开始就符合需求。

三、完整案例：为团队任务看板增加状态筛选

假设产品经理提出：

给任务看板加一个状态筛选，用户可以查看未开始、进行中和已完成的任务。

这句话足以表达意图，却不足以指导可靠实现。

1. 先把问题和范围说清楚

# 任务状态筛选

## 问题
用户的任务列表较长，很难快速查看特定状态的任务。

## 目标
让用户按状态查看自己有权限访问的任务。

## 范围
- 支持全部、未开始、进行中、已完成。
- 筛选作用于服务端可访问任务集合。
- 与现有分页和排序共同使用。
- 筛选状态反映在 URL 中，支持刷新与浏览器前进、后退。

## 不在本次范围
- 不新增任务状态。
- 不改变已有权限模型。
- 不提供跨团队的管理报表。

这里最关键的一句是“筛选作用于服务端可访问任务集合”。如果缺少它，Agent 对当前页数据做前端过滤也可能看起来合理。

2. 把验收标准写成可观察行为

AC-1
给定用户有 45 条可访问任务，其中 8 条进行中，
当用户选择“进行中”，
列表只展示符合该状态的任务，分页总数为 8。

AC-2
给定用户当前位于第 3 页，
当用户切换状态，
页码重置为第 1 页。

AC-3
给定用户选择“已完成”，
当用户刷新或通过浏览器历史返回，
筛选状态与 URL 一致。

AC-4
当没有匹配任务时，展示空状态；
请求失败时展示错误和重试入口，不把错误误报为空列表。

AC-5
用户只能查看已有权限允许的任务，
筛选参数不能扩大访问范围。

这些数字是示例数据，不是性能基准。标准描述的是用户能观察到的结果，而不是要求必须用某个组件名或数据库表名。

3. 显式记录不确定性

规格不是把不知道的事情猜出来。对于尚未决定的问题，应记录并解决：

待确认：URL 是否允许多选状态？
待确认：用户分享 URL 后，接收者是否只看到自己的可访问结果？
待确认：现有默认排序是什么？

其中第二项涉及权限和数据边界，应查现有系统并与负责人确认。若某项可以从现有约定可靠推断，就应记录依据并继续；不要把每一个普通工程选择都变成审批。

4. 将规格转换成技术计划

1. 检查现有任务 API、权限约束和分页方式。
2. 在现有列表查询中增加状态参数，保持原权限过滤。
3. 前端读写 URL 参数，并在状态变化时重置页码。
4. 保持已有排序，处理加载、空结果和错误状态。
5. 验证筛选、分页、权限及浏览器历史行为。

计划应基于现有代码，而不是凭空假设项目有某个框架或数据库。索引是否需要新增，也应先看查询计划和实际数据规模，而不是因为“生产级系统”就提前建一组索引。

5. 拆成可验证任务

任务可以由人或 Agent 执行，关键是每项都能清楚地对应预期和验证。

四、AI 可以写规格，人仍要审核假设

一个实用的提示词可以这样写：

请阅读这个仓库的相关代码与项目约定，为“任务状态筛选”起草规格。

先分析现有列表、分页、排序、权限和 URL 状态。
不要编造尚未确认的业务规则；将不确定事项单独列出。

输出：
1. 用户问题与目标
2. 功能范围和不在范围内的内容
3. 可观察的验收标准与边界场景
4. 需要确认的问题，注明哪些可从仓库推断
5. 建议验证方式

当前先不修改生产代码。

随后让 Agent 基于确认后的规格拟定计划，并指出涉及的文件、兼容性、风险和检查方式。真正的研发并非始终分成完全隔离的阶段：可以先做只读调查、原型或小实验，再回来修正规格；但这些探索结果应与正式要求区分。

OpenAI 关于长期任务的公开案例采用了目标、非目标、约束和完成条件等内容来降低目标偏移，并使用里程碑计划管理实现过程。OpenAI：Run long-horizon tasks with Codex

五、规格要写到什么程度？

规格的质量不等于篇幅。太短，关键边界缺失；太长，把每个内部实现都预先固定，也可能妨碍更好的方案。

一个判断原则是：把会影响用户结果、系统边界和验证方式的内容写清楚；把可以由实现阶段合理决定的细节留给工程判断。

例如：

• “筛选作用于全部有权限的数据”属于行为契约。
• “请求失败时不能显示成无数据”属于可观察行为。
• “必须把按钮变量命名为 filterButton”通常没有必要。
• “延迟必须小于 200 毫秒”只有在说明测量条件、数据规模和业务目标后才有意义。

性能指标可以写成：

在预发布环境、指定数据规模和负载条件下，
列表接口的 p95 延迟目标为某个团队约定值。
如未达到，记录测量结果与瓶颈，不宣称目标已满足。

具体目标需要实际需求和基线，不能由 AI 为了让规格看起来完整而随意编造。

六、规格、项目规则、Skill 和测试如何配合？

Skill 可以帮助 Agent 使用团队方法审查规格，但 Skill 不应覆盖本次任务的明确目标。测试可以验证规格，但如果测试与实现共享同一个错误假设，两者一起通过也不代表用户需求被满足。

例如，前端筛选当前页的代码和对应单元测试都可能通过；只有包含跨页数据的验收案例，才能发现目标没有实现。

七、团队如何管理规格的生命周期？

规格写完后放在哪里、维护多久，取决于团队的协作成本和业务需要。

常见方式包括：

1. 交付前使用：完成后保留在 issue 或 PR 中，作为变更记录。
2. 长期维护：把核心行为规格保存在仓库，后续修改同步更新。
3. 规格作为生成来源：将规格视为主要输入，由工具生成部分实现；这种方式对工具链和约束要求更高。

GitHub Spec Kit 的文档区分这些生命周期选择，并明确由团队决定交付后的维护方式。Spec Persistence Models

无论选择哪一种，重要的是确定谁拥有哪类事实：

• 当前用户行为预期由哪里定义？
• API 的字段契约由哪里维护？
• 项目通用约定放在哪里？
• 若代码与文档冲突，谁来判断应修正哪一边？

代码描述当前实现，测试描述被检查的行为，规格表达约定意图。三者可能不同步；发现冲突时，应根据证据与负责人决策处理，而不是默认其中一份永远正确。

八、如何把 SDD 用进已有项目？

成熟项目已经有代码、用户和历史行为。不能因为引入 SDD，就假设从一张白纸开始。

合理的起点是：

1. 找到相关代码、接口、测试和使用场景。
2. 区分当前事实、历史约定和新需求。
3. 为本次变更编写足够清楚的规格。
4. 保持现有用户行为，除非需求明确要求改变。
5. 用实际案例验证新行为和关键回归。
6. 如果发现历史实现与现有文档冲突，记录差异并判断如何处理。

例如，为现有列表增加筛选，不应该顺手重写整个任务模块。规格应明确允许修改的范围，同时保留必要的工程自由度。

根据任务大小调整流程

如果为改一段文案生成十个文档，团队很可能正在维护流程，而不是解决问题。

九、SDD 常见的坑

1. 把 AI 生成的规格当成业务事实

AI 能把模糊描述写得很完整，但完整的文档也可能包含完全错误的业务规则。尤其是金额、权限、隐私、状态和默认行为，必须找到依据。

2. 验收标准只是重复需求

“筛选功能正常工作”无法告诉团队如何检查；跨页过滤、浏览器历史、空状态和权限才是可观察的行为。

3. 规格写得过死

如果把内部变量、组件结构和所有实现步骤写死，Agent 即使发现更好的实现，也可能不敢调整。应区分必须满足的约束与可讨论的设计方案。

4. 实现改变后，规格留在过去

团队需要决定规格是否长期维护。若决定维护，就要在需求变化时同步更新，并让 PR 说明变更原因；如果仅作一次性交付记录，也要明确其时效，避免被当成当前行为。

5. 自动化测试与规格一起犯错

Agent 可能根据同一个错误假设同时写代码和测试。应加入独立的用户案例、边界数据、已有系统约束和必要的人工验收。

6. 把流程完成当作产品完成

规格写完、任务全部打勾、测试全绿，都不必然证明用户能完成任务。尤其是界面功能，还需要检查真实交互、加载和失败状态。

7. 没有记录未验证内容

“已完成”与“代码已生成”不同。不能运行集成测试、无法接入外部服务或没有在浏览器检查时，应明确写出限制，而不是用计划代替结果。

十、怎样判断 SDD 是否真的有帮助？

不要用“规格有多少页”或“AI 写了多少行代码”衡量。

可以在团队中记录一段时间，比较类似任务：

• 需求澄清发生在开发前，还是返工后？
• 交付后有多少需求遗漏和行为回归？
• 从开始到可用交付需要多久？
• 规格与代码不一致的问题多久被发现？
• 关键验收标准有多少可复现的验证证据？
• 编写与维护规格增加了多少工作量？

这些数据需要结合任务复杂度和团队规模解释。引入 SDD 前后的任务若完全不同，不能把变化都归因于 SDD；最好选择相近类型的任务进行比较，并保留定性反馈。

一个有效的流程应该减少昂贵误解，同时让团队更快地交付正确结果。如果流程让小任务严重变慢，却没有改善协作或质量，就应缩小它的范围。

结语

AI 可以很快实现一个看似完整的功能，但它不能替团队决定哪些行为真正重要。SDD 把这些决定变成清晰的规格，再用计划、实现和验证持续检查它们。

应用 SDD 的重点不是让开发者先写更多文档，而是让每一次开发都有一条可追溯的线索：

为什么做、应该发生什么、如何实现、实际验证了什么，以及还有什么不知道。

当团队能围绕这条线索协作，AI 才不仅是在加快写代码，也在帮助团队更可靠地交付软件。

参考资料

• GitHub Spec Kit：规格、计划、任务、实现与收敛的工具流程。
• GitHub：Spec-driven development with AI：以规格驱动开发的基础工作流。
• Spec Kit：Spec Persistence Models：规格交付后的维护选择。
• OpenAI：Run long-horizon tasks with Codex：长期任务中目标、约束和完成条件的示例。
• OpenAI：Build iterative repair loops with Codex：以验证反馈推动实现改进。

延伸阅读：理解 Agent Loop；AI Coding 中的 Skill 最佳实践。