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 的 14 个 Skill，覆盖从创意到交付的完整软件生命周期，并从 Rex-CLI 项目中提炼出值得借鉴的基础设施设计模式。
一、为什么 AI 写代码需要”纪律”
用 AI 写代码一段时间后，你大概率遇到过这些场景：
| # | 翻车场景 | 根因 |
|---|
| 1 | AI 说”完成了”，但功能根本没跑通 | 不验证就报告成功 |
| 2 | 改了 A 模块，B 模块悄悄坏了 | 没有测试保护 |
| 3 | Bug 修了 3 次还没修好 | 没做根因分析，靠猜 |
| 4 | 需求理解偏了，500 行代码白费 | 没有设计环节 |
| 5 | 计划太模糊，“添加验证逻辑”没法执行 | 计划粒度不够 |
| 6 | 让 AI 修 10 个测试，它把测试改成永远通过 | 没有约束和隔离 |
| 7 | 代码在 main 分支上乱改，回滚困难 | 没有工作区隔离 |
| 8 | 功能做完不知道怎么收尾，分支散落一地 | 没有标准收尾流程 |
没有纪律：想法 → 直接写代码 → "应该好了" → 出 bug → 猜修复 → 循环...
有了纪律：想法 → 设计 → 计划 → TDD 实现 → 审查 → 验证 → 交付
项目地址：https://github.com/obra/superpowers
Claude Code
通过官方插件市场安装：
/plugin install superpowers@claude-plugins-official
superpowers:brainstorming 等命名空间前缀被识别。
其他平台
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
三、完整软件生命周期：从想法到交付
以”接手一个产品需求”为例，看 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 步流程概要：
- 探索项目上下文
- 提供 Visual Companion（如有视觉需求）
- 一次一个澄清问题（优先选择题而非开放题）
- 提出 2-3 种方案并给出推荐
- 分段展示设计，逐段获得批准
- 写入设计文档
- spec-reviewer 子代理审查（最多 5 轮）
- 用户最终审核
- 转交 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 个以上独立问题同时存在，每个问题可以在不了解其他问题的情况下解决。
核心判断流程：
多个失败？→ 它们独立吗？→ 能并行工作吗？→ 并行派遣！
↓ 不独立 ↓ 有共享状态
单一代理调查 顺序处理
- 具体范围 — 一个测试文件或子系统
- 明确目标 — “让这 3 个测试通过”
- 约束条件 — “不要修改其他代码”
- 预期输出 — “总结发现了什么和修复了什么”
反模式（避免）：
- 太宽泛：“修复所有测试” → 代理会迷失
- 无上下文：“修复竞态条件” → 代理不知道在哪
- 无约束：代理可能重构一切
4.9 requesting-code-review — 主动请求审查
触发时机： subagent-driven-dev 中每个任务完成后、主要功能完成后、合并到 main 前。
流程：
- 获取 git SHA（BASE_SHA 和 HEAD_SHA）
- 派遣审查子代理
- 根据反馈严重级别行动：
- 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 个选项：
- 本地合并回基础分支
- 推送并创建 Pull Request（最常用）
- 保留分支原样
- 丢弃这些工作
流程： 验证测试 → 确定基础分支 → 呈现 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 | 发现新漏洞 → 堵住 → 重新测试 |
五、7 种场景化组合方案
不需要一上来就装全部 14 个 Skill。按场景选 3-14 个组合使用。
方案 1：最小纪律（3 个 Skill）
适合： 日常编码、快速原型、side project
test-driven-development ← 写代码有测试保护
systematic-debugging ← 遇 bug 做根因分析
verification-before-completion ← 说完成前必须跑验证
方案 2：设计先行（5 个 Skill）
适合： 需要想清楚再动手，但不需要复杂的执行编排
方案 1 的 3 个 + 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
方案 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 是一个开源的 AI 开发辅助工具。
一句话理解两者的关系： Superpowers 是一套”规矩”——告诉 AI 该怎么做事（先写测试、先做设计、完成前要验证）；Rex-CLI 是一套”配套工具箱”——帮你把这些规矩落地，还额外提供了记忆存储、多 Agent 编排、成本追踪等 Superpowers 管不了的基础设施能力。
打个比方：Superpowers 像驾校教材（教你怎么开车），Rex-CLI 像一辆装好了导航、行车记录仪、油耗仪表的车——教材的规矩内置在车里，但车还额外提供了教材覆盖不到的工具。
更技术化的类比：
| 定位 | 类比 |
|---|
| Superpowers | AI Agent 的”开发流程宪法” | 交通法规——定义规则，不建公路 |
| Rex-CLI | AI Agent 的”开发操作系统” | 公路系统——铺路 + 执行交通法规 |
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 先分析后修复，不猜 |
第 2 周：掌握设计流程
| 学什么 | 目标 |
|---|
| brainstorming | 学会”想清楚再动手” |
| writing-plans | 学会写细到每步 2-5 分钟的可执行计划 |
第 3 周：掌握执行和收尾
| 学什么 | 目标 |
|---|
| using-git-worktrees | 学会工作区隔离 |
| executing-plans | 用正式框架执行计划 |
| finishing-a-development-branch | 标准化收尾 |
第 4 周：进阶编排
| 学什么 | 目标 |
|---|
| subagent-driven-development | 多代理协作 + 双阶段审查 |
| dispatching-parallel-agents | 并行解决独立问题 |
| requesting / receiving-code-review | 完整审查循环 |
八、对照阅读：OpenAI 的 Harness Engineering
2026 年 2 月，OpenAI 工程师 Ryan Lopopolo 发表了 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 |
| 可观测性 | 无（靠人看输出） | 完整本地可观测栈（日志 / 指标 / 链路追踪） |
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 的启示是：纪律层之上还需要基础设施。持久化记忆、程序化编排、成本追踪、隐私保护——这些是纪律层解决不了的工程问题。
实际行动建议：
- 今天就装 3 个 Skill（TDD + Debugging + Verification），零成本获得最高频翻车问题的防护
- 下周加设计层，体验”想清楚再动手”的效率提升
- 逐步叠加，按需升级，不要试图一次掌握全部
按你的场景选 3-14 个 Skill 组合使用，从最小纪律开始，逐步构建你的 AI 工程化工作流。