Kiro、OpenSpec 与 GitHub Spec Kit：AI 规格编程工具对比

从一次返工说起

三周前我接手一个需求：给电商后台加一个「批量导出订单」功能。需求评审会上大家点头确认，我打开编辑器直接开写。两个小时后，Agent 生成了四百多行代码，跑了测试，看着像是那么回事。提交后产品经理过来看了一眼，说「我要的是按物流状态分组导出，不是按时间」。

这不是代码质量问题，也不是 Agent 不好用。问题出在我跳过了「把需求写清楚」这一步，直接让 AI 去猜我想要什么。返工的根源不是代码写得慢，而是规格没对齐。

这类问题在 AI 编程时代被成倍放大了。以前手写代码时，至少会先画个草图、写几行伪代码。现在 Agent 生成速度太快，我们很容易跳过思考阶段，直接进入「让 AI 写写看」的模式。规格驱动开发（Spec-Driven Development, SDD）就是在这个背景下出现的——它不是要增加流程负担，而是帮我在 AI 动手之前把意图锁定清楚。

规格驱动开发的三个层次

Martin Fowler 的团队在 2025 年 10 月发表了一篇分析文章，把规格驱动开发分成了三个递进层次¹：

• Spec-first：在 AI 编码前先写一份规格，作为本次任务的约束。写完后规格和代码各自演化。
• Spec-anchored：规格在实现后继续维护，作为后续功能演进的参照物。代码变了，规格也同步更新。
• Spec-as-source：规格成为唯一的真实源，人类只修改规格，代码完全由规格生成。

这三个层次不是工具选型标准，而是帮判断当前团队处在哪个阶段。大多数团队刚从 spec-first 起步，直接跳到 spec-as-source 不现实，也不需要。

2026 年 1 月发表在 OpenReview 上的论文「Spec-Driven Development: From Code to Contract in the Age of AI」进一步指出，SDD 本质上颠覆了传统开发流程——规格不再是代码的附属品，而是代码的生产源²。这个转变意味着规格文件的质量直接决定了产出代码的质量。

三个工具的核心差异

目前主流的规格工具走的是三条不同路径。它们不是竞品关系，更像是从不同角度解决同一个问题：怎么让 AI 在写代码之前理解开发者要做什么。

Kiro：IDE 内的完整闭环

Kiro 是 AWS 推出的 AI IDE，核心卖点是把需求、设计、任务和实现全塞进编辑器里。它的 Spec 体系分三层³：

1. Requirements：用户故事格式，每个需求带验收标准
2. Design：技术架构、序列图、数据流
3. Tasks：可追踪的实现步骤，带依赖关系

Kiro 的执行面板能实时更新任务状态，点击「Run all Tasks」会构建依赖图，把无依赖的任务并行执行。这种 IDE 内闭环体验的好处是入口集中，不用在多个工具间切换。代价是整个流程绑死在 Kiro 这一个 IDE 上，技术栈和模型选择都受限。

我实际试用下来，发现 Kiro 在处理小需求时有个倾向：会把一个简单 bug 描述膨胀成「4 个用户故事 + 16 条验收标准」。Martin Fowler 团队也观察到类似现象¹——规格工具在控制 AI 输出方向上很有效，但在控制输出体积上还有欠缺。

OpenSpec：仓库即规格

OpenSpec 的思路完全不同。它不做 IDE，而是把规格文件直接塞进 Git 仓库⁴。每个变更有独立目录，包含四个核心文件：

openspec/changes/add-dark-mode/
├── proposal.md   # 为什么要做、改什么
├── specs/        # 需求和场景
├── design.md     # 技术方案
└── tasks.md      # 实现清单

完成后整体归档到 openspec/changes/archive/ 目录。整个流程通过斜杠命令驱动：/opsx:explore 做探索、/opsx:propose 生成全套文件、/opsx:apply 让 Agent 逐步执行、/opsx:archive 归档。

OpenSpec 强调「随时可改任何文件，没有刚性阶段门禁」。这个设计很务实——实际需求变更不会等人走完流程。它支持 25+ AI 工具，不绑定特定 IDE 或模型。风险在于团队需要自己维护规范执行纪律，工具本身不强制。

