Superpowers：把软件工程实践写进 Coding Agent 工作流

1. 引言：Coding Agent 不缺产出能力，缺默认工程实践

最新 Coding Agent 已经能写相当多代码。它能读仓库、改文件、跑命令、解 bug，也能在局部模块给出资深工程师水平的实现。但它真正的问题往往不是「不会写」，而是「写得不好」。

当用户说「帮我加一个登录功能」，普通 Coding Agent 很容易直接开写：建表、写接口、补前端页，最后告诉你 done。问题是，它可能没有确认认证方式是 password、OAuth 还是 passkey；没有问失败重试、锁定策略、错误码、数据迁移、兼容旧用户和测试范围；也没有确认这次到底是 MVP、后台能力，还是对外的生产功能。这不是单纯的模型能力问题，而是工程流程缺失的问题。

人类工程师是有经验的，他们会在动手前形成一套隐性的检查清单：需求要澄清，方案要对齐，工作区要隔离，测试要先定义正确性，代码要评审，交付前要验证。而 Agent 没有这种稳定的职业习惯，除非把它显式编码进上下文和 workflow。

这正是 Superpowers 这类工具发挥作用的地方：它没有重新发明一套 Agent runtime，而是在回答一个更工程化的问题：怎样让已有的 Agent 遵守已知的软件工程最佳实践？它的答案是：把成熟工程师的工作流编码成可触发、可组合、可验证的 agentic workflow。

2. Superpowers：把工程实践拆成可复用 SOP

表面上看，Superpowers 只是一个 skills 集合，但事实上，它更接近于一套面向 Coding Agent 的软件工程方法论。它把开发流程拆成一组可组合的 skills，再通过 hook 和 plugin manifest 适配 Claude Code、Codex、Cursor 等 Agent runtime。

它的静态结构非常清楚：skills/ 定义工程 SOP，hooks/ 负责启动注入，plugin manifests（.*-plugin/）负责跨平台适配，scripts/ 和 tests/ 则服务同步、发布和验证：

Text

superpowers/
├── skills/                         # 可触发的软件工程 SOP
│   ├── using-superpowers/
│   ├── brainstorming/
│   ├── writing-plans/
│   ├── test-driven-development/
│   ├── subagent-driven-development/
│   ├── requesting-code-review/
│   ├── receiving-code-review/
│   ├── verification-before-completion/
│   └── finishing-a-development-branch/
├── hooks/                          # 把启动规则注入 Agent session
│   ├── session-start
│   ├── hooks.json
│   ├── hooks-cursor.json
│   └── run-hook.cmd
├── .claude-plugin/
├── .codex-plugin/
├── .cursor-plugin/
├── .opencode/                      # 各 runtime 的 plugin / extension 适配
├── docs/
├── scripts/
└── tests/

2.1 Skills：工程实践的最小单元

Skills 是方法论的核心。每个 skill 都是一份可渐进式加载的 markdown 文档集合：它说明适用场景、执行步骤、常见误区和完成条件，让 Agent 在特定阶段拿到一段明确的工程 SOP：

#	Phase	Skills	Practice	Agent problem
1	Bootstrap	`using-superpowers`	工作前先检查流程	忘记加载相关 skill
2	Requirement Clarification	`brainstorming`	先澄清需求和设计	听到需求就开写
3	Planning	`writing-plans`	写可执行 implementation plan	计划空泛、缺文件和验证步骤
4	Workspace Setup	`using-git-worktrees`	隔离开发环境	污染当前分支或用户改动
5	Execution	`subagent-driven-development`、`executing-plans`	按任务执行和跟踪	长上下文漂移、跳步骤
6	Parallel Investigation	`dispatching-parallel-agents`	独立问题并行排查	把无关问题串行处理
7	Development Discipline	`test-driven-development`	Red → Green → Refactor	先写实现后补测试
8	Debugging	`systematic-debugging`	先找根因再修复	猜测式改代码
9	Review	`requesting-code-review`、`receiving-code-review`	早 review，认真处理反馈	自我确认、盲从 reviewer
10	Verification	`verification-before-completion`	证据先于结论	没跑验证就说完成
11	Finishing	`finishing-a-development-branch`	交付前选择 merge / PR / keep / discard	完成后状态混乱
12	Meta	`writing-skills`	用 TDD 写流程文档	skill 本身不可验证

