规范驱动 AI 编程：从工具失效到工程化落地

一、问题的起点：工具很强，为什么用不好

团队在 2024 年中开始引入 AI 辅助编程。最初的体验具有普遍性：在短上下文、边界清晰的场景里，AI 表现相当不错——写一个独立函数、实现一个工具方法、生成代码补全与格式化、补充注释，这些任务确实带来了可感知的提效。

但一旦进入规模化复用阶段，问题就暴露了：

• 规范没有形成共识：每个人对“怎么用好 AI”的理解不同，产出质量高度依赖个人经验。
• 工程化没有标准认识：不知道该往哪个方向沉淀，也不知道什么样的实践值得推广。
• 提示词复用习惯没建立：好的提示词停留在个人对话历史里，没有变成团队资产。

当时只有少量触发类型的规则文件（早期规则体系的雏形），虽然提出过“在基础智能体之上封装智能体”的想法，但几个月过去，真正动起来的人并不多。

这个困境的本质不是模型能力不足，而是缺少一套把 AI 编程从“个人技巧”变成“工程流程”的方法论。带着这个问题，我开始寻找外部已经成熟的实践：有没有可以直接借鉴的 AI 编程工程化方案？

二、行业早期的共性痛点

AI 编程助手快速普及后，很多团队都经历了相似的兴奋与失落：

1. 生成质量参差不齐：同一个需求，不同人、不同时间问出来的代码质量差异巨大。
2. 需求理解偏离预期：AI 倾向于“猜”，而猜错的成本由人来承担。
3. 上下文丢失严重：跨文件、跨会话的连续性差，改一处坏十处。
4. 维护成本上升：生成代码缺少统一的结构约束，后期重构负担加重。

这些痛点的共同指向是：AI 缺少稳定的“规范输入”和“协作结构”。如果没有规范，AI 只能在概率空间里自由发挥；如果没有结构，多轮协作就会退化成一次性问答。

三、规范驱动开发的核心思想

规范驱动开发（Spec-Driven Development，SDD）提供了一套值得借鉴的框架。它的核心理念可以概括为三点：

• 规范即代码：规范不只是指导文档，而是直接用于生成实现的输入。
• 权力倒置：代码服务于规范，而不是规范迁就既有代码。
• 测试优先：强制先写测试，把验收标准前置到实现之前。

它把开发流程拆成清晰的多阶段推进路径：

宪章（Constitution）
  → 规范（Specify）
  → 计划（Plan）
  → 任务（Tasks）
  → 实施（Implement）

每个阶段对应一个明确的产出物：项目宪章确定开发原则与约束；规范定义需求与用户故事；计划描述技术实现路径；任务列表把计划拆成可执行单元；实施阶段按任务逐个落地。

这套流程的价值在于：它把“和 AI 对话”变成了“按阶段交付工程产物”。每一步都有可检查的中间物，AI 的产出不再是一次性的黑箱结果，而是可以评审、可以回滚、可以复用的工程资产。

四、我的实践：三个月踩坑与转向

我在实际项目中完整使用了这套规范驱动流程约三个月，最终选择放弃“照搬流程”的做法。原因并不是理念错误，而是流程成本与团队现状不匹配：

• 五阶段全量执行对小需求而言过重，宪章与计划的维护成本高于收益。
• 阶段之间的产物如果缺少自动化校验，很容易退化成“为了填模板而填模板”。
• 团队成员的规范意识参差不齐，流程强制反而增加了摩擦。

但这段经历并非浪费。它让我确认了三件真正有效的事：

1. 规范必须存在，但可以轻量化：不必每个需求都写完整宪章，但关键约束（接口契约、错误处理约定、目录结构）必须显式化。
2. 多智能体协作比单一大提示更稳定：把“规划、实现、评审”拆给不同角色，比让一个智能体一次性完成更可控。
3. 上下文需要被工程化管理：上下文不是越长越好，而是要被筛选、分层、按需注入。

五、可落地的工程化框架

综合上述经验，我逐步形成了一套更轻、更可持续的做法，核心是四个层次。

5.1 规范层：用最小契约约束 AI

不必追求完整规范文档，而是维护一组最小契约：

• 接口签名与数据结构的类型定义；
• 错误码与异常处理约定；
• 目录结构与命名规范；
• 关键业务的验收用例。

这些契约以结构化文件形式存放，作为每次生成任务的固定输入。示例（示意性伪代码）：

contracts/
  api.yaml          # 接口契约
  errors.md         # 错误处理约定
  conventions.md    # 命名与结构规范
  cases/            # 验收用例

5.2 协作层：多角色智能体分工

借鉴多智能体协作思路，把任务拆成角色：

• 规划角色：读取规范与需求，产出实现计划与任务拆分；
• 实现角色：在给定上下文内完成单个任务的代码生成；
• 评审角色：对照规范检查产出，输出差异与修改建议。

关键在于角色之间的输入输出是结构化产物，而不是自由对话。这样每个环节都可审计、可复现。

5.3 上下文层：分层注入而非全量拼接

上下文工程的重点是“给对的信息”，而不是“给多的信息”。实践中可以分三层：

• 稳定层：项目宪章、编码规范、目录约定——每次必带；
• 任务层：当前任务的规范片段、相关接口、邻近代码——按需检索；
• 会话层：本轮对话的临时结论与待办——短生命周期。

分层的好处是上下文体积可控，且稳定层的内容可以持续迭代，形成团队共识。

5.4 复利层：让知识持续沉淀

真正让边际成本递减的，是把每次有效实践固化为可复用资产：

• 把验证有效的提示模板沉淀为团队模板库；
• 把评审中反复出现的问题整理成检查清单；
• 把典型任务的实现路径整理成可检索的案例。

当这些资产积累到一定规模，新任务的启动成本会显著下降，形成知识复利。

六、效果与反思

采用这套轻量框架后，几个变化比较明显：

• 生成产出的一致性提升，评审返工减少；
• 新成员上手更快，因为规范与模板是显式存在的；
• 提示词从个人经验变成团队资产，复用率上升。

需要诚实指出的是，这套方法并非万能：它依赖团队愿意维护契约与模板，也依赖评审环节的严格执行。工具再强，也只是放大器——放大的永远是流程与规范的质量。

如果你也处在“AI 工具明明很强但就是用不好”的阶段，建议不要急于追求更复杂的工具链，而是先回答三个问题：规范是否显式？协作是否有结构？经验是否在沉淀？这三个问题答好了，工具的价值才会真正释放。