GitHub Spec Kit：结构化模板与多 Agent 兼容

GitHub 在 2025 年 9 月开源了 Spec Kit，定位是「让规格成为工程流程的中心」⁵。它的四阶段流程很清晰：

1. Specify：描述要做什么，Agent 生成用户旅程和期望结果
2. Plan：提供技术栈和约束，Agent 输出技术方案
3. Tasks：拆成可审查的小块任务
4. Implement：逐个任务执行，每个变更都可对比原始规格

Spec Kit 的核心哲学是「把稳定的 what 和灵活的 how 分开」。规格文件充当不可变宪法（Constitution），技术计划是可迭代的实现路径。它兼容 Copilot、Claude Code、Gemini CLI 等 30+ Agent，通过 /specify、/plan、/tasks 斜杠命令驱动。

Martin Fowler 团队的实测发现，Spec Kit 在处理中等复杂度需求时，会生成大量重复的 Markdown 文档，且 Agent 有时会忽略已有代码上下文，产生重复类¹。这说明模板化程度越高，越需要人工审查 Agent 是否真的「读了」现有代码。

工具选择的核心维度

三个工具各有侧重，选择时与其看功能列表，不如从五个维度评估团队当前的瓶颈：

三个实际案例

案例一：规格太模糊导致 Agent 自由发挥

场景：我需要用 OpenSpec 给内部工具加一个「用户权限管理」模块。

翻车：我直接在 /opsx:propose 后面写了一句「加个权限管理」。Agent 生成了完整的 RBAC 模型，包含角色继承、资源级权限、审计日志——而我实际只需要一个简单的「管理员 / 普通用户」二级权限。

修复：把需求拆成更具体的约束。先写清楚现有系统状态，再明确要改什么、不改什么。

<!-- ❌ 坏做法：模糊的一句话需求 -->
/opsx:propose 加个权限管理
 
<!-- ✅ 好做法：带约束的具体描述 -->
/opsx:propose 为内部运营后台增加二级权限控制：
- 现有用户角色：admin（全部权限）、operator（只读）
- 新增需求：operator 可以编辑订单状态，但不能修改用户信息
- 不涉及：不需要角色继承、不需要资源级权限、不需要审计日志
- 数据模型：在 user 表增加 permission_level 字段，枚举值 admin/operator/editor

差异在于：坏做法把决策权全部交给 Agent，好做法用约束条件框定了 Agent 的发挥空间。规格文件不是越短越好，也不是越长越好——精确到「Agent 不需要猜」就够了。

案例二：规格和代码脱节后的同步灾难

场景：用 Spec Kit 开发一个数据导出功能，前期规格写得不错，后续迭代时只改了代码没更新规格。

翻车：两周后新人接手，读规格文件发现「导出格式只支持 CSV」，但代码里已经有 Excel 和 PDF 导出。规格和代码的矛盾导致新人按旧规格写了一个重复的 CSV 导出模块。

修复：在 CI 中加了一个规格同步检查，每次 PR 如果修改了导出相关代码，必须同步更新 specs/ 目录下的对应文件。

# ❌ 坏做法：规格和代码各自为政
# specs/export-feature.md
## 导出格式
- 支持 CSV 格式导出
# 实际代码已经支持 CSV + Excel + PDF，但规格没有更新
 
# ✅ 好做法：规格作为 PR 检查项
# .github/workflows/spec-sync-check.yml
name: Spec Sync Check
on:
  pull_request:
    paths:
      - 'src/features/export/**'
 
jobs:
  check-spec-sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: 检查导出功能代码变更是否同步了规格
        run: |
          if git diff --name-only ${{ github.event.before }} HEAD \
            | grep -q 'src/features/export/'; then
            git diff --name-only ${{ github.event.before }} HEAD \
              | grep -q 'openspec/.*export' \
              || (echo "导出功能变更需要同步更新规格文件" && exit 1)
          fi