这张表不是硬编码的状态机，而是典型的任务路径示例。当 Coding Agent 在真实执行时，Main Agent 会根据当前上下文选择 skill：遇到失败进入 systematic-debugging，遇到并行调查进入 dispatching-parallel-agents，写新 skill 时进入 writing-skills 等。

2.2 Hooks：把启动规则注入 session 起点

Hooks 是启动注入层：其核心是 session-start，它会读取 using-superpowers skill，将它包装成额外上下文输出给 runtime。hooks.json 负责把 SessionStart 绑定到启动、清空、压缩等事件；hooks-cursor.json 则是把同一套启动规则接入 Cursor 的 sessionStart。

2.3 Plugin manifests：跨平台适配层

Plugin manifests 是平台适配层。.codex-plugin/、.cursor-plugin/、.claude-plugin/ 分别服务于 Codex、Cursor、Claude Code，指定 skills 目录、插件元数据、hook 配置等信息，把同一套工程实践暴露给不同的 Coding Agent。

3. 软件工程：如何完整地跑一次任务

下面用一次典型任务说明这些组件如何服务于软件工程，先定义几个角色：

Role	Responsibility	Why it matters
User	提出目标、确认需求、批准关键方案	防止 Agent 自行扩大或误解目标
Agent Runtime	执行会话、注入上下文、提供工具入口	决定 skill 和 hook 如何被加载
Main Agent	判断阶段、加载 skill、拆分任务、整合结果	把松散能力组织成工程流程
Skill Loader	读取匹配的 skills	让 SOP 在需要时进入上下文
Implementer Subagent	按任务实现、测试、提交、自查	隔离上下文，减少主会话污染
Reviewer Subagent	做代码审核（合规与质量）	把「做对」和「做好」分开检查
Tool Executor	执行 shell、文件、git、测试等操作	把自然语言决策转成可验证动作

3.1 Session Bootstrap：让流程进入上下文

任务开始前，Agent Runtime 运行 session-start hook，它会读取 using-superpowers skill，将「行动前须检查相关 skill」注入上下文：

mermaid

sequenceDiagram
    actor User as User
    participant Runtime as Agent Runtime
    participant Main as Main Agent
    participant Skill as Skill Loader
    participant Impl as Implementer Subagent
    participant Review as Reviewer Subagent
    participant Tool as Tool Executor

    rect rgba(148,163,184,0.14)
        Note over Runtime,Main: Session Bootstrap
        Runtime->>Runtime: Run `session-start` hook
        Runtime->>Tool: Read `using-superpowers`
        Tool-->>Runtime: Return startup instructions
        Runtime-->>Main: Start Main Agent with injected workflow rules
    end

这一步不直接处理业务需求，只负责把后续判断的入口放进上下文。Main Agent 一进入会话，就先知道自己需要检查有没有适用 skill。

这里 using-superpowers 更像软调度器。它不是传统的 workflow engine，不维护外部状态表，也不硬编码「第一步必须 X，第二步必须 Y」；它只把一条规则放进上下文：行动前先检查有没有适用的 skill，多个 skill 同时适用时优先加载流程类 skills。

这种方式轻量、跨平台、易扩展，新增 skill 不需要改 runtime。代价是约束仍然依赖 Main Agent 对上下文的解释，不如代码状态机强。

3.2 Requirement Clarification：先澄清需求

用户提交任务后，Main Agent 通过 using-superpowers skill 判断是否需要加载 brainstorming skill 进行头脑风暴。如果任务涉及设计、功能或行为变更，就先理解项目上下文，再逐步确认目的、约束和成功标准：

mermaid

sequenceDiagram
    actor User as User
    participant Runtime as Agent Runtime
    participant Main as Main Agent
    participant Skill as Skill Loader
    participant Impl as Implementer Subagent
    participant Review as Reviewer Subagent
    participant Tool as Tool Executor

    rect rgba(59,130,246,0.14)
        Note over User,Main: Requirement Clarification
        User->>Main: Submit coding task
        Main->>Skill: Check applicable skills via `using-superpowers`
        Skill-->>Main: Use matching skill before proceeding
        Main->>Skill: Load `brainstorming`
        Skill-->>Main: Return brainstorming SOP
        loop Until direction is clear
            Main->>User: Clarify goals, constraints, edge cases, and success criteria
            User-->>Main: Answer and refine direction
        end
    end

