Agent Harness系列：要用好superpowers，我们先把它拆开看一看

本文面向已经在用或准备用 coding agent 做工程的开发者。不吹"AI 写代码很厉害"，只讲一件事：Superpowers 到底是怎么把软件工程方法论"编译"成技能、让 Agent 从"会写码"变成"有纪律"，以及它留给我们的那个没人填的坑——串行执行。

开场：AI 编码不缺会写代码的 Agent，缺工程纪律

过去一年，coding agent 的进步让人误以为"给 Agent 一个需求，它就会像资深工程师一样干活"。真实情况是：裸 Agent 写代码没有章法。它会在你还没想清楚需求时就开始写；它不写测试；它不读现有代码结构；它声称"完成"但从不验证；一个改动可能破坏三个模块。

这不是能力问题，是纪律问题。就像让一个绝顶聪明但从不守规矩的程序员直接上生产代码库——他写得出漂亮代码，也埋得下漂亮的雷。

Superpowers（由 Jesse Vincent 和 Prime Radiant 团队维护，github.com/obra/superpowers）要解决的，正是"让 Agent 有工程纪律"这件事。它不教 Agent 写代码——它给 Agent 装上了一套完整的软件开发方法论，并且用技术手段强制 Agent 遵守。

一、架构三层：引导层、技能层、工具层

Superpowers 的架构可以拆成三层，理解这三层，就理解了它为什么有效。

1. 引导层：using-superpowers —— 让技能"自动触发"的 bootstrap

这是整套体系最容易被忽略、却最关键的一环。Superpowers 不是一个"技能文件夹"，它是一套在会话启动时注入的引导程序。

它的作用机制：harness 在 SessionStart 注入 using-superpowers skill，这段引导指令做了一件事——告诉 Agent："任何时候，只要有一个技能可能适用于你正在做的事，你就必须先调用它，没有例外。"

这意味着技能不是"给用户用的工具"，而是Agent 运行时自动加载的行为约束。Superpowers 官方在贡献指南里说得很直白：没有这个 bootstrap，技能就只是"磁盘上的死文件——存在但永远不会被调用"。

你可以把它理解成代码中的 __init__：它定义了 Agent 处理一切任务的默认行为协议。

2. 技能层：14 个技能，四族分工

Superpowers 的核心是 14 个技能（v6.2.0），按职责分四族：

注意协作族占了 9 个——Superpowers 的真正重点不在"写代码"，而在"把软件的协作过程流程化"。

3. 工具层：worktree 隔离、子代理隔离、ledger 记忆

技能只是指令，真正让指令落地的是三个配套机制：

• git worktree 隔离：每次功能开发都在独立的 worktree + 分支上进行，主分支永远干净。

• 子代理上下文隔离：每个任务派发一个"干净"的子代理，它只拿到自己任务所需的上下文，不继承主会话的历史——既防止上下文污染，也保护主会话的上下文预算。

• ledger（progress.md）持久化：SDD 用 .superpowers/sdd/<plan>/progress.md 记录每个任务的完成状态。这不是给用户看的，是给 Agent 自己看的——会话压缩后，Agent 靠 ledger 而不是记忆恢复进度。

二、实战：一个需求从想法到合入，Superpowers 是怎么管的

架构讲完，看真实的执行链路。Superpowers 官方 README 定义的标准流程是 7 步：

Step 1：brainstorming —— 先想清楚，再动手

你抛出一个想法，Agent 不会立刻写代码。它会像 苏格拉底 对话一样一个问题一个问题地问你，把模糊想法磨成明确需求。设计确认后才写成设计文档。

它强制了什么： HARD-GATE  —— 在用户批准设计之前，禁止调用任何实现技能、禁止写任何代码。这条铁律挡掉了 Agent 最常见的毛病：抢跑。

Step 2：using-git-worktrees —— 隔离工作区

设计批准后，先建隔离的 worktree 和分支，跑项目 setup，验证测试基线是绿的。脏基线会让之后所有失败都变得不可归因，所以必须先确认起点干净。

Step 3：writing-plans —— 把设计翻译成可执行的步骤

这是把"设计文档"变成"实现计划"。要求极端具体：每个任务 2-5 分钟粒度，每个步骤包含精确文件路径、完整代码、验证步骤。计划是为"一个热情的初级工程师"写的——他对代码库一无所知、审美可疑、厌恶测试。

计划文档有严格格式：Header（目标/架构/技术栈/全局约束）+ 任务列表（Files / Interfaces / 逐步 TDD 步骤）。

Step 4：subagent-driven-development —— 子代理逐任务执行

SDD 是这个体系的核心执行机制。每个任务派一个全新子代理（上下文隔离），实现 + 自测 + 提交；然后派一个任务审查者（同样是独立子代理）做双段审查：规格符合性 + 代码质量。发现问题进修复循环，最多 5 轮。

这里有一句原文值得记住（后面会反复用到）：

"Never dispatch multiple implementation subagents in parallel (conflicts)." —— subagent-driven-development 明令禁止并行派发实现子代理。

Step 5：test-driven-development —— 先写测试

