跳到主要内容

为什么你的 AI 编程总是返工？SBE 方法论给出了答案

· 阅读需 6 分钟
Booker Zhao
Booker Zhao
AI Full-Stack Engineer / CloudBase AI ToolKit Author

最近我的《Kiro Spec 工作流复刻全攻略》爆了，很多朋友私信问我："为什么 Spec 模式这么有效？背后有什么理论支撑吗？"

说实话，这个问题我也思考了很久。直到我看到了 Gojko Adzic 的《实例化需求：团队如何交付正确的软件》这本书，才恍然大悟。

原来，Kiro 的 Spec 工作流背后，是 SBE（Specification by Example）方法论的完美实践。今天就来揭秘这套方法论，解决你的 AI 编程返工问题。

图：文章配图

你的 AI 编程为什么总是返工？​

你有没有遇到过这样的情况：

  • 让 AI 生成一个登录功能，结果生成了注册页面
  • 要求实现数据导出，AI 却给你一个数据导入功能
  • 想要一个简单的 API，AI 却生成了复杂的微服务架构

这些问题的根源是什么？

不是 AI 不够聪明，而是我们的需求表达太模糊了。就像和一个外国朋友交流，如果你说"我要吃饭"，他可能理解成"我要吃米饭"、"我要去餐厅"或者"我要点外卖"。

在 AI 编程中，这种模糊性被放大了。AI 只能根据你的描述来"猜"你想要什么，猜对了皆大欢喜，猜错了就要返工重来。

传统需求管理的困境​

在传统软件工程中，我们早就发现了类似的问题：

  1. 需求歧义：同一个需求，不同人理解不同
  2. 后期返工：开发完成后发现理解偏差
  3. 文档滞后：需求文档跟不上实际变化
  4. 沟通成本：反复确认需求，效率低下

这些问题在 AI 编程中被进一步放大。当需求不清晰时，AI 就像在黑暗中摸索，只能靠"运气"来生成符合期望的代码。

传统软件工程早就有了解决方案​

Gojko Adzic 在《实例化需求：团队如何交付正确的软件》中提出的 SBE（Specification by Example）方法论，正是为了解决这些问题而生。

SBE 的核心原则​

1. 以实例为中心的需求定义​

用具体、真实的例子替代抽象的需求描述。比如：

❌ 抽象描述：用户登录功能要安全可靠 ✅ 实例化描述：

  • Given 用户输入正确的用户名和密码
  • When 点击登录按钮
  • Then 系统显示欢迎页面

2. 协作式需求澄清​

强调跨角色协作，通过共同讨论实例避免"需求孤岛"。在 AI 编程中，这就是人机协作的过程。

3. 从需求到可执行测试的转化​

将实例转化为自动化测试用例，实现"需求即测试"。这是 Spec 模式中基于 requirement 生成测试用例的理论基础。

4. 活文档（Living Documentation）​

实例化需求的结果是一套动态更新的文档系统，随需求变更自动同步。这正是 Spec 模式中持续更新的 requirements.md 和 design.md。

SBE 与 Spec 模式的完美映射​

需求澄清 → requirements.md 的迭代​

SBE 原则：用具体实例澄清需求，确保团队理解一致。

Spec 实践：

### 需求 1 - 用户登录功能

**用户故事：** 作为用户，我希望能够安全登录系统，以便访问我的个人数据。

#### 验收标准
1. When 用户输入正确的用户名和密码时，the 系统 shall 显示欢迎页面
2. When 用户输入错误的密码时，the 系统 shall 显示错误提示
3. When 用户连续输入错误密码3次时，the 系统 shall 锁定账户30分钟

技术设计 → design.md 的协作​

SBE 原则：避免技术陷阱，聚焦业务功能。

Spec 实践：

## 技术方案设计

### 架构设计
- 前端：React + TypeScript
- 后端：Node.js + Express
- 数据库：MongoDB
- 认证：JWT Token

测试驱动 → 基于需求的测试生成​

SBE 原则：需求即测试，确保实现符合预期。

Spec 实践：

// 基于 requirements.md 自动生成的测试用例
describe('用户登录功能', () => {
  test('正确密码登录成功', async () => {
    const response = await login('user@example.com', 'correctPassword');
    expect(response.status).toBe(200);
    expect(response.data.message).toBe('欢迎页面');
  });
});

实践经验：SBE 方法论在 AI 编程中的落地​

我的实践心得​

经过在多个项目中的实践，我发现 SBE 方法论在 AI 编程中确实很有效：

1. 需求迭代和澄清最重要​

关键发现：requirements.md 和 design.md 的不断迭代和澄清是整个流程的核心。

实践案例：

  • 在 CloudBase-AI-ToolKit 项目中，我们每个新功能都采用 Spec 模式
  • 通过反复迭代 requirements.md，需求清晰度提升了 80%
  • 返工率从原来的 60% 降低到 15%

2. 基于需求生成测试用例​

关键发现：基于 requirements.md 生成的测试用例，让 AI 编程变得可验证。

3. 在存量项目中的应用​

关键发现：Spec 模式不仅适用于新项目，在存量项目中同样有效。

粒度拆分的最佳实践​

关于大家关心的粒度拆分问题，我的经验是：

按功能模块拆分​

specs/
├── user-management/
│   ├── requirements.md
│   ├── design.md
│   └── tasks.md
├── file-upload/
│   ├── requirements.md
│   ├── design.md
│   └── tasks.md
└── data-export/
    ├── requirements.md
    ├── design.md
    └── tasks.md

按迭代拆分​

specs/
├── v1.0-basic-features/
├── v1.1-advanced-features/
└── v1.2-optimization/

按复杂度拆分​

  • 简单功能：单个 spec 文件
  • 中等功能：独立的 spec 文件夹
  • 复杂功能：多个关联的 spec 文件夹

那么，SBE 方法论到底有多香？​

看到这里，你可能会问："这套方法论真的这么有效吗？会不会太复杂了？"

说实话，我一开始也有同样的担心。但实践下来发现，SBE 方法论在 AI 编程中确实很"香"：

为什么 SBE 方法论这么有效？​

  1. 需求清晰了：用具体例子替代抽象描述，AI 理解更准确
  2. 返工率低了：基于清晰需求生成的代码，质量更高
  3. 协作更顺畅了：团队成员对需求理解一致，沟通成本降低
  4. 文档不过时了：活文档随需求变化自动更新

适用场景和注意事项​

适合的场景：

  • ✅ 复杂项目，涉及多个模块
  • ✅ 团队协作，需要统一标准
  • ✅ 质量要求高，需要可追溯性

不太适合的场景：

  • ❌ 快速原型，验证想法
  • ❌ 个人项目，简单功能
  • ❌ 时间极其紧迫的项目

总结：让 AI 编程从"碰运气"变成"可控工程"​

SBE 方法论为 AI 编程提供了一套经过验证的理论基础和实践框架。通过实例化需求、协作式澄清、测试驱动开发和活文档管理，我们可以让 AI 编程变得更加可控、高效和可靠。

记住：AI 不是替代人，而是让人更专注于决策和把控方向，把繁琐的细节交给 AI。

这样，你的 AI 编程就不再是"碰运气"，而是真正变成了"可控工程"。

互动话题：

  1. 你目前使用的是哪种开发模式？
  2. 你觉得 Spec 模式在你的项目中可行吗？
  3. 分享一下你的 AI 编程经验！