规范驱动开发实战：从需求到可维护代码

一、教程目标

本教程要帮助读者完成一件事：把“让 AI 代理写代码”这件模糊的事，改造成一套可重复、可验证、可维护的工程流程。具体来说，你将学会：

1. 把一句自然语言提示，转化为结构化的需求条目与可执行的验收标准；
2. 在需求、设计、实现三个阶段引入合适的工件（需求文档、设计说明、测试用例、界面草图等），把问题前置暴露；
3. 用属性测试（property-based testing）验证生成代码的行为是否稳定可复现；
4. 通过外部上下文集成，让代理在生成前就拿到足够的背景信息；
5. 对代理给出的初始方案保持怀疑，主动寻找替代实现；
6. 在大型、结构混乱的代码库中识别代理能力下降的信号，并给出治理思路。

适合阅读人群：有一定工程经验、正在或计划把 AI 代理引入日常研发流程的开发者、测试工程师、技术负责人与运维人员。读者应具备基本的版本控制、单元测试与持续集成概念。

二、适用场景

规范驱动开发（Specification-Driven Development，下称 SDD）适合以下场景：

• 需求相对明确但表述松散：产品同学给了一段描述，需要转成开发可执行的条目；
• 重复性代码生成：接口层、数据转换层、校验逻辑等结构相似的模块；
• 对可维护性要求高的模块：核心业务逻辑、边界条件多的计算逻辑；
• 多人协作、需要留痕：需求变更需要可追溯，验收标准需要可评审；
• 测试先行或测试补齐：希望生成代码同时产出对应测试用例。

不太适合的场景：探索性原型、一次性脚本、需求本身仍在剧烈变动且无法收敛的阶段。此时强上规范流程会带来不必要的开销。

三、前置准备

在开始之前，请确认具备以下条件：

• 基础知识：了解需求分析、验收标准（Acceptance Criteria）的写法；了解单元测试与断言；了解属性测试的基本思想（用“对所有输入都成立的性质”代替逐条举例）。
• 环境准备：一个可用的代码仓库与分支策略；一套可本地运行的测试框架；一个能读取仓库文件的开发环境；如涉及外部上下文集成，需要相应的访问凭据与权限配置。
• 流程准备：明确“谁评审需求、谁评审设计、谁验收测试”的角色分工；约定工件存放位置（例如仓库内固定目录）。
• 数据准备：整理领域术语表、既有接口约定、历史缺陷记录。这些是后续喂给代理的高价值上下文。

四、实施步骤

步骤 1：明确任务边界，写清“做什么、不做什么”

在写任何提示之前，先用一段话界定任务范围：输入是什么、输出是什么、边界条件有哪些、明确排除哪些情况。这一步的作用是防止代理自由发挥、把范围扩大到无法评审的程度。

建议在任务描述中固定包含四要素：目标、输入、输出、约束。约束里显式写出“不修改公共接口”“不引入新依赖”等硬性条件。

步骤 2：把提示转化为结构化需求（EARS 风格）

EARS（Easy Approach to Requirements Syntax）是一种把自然语言需求规范化的写法，核心是用固定句式消除歧义。常见句式包括：

• 普遍式：系统应当……（描述始终成立的性质）
• 事件式：当……时，系统应当……
• 状态式：在……状态下，系统应当……
• 异常式：如果……，则系统应当……
• 可选式：在……特性启用时，系统应当……

示例（伪代码形式的需求条目）：

需求 R-01（事件式）：
当 用户提交的表单缺少必填字段 时，
系统 应当 返回结构化错误列表，且不写入任何数据。
需求 R-02（异常式）：
如果 外部依赖调用超时，
则 系统 应当 在有限次数内重试，并在最终失败时记录可检索的日志。

为什么这么做：结构化句式让每条需求都具备“触发条件 + 期望行为”的完整语义，既能被人评审，也能被代理直接消费，还能一对一派生出验收标准。注意每条需求只描述一件事，避免复合句。

步骤 3：为每条需求派生验收标准

验收标准是需求的“可验证表达”。推荐使用“给定—当—则”三段式，每个条目对应一个可自动化验证的断言。

验收标准 AC-01（对应 R-01）：
给定 一个包含空必填字段的请求，
当 提交表单时，
则 返回的错误列表中包含对应字段标识，且存储层无新增记录。

注意点：验收标准必须可判定，避免“体验良好”“响应较快”这类主观描述；涉及数值的地方写明阈值来源（由业务约定，而非代理臆测）。

步骤 4：补充设计与定制工件，把问题前置

在需求之后、实现之前，插入轻量设计工件。常见三类：

• 接口契约：函数签名、请求/响应结构、错误码约定；
• 界面草图或流程图：用文字描述或简单示意表达交互顺序，帮助代理理解状态流转；
• 测试用例清单：先列出要覆盖的正常路径、边界路径、异常路径。

