OpenSpec 工作流：为 AI 编码装上规范引擎

犹豫的果冻布丁
0 阅读9分钟

OpenSpec 工作流：为 AI 编码装上规范引擎

一套 8 步技能包，让 Claude Code 从"随心所欲写代码"进化为"规范驱动的工程化开发"。

你有没有遇到过这些问题？

用 AI 写代码时，很多人都有过这样的体验：

  • 你说"加个导出功能"，AI 二话不说给你生成了一堆 CSV 代码——但你其实要的是带格式的 Excel
  • AI 跳过测试直接写实现，等你发现逻辑漏洞时已经改了好几轮
  • 每次对话 AI 都要重新理解你的项目，光 context 就吃掉几千行，聊几轮就开始"失忆"
  • Bug 修了一个又一个，因为 AI 在症状上打补丁，从没找到根因

根本原因很简单：AI 缺一套工程规范。  它擅长写代码，但不会主动走需求澄清 → 方案设计 → 规约编写 → TDD → 归档的完整流程。

这就是 OpenSpec 工作流 要解决的问题。

一句话概括

OpenSpec 工作流是一个为 Claude Code 打造的规范驱动开发技能包，将 OpenSpec 6 步流程拆分为 8 个按需加载的 os-* Skill，配合精简版路由器，让 AI 编码每一步都有据可依。

核心数据：基础 context 消耗从 1095 行降至 284 行，降幅 74%。

架构一览

CLAUDE.md  (284 行，始终加载 — 判定表 + 路由规则)
  ├── os-scope    需求澄清（一次一问、多选题、场景三问）
  ├── os-plan     提案设计（方案对比、YAGNI、分段确认）
  ├── os-spec     规约编写（GIVEN/WHEN/THEN、Spec↔测试映射）
  ├── os-design   设计 + 任务拆分（测试策略、RED→GREEN→REFACTOR、依赖声明）
  ├── os-build    TDD 实施 + 代码审查（并行调度、两阶段审查）
  ├── os-ship     归档发布（合并 delta spec、全量测试）
  ├── os-trace    系统化调试（四阶段根因分析、数据流溯源、3次上限规则）
  └── os-fork     Git Worktree 隔离（多模块并行开发）

8 个 Skill 各司其职，按需加载，互不干扰。

工作流全景：8 步让 AI "想清楚再动手"

Step 1：os-scope — 需求澄清

AI 接到需求后的第一反应不是写代码，而是一次只问一个问题，用多选题降低你的回答成本。

用户："帮我加个导出功能"

AI：先确认最核心的问题：导出什么数据？
    A. 订单  B. 用户  C. 公告  D. 其他

用户："订单"

AI：导出格式偏好？
    A. CSV（简单无格式）  B. Excel（带表头格式，支持筛选/排序）

三轮"场景三问"（给谁用、在哪用、何时触发）下来，需求边界一清二楚。再也不会出现"做了 CSV 但用户要 Excel"的翻车现场。

Step 2：os-plan — 提案设计

不是上来就干，而是先亮方案。至少 2 个备选方案对比，分析优劣，给出推荐理由。还有一道硬性关卡——YAGNI 审查：刻意排除不需要的特性，防止过度设计。

"不做邮件发送——由外部邮件服务通过事件触发；不做 token 黑名单——单次使用后直接删除；不做重置次数限制——本期无暴力破解风险。"

Step 3：os-spec — 规约编写

用 GIVEN/WHEN/THEN 格式描述系统行为，每个 Scenario 直接对应一条测试用例。每个 Requirement 至少包含一个异常/边界 Scenario。

#### Scenario: Valid token（正常路径）
- GIVEN 一个有效的 reset token
- WHEN 用户提交新密码
- THEN 返回 200 状态码
- AND 密码被更新

#### Scenario: Expired token（异常路径）
- GIVEN 一个已过期的 reset token
- WHEN 用户尝试重置密码
- THEN 返回 410 状态码

Spec 是真相源头——实现和测试冲突时，Spec 说了算。

Step 4：os-design — 技术设计 + 任务拆分

将 Spec 中的每个 Scenario 映射到具体的测试文件和测试用例，制定 Mock 策略，声明任务依赖关系（blockedBy）。

每个任务组遵循 RED → GREEN → REFACTOR 三段式，末尾强制包含并行策略——哪些任务不共享文件、可以并发执行，一目了然。

Step 5：os-build — TDD 实施

这是最硬核的阶段。写代码前必须先输出 GATE 声明：

[GATE] 当前阶段: RED
[GATE] 对应测试: tests/auth.test.ts
[GATE] 测试状态: ✗ FAIL（已确认红色）

严格遵循 RED（先写测试，看到失败）→ GREEN（最简实现，让测试通过）→ REFACTOR（重构优化，保持绿色）循环。还包含一套完善的分支处理：

  • 测试意外通过 → 暂停，检查测试是否正确复现了 Bug
  • 回归测试失败 → 立即停止，评估是设计冲突还是副作用
  • 并行调度 → 3 个以上独立任务组强制并发执行

Step 6：两阶段 Code Review

全部 task 完成后，不是直接收工，而是走两阶段审查：

  • 阶段 1 — Spec 合规审查：改动是否覆盖了所有 Scenario？是否多做了 Spec 没要求的事？
  • 阶段 2 — 代码质量审查：是否有冗余代码？命名是否清晰？新增测试覆盖率是否 ≥80%？

Step 7：os-trace — 系统化调试

当 Bug 来临时，禁止在找到根因前提出任何修复方案。四阶段流程：

  1. 根因调查 — 读错误、稳定复现、检查变更、数据流溯源
  2. 模式分析 — 找同类正常工作的代码，逐行对比差异
  3. 假设与验证 — 一次只验证一个假设
  4. 实施修复 — 先写失败测试，再修根因（不是症状）