这个案例的核心教训是：规格文件一旦写出来，如果不同步维护，它的价值会随时间变成负数——过时的规格比没有规格更危险，因为它给人一种「有人管着」的错觉。

案例三：规格粒度失控导致上下文爆炸

场景：用 Kiro 开发一个包含 12 个接口的报表服务，把整个需求写成一份规格文件。

翻车：规格文件超过 3000 行，Agent 读取后生成的代码质量明显下降——后面的接口实现开始「忘记」前面定义的数据模型，字段命名不一致，错误处理逻辑重复。

修复：按功能模块拆分成独立规格文件，每个文件控制在 500 行以内，通过引用共享数据模型定义。

<!-- ❌ 坏做法：一份巨型规格包含所有内容 -->
<!-- specs/report-service.md (3000+ 行) -->
# 报表服务完整规格
## 用户管理接口 (12个接口)
## 订单查询接口 (8个接口)
## 数据导出接口 (6个接口)
## 权限校验逻辑
## 缓存策略
## 错误处理规范
<!-- Agent 上下文放不下，后面实现开始丢失前面定义 -->
 
<!-- ✅ 好做法：模块化拆分 + 共享引用 -->
<!-- specs/shared/data-models.md -->
# 共享数据模型
## User { id, name, role, permissions }
## Order { id, userId, status, items, totalAmount }
## ExportTask { id, format, filters, status, downloadUrl }
 
<!-- specs/report/user-api.md -->
# 用户管理接口
引用: ../shared/data-models.md#User
<!-- 约 200 行，Agent 可以完整理解 -->
 
<!-- specs/report/order-api.md -->
# 订单查询接口
引用: ../shared/data-models.md#Order
<!-- 约 300 行，独立上下文 -->

Allegro 工程团队在 2026 年 6 月的实践总结中也指出了同样的问题⁶：「单份规格覆盖所有内容，会导致上下文大小问题，随着项目增长变得难以维护。」他们的建议是「按功能拆分规格，每份规格保持轻量和独立」。

规格工具的工作流程

这个流程里有几个关键的人工检查点：规格生成后必须人工审查、每个任务完成后对比规格、PR 提交时检查规格同步。跳过任何一个检查点，规格就退化成了一次性的「许愿单」。

好规格和坏规格的区别

规格编写的常见陷阱

陷阱一：把规格写成口号

<!-- ❌ 坏做法：口号式规格 -->
# 需求：提升用户体验
- 页面要快
- 交互要流畅
- 错误提示要友好
 
<!-- ✅ 好做法：可执行的规格 -->
# 需求：订单列表页性能优化
- 首屏加载时间 < 1.5s（当前 3.2s）
- 滚动列表使用虚拟滚动，DOM 节点不超过 50 个
- 接口超时返回具体错误码和重试按钮，不显示通用错误页

口号式规格的问题在于：人类读着觉得「有道理」，Agent 读完后完全不知道具体要做什么。「页面要快」是多快？「交互要流畅」是什么标准？这种规格除了给需求评审会增加仪式感，对代码生成没有任何约束力。

陷阱二：规格和实现混在一起

<!-- ❌ 坏做法：规格里写实现细节 -->
# 数据导出功能
1. 使用 bull 创建任务队列
2. 用 stream 方式写入 CSV
3. 上传到 S3 的 exports/ 桶
4. 用 Redis 存任务状态
5. 前端轮询 /api/export/:id/status
 
<!-- ✅ 好做法：规格只描述行为和约束 -->
# 数据导出功能
## 行为
- 用户提交导出请求后，异步生成文件
- 文件就绪后提供下载链接，有效期 24 小时
- 支持 CSV 和 Excel 两种格式
## 约束
- 单次导出不超过 10 万行
- 导出过程不阻塞其他请求
- 文件存储使用对象存储，不放应用服务器本地

规格写实现细节会导致两个问题：一是限制了 Agent 选择更优实现方案的空间，二是当实现方案变化时规格立刻过时。规格应该描述「做什么」和「约束是什么」，把「怎么做」留给 Agent 和开发者。

陷阱三：一次生成全部代码

