一、为什么 AI 编程需要“工作流”？
AI 编程最大的陷阱，不是它写不出代码，而是它永远走最短路径。
没有需求澄清就直接开写，没有测试就直接提 PR，没有设计评审就直接上生产——这不是 AI 的问题，这是使用 AI 没有工程约束的问题。
具体来说，AI 辅助开发面临三个系统性问题：
问题一：跳过设计直接写代码。 AI 最擅长的是“生成”，它会把你最模糊的输入解释成最能快速完成的版本，而不是你真正需要的版本。
问题二：没有测试就说“完成了”。 AI 不会主动先写测试，不会系统定位 bug 根因，也不会在写代码前检查 spec。如果没有外部结构约束，产出质量完全依赖于人类工程师在每次对话中是否足够谨慎。
问题三：设计共识随对话消失。 AI 在长对话中会遗忘早期约束。brainstorm 中否决的方案，可能在第 50 轮对话时被重新提出。一旦 /clear 释放上下文，之前达成的共识全部丢失。
这三个问题的共同根源是：缺乏稳定、可验证的真相来源。 没有正式规范，AI 助手被迫解释模糊的指令，导致一系列常见的挫败感——遗漏细微的需求、添加不需要的功能、生成“听起来正确但实际上无法运行”的代码。
因此，我们需要一套工作流，把 AI 从“凭感觉聊天”拉回到“按规范开发”的轨道上。
二、两大核心引擎：OpenSpec 与 Superpowers
要理解这套工作流，首先要认清两个工具的定位。它们不是竞争关系，而是 “上层定规、下层执行”的互补关系。
2.1 OpenSpec：管“做什么”
OpenSpec 是由 Fission-AI 打造的轻量级规范驱动开发（SDD）框架，核心定位是锁定需求意图、解决上下文丢失问题，被称为 AI 开发的“施工图纸”。
它解决的核心问题是：多个 Agent 协作时，怎么保证大家对“做什么”的理解一致？
没有 OpenSpec 的场景：你在聊天窗口里告诉 Agent “加一个用户认证模块”，Agent 按自己的理解去做。做出来发现接口不对、字段命名不一致、验收标准不明确。改了三轮还在返工。
有 OpenSpec 的场景：先写一份 spec 文件，明确定义需求、接口、数据模型、验收条件。所有 Agent 读同一份 spec 开工，做完了按 spec 验证——符合就通过，不符合就打回。
2.2 Superpowers：管“怎么做”
Superpowers 是由 Jesse Vincent 打造的开源 AI 编程工作流框架，核心理念是 Process over Prompt（流程大于提示词） 。
它的本质是：把软件工程最佳实践（TDD、Code Review、Spec-Driven、Git Worktree、子 Agent 协作）全部封装成 AI 可自动执行的 Skills，让大模型从“代码生成器”变成“真正懂工程的 Junior Engineer”。
如果把 AI 开发比作盖楼，OpenSpec 就是建筑施工图，明确“做什么、做成什么样”；Superpowers 就是施工操作手册，明确“怎么做、按什么标准做”，保障施工过程合规、高质量。
2.3 分工一览表
| 维度 | OpenSpec | Superpowers |
|---|---|---|
| 管什么 | 做什么——需求、接口、验收标准 | 怎么做——TDD、审查、验证流程 |
| 类比 | 施工图纸 | 施工规范手册 |
| 核心产出 | proposal、spec、design、tasks | 测试代码、实现代码、审查报告 |
| 解决的问题 | 需求漂移、共识丢失 | 工程质量、执行纪律 |
| 工作流 | propose → apply → archive | 头脑风暴 → 规划 → TDD → 审查 |
二者结合：形成“意图锁定 + 执行保障”的闭环，彻底解决 AI 开发的核心痛点。
三、完整工作流的四步法
这是本文的核心——基于 SDD（规范驱动开发）+ TDD（测试驱动开发）的 AI 编程工作流，将 OpenSpec 和 Superpowers 整合为一套从提案到归档的完整流程。
步骤一：提案 (Proposal) —— 用 OpenSpec 锁定意图
一句话理解：这是“写合同”的阶段。在写任何代码之前，先用结构化文档锁定“为什么做”和“做什么”。
执行方：OpenSpec
关键命令：/opsx:propose
核心产出：
| 文件 | 职责 | 核心内容 |
|---|---|---|
proposal.md |
变更提案 | 为什么做、目标/非目标、影响范围 |
design.md |
设计决策 | 技术方案选择、替代方案对比、风险评估 |
specs/*.md |
需求规格 | Requirements + GIVEN-WHEN-THEN 场景 |
tasks.md |
任务清单 | 可执行的 checkbox 任务列表 |
💡 为什么用 GIVEN-WHEN-THEN？
这是 BDD（行为驱动开发）的标准写法，能确保每个需求都是可验证的。
举个例子，为“用户登录”功能写 spec：
Scenario: 成功登录 GIVEN 用户已注册且账号未被锁定 WHEN 用户输入正确的用户名和密码 THEN 系统返回 JWT token 并跳转到首页
步骤二：计划 (Plan) —— 用 Superpowers 拆解可执行步骤
一句话理解：这是“画施工图”的阶段。把宏观任务拆成一个个 2-5 分钟能搞定的原子任务。
执行方：Superpowers
关键命令：/superpowers:write-plan
核心产出：plan.md（更细粒度的执行计划）
这一步是连接“设计”与“实施”的关键桥梁。Superpowers 的 writing-plans 技能会将任务拆解为更原子化、可并行的子任务，确保每个子任务小而独立、可单独完成。
💡 为什么这一步不能跳过？
不拆解就开工的后果是：AI 一口气生成几百行代码，逻辑纠缠在一起，出了问题根本不知道从哪改。拆分后，每个子任务 2-5 分钟即可完成，验证和回滚的成本都极低。
任务拆解示例（以“用户登录”功能为例）：
原始任务：实现用户登录功能
↓ 拆解后
1.1 创建 login 路由和 handler 骨架
1.2 实现密码加密验证逻辑
1.3 实现 JWT token 生成
1.4 添加登录失败次数限制
1.5 编写单元测试覆盖所有场景
步骤三：实施 (Implementation) —— 用 Superpowers 保障质量
一句话理解：这是“按图纸施工”的阶段。AI 必须严格遵循 TDD 铁律：先写测试 → 看到测试失败 → 再写实现代码。
执行方：Superpowers
关键命令：/superpowers:execute-plan
执行机制的四个层次
① 子代理调度
为每个任务创建全新的 agent 实例，只携带最小必要上下文。这保证了每个任务独立执行、互不干扰，也避免了长会话带来的上下文污染。
② TDD 强制执行
Superpowers 把 TDD 从“工程建议”升级为零妥协的质量准则。
执行流程是经典的“红-绿-重构”循环：
- 红（RED） ：先写一个会失败的测试
- 绿（GREEN） ：用最少的代码让它通过
- 重构（REFACTOR） ：优化代码结构和质量
子代理必须先在测试文件中看到测试失败，然后才允许编写实现代码。没有失败测试，就没有生产代码。
③ 双阶段代码审查
任务完成后，子代理先进行自审查，然后提交给专门的 code-reviewer 代理进行独立审查。只有通过审查的代码才能被接受。这套机制确保每段代码都经过评审，而非“写完就过”。
④ Git 工作流隔离
自动在隔离的 worktree 中工作，保持 main 分支干净。所有变更都在独立分支上完成，不影响主干稳定性。
步骤四：归档 (Archive) —— 用 OpenSpec 沉淀项目知识资产
一句话理解：这是“存档案”的阶段。把这次变更的所有文档永久保存，形成可追溯的历史记录。
执行方：OpenSpec
关键命令：/opsx:archive
核心产出：整个变更（提案、设计、规范、任务等）移动到 archive/ 目录，形成一份永久的、可追溯的变更历史记录。
归档后，目录结构如下：
openspec/
├── archive/
│ └── 2026-04-17-user-login/ # 归档的完整变更记录
│ ├── proposal.md
│ ├── design.md
│ ├── specs/
│ ├── tasks.md
│ └── plan.md
└── specs/ # 当前生效的规范（已更新）
💡 为什么归档这一步如此重要？
三个月后，你接手一个遗留项目，代码里有个奇怪的判断逻辑。没人知道为什么这么写，聊天记录里也找不到当时的上下文。归档解决了这个问题——每次变更的“为什么”都永久记录在案，任何人都能追溯到当时的设计决策。
四、补充理解：规范驱动开发（SDD）的核心理念
4.1 什么是 SDD？
SDD（Spec-Driven Development，规范驱动开发）的核心理念只有一句话：先想清楚再动手，用文档约束行为，用验证确保正确。
传统 AI 辅助编码是这样的：
用户描述需求 → AI 直接写代码 → 用户检查代码 → 发现不对 → 重来
SDD 的思路完全不同：
用户描述需求 → 生成规范文档 → AI 按规范实现 → 按规范验证
4.2 为什么 AI 时代更需要 SDD？
在 AI 编程盛行的今天，我们似乎习惯了“提示词即代码”的快节奏。然而，当面对复杂业务逻辑时，这种“即兴发挥”的模式会带来巨大的维护灾难。
SDD 提供了三大核心价值：
- 需求不再只活在聊天记录里，而是结构化文档
- 多 Agent 共享同一份规范，不会各做各的
- 验收有明确标准，不是“看起来差不多就行”
五、完整实战示例：从零实现用户登录功能
假设你要实现一个“用户登录”功能，下面展示完整流程。
步骤 1：初始化 OpenSpec
cd your-project
openspec init
步骤 2：生成提案（OpenSpec）
在 AI 助手中执行：
/opsx:propose 实现用户登录功能：支持邮箱+密码登录，失败5次后锁定账号30分钟
AI 会自动生成：
proposal.md— 为什么需要登录功能，目标与非目标design.md— 选择 JWT 还是 Session、密码加密方案、锁定时长设计specs/login/spec.md— GIVEN-WHEN-THEN 场景覆盖成功登录、密码错误、账号锁定等tasks.md— 任务清单
步骤 3：细化计划（Superpowers）
AI 使用 writing-plans 技能，将 tasks.md 拆解为更细粒度的 plan.md，每个任务约 2-5 分钟可完成。
步骤 4：TDD 实施（Superpowers）
执行：
/superpowers:execute-plan
系统将自动：
- 为每个子任务创建隔离的 worktree 和 agent
- 先写测试，看到测试失败（红）
- 编写最小实现代码让测试通过（绿）
- 优化代码结构（重构）
- 自审查 → 提交给 code-reviewer 代理审查
步骤 5：归档
执行：
/opsx:archive
所有文档归档到 openspec/archive/2026-04-17-user-login/。