还有一个杀手级规则——3 次上限：修复尝试 3 次仍不生效，立即停止，反思架构是否有问题。

Step 8：os-ship — 归档发布

合并 delta spec 到主 spec，跑全量测试，变更历史归档保留。任一测试失败则停止归档，路由回对应阶段修复。

判定表：AI 的决策起点

整个工作流的"大脑"是一张判定表。AI 收到你的请求后，先查表匹配场景：

场景工作流链调用 Skill
新功能Scope → Plan → Specs → Design → Tasks → Build → Shipos-scope → … → os-ship
Bug 修复Trace → Specs → Design → Tasks → Build → Shipos-trace → … → os-ship
重构（≥3 文件）Fork → Plan → Specs → Design → Tasks → Build → Shipos-fork → … → os-ship
依赖升级（patch）[FAST-PATH]不调用
微小修复（≤5 行）[FAST-PATH]不调用

快速通道有、完整流程也有，不搞一刀切。

为什么 context 能降 74%？

传统做法是把所有规则写在一个巨型 CLAUDE.md 里（1095 行），每次对话全部加载。但 90% 的场景你只需要其中 10% 的规则。

OpenSpec 的做法：

CLAUDE.md（284 行，始终加载）
  ├── 判定表 — 轻量路由，快速匹配场景
  ├── 通用铁律 — 所有阶段适用的核心原则
  └── 路由规则 — 指向具体的 os-* skill

当判定表匹配到"新功能"时，AI 按阶段依次加载 os-scope → os-plan → os-spec → …，每个 Skill 平均只有 100 行。用多少，加载多少；不用，就不占 context。

实战演示：一个 Bug 修复的完整旅程

假设你报告："登录接口在密码错误时有时返回 500，应该返回 401。"

❌ 没有 OpenSpec 时

AI 可能直接改 AuthService，加个 if-else 判断异常类型。修完跑一下测试——咦，登录测试挂了，因为改了异常处理又影响了正常流程。再改，再跑……来来回回。

✅ 有 OpenSpec 时

[WORKFLOW] 判定表情况: Bug 修复 → Trace → Specs → Design → Tasks → Build → Ship

# Step 1: os-trace — 数据流溯源
追踪调用链：login form → authApi.login() → POST /auth/login → AuthController → AuthService
发现 catch 块捕获了 SQLException 但没有区分 401 和 500，所有异常统一返回 500。
根因确认：异常类型映射缺失。

# Step 2: os-spec — 写 Delta Spec
#### Scenario: Invalid credentials
- GIVEN 一个已注册的用户
- WHEN 用户提交错误的密码
- THEN 返回 401 状态码（SHALL，不可返回 5xx）
- AND 返回错误信息

# Step 3: os-design — 任务拆分
1.1 RED: 编写密码错误返回 401 的测试 — 验证当前返回 500（复现 Bug）
1.2 GREEN: 在 AuthService 中区分异常类型
1.3 REFACTOR: 提取异常映射为独立函数

# Step 4: os-build — TDD 实施
RED → 测试确认 ✗ FAIL（返回 500 而非 401）✓
GREEN → 最简修复，异常类型判断 ✓
全部测试回归 → ✓ 18 passed, 0 failed

# Step 5: os-ship — 归档
Delta spec 合入主 spec，变更历史归档。

每一步都有据可查，每一个决策都有文档记录。

安全护栏：反例警示

工作流设计了一套硬性约束，违规操作会被拦截：

反例正确做法
输出 header 后不调用 skill，直接查代码先调用 skill，返回后再按指示行动
把"列表中没数据"当作一般提问识别为可观测异常，走 Bug 修复流程
没声明 GATE 就直接写代码先输出 GATE 声明（RED/GREEN/REFACTOR），再 Edit/Write
4 个独立任务串行执行先评估并行机会，N≥3 强制并发

快速上手

安装（30 秒）

# macOS / Linux / Git Bash
cd openspec-workflow
bash install.sh

# Windows PowerShell
.\install.ps1

安装脚本会自动备份现有 CLAUDE.md，然后部署路由器 + 8 个 Skill 到 ~/.claude/ 目录。下次启动 Claude Code 自动生效，零配置。

卸载

rm ~/.claude/CLAUDE.md
mv ~/.claude/CLAUDE.md.bak.* ~/.claude/CLAUDE.md  # 恢复备份
rm -rf ~/.claude/skills/os-*

谁适合用？

  • 用 Claude Code 做日常开发的工程师——让你的 AI 搭档从"随性发挥"变成"有章可循"
  • 追求工程质量的团队——Spec 优先、TDD 兜底，每一步都可追溯
  • 对 AI 辅助编程好奇的开发者——这套工作流展示了 AI 编程的"正确打开方式"
  • 遭受过 AI "盲目输出"折磨的人——再也不会出现"做了半天发现需求理解错了"的惨案

写在最后

AI 编程工具越来越强，但工具强不等于产出好。写代码只占软件工程的 20%，真正决定质量的，是需求澄清、方案设计、测试策略、代码审查这些"慢功夫"。

OpenSpec 工作流做的，就是把这些"慢功夫"变成 AI 的肌肉记忆——不用你催，AI 自己就知道该走哪一步、不该跳过哪一步。

规范不是束缚，是让 AI 与你更好协作的桥梁。

项目地址：GitHub - OS Workflow

如果你也在用 Claude Code 开发，欢迎试试这套工作流，也欢迎在评论区交流你的 AI 编程实践。

avatar
文章
阅读
粉丝