工程实践01

AI 编程实践

用规格驱动开发(Spec-Driven Development)组织 AI 编码:需求和验收条件先写成 spec,再拆任务交给 Agent 实现,由自动化测试判定完成。

P0 · 《AI Agentic Coding 工程实践手册》

目标

让 AI 编码进入可管理、可复现的工程流程:产出由规格决定,完成由测试判定,每一步都能回放。

  • 需求、约束与验收条件写成可判定的 spec
  • 上下文按 Rules、Skills、MCP、子 Agent 分层提供
  • 任务拆到单个可独立验证,产物可交接
  • 验证失败回到规格修改,不在对话里打补丁

原则

  1. 规格是唯一事实源需求、约束和验收条件都写在 spec 里;改需求先改 spec,再重新生成计划。
  2. 上下文按需加载Rules 只写不变量,Skills 命中才加载,MCP 统一工具入口,子 Agent 之间用结构化产物交接。
  3. 任务拆到可验证一个任务只做一件事,能单独跑测试;拆不开说明边界还没想清楚。
  4. 实现后必须验证每个任务写完就跑测试和静态检查;没通过不算完成,回到 spec 修改。
  5. 产物留痕可回放spec、plan、diff 和测试报告都留在仓库,任何一步都能重跑并对照结果。

流程

定义派发校验发布回流需求输入目标 · 约束 · 非目标Spec 与任务拆解验收条件 · 单任务可验证spec.md / tasks.mdAgent 编码执行逐任务实现 · 产物交接diff代码审查与自动化测试评审 · 单测 · Agent EvalsCI 门禁集成与发布交付灰度 · 回滚 · 观测release评估与持续改进偏差回写规格与规则spec v2Loop: AI 原生软件开发闭环
阶段与产物
阶段输入处理输出
需求输入业务目标、硬约束、非目标人和 Agent 澄清歧义,确认边界确认过的问题清单
Spec 与任务拆解需求与约束写验收条件,拆成单任务可验证的计划spec.md、plan.md、tasks.md
Agent 编码执行spec、任务、相关接口契约子 Agent 在沙箱内逐任务实现diff、变更说明
审查与测试diff、spec 验收条件人工评审设计,机器跑单测、契约测试和 Evals评审意见、测试与评测报告
集成与发布通过门禁的产物灰度发布,观测错误率和延迟发布记录、观测数据
评估与改进线上偏差、失败用例归因后回写规格、规则或数据集新版 spec、规则与用例

规范

个人实践

Spec 模板与验收条件

  • 目标与非目标分开写,非目标用来挡住范围蔓延
  • 约束写明技术栈、兼容范围和不可改动的接口
  • 验收条件逐条编号,测试报告按编号对应
示例
# spec.md(节选)
## 目标
- 支持按时间窗查询设备巡检结果
## 非目标
- 不做跨项目聚合
## 验收条件
- [ ] 给定 3 台设备、7 天窗口,接口返回按设备分组的结果
- [ ] 窗口超过 31 天返回 400 与错误码 RANGE_TOO_LARGE
- [ ] ./gradlew test --tests DeviceQueryTest 全部通过

个人实践

任务验收检查单

  • 任务只做一件事,能单独运行验收命令
  • 改动范围与 spec 一致,没有顺手重构
  • 测试覆盖成功、参数非法、超时三类路径
  • diff 与接口契约一致,错误码已登记

个人实践

AGENTS.md 规则文件

  • 一条规则只约束一件事,能被评审引用
  • 禁止改动区域写到具体路径,避免 Agent 自行推断
  • 完成标准写命令,不写「代码规范」这类不可判定的表述
示例
# AGENTS.md(节选)
## 不变量
- 后端只改 src/main/java,前端只改 src/web
- 不允许修改 src/proto 下的接口定义,改契约先提 ADR
## 完成标准
- 每个任务必须附带可执行的验收命令
- 提交前跑 ./gradlew test 与 pnpm typecheck
交付物与提示词模板
  • 《AI Agentic Coding 工程实践手册》
  • AGENTS.md / spec / plan / tasks 模板与验收检查单
  • 上下文分层方案(Rules / Skills / MCP / 子 Agent)
  • Copilot 10 个设备动作清单与项目复盘
你是一名规格工程师。请先不要写任何代码。
基于我给出的需求,按《AI Agentic Coding 工程实践手册》分阶段产出:
阶段 1(定义):输出 spec.md,含目标、非目标、约束,以及每条都能被命令或测试判定的验收条件;停下来等我确认。
阶段 2(计划):输出 plan.md 与 tasks.md,任务拆到单任务可独立验证,每个任务带验收命令。
阶段 3(实现):逐任务产出 diff,一次只做一个任务;上下文只包含相关 spec 与接口契约。
阶段 4(验证):每个任务跑完验收命令并贴出结果;失败回阶段 2,不许在对话里打补丁。
阶段 5(归档):输出 test report,把变更回写到 spec 与 ADR。
规则:需求有歧义先提问,不许自行假设;验收条件禁止写「代码规范」「体验良好」这类不可判定的表述;任一阶段缺少产物,不得进入下一阶段。
行业参考

案例真实项目

无人机 Copilot 的编码流程复盘

  • 10 个动作写清输入输出、幂等性和失败语义
  • 不可逆动作分级,权限边界写进 Rules
  • 每个动作单独实现、单独验收
  • 偏差回写 spec 和评测数据集

真实项目:无人机智能作业平台 Copilot 改造,10 个设备动作逐项交付。

效果与局限

10 个设备动作

均有 spec、验收命令与失败语义

3 个工作台共用上下文

同一份 Skills 通过软链接加载

5 类阶段产物

spec / plan / tasks / diff / test report

局限

  • 规格不到位的需求,Agent 仍会补假设;评审必须逐条对照验收条件。
  • 跨仓库重构仍由人拆任务,Agent 负责局部实现。
  • 手册只在单一项目上迭代,尚无多项目基线对比。

计数来自项目内的 spec 与任务清单,不含效率提升比例。