为什么这么做：把潜在问题（字段缺失、状态冲突、并发顺序）在设计和测试用例阶段就暴露出来，比等到实现完成后再返工成本低得多。工件不必复杂，关键是“先写下来、可被评审”。

步骤 5：引入外部上下文集成

代理生成质量很大程度取决于上下文是否充分。可通过通用的外部系统集成方式，把以下信息接入工作流：

• 任务与需求管理系统中的原始需求条目；
• 内部文档站点中的领域术语、接口规范；
• 监控与日志系统中的历史故障模式。

实施要点：只接入与当前任务相关的片段，避免整库灌入导致上下文噪声；对敏感信息做脱敏；为接入内容标注来源与版本，便于回溯。配置上通常需要凭据管理、访问范围限定与调用频率限制，具体参数依所用集成方式而定，切勿把凭据写入仓库明文。

步骤 6：生成实现与测试，并执行属性测试

在需求、验收标准、设计工件齐备后，再让代理生成实现与测试。此时代理的输出应被约束为：实现代码 + 对应验收标准的测试 + 属性测试。

属性测试的思路是：不去逐条列举输入，而是声明“对所有合法输入都应成立的性质”，由测试框架自动生成大量输入进行验证。示例性质：

性质 P-01：对任意合法输入，序列化后再反序列化，结果与原对象等价。
性质 P-02：对任意合法输入，处理函数的输出长度不超过输入长度的固定倍数。
性质 P-03：对任意两个合法输入，合并操作满足幂等性。

为什么这么做：属性测试能覆盖人工举例想不到的输入组合，对代理生成代码尤其有价值——它能有效暴露“只在样例上正确”的实现。注意生成器的输入域要与需求中的约束一致，否则会产生大量无效失败。

步骤 7：审查初始方案，主动寻找替代实现

不要直接接受代理给出的第一个方案。按以下顺序审查：

1. 是否满足全部验收标准，有无遗漏条目；
2. 是否引入了不必要的依赖或抽象；
3. 是否存在更符合现有代码风格的写法；
4. 边界与异常路径是否与需求一致。

对存疑之处，主动要求给出至少两种替代实现并比较取舍（复杂度、可读性、性能影响）。必要时借助外部上下文检索既有实现范式。这一步是质量分水岭，跳过它就等于把评审责任完全交给代理。

步骤 8：在真实代码库中做小步验证

先在仓库的一个模块内落地，跑通测试与静态检查，再逐步扩大范围。观察代理在修改跨模块调用时的表现，记录失败模式，作为后续流程改进的输入。

五、配置说明

• 工件目录约定：建议在仓库内固定需求、设计、测试用例的存放路径，并在任务描述中显式引用，避免代理随意新建文件。
• 测试阈值：属性测试的迭代次数、超时时间属于通用配置项，取值需与CI时长预算平衡；次数过少覆盖不足，过多则拖慢流水线。
• 访问范围：外部集成的凭据应最小权限，只读优先；对不同环境使用不同凭据。
• 风险提示：任何自动化生成都不应绕过代码评审与合并门禁；生成内容需与人工提交同等对待。

六、结果验证

判断流程是否跑通，可看四个信号：

1. 每条需求都有对应的验收标准与测试用例，且能自动执行；
2. 属性测试在合理迭代次数内稳定通过，失败时能定位到具体性质；
3. 代码评审中“需求理解偏差”类问题显著减少；
4. 变更可回溯：从代码能追到需求条目，从需求条目能追到原始任务。

七、常见问题与排查

• 代理输出偏离需求：检查需求条目是否被拆得足够细、验收标准是否可判定；复合句是常见根因。
• 属性测试大量误报：核对生成器输入域与需求约束是否一致，常见原因是约束未写入需求。
• 代理在大型仓库中表现下降：这是普遍现象。排查方向包括模块耦合度过高、缺少可靠测试套件、上下文注入过多噪声。治理手段是清晰模块分离、提高内聚、补齐测试。
• 集成上下文后输出反而变差：多为上下文过量或版本不一致，缩小注入范围并标注版本来验证。

八、优化建议

• 可维护性：把需求与验收标准当作活文档维护，需求变更时同步更新，避免文档与代码脱节。
• 稳定性：把属性测试纳入持续集成，设定失败即阻断的规则。
• 安全：对外部上下文做脱敏与权限收敛，生成代码进入人工评审环节。
• 成本控制：按任务复杂度分级，简单任务走轻流程，核心模块走完整流程，避免一刀切。

九、总结

规范驱动开发的价值不在于让代理“写得更快”，而在于让生成结果可评审、可验证、可复现。关键动作是四步：结构化需求、派生验收标准、前置设计工件、用属性测试兜底。配合充分且干净的外部上下文、对初始方案的主动质疑，以及对大型代码库的结构治理，才能把 AI 代理稳定地纳入工程流程。后续可继续关注的方向包括：工件模板的沉淀、测试生成策略的调优，以及活文档与需求管理系统的持续同步。