这一步对应人类工程师最基本的职业习惯：不把「一句话需求」直接翻译成代码，而是把模糊目标变成可验证的约束，避免 Agent 写出功能完整但方向错误的实现。

3.3 Planning：先写计划，再写代码

需求澄清后，Main Agent 加载 writing-plans skill，把已经确认的 spec 写成 implementation plan。这个 plan 不是「实现登录」这种一句话计划，而是包含文件路径、测试代码、命令、预期输出和提交步骤的任务列表，并请求用户确认：

mermaid

sequenceDiagram
    actor User as User
    participant Runtime as Agent Runtime
    participant Main as Main Agent
    participant Skill as Skill Loader
    participant Impl as Implementer Subagent
    participant Review as Reviewer Subagent
    participant Tool as Tool Executor

    rect rgba(34,197,94,0.13)
        Note over Main,Tool: Planning
        Main->>Skill: Load `writing-plans`
        Skill-->>Main: Return planning SOP
        Main->>Tool: Write implementation plan with files, tests, and commands
        Tool-->>Main: Plan document created
        Main->>User: Ask for plan approval
        alt Changes requested
            User-->>Main: Request plan changes
            Main->>Tool: Revise implementation plan
            Tool-->>Main: Updated plan
        else Approved
            User-->>Main: Approve plan
        end
    end

计划不是为了仪式感，而是把隐性的判断外显成明确的文字——哪些文件会改、哪些行为要测、哪些命令能证明结果、哪些地方需要用户确认，都应该在写代码前暴露出来。后面的代码实现、评审与验证才有共同的参照。

3.4 Isolated Workspace Setup：隔离工作区

进入实现前，Main Agent 加载 using-git-worktrees skill，先检测当前是否已经在隔离 worktree，再决定创建或复用 worktree / branch。核心目标是保护当前分支和用户未提交改动，让 Agent 的实验空间和主工作区隔离：

mermaid

sequenceDiagram
    actor User as User
    participant Runtime as Agent Runtime
    participant Main as Main Agent
    participant Skill as Skill Loader
    participant Impl as Implementer Subagent
    participant Review as Reviewer Subagent
    participant Tool as Tool Executor

    rect rgba(245,158,11,0.14)
        Note over Main,Tool: Isolated Workspace Setup
        Main->>Skill: Load `using-git-worktrees`
        Skill-->>Main: Return worktree SOP
        Main->>Tool: Detect current workspace state
        Tool-->>Main: Current repo, branch, and worktree status
        Main->>Tool: Create or reuse isolated worktree and branch
        Tool-->>Main: Worktree and branch ready
        Main->>Tool: Run preflight checks if available
        Tool-->>Main: Preflight result
        alt Preflight fails
            Main-->>User: Report blocking issue before implementation
        else Preflight passes or no check exists
            Main->>Main: Continue to plan execution
        end
    end

隔离工作区之后，还需要先确认当前起点是干净的：依赖能安装、项目能启动，已有的 test / lint / build 至少按项目现状跑一遍。它并不是检查新功能是否正确，而是检查当前环境是否足够可信。否则后面遇到失败时，Agent 很难判断问题来自这次改动，还是项目的初始状态本身就有问题。

3.5 Plan Execution：subagent、TDD 与任务推进

执行阶段，Main Agent 加载 subagent-driven-development skill，将每个任务分配给 Implementer Subagent，Implementer 再按需要加载 test-driven-development skill，遵守 Red → Green → Refactor：先写失败测试，确认失败原因正确，再写最小实现，再重构：

mermaid