<!-- ❌ 坏做法：让 Agent 一次性实现所有任务 -->
/opsx:apply 实现所有任务
 
<!-- ✅ 好做法：逐个任务执行，每个任务后审查 -->
/opsx:apply task-1  # 实现数据模型
# 审查 -> 确认 -> 继续
/opsx:apply task-2  # 实现 API 接口
# 审查 -> 确认 -> 继续
/opsx:apply task-3  # 实现前端组件

Allegro 团队的实践建议很直接⁶：「LLM 在聚焦单一任务时最有效」。一次让 Agent 实现所有任务，上下文窗口装不下，后面的实现会「忘记」前面的决策，导致内部不一致。

陷阱四：忽视规格审查

<!-- ❌ 坏做法：Agent 生成规格后直接开始实现 -->
/opsx:propose 用户注册功能
# Agent 输出了 500 行规格
/opsx:apply  # 没有审查就直接实现
 
<!-- ✅ 好做法：规格必须经过人工审查 -->
/opsx:propose 用户注册功能
# Agent 输出了 500 行规格
# 人工审查：
#   - 注册流程是否遗漏了邮箱验证？
#   - 密码策略是否和公司安全规范一致？
#   - 是否考虑了手机号注册的边界情况？
# 补充遗漏的验收标准后
/opsx:apply

规格审查是最容易被跳过但最重要的环节。Agent 生成规格的速度很快，但速度不等于质量。规格里的遗漏和错误会在实现阶段被成倍放大——代码层面改一个字段名可能只要一分钟，但如果这个字段名已经写进了三个接口、两个数据模型和一份前端契约，修改成本就完全不一样了。

不同团队的选择路径

规格工具落地检查清单

阶段一：准备（第 1 周）

• 选一个中等复杂度的功能做试点，不要太简单也不要太复杂
• 确认团队对「规格」的定义达成一致：它不是 PRD，也不是技术方案，是两者之间的桥梁
• 安装并初始化选定的工具（Kiro / OpenSpec / Spec Kit）
• 准备一份一页纸的规格模板，包含：背景、目标用户、核心场景、数据模型、验收标准、不做什么

阶段二：试点（第 2-3 周）

• 用选定工具完成一个完整功能：从规格生成到代码实现
• 每个阶段设置人工检查点：规格审查、任务拆分审查、实现结果对比
• 记录哪些环节减少了返工，哪些环节只是增加了流程负担
• 试点结束后做一次回顾：规格文件在后续维护中是否真的被用到

阶段三：推广（第 4-6 周）

• 根据试点经验调整规格模板，去掉不必要的部分
• 建立规格审查机制：PR 中必须包含规格变更或说明为什么不需要
• 在 CI 中加入规格同步检查：核心功能代码变更必须同步更新规格
• 建立规格质量评估标准：好的规格应该让新人读完就能理解功能边界

阶段四：持续优化

• 每月回顾一次规格文件的实际使用情况，清理过时规格
• 根据团队规模变化调整规格粒度：人越多，规格需要越精确
• 跟踪工具的版本更新，评估新功能是否值得引入
• 建立内部最佳实践文档，记录成功的规格写法和常见的失败模式

规格工具的局限

Martin Fowler 团队在实测后提出了一个值得警惕的观点¹：当前的规格工具可能在放大审查负担和幻觉问题。当 Agent 生成大量规格文档时，人工审查的工作量反而可能增加。这和十多年前「模型驱动开发」（Model-Driven Development）遇到的问题有相似之处——抽象层级过多，维护成本超过了它带来的收益。

另一个现实问题是规格的非确定性。同样的规格输入给 Agent，不同时间生成的代码可能不一样。Tessl 团队的实测就发现了这个问题¹。这意味着规格工具不能简单地用「规格是否完整」来衡量质量，还要看实现结果是否稳定可预期。

规格驱动开发不是银弹。它解决的是「需求到代码的翻译损耗」问题，但如果团队主要瓶颈不在这里——比如是部署流程慢、测试覆盖不够、或者产品方向不清晰——那规格工具带来的改善可能很有限。先判断瓶颈在哪，再决定是否引入工具。

参考资料