> ## Documentation Index
> Fetch the complete documentation index at: https://adonis-til.mintlify.app/llms.txt
> Use this file to discover all available pages before exploring further.

# AI 辅助开发的工程化之路：Superpowers Skills 全生命周期实战指南

> 系统梳理 Superpowers 的 14 个 Skill，覆盖从创意到交付的完整软件生命周期，并对照 OpenAI Harness Engineering 实践总结 AI 工程化落地经验

> AI 写代码很快，但"写得快"不等于"做得对"。本文系统梳理 [Superpowers](https://github.com/obra/superpowers) 的 14 个 Skill，覆盖从创意到交付的完整软件生命周期，并从 Rex-CLI 项目中提炼出值得借鉴的基础设施设计模式。

***

## 一、为什么 AI 写代码需要"纪律"

用 AI 写代码一段时间后，你大概率遇到过这些场景：

| # | 翻车场景                     | 根因        |
| - | ------------------------ | --------- |
| 1 | AI 说"完成了"，但功能根本没跑通       | 不验证就报告成功  |
| 2 | 改了 A 模块，B 模块悄悄坏了         | 没有测试保护    |
| 3 | Bug 修了 3 次还没修好           | 没做根因分析，靠猜 |
| 4 | 需求理解偏了，500 行代码白费         | 没有设计环节    |
| 5 | 计划太模糊，"添加验证逻辑"没法执行       | 计划粒度不够    |
| 6 | 让 AI 修 10 个测试，它把测试改成永远通过 | 没有约束和隔离   |
| 7 | 代码在 main 分支上乱改，回滚困难      | 没有工作区隔离   |
| 8 | 功能做完不知道怎么收尾，分支散落一地       | 没有标准收尾流程  |

**核心问题不是 AI 的能力不够，而是缺乏工程纪律。**

```
没有纪律：想法 → 直接写代码 → "应该好了" → 出 bug → 猜修复 → 循环...
有了纪律：想法 → 设计 → 计划 → TDD 实现 → 审查 → 验证 → 交付
```

Superpowers 就是把后者编码成 AI 可执行的流程——14 个 Skill，覆盖软件开发生命周期的每个环节。

***

## 安装

项目地址：[https://github.com/obra/superpowers](https://github.com/obra/superpowers)

### Claude Code

通过官方插件市场安装：

```bash theme={null}
/plugin install superpowers@claude-plugins-official
```

安装后新开会话即可生效，Skills 会以 `superpowers:brainstorming` 等命名空间前缀被识别。

### 其他平台

```bash theme={null}
npx skills add obra/superpowers
```

***

## 二、14 个 Skill 速览

### 分层架构

14 个 Skill 按职责分为 5 层，从底层纪律到顶层元能力：

```
┌──────────────────────────────────────────────────────────────┐
│ 元层 (Meta)                                                   │
│   using-superpowers .............. 路由器，决定加载哪个 skill   │
│   writing-skills ................. 用 TDD 方法创建新 skill     │
├──────────────────────────────────────────────────────────────┤
│ 审查层 (Review)                                               │
│   requesting-code-review ......... 主动请求代码审查            │
│   receiving-code-review .......... 正确处理审查反馈            │
├──────────────────────────────────────────────────────────────┤
│ 执行层 (Execution)                                            │
│   using-git-worktrees ............ 创建隔离工作区              │
│   executing-plans ................ AI 直接逐步执行计划         │
│   subagent-driven-development .... 派子代理执行（带双阶段审查） │
│   finishing-a-development-branch . 开发完成后标准化收尾        │
├──────────────────────────────────────────────────────────────┤
│ 设计层 (Design)                                               │
│   brainstorming .................. 模糊想法 → 设计文档         │
│   writing-plans .................. 设计文档 → 可执行计划       │
├──────────────────────────────────────────────────────────────┤
│ 纪律层 (Discipline) — 独立可用，装了就有收益                    │
│   test-driven-development ........ RED-GREEN-REFACTOR          │
│   systematic-debugging ........... 4 阶段根因分析              │
│   verification-before-completion . 完成前必须跑验证            │
│   dispatching-parallel-agents .... 多个独立问题并行修复        │
└──────────────────────────────────────────────────────────────┘
```

### 依赖关系

一张图看清哪些 Skill 有硬依赖，哪些可以独立使用：

```
brainstorming → writing-plans → using-git-worktrees → 二选一：
                                       │
                     ┌─────────────────┴─────────────────┐
                     ▼                                   ▼
              executing-plans                subagent-driven-development
              (AI 自己写代码)                 (派子代理写 + 自动审查)
                     │                                   │
                     └──────────┬────────────────────────┘
                                ▼
                  finishing-a-development-branch

独立可用（无依赖，随时可装）：
  ● test-driven-development
  ● systematic-debugging
  ● verification-before-completion
  ● dispatching-parallel-agents
  ● receiving-code-review
```

**关键信息：** 纪律层的 5 个 Skill 没有任何依赖，装了就能用，是最低成本的收益起点。

***

## 三、完整软件生命周期：从想法到交付

以"接手一个产品需求"为例，看 Superpowers 如何覆盖每个阶段。

### 阶段 0：需求理解

这个阶段不需要特定 Skill。阅读 PRD / Issue / 口头描述，明确范围和边界。

### 阶段 1：设计 — brainstorming

**目标：** 把模糊的想法变成明确的设计文档。

```
用户: "帮我加一个用户认证系统"
  → AI 一次一个问题了解需求（JWT 还是 Session？需要 OAuth？）
  → 提出 2-3 种方案，给出推荐
  → 分段确认设计
  → 输出设计文档 → spec-reviewer 子代理审查
  → 用户最终确认
```

### 阶段 2：计划 — writing-plans

**目标：** 把设计文档翻译成可执行计划，粒度细到每步 2-5 分钟。

```
设计文档 → 定义文件结构 → 拆分细粒度任务
  每个任务包含：
  - 精确文件路径
  - 完整代码片段（不是"添加验证"这种模糊描述）
  - 要运行的命令和预期输出
  - TDD 节奏：写测试 → 验证失败 → 写实现 → 验证通过 → 提交
```

### 阶段 3：隔离 — using-git-worktrees

**目标：** 创建独立工作区，不影响当前代码。

```
创建功能分支 → 创建隔离 worktree → 在独立目录中工作
```

### 阶段 4：实现 — subagent-driven-development

**目标：** 逐个执行计划中的任务，每个任务有三道关卡。

```
对每个 task 循环：
  ① implementer 子代理 → TDD 写代码（RED → GREEN → REFACTOR）
  ② spec-reviewer 子代理 → 需求都实现了吗？不多不少？
  ③ code-quality-reviewer → 代码干净吗？可维护吗？
  → 标记完成 → 下一个 task
```

### 阶段 5：验证 — verification-before-completion

**目标：** 用证据（不是信心）确认一切正常。

```
运行全套测试 → 读完整输出 → 检查退出码 → 用证据确认
```

### 阶段 6：交付 — finishing-a-development-branch

**目标：** 标准化收尾，4 个选项。

```
验证测试通过 → 选择：
  a. 本地合并回主分支
  b. 推送并创建 Pull Request（最常用）
  c. 保留分支原样
  d. 丢弃
→ 清理 worktree
```

### 中途遇 Bug — systematic-debugging 随时插入

```
实现 Task 3 → 发现测试意外失败 → 暂停
  → 切入 systematic-debugging
  → 根因调查 → 模式分析 → 假设测试 → TDD 修复
  → 回到 Task 3 继续
```

### 日常简化：80% 的需求不用走全流程

| 需求规模            | 做法                                  | 涉及 Skill                                                                                                                                                        | 跳过什么              |
| --------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
| **小需求**（1-2 小时） | 快速 brainstorming → TDD 实现 → 验证 → 提交 | `brainstorming` → `test-driven-development` → `verification-before-completion`                                                                                  | worktree、子代理、正式审查 |
| **中需求**（半天到一天）  | 完整设计 → 计划 → worktree → 子代理实现 → 收尾   | `brainstorming` → `writing-plans` → `using-git-worktrees` → `subagent-driven-development` → `verification-before-completion` → `finishing-a-development-branch` | 无                 |
| **大需求**（多天）     | 阶段 0-6 全部走完，不跳步骤                    | 全部 Skill 按需参与，含 `systematic-debugging`、`dispatching-parallel-agents`、`requesting-code-review`、`receiving-code-review`                                           | 无                 |

***

## 四、每个 Skill 的使用技巧

这是本文的核心章节。逐个 Skill 拆解**触发时机、关键规则、实战技巧和常见误区**。

### 4.1 test-driven-development — 所有实现的基础纪律

**触发时机：** 任何功能开发、Bug 修复、重构、行为变更。

**核心规则：** 没有失败的测试就没有生产代码。

**Red-Green-Refactor 循环：**

```
RED（写失败测试）→ 验证它确实失败
  → GREEN（写最小实现让测试通过）→ 验证通过
    → REFACTOR（清理代码）→ 重复
```

**实战技巧：**

* 先写了代码再写测试？**删除代码，从头开始**。不能保留作为"参考"，不能"适配"已有代码。这是最强硬的规则，也是最容易违反的。
* 每次只让一个测试从 RED 变 GREEN，不要一次写多个测试。
* REFACTOR 阶段只改结构不改行为，改完后所有测试必须仍然通过。

**常见误区：**

| 借口               | 现实                                       |
| ---------------- | ---------------------------------------- |
| "太简单不需要测试"       | 简单代码也会坏。测试只需 30 秒。                       |
| "先写代码再补测试效果一样"   | 先写测试 = "应该做什么？" 后补测试 = "做了什么？" 两者方向完全相反。 |
| "删掉 X 小时的工作太浪费了" | 沉没成本谬误。保留不可信的代码才是真正的浪费。                  |

***

### 4.2 systematic-debugging — 遇 Bug 的第一反应

**触发时机：** 测试失败、生产 Bug、意外行为、性能问题、构建失败。**特别在时间压力下使用**——紧急情况最容易让人跳过流程猜修复。

**核心规则：** 没有根因分析就不能提出修复方案。

**四阶段流程：**

| 阶段      | 做什么                 | 通过标准          |
| ------- | ------------------- | ------------- |
| 1. 根因调查 | 读错误信息、复现、查最近变更、收集证据 | 理解了"什么"和"为什么" |
| 2. 模式分析 | 找到工作的类似代码，对比差异      | 识别出关键差异       |
| 3. 假设测试 | 形成假设，做最小化测试验证       | 确认或推翻假设       |
| 4. 实现修复 | 写失败测试 → 修复 → 验证     | Bug 解决，测试通过   |

**实战技巧：**

* **三次修复失败规则：** 如果尝试了 3 次以上还没修好，停下来质疑架构。这不是假设错了——是架构层面有问题。
* **15-30 分钟系统化修复 vs 2-3 小时瞎猜修复**——这是实际的时间差异。
* 三个子技术值得掌握：
  * **root-cause-tracing**：沿调用链反向追踪到根触发点
  * **defense-in-depth**：在数据流经的每一层加验证
  * **condition-based-waiting**：用条件轮询替代固定延时，消灭 flaky 测试

***

### 4.3 verification-before-completion — 完成前的最后一道门禁

**触发时机：** 任何时候你想说"完成了"、"应该可以了"、"测试通过了"之前。

**核心规则：** 没有新鲜的验证证据就不能声称完成。

**门禁清单：**

```
声称完成之前：
  1. 识别：什么命令能证明这个声明？
  2. 运行：执行完整命令（必须是新鲜的、完整的）
  3. 阅读：读完整输出，检查退出码
  4. 验证：输出确认了声明吗？
  5. 然后才能：做出声明
```

**实战技巧：**

* 如果你发现自己在用 "should"、"probably"、"seems to" 这些词——停下来，你还没验证。
* 不要信任子代理的成功报告，**独立验证**。
* 这个 Skill 诞生于 24 次失败的教训——用户曾说 "I don't believe you"，未定义的函数被发布，不完整的功能被声称完成。

**背景故事：** 这是整个体系中最"痛感"最强的 Skill，因为它来自真实的信任崩塌。核心教训只有一句话：**信心 ≠ 证据**。

***

### 4.4 brainstorming — 把模糊想法变成明确设计

**触发时机：** "帮我做一个 XX 功能"、"我想重构 XX 模块"、"建一个新项目"——任何涉及创造性工作的请求。

**核心规则：** 不管项目多简单，不允许跳过设计直接写代码。一个 TODO 应用也要走这个流程（只是设计文档会很短）。

**9 步流程概要：**

1. 探索项目上下文
2. 提供 Visual Companion（如有视觉需求）
3. **一次一个**澄清问题（优先选择题而非开放题）
4. 提出 2-3 种方案并给出推荐
5. 分段展示设计，逐段获得批准
6. 写入设计文档
7. spec-reviewer 子代理审查（最多 5 轮）
8. 用户最终审核
9. 转交 writing-plans

**实战技巧：**

* "一次一个问题"防止用户被问题淹没，这是从实践中总结出来的——连续抛 5 个问题，用户通常只回答前 2 个。
* 终态只能是 `writing-plans`，不能直接跳到实现——设计和实现之间必须有计划层。
* 如果你在做小需求，brainstorming 可能只需 2-3 个问题就够了，但**流程不能跳过**。

***

### 4.5 writing-plans — 设计文档翻译成可执行计划

**触发时机：** brainstorming 完成后，或已有需求文档需要转化为执行计划。

**核心理念：** 假设执行者对代码库零了解、对测试设计不太擅长。所以计划必须做到：

* 给出**精确的文件路径**（不是"在相关文件中"）
* 包含**完整的代码片段**（不是"添加验证逻辑"）
* 提供**精确的命令和预期输出**
* 每步 2-5 分钟可完成

**任务粒度示例：**

```
- [ ] Step 1: 在 src/auth/auth.test.ts 写登录失败测试
- [ ] Step 2: 运行 pnpm test auth.test.ts，验证测试失败（RED）
- [ ] Step 3: 在 src/auth/auth.service.ts 写最小实现
- [ ] Step 4: 运行 pnpm test auth.test.ts，验证测试通过（GREEN）
- [ ] Step 5: git commit -m "feat: add login validation"
```

**实战技巧：**

* 文件结构先于任务分解——先定义文件边界，再决定如何分配任务。
* 计划分 chunk（每 chunk ≤1000 行），每个 chunk 写完后有 plan-reviewer 审查。
* 每个文件应该有**单一职责**，这不仅是好的设计，也让 AI 更容易在上下文中理解和编辑。

***

### 4.6 subagent-driven-development — 首选的计划执行方式

**触发时机：** 有实现计划，需要高质量保证（双阶段审查），任务大多独立。

**核心模式（每个任务经过三个角色）：**

| 角色                        | 职责                    |
| ------------------------- | --------------------- |
| **Implementer**           | 写代码、写测试、提交。遵循 TDD 纪律。 |
| **Spec Reviewer**         | 需求都实现了吗？不多不少？         |
| **Code Quality Reviewer** | 代码干净吗？可测吗？可维护吗？       |

**实战技巧：**

* 子代理**永远不继承**控制器的会话上下文。控制器手工构建每个子代理需要的信息。原因：会话历史包含大量无关信息，精心构建的上下文比完整历史更高效。
* Spec 审查**必须先于**质量审查——先确认做对了，再确认做好了。反过来会浪费时间优化一个做错了的实现。
* Spec Reviewer 被设计得天然不信任 Implementer："实现者可能报告不完整、不准确或过于乐观。你**必须**独立验证。"这种对抗性审查比友好检查更有效。
* 用**便宜模型**（Haiku/Sonnet）做机械实现，用**强模型**（Opus）做审查和设计。

**实现者的 4 种状态报告：**

* `DONE` — 完成
* `DONE_WITH_CONCERNS` — 完成但有顾虑
* `NEEDS_CONTEXT` — 缺少信息
* `BLOCKED` — 被阻塞

***

### 4.7 executing-plans — 轻量级替代方案

**触发时机：** 有计划，但不需要子代理和双阶段审查。个人项目、快速迭代、想省 token。

**和 subagent-driven-dev 的区别：**

| 维度       | subagent-driven-dev   | executing-plans |
| -------- | --------------------- | --------------- |
| 代码由谁写    | Implementer 子代理       | AI 自己直接写        |
| 自动审查     | 有（spec + quality 双阶段） | 无               |
| Token 成本 | 高（每 task ×3 子代理）      | 低               |
| 适合什么     | 开源库 / 团队项目            | 个人项目 / 快速迭代     |

**选择决策：**

```
需要自动双阶段审查？→ subagent-driven-development
个人项目 / 省 token？→ executing-plans
不需要正式执行框架？→ 连 executing-plans 都不装，直接对话式写
```

***

### 4.8 dispatching-parallel-agents — 并行灭火

**触发时机：** 3 个以上独立问题同时存在，每个问题可以在不了解其他问题的情况下解决。

**核心判断流程：**

```
多个失败？→ 它们独立吗？→ 能并行工作吗？→ 并行派遣！
                ↓ 不独立          ↓ 有共享状态
           单一代理调查         顺序处理
```

**好的代理 Prompt 4 要素：**

1. **具体范围** — 一个测试文件或子系统
2. **明确目标** — "让这 3 个测试通过"
3. **约束条件** — "不要修改其他代码"
4. **预期输出** — "总结发现了什么和修复了什么"

**反模式（避免）：**

* 太宽泛："修复所有测试" → 代理会迷失
* 无上下文："修复竞态条件" → 代理不知道在哪
* 无约束：代理可能重构一切

***

### 4.9 requesting-code-review — 主动请求审查

**触发时机：** subagent-driven-dev 中每个任务完成后、主要功能完成后、合并到 main 前。

**流程：**

1. 获取 git SHA（BASE\_SHA 和 HEAD\_SHA）
2. 派遣审查子代理
3. 根据反馈严重级别行动：
   * **Critical** — 立即修复
   * **Important** — 继续前必须修复
   * **Minor** — 记录后续处理

***

### 4.10 receiving-code-review — 正确处理审查反馈

**触发时机：** 收到任何代码审查反馈时。

**核心原则：** 技术评估，不是情感表演。

**禁止：**

```
❌ "You're absolutely right!"
❌ "Great point!"
❌ "Thanks for catching that!"
```

**正确：**

```
✅ "Fixed. [简述变更]"
✅ "Good catch - [具体问题]. Fixed in [位置]."
✅ 直接修复，让代码说话。
```

**实战技巧：**

* 对外部审查者的建议：先验证技术正确性，再决定是否实施。如果建议有误，用技术理由推回。
* **YAGNI 检查：** 如果审查者建议"properly implement"一个功能，先 grep 代码库看是否实际使用。没用？建议删除。

***

### 4.11 using-git-worktrees — 隔离工作空间

**触发时机：** 开始功能开发前，需要在不影响当前工作区的情况下开展新工作。

**实战技巧：**

* 创建前必须确认目录被 gitignore，防止意外提交 worktree 内容。
* 目录选择优先级：已有 `.worktrees` 目录 > `worktrees` 目录 > CLAUDE.md 配置 > 询问用户。

***

### 4.12 finishing-a-development-branch — 标准化收尾

**触发时机：** 任何开发工作完成后。

**固定 4 个选项：**

1. 本地合并回基础分支
2. 推送并创建 Pull Request（最常用）
3. 保留分支原样
4. 丢弃这些工作

**流程：** 验证测试 → 确定基础分支 → 呈现 4 个选项 → 执行 → 清理 worktree。

***

### 4.13 using-superpowers — 系统路由器

**触发时机：** 每次对话开始时自动激活，你不需要手动调用。

**核心规则（1% Rule）：** 只要有 1% 的可能性某个 Skill 适用，就**必须**加载它。

这个 Skill 的设计很精妙——它用详细的 "Red Flags" 表格列举了所有 AI 可能跳过 Skill 的借口，并逐一反驳。解决了 AI 最常见的问题：**跳过流程直接干活**。

**优先级：** 用户指令 > Superpowers Skills > 系统默认行为。

***

### 4.14 writing-skills — 创建新 Skill

**触发时机：** 想把团队最佳实践编码成可复用的 Skill。

**核心方法：对文档做 TDD。**

| TDD 概念      | Skill 创建对应        |
| ----------- | ----------------- |
| 测试用例        | 带压力场景的子代理         |
| 生产代码        | SKILL.md 文档       |
| RED（测试失败）   | 代理在没有 Skill 时违反规则 |
| GREEN（测试通过） | 代理有 Skill 时遵守规则   |
| REFACTOR    | 发现新漏洞 → 堵住 → 重新测试 |

**关键发现（CSO 规则）：** Skill 的 description 只写**何时使用**，不写 Skill 做什么。原因：如果 description 总结了工作流（"先做 A 再做 B"），AI 会走捷径跟着 description 做，而跳过阅读完整 Skill 内容。这是实际测试发现的。

***

## 五、7 种场景化组合方案

不需要一上来就装全部 14 个 Skill。按场景选 3-14 个组合使用。

### 方案 1：最小纪律（3 个 Skill）

**适合：** 日常编码、快速原型、side project

```
test-driven-development        ← 写代码有测试保护
systematic-debugging           ← 遇 bug 做根因分析
verification-before-completion ← 说完成前必须跑验证
```

没有计划、没有 worktree、没有子代理。最轻量，但已经解决了 AI 最高频的 3 个翻车问题。

### 方案 2：设计先行（5 个 Skill）

**适合：** 需要想清楚再动手，但不需要复杂的执行编排

```
方案 1 的 3 个 + brainstorming + writing-plans
```

brainstorming 产出设计文档，writing-plans 产出计划，然后**手动跟着计划写**。适合你自己能把控节奏的场景。

### 方案 3：Solo Dev 完整版（8 个 Skill）

**适合：** 独立开发者做完整项目，从设计到交付

```
方案 2 的 5 个 + using-git-worktrees + executing-plans + finishing-a-development-branch
```

完整的设计→计划→隔离→执行→验证→交付流水线。

### 方案 4：质量极客（12 个 Skill）

**适合：** 开源库、SDK、团队项目、对质量零容忍

```
方案 3 的基础上，把 executing-plans 换成 subagent-driven-development
+ requesting-code-review + receiving-code-review + dispatching-parallel-agents
```

Token 成本最高但质量最高，每个 task 有 spec + quality 双阶段审查。

### 方案 5：救火队长（4 个 Skill）

**适合：** 接手遗留项目、日常修 bug、维护期

```
systematic-debugging + test-driven-development
+ dispatching-parallel-agents + verification-before-completion
```

全部独立可用，无依赖，专注调试和修复。

### 方案 6：架构师（4 个 Skill）

**适合：** 做设计不写代码、技术方案评审、大型重构规划

```
brainstorming + writing-plans + writing-skills + verification-before-completion
```

产出设计文档和计划，交给别人执行。

### 方案 7：渐进式全装（3→14，4 周计划）

```
第 1 周：纪律层 3 个 → 养成"写测试、查根因、跑验证"的肌肉记忆
第 2 周：+ 设计层 → 学会"想清楚再动手"
第 3 周：+ 执行层 → 学会隔离工作区、正式执行、标准收尾
第 4 周：+ 编排层 → 子代理、双审查、并行修复
最终：  + 元层 → 理解路由逻辑、创建自己的 Skill
```

### 组合决策速查表

| 场景           | 方案       | Skill 数 | 执行方式                |
| ------------ | -------- | ------- | ------------------- |
| 日常编码 / 快速原型  | 最小纪律     | 3       | 对话式直接写              |
| 想先设计再做       | 设计先行     | 5       | 手动跟计划写              |
| 独立做完整项目      | Solo Dev | 8       | executing-plans     |
| 开源库 / 团队项目   | 质量极客     | 12      | subagent-driven-dev |
| 维护项目 / 修 bug | 救火队长     | 4       | 对话式 + 并行            |
| 只做设计不写代码     | 架构师      | 4       | 不执行代码               |
| 逐步掌握全部       | 渐进式      | 3→14    | 逐步升级                |

***

## 六、进阶：Rex-CLI 的基础设施启示

> [Rex-CLI](https://github.com/rexleimo/rex-cli) 是一个开源的 AI 开发辅助工具。

**一句话理解两者的关系：** Superpowers 是一套"规矩"——告诉 AI 该怎么做事（先写测试、先做设计、完成前要验证）；Rex-CLI 是一套"配套工具箱"——帮你把这些规矩落地，还额外提供了记忆存储、多 Agent 编排、成本追踪等 Superpowers 管不了的基础设施能力。

打个比方：Superpowers 像驾校教材（教你怎么开车），Rex-CLI 像一辆装好了导航、行车记录仪、油耗仪表的车——教材的规矩内置在车里，但车还额外提供了教材覆盖不到的工具。

更技术化的类比：

|                 | 定位                 | 类比                |
| --------------- | ------------------ | ----------------- |
| **Superpowers** | AI Agent 的"开发流程宪法" | 交通法规——定义规则，不建公路   |
| **Rex-CLI**     | AI Agent 的"开发操作系统" | 公路系统——铺路 + 执行交通法规 |

Rex-CLI 将 Superpowers 作为"执行纪律层"嵌入自身，再在其上构建 6 层基础设施。

### Rex-CLI 的 6 层能力

#### 1. ContextDB — 跨 CLI 持久化记忆

**解决什么：** Agent 会话是无状态的，换个 CLI 或新开会话就丢失所有上下文。

**怎么做的：** 用 SQLite + JSONL 存储 session / event / checkpoint，支持跨 CLI（Claude Code → Codex → Gemini）、跨天恢复上下文。

```
Day 1 用 Claude Code → ContextDB 记录进度
Day 2 换 Codex CLI   → 自动注入 Day 1 上下文，从断点继续
Day 3 换 Gemini CLI  → 加载 Day 1 + Day 2 全部上下文
```

核心能力：`context:pack` 按 token budget 打包最近 N 条 event，防止上下文爆炸。

#### 2. Orchestrator — 程序化多 Agent 编排

**解决什么：** Superpowers 的 subagent dispatch 全靠 prompt 指令，没有 DAG 依赖、并行控制、merge 冲突检测。

**怎么做的：** 4 种 Blueprint（feature / bugfix / refactor / security），每种定义了固定的 Phase 流程和 Agent 角色。支持 `dry-run` 零成本预览。

```
feature blueprint:
  Plan（只读）→ Implement（可写）→ Review | SecurityReview（只读，并行）→ Merge Gate
```

#### 3. Browser MCP — 通用浏览器自动化

**解决什么：** AI Agent 天然无法操作浏览器。提供 11 个 Playwright 工具（launch / navigate / click / type / screenshot 等），加反检测。

#### 4. Privacy Guard — 敏感文件脱敏

**解决什么：** `.env`、credentials 等敏感文件不应该暴露给 AI。提供 regex / ollama / hybrid 三种脱敏模式。

#### 5. Cost Telemetry — 全链路成本追踪

**解决什么：** 不知道每步花了多少 token 和钱。每个 checkpoint 记录 inputTokens / outputTokens / usd / retryCount。

#### 6. Quality Gate — 发布前门禁

**解决什么：** 程序化的质量检查。仓库健康、依赖扫描、测试通过率，一键跑完。

### 值得借鉴的 5 个设计模式

**1. 持久化是基础设施**

没有持久化，Agent 就是金鱼记忆，每次从头开始。ContextDB 的 session → event → checkpoint 三级模型值得复用。

**2. Shell 拦截 > Plugin 注入**

在 shell 层为 `codex()`, `claude()`, `gemini()` 创建透明函数包装，比在每个 CLI 写 plugin 更通用。一次拦截，多 CLI 受益。

**3. Blueprint + DAG > Prompt 编排**

程序化编排（Blueprint → DAG → Dispatch）可验证、可回放、可成本追踪。比纯 prompt 指令驱动更可靠。

**4. 结构化 Handoff 协议**

Agent 间用 JSON Schema 定义通信契约，比自由文本可靠。包含 status / fromRole / toRole / findings / filesTouched 等结构化字段。

**5. 零成本预览（Dry-Run）**

在花 token 前验证编排逻辑。`aios orchestrate --execute dry-run` 只构建 job plan，不启动 Agent。这个设计极大降低了试错成本。

### 自建工作流的设计清单

如果你想从头构建自己的 AI Agent 工作流，以下是从两个项目中提炼的完整清单：

```
□ 纪律层：Skill 发现机制 + 强制调用规则（1% Rule）
□ 状态层：持久化 session / event / checkpoint，支持跨工具恢复
□ 编排层：Blueprint → DAG → Dispatch，支持 dry-run
□ 通信层：结构化 Handoff 协议（JSON Schema）
□ 成本层：per-step token / USD 追踪 + 预算控制
□ 验证层：evidence-first，程序化 Quality Gate
□ 安全层：隐私脱敏 + 敏感操作确认
□ 可观测层：从历史数据分析优化流程
```

***

## 七、学习路径：4 周渐进式上手计划

### 第 1 周：建立基础纪律

| 学什么                            | 目标                         |
| ------------------------------ | -------------------------- |
| test-driven-development        | 养成 Red-Green-Refactor 肌肉记忆 |
| verification-before-completion | 养成"证据驱动"习惯                 |
| systematic-debugging           | 遇 Bug 先分析后修复，不猜            |

**练习建议：** 用这 3 个 Skill 做一周的日常开发，每次写代码前先写测试，每次说"完成"前跑一遍验证。

### 第 2 周：掌握设计流程

| 学什么           | 目标                   |
| ------------- | -------------------- |
| brainstorming | 学会"想清楚再动手"           |
| writing-plans | 学会写细到每步 2-5 分钟的可执行计划 |

**练习建议：** 接一个中等需求，完整走 brainstorming → writing-plans → 手动实现。体会"有计划"和"没计划"的差异。

### 第 3 周：掌握执行和收尾

| 学什么                            | 目标        |
| ------------------------------ | --------- |
| using-git-worktrees            | 学会工作区隔离   |
| executing-plans                | 用正式框架执行计划 |
| finishing-a-development-branch | 标准化收尾     |

**练习建议：** 完整走一遍设计→计划→隔离→执行→收尾的流水线。

### 第 4 周：进阶编排

| 学什么                                | 目标            |
| ---------------------------------- | ------------- |
| subagent-driven-development        | 多代理协作 + 双阶段审查 |
| dispatching-parallel-agents        | 并行解决独立问题      |
| requesting / receiving-code-review | 完整审查循环        |

**练习建议：** 用 subagent-driven-dev 做一个完整功能，体验自动审查的质量提升。

***

## 八、对照阅读：OpenAI 的 Harness Engineering

> 2026 年 2 月，OpenAI 工程师 Ryan Lopopolo 发表了 [Harness Engineering](https://openai.com/index/harness-engineering/)，记录了一个内部实验：3 人团队用 5 个月、0 行手写代码，完全由 Codex Agent 生成了约 100 万行代码的生产级产品。人均日产 3.5 个 PR，估算效率是纯手写的 10 倍。

### 理念对比：殊途同归

两个项目的核心信念惊人地一致——**AI 写代码的瓶颈不是能力，而是纪律和环境**。

| 共识            | Superpowers 怎么做                               | Harness Engineering 怎么做             |
| ------------- | --------------------------------------------- | ----------------------------------- |
| 不能跳过设计直接写代码   | `brainstorming` + `writing-plans` 强制设计→计划     | 设计文档 + 执行计划作为一等公民签入仓库               |
| 必须有验证才能声称完成   | `verification-before-completion` 门禁           | CI linter + 结构化测试 + Agent 自驱动 UI 验证 |
| 架构约束要机械化执行    | Skill 规则写在 SKILL.md 里，1% Rule 强制加载            | 自定义 linter 强制分层依赖方向，违反即 CI 红灯       |
| 上下文不能一股脑倒给 AI | Skill 按需加载（渐进式披露）                             | AGENTS.md 只当目录，指向 `docs/` 深层文档      |
| 代码审查不能走过场     | `spec-reviewer` + `code-quality-reviewer` 双阶段 | Agent-to-Agent 审查循环，直到所有审查者满意       |
| 技术债要持续清理      | `receiving-code-review` 的 YAGNI 检查            | "垃圾回收"机制：后台 Agent 定期扫描偏差，开修复 PR     |

### 关键差异：作用层面不同

一句话：**Superpowers 管 Agent 的行为，Harness Engineering 管 Agent 的环境。**

```
Superpowers（个人/团队层）
  "Agent 写代码时应该遵守什么规矩"
  → Skill = 行为规则，注入 Agent 的 prompt

Harness Engineering（组织/基础设施层）
  "仓库应该长什么样，Agent 才能可靠工作"
  → 架构约束 + 可观测性 + CI 门禁 + 知识库结构
```

| 维度     | Superpowers         | Harness Engineering           |
| ------ | ------------------- | ----------------------------- |
| 作用对象   | Agent 的行为（prompt 层） | Agent 的环境（仓库 + 工具链）           |
| 人写不写代码 | 人和 AI 协作写           | 0 行手写，人只设计环境                  |
| 典型用户   | 独立开发者 / 小团队         | 有基础设施投入能力的工程团队                |
| 质量保障   | Skill 规则 + 子代理审查    | 自定义 linter + CI + Agent 自测 UI |
| 上下文管理  | Skill 渐进加载          | 仓库即知识库 + 文档园丁 Agent           |
| 可观测性   | 无（靠人看输出）            | 完整本地可观测栈（日志 / 指标 / 链路追踪）      |

**两者不冲突，反而互补。** Superpowers 的 Skill 可以作为 Harness Engineering 环境中的行为层——在一个架构严格、可观测性完备的仓库里，Agent 同时遵守 TDD、根因分析、验证门禁等行为纪律，效果叠加。

### AI 工程化落地的 8 条经验

以下经验综合了两个项目的实践，适用于任何正在引入 AI 辅助开发的团队。

**1. 工程师的角色正在从"写代码"变成"设计环境"**

OpenAI 的团队发现，早期进展慢不是因为 Codex 能力不够，而是环境"欠规格"——Agent 缺少工具、抽象和结构来完成高层目标。Superpowers 的 `brainstorming` 和 `writing-plans` 解决的是同一个问题：AI 不是不能做，是不知道该做什么。**技术领导要投资的不是更强的模型，而是更好的脚手架。**

**2. 仓库就是知识库——不在仓库里的知识对 Agent 不存在**

OpenAI 的原话："What Codex can't see doesn't exist." Slack 里对齐的架构决策、口头传达的产品原则、人脑里的隐式知识——Agent 一概看不到。**推动团队把决策写进仓库**（设计文档、ADR、执行计划），而不是停留在聊天记录里。这对人类新成员同样有益。

**3. 给 AI 一张地图，而不是一本千页手册**

OpenAI 试过把所有指令塞进一个大 AGENTS.md，失败了——上下文是稀缺资源，塞太多反而让 Agent 抓不住重点。Superpowers 的 `using-superpowers` 用 1% Rule 按需加载 Skill，而不是一次全部注入。**控制信息密度，用渐进式披露替代信息轰炸。**

**4. 架构约束要尽早建立，而且必须机械化执行**

OpenAI 在项目第一天就建立了严格的分层依赖规则（Types → Config → Repo → Service → Runtime → UI），用自定义 linter 强制执行。通常你会觉得"等团队到几百人再搞架构治理"，但在 Agent 时代，**架构约束是速度的前提，不是速度的代价**。没有约束的 Agent 会以 10 倍速度制造技术债。

**5. 纠错成本低的时候，合并哲学要变**

当 Agent 吞吐量远超人类审查能力时，OpenAI 选择了最小化阻塞式合并门禁——PR 短命、测试 flake 用 follow-up 修复而不是无限阻塞。**在低吞吐环境下这很危险，但在高吞吐环境下，等待比纠错更贵。** 技术领导需要根据团队的实际 Agent 吞吐量重新校准合并策略。

**6. AI 代码的技术债需要"垃圾回收"机制**

Agent 会复制仓库中已有的模式——包括不好的模式。OpenAI 的团队曾经每周五花 20% 时间手动清理"AI slop"，后来改为自动化：编码"黄金原则"，让后台 Agent 定期扫描偏差并开修复 PR。**不要指望 Agent 不制造技术债，要建立持续清理的机制。**

**7. "无聊"的技术选型对 Agent 更友好**

OpenAI 发现，API 稳定、可组合、训练集覆盖充分的"无聊"技术，比新潮但 Agent 难以推理的技术更有效。他们甚至会让 Agent 重新实现一个功能子集，而不是依赖行为不透明的第三方库。**技术选型时增加一个评估维度：Agent 能不能理解和可靠使用这个工具？**

**8. 从纪律层开始，不要试图一步到位**

Superpowers 的渐进式路径（3 个 Skill → 14 个 Skill，4 周计划）和 OpenAI 的深度优先方法（先建最小构建块，再解锁复杂任务）传达同一个信息：**不要试图一步建成完整的 AI 工程化体系。** 先装 TDD + 验证 + 调试三个纪律，就能解决 80% 的 AI 翻车问题。基础设施层（可观测性、自动审查、知识库结构）在团队积累经验后再逐步叠加。

***

## 九、总结

**Superpowers 的本质**不是让 AI 做更多事，而是让 AI **做对事**。14 个 Skill 覆盖了从创意到交付的完整生命周期，核心建立在三个基石上：

* **纪律优先**：流程不是建议而是规则
* **隔离与专注**：每个子任务独立执行，互不污染
* **证据驱动**：不说"应该可以了"，而是"我运行了命令，输出是..."

**Rex-CLI 的启示**是：纪律层之上还需要基础设施。持久化记忆、程序化编排、成本追踪、隐私保护——这些是纪律层解决不了的工程问题。

**实际行动建议：**

1. **今天就装 3 个 Skill**（TDD + Debugging + Verification），零成本获得最高频翻车问题的防护
2. **下周加设计层**，体验"想清楚再动手"的效率提升
3. **逐步叠加**，按需升级，不要试图一次掌握全部

按你的场景选 3-14 个 Skill 组合使用，从最小纪律开始，逐步构建你的 AI 工程化工作流。