sequenceDiagram
    actor User as User
    participant Runtime as Agent Runtime
    participant Main as Main Agent
    participant Skill as Skill Loader
    participant Impl as Implementer Subagent
    participant Review as Reviewer Subagent
    participant Tool as Tool Executor

    rect rgba(168,85,247,0.13)
        Note over Main,Impl: Plan Execution
        Main->>Skill: Load `subagent-driven-development`
        Skill-->>Main: Return subagent execution SOP
        loop Each task in plan
            Main->>Impl: Assign one task with acceptance criteria
            Impl->>Skill: Load `test-driven-development`
            Skill-->>Impl: Return TDD SOP
            Impl->>Tool: Write failing test
            Tool-->>Impl: RED: test fails for expected reason
            Impl->>Tool: Implement minimal code
            Tool-->>Impl: Code changed
            Impl->>Tool: Run relevant tests
            Tool-->>Impl: GREEN: tests pass
            Impl->>Tool: Refactor and rerun tests
            Tool-->>Impl: Tests still pass
            Impl-->>Main: Return implementation result
        end
    end

这套流程解决的是 Agent 长上下文开发最常见的问题：越写越漂（drift）、一次塞太多变更、最后靠主观判断说完成。把 plan 拆成任务，再让每个任务用 TDD 推进，用更多的闭环小循环来保证结果与流程的正确性。

3.6 Two-Stage Review：先问做没做对，再问做得好不好

任务实现后，Main Agent 加载 requesting-code-review skill 进行代码评审，这里明确拆成两步：先做 spec compliance review，确认实现有没有做对、有没有漏需求、有没有多做；通过后再做 code quality review，检查结构、测试、可维护性和生产风险：

Review type	Question	Typical issues	Example
`spec compliance review`	有没有做对？	漏需求、多做功能、误解验收条件	需求要求登录失败 10 次返回 429，实现成失败 5 次返回 403
`code quality review`	做得好不好？	重复代码、耦合、错误处理弱、测试不实	功能符合需求，但限流逻辑硬编码在 controller 里

具体交互如下：

mermaid

sequenceDiagram
    actor User as User
    participant Runtime as Agent Runtime
    participant Main as Main Agent
    participant Skill as Skill Loader
    participant Impl as Implementer Subagent
    participant Review as Reviewer Subagent
    participant Tool as Tool Executor

    rect rgba(236,72,153,0.13)
        Note over Main,Review: Two-Stage Review
        Main->>Skill: Load `requesting-code-review`
        Skill-->>Main: Return review request SOP
        Main->>Review: Request spec compliance review
        Review-->>Main: Spec review result
        alt Spec issue found
            Main->>Skill: Load `receiving-code-review`
            Skill-->>Main: Return review handling SOP
            Main->>Impl: Send required spec fixes
            Impl->>Tool: Fix implementation and rerun relevant tests
            Tool-->>Impl: Verification result
            Impl-->>Main: Updated implementation result
        else Spec passes
            Main->>Review: Request code quality review
            Review-->>Main: Quality review result
            alt Quality issue found
                Main->>Skill: Load `receiving-code-review`
                Skill-->>Main: Return review handling SOP
                Main->>Impl: Send required quality fixes
                Impl->>Tool: Fix implementation and rerun relevant tests
                Tool-->>Impl: Verification result
                Impl-->>Main: Updated implementation result
            else Quality review passes
                Main->>Tool: Mark task complete in plan
                Tool-->>Main: Plan document updated
            end
        end
    end

这不是流程洁癖，而是在避免一种常见误判：实现质量高，不等于实现目标对。发现问题时，Main Agent 加载 receiving-code-review skill，把反馈转成修复任务，再回到实现和测试循环。

3.7 Final Verification：证据先于声明

所有任务完成后，Main Agent 加载 verification-before-completion skill，跑 full tests、lint、build 和关键检查。失败则加载 systematic-debugging skill，先复现、收集证据、定位根因，再决定修复方式：

mermaid

sequenceDiagram
    actor User as User
    participant Runtime as Agent Runtime
    participant Main as Main Agent
    participant Skill as Skill Loader
    participant Impl as Implementer Subagent
    participant Review as Reviewer Subagent
    participant Tool as Tool Executor

    rect rgba(20,184,166,0.13)
        Note over Main,Tool: Final Verification
        Main->>Skill: Load `verification-before-completion`
        Skill-->>Main: Return completion verification SOP
        Main->>Tool: Run full tests, lint, build, and key checks
        Tool-->>Main: Verification output
        alt Verification fails
            Main->>Skill: Load `systematic-debugging`
            Skill-->>Main: Return debugging SOP
            Main->>Tool: Reproduce failure and collect evidence
            Tool-->>Main: Evidence and logs
            Main->>Impl: Return to fix loop
        else Verification passes
            Main->>Main: Completion evidence is ready
        end
    end