实现阶段强制 RED-GREEN-REFACTOR：先写失败的测试 → 看着它失败 → 写最小实现 → 看着它通过 → 提交。测试先行不是"最佳实践"，是纪律——先于测试写的代码会被删除。

Step 6：requesting-code-review —— 任务间审查

每个任务完成后审查，按严重度分级。Critical 阻塞进度。

Step 7：finishing-a-development-branch —— 收尾

全部任务完成，最终全分支审查（用最强模型），跑测试，然后给你三个选项：合并 / 开 PR / 保留分支。收尾后清理 worktree。

三、它到底强在哪：三个支撑机制

抛开具体流程，Superpowers 的有效性来自三个底层机制：

① 上下文隔离 每个子代理只拿到它该知道的。执行任务的子代理看不到主会话的历史，审查者看到的只是 diff 包。这防止了两件事：上下文污染（Agent 把不相干的历史带进决策）和主会话上下文爆炸（主会话只管协调，不装实现细节）。

② 证据驱动 "验证通过才算完成"不是口号。TDD 要求先看测试失败再看它通过；verification-before-completion 要求你演示证据；最终审查要过审查者。Agent 无法靠"我认为没问题"过关——必须拿出可复现的证据。

③ 过程可恢复 ledger + git 历史让 Agent 在会话压缩、甚至崩溃后都能从 progress.md 恢复进度，而不是靠记忆重来。这是为长周期自主工作设计的。

四、问题：一台优秀的单需求执行引擎，却不是多需求调度系统

现在到了本文的重点。Superpowers 把"一个需求从想法到交付"做到了极致，但它有一个结构性的、被大多数教程忽略的缺陷：

Superpowers 是单需求执行引擎，不是多需求调度系统。

翻译成人话：它一次只能老老实实跑完一个需求，你没法在它跑 A 需求的同时讨论 B 需求。

问题 1：需求与实现强耦合

Superpowers 的流程是"需求 A 进来 → brainstorm → 设计 → 计划 → 实现 → 验收 → 结束 → 才能开需求 B"。整个生命周期里，主会话被需求 A 占住。你想趁它实现 A 的时候讨论 B？做不到——因为流程模型里没有 B 的位置。

这就是用户最真实、最痛的体感："每次只能等着当前迭代完成，然后再进入下一轮需求讨论。"

问题 2：SDD 明令禁止并行

SDD 的规则原文已经写明了："Never dispatch multiple implementation subagents in parallel (conflicts)." 这不是疏忽，是刻意的设计取舍——多个实现子代理同时改代码，会互相踩踏、制造冲突、让审查失去意义。为了避免踩踏，Superpowers 选择了串行。

但这是有代价的：串行意味着吞吐上限 = 单需求的完成时间。需求越多，等待越久。

问题 3：dispatching-parallel-agents 只覆盖调试场景

有人会说"Superpowers 不是有 dispatching-parallel-agents 吗？"。对，但它解决的问题域完全不同。看它的触发条件：

"Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies"

它针对的是调试场景——多个独立的测试文件同时挂了，各派一个子代理去修（修 A 不影响修 B）。它解决的是"多个独立故障"，不是"多个独立需求"。需求的实现往往共享代码库、共享模块、有依赖关系——这正是它明确说"Don't use when"的场景。

所以：Superpowers 有"并行修 bug"的能力，但没有"并行开发多个需求"的能力。

问题 4：缺一整套调度层能力

具体列一下，Superpowers 缺什么：

• ❌ 没有需求 backlog——需求不能"先存起来再说"，必须当下做完。

• ❌ 没有跨需求依赖分析——需求 A 依赖需求 B ？没人管，反正一个个来。

• ❌ 没有冲突检测——需求 A 和需求 C 语义冲突？同样没人管。

• ❌ 没有并发上限管理——不是"上限 0"（串行），而是根本没有"并发"这个概念。

• ❌ 没有调度视角的报告——你永远看不到"哪些需求现在能并行跑、哪些在等谁、哪些有冲突"。

定性：串行不是 bug，是取舍——但它就是吞吐瓶颈

必须公平地说：串行是 Superpowers 主动选择的取舍。它优先保证正确性（不踩踏、可审查、可回滚），牺牲了吞吐。对一个小团队、一个小需求，这完全正确。

但当需求积累到两位数、当你想"一边跑 A 一边聊 B"、当你希望多个独立需求并行推进时——取舍就变成了瓶颈。

而解决问题的方向也很清晰：Superpowers 已经把"执行引擎"做到位了，问题不在执行，在调度。缺的是一层"多需求调度器"叠在它上面。

结语：给执行引擎装一个调度器

Superpowers 是好东西——它把 Agent 从"会写码"变成了"有纪律地写码"。但它的纪律是单线程的纪律。真实研发不是单线程的：需求有优先级、有依赖、有冲突、可以并行。

下一篇，我会讲我们在这台执行引擎上叠的一层调度器——wdp-prd。它不做 Superpowers 已经做好的事，只做它没做的事：把需求变成持久化卡片，用依赖/冲突算法算出"现在谁能并行、谁在等谁、谁有冲突"，然后交给 Superpowers 去执行。

下一篇：给 Superpowers 套一层调度器：wdp-prd