这一步针对的是 Agent 最危险的汇报习惯：没有最新验证就说 done。这个环节把证据放在结论之前，要求 Agent 先跑命令、读输出、确认结果，再声明完成。

它和前面的 preflight checks 是两道门。两者都可能表现为「跑测试」，但回答的问题不同：preflight 发生在开工前，确认环境可信；final verification 发生在交付前，证明结果可信。

Gate	Timing	Purpose	Examples
`preflight checks`	开工前	确认工作区、依赖、项目状态可用	test、lint、build、dependency check、startup check
`final verification`	完成前	证明本次改动没有破坏目标结果	full tests、关键回归、build、需求 checklist

3.8 Branch Finishing：把开发状态收束干净

验证通过后，Main Agent 加载 finishing-a-development-branch skill，给出 merge、PR、keep、discard 等明确选项，并汇报验证证据：

mermaid

sequenceDiagram
    actor User as User
    participant Runtime as Agent Runtime
    participant Main as Main Agent
    participant Skill as Skill Loader
    participant Impl as Implementer Subagent
    participant Review as Reviewer Subagent
    participant Tool as Tool Executor

    rect rgba(99,102,241,0.13)
        Note over Main,User: Branch Finishing
        Main->>Skill: Load `finishing-a-development-branch`
        Skill-->>Main: Return branch finishing SOP
        Main->>User: Offer merge, PR, keep, or discard
        User-->>Main: Choose finishing action
        Main->>Tool: Execute chosen git action
        Tool-->>Main: Branch finishing done
        Main-->>User: Report result with verification evidence
    end

这一步看起来只是简单的收尾，但事实上非常重要。代码写完不等于任务结束，分支如何合并、是否开 PR、是否保留 worktree、是否丢弃实验，都需要一个明确动作。否则 Agent 很容易留下一个「好像完成了，但仓库状态不清楚」的尾巴。

到这里，Superpowers 的主线已经完整：它把一次任务拆成一组可触发的工程节点，让 Agent 在每个关键处触发与进入标准流程。

4. 结尾：真正的 superpower 是把工程实践变成默认路径

Superpowers 更像 workflow layer，不是完整 Agent runtime。它不直接解决 eval、observability、cost control、long-term memory、permission management，也不提供硬状态机、任务数据库或统一调度器。skills 的执行质量仍然依赖底层模型，多平台适配也会带来维护成本。

这个定位也让它的价值更清楚：Superpowers 不替代 runtime，它只负责把成熟工程师的默认路径注入 runtime。它没有把 eval 做完，却把 TDD、review、verification 和人工确认这些任务级约束编码得很清楚。

它真正有价值的地方，是把成熟工程师的隐性工程实践变成 Agent 的默认路径：先问清楚，先计划，隔离开发，写测试，接受 review，最后用证据交付。真正的 superpower 不是产出速度，而是在关键节点不跳过判断。

5. 附录：完整任务时序图

Superpowers 的完整工作时序图如下：

mermaid

sequenceDiagram
    autonumber

    actor User as User
    participant Runtime as Agent Runtime
    participant Main as Main Agent
    participant Skill as Skill Loader
    participant Impl as Implementer Subagent
    participant Review as Reviewer Subagent
    participant Tool as Tool Executor

    rect rgba(148,163,184,0.14)
        Note over Runtime,Main: Session Bootstrap
        Runtime->>Runtime: Run `session-start` hook
        Runtime->>Tool: Read `using-superpowers`
        Tool-->>Runtime: Return startup instructions
        Runtime-->>Main: Start Main Agent with injected workflow rules
    end

    rect rgba(59,130,246,0.14)
        Note over User,Main: Requirement Clarification
        User->>Main: Submit coding task
        Main->>Skill: Check applicable skills via `using-superpowers`
        Skill-->>Main: Use matching skill before proceeding
        Main->>Skill: Load `brainstorming`
        Skill-->>Main: Return brainstorming SOP
        loop Until direction is clear
            Main->>User: Clarify goals, constraints, edge cases, and success criteria
            User-->>Main: Answer and refine direction
        end
    end

    rect rgba(34,197,94,0.13)
        Note over Main,Tool: Planning
        Main->>Skill: Load `writing-plans`
        Skill-->>Main: Return planning SOP
        Main->>Tool: Write implementation plan with files, tests, and commands
        Tool-->>Main: Plan document created
        Main->>User: Ask for plan approval
        alt Changes requested
            User-->>Main: Request plan changes
            Main->>Tool: Revise implementation plan
            Tool-->>Main: Updated plan
        else Approved
            User-->>Main: Approve plan
        end
    end

    rect rgba(245,158,11,0.14)
        Note over Main,Tool: Isolated Workspace Setup
        Main->>Skill: Load `using-git-worktrees`
        Skill-->>Main: Return worktree SOP
        Main->>Tool: Detect current workspace state
        Tool-->>Main: Current repo, branch, and worktree status
        Main->>Tool: Create or reuse isolated worktree and branch
        Tool-->>Main: Worktree and branch ready
        Main->>Tool: Run preflight checks if available
        Tool-->>Main: Preflight result

        alt Preflight fails
            Main-->>User: Report blocking issue before implementation
        else Preflight passes or no check exists
            Main->>Main: Continue to plan execution
        end
    end

    rect rgba(168,85,247,0.13)
        Note over Main,Impl: Plan Execution
        Main->>Skill: Load `subagent-driven-development`
        Skill-->>Main: Return subagent execution SOP

        loop Each task in plan
            Main->>Impl: Assign one task with acceptance criteria

            Impl->>Skill: Load `test-driven-development`
            Skill-->>Impl: Return TDD SOP

            Impl->>Tool: Write failing test
            Tool-->>Impl: RED: test fails for expected reason

            Impl->>Tool: Implement minimal code
            Tool-->>Impl: Code changed

            Impl->>Tool: Run relevant tests
            Tool-->>Impl: GREEN: tests pass

            Impl->>Tool: Refactor and rerun tests
            Tool-->>Impl: Tests still pass

            Impl-->>Main: Return implementation result
        end
    end

    rect rgba(236,72,153,0.13)
        Note over Main,Review: Two-Stage Review
        Main->>Skill: Load `requesting-code-review`
        Skill-->>Main: Return review request SOP

        Main->>Review: Request spec compliance review
        Review-->>Main: Spec review result

        alt Spec issue found
            Main->>Skill: Load `receiving-code-review`
            Skill-->>Main: Return review handling SOP
            Main->>Impl: Send required spec fixes
            Impl->>Tool: Fix implementation and rerun relevant tests
            Tool-->>Impl: Verification result
            Impl-->>Main: Updated implementation result

        else Spec passes
            Main->>Review: Request code quality review
            Review-->>Main: Quality review result

            alt Quality issue found
                Main->>Skill: Load `receiving-code-review`
                Skill-->>Main: Return review handling SOP
                Main->>Impl: Send required quality fixes
                Impl->>Tool: Fix implementation and rerun relevant tests
                Tool-->>Impl: Verification result
                Impl-->>Main: Updated implementation result

            else Quality review passes
                Main->>Tool: Mark task complete in plan
                Tool-->>Main: Plan document updated
            end
        end
    end

    rect rgba(20,184,166,0.13)
        Note over Main,Tool: Final Verification
        Main->>Skill: Load `verification-before-completion`
        Skill-->>Main: Return completion verification SOP
        Main->>Tool: Run full tests, lint, build, and key checks
        Tool-->>Main: Verification output

        alt Verification fails
            Main->>Skill: Load `systematic-debugging`
            Skill-->>Main: Return debugging SOP
            Main->>Tool: Reproduce failure and collect evidence
            Tool-->>Main: Evidence and logs
            Main->>Impl: Return to fix loop

        else Verification passes
            Main->>Main: Completion evidence is ready
        end
    end

    rect rgba(99,102,241,0.13)
        Note over Main,User: Branch Finishing
        Main->>Skill: Load `finishing-a-development-branch`
        Skill-->>Main: Return branch finishing SOP
        Main->>User: Offer merge, PR, keep, or discard
        User-->>Main: Choose finishing action
        Main->>Tool: Execute chosen git action
        Tool-->>Main: Branch finishing done
        Main-->>User: Report result with verification evidence
    end

6. 参考资料

obra/superpowers: An agentic skills framework & software development methodology that works.