superpowers 是为 AI 编码智能体（如 Claude Code、Cursor、Codex 等）提供完整软件开发工作流的插件和技能 (Skill) 集合。项目通过引入“子智能体驱动开发 (SDD)”模式，强制 AI 在编写代码前进行需求澄清与任务拆解。核心特性包括：测试驱动开发 (TDD)的强制执行、双阶段代码审查（规范审查与质量审查），以及通过隔离的 Git 工作树和独立子智能体避免长上下文污染。该设计将 AI 从单纯的代码生成器转变为遵循严谨工程规范的虚拟开发团队。
项目采用高度解耦的声明式架构，核心逻辑由 Markdown 编写的技能约束定义，而非传统可执行代码。系统自上而下分为触发层、控制流层、技能执行层与基础设施层。
graph TD
subgraph 触发层
A[用户输入] --> B(IDE / CLI)
B --> C{Hook 拦截}
end
subgraph 控制流层
C -->|匹配意图| D[主智能体 Orchestrator]
D --> E[任务拆解与分发]
end
subgraph 技能与执行层
E --> F[技能模块 Skills]
F --> G[子智能体 Subagent]
F --> H[审查智能体 Reviewer]
end
subgraph 基础设施
G --> I[Git 工作树隔离]
H --> J[测试驱动执行 TDD]
end
系统核心由技能定义、独立审查智能体以及平台拦截钩子三部分组成，共同保障代码生成的规范性与可靠性。
SKILL.md 是项目的核心执行契约，由高度结构化的“人设与工作流约束”构成。以下提取 dispatching-parallel-agents/SKILL.md 的骨架作为示例：
## <!-- 该代码块展示了 dispatching-parallel-agents 技能的核心定义结构，包含触发条件与执行流程 -->
name: dispatching-parallel-agents
description: Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies
---
# Dispatching Parallel Agents
## Overview
When you have multiple unrelated failures (different test files, different subsystems, different bugs), investigating them sequentially wastes time. Each investigation is independent and can happen in parallel.
**Core principle:** Dispatch one agent per independent problem domain. Let them work concurrently.
## When to Use
```dot
digraph when_to_use {
"Multiple failures?" -> "Are they independent?" [label="yes"];
"Are they independent?" -> "Can they work in parallel?" [label="yes"];
"Can they work in parallel?" -> "Parallel dispatch" [label="yes"];
}
```
## The Pattern
### 1. Identify Independent Domains
Group failures by what's broken.
### 2. Create Focused Agent Tasks
Each agent gets: Specific scope, Clear goal, Constraints, Expected output.
### 3. Dispatch in Parallel
// In Claude Code / AI environment
Task("Fix agent-tool-abort.test.ts failures")
Task("Fix batch-completion-behavior.test.ts failures")
### 4. Review and Integrate
When agents return: Read each summary, Verify fixes don't conflict, Run full test suite.
## Common Mistakes
❌ Too broad: "Fix all the tests" - agent gets lost
✅ Specific: "Fix agent-tool-abort.test.ts" - focused scope
通过对比上述示例与项目中的其他技能文件 (如 systematic-debugging/SKILL.md )，我们可以归纳出编写一个标准技能 (Skill) 所必须遵循的结构范式：
name 和 description 开头。这是系统进行意图匹配和触发技能的唯一依据。例如，当用户要求“处理多个独立的测试失败”时，系统会根据这段描述来自动挂载 dispatching-parallel-agents 技能。Digraph)，明确告诉 AI 在何种上下文下才允许调用此技能 (如必须是多个失败且无状态共享)，以此防止技能滥用。项目在 agents/ 目录下定义了具有特定人设和约束的独立 AI 实例，确保代码生成与代码审查的关注点隔离。以 code-reviewer.md 为例，该审查员被设定为高级代码审查员，通过明确的 Prompt 约定其核心审查维度：
平台集成依赖于钩子拦截和快捷命令。
hooks/session-start 脚本在会话初始化时被触发。它通过 Bash 脚本读取 skills/using-superpowers/SKILL.md 的内容，并使用特定格式 (如 Cursor 的 additional_context 或 Claude Code 的 hookSpecificOutput) 将其注入为全局 <EXTREMELY_IMPORTANT> 上下文，从而让智能体在对话伊始就“知道”自己拥有调用技能的能力。
hooks/session-start.sh；请以仓库实际文件为准。commands/ 目录下的 brainstorm.md 包含系统性提问的提示词，要求 AI 扮演资深产品经理/架构师，采用苏格拉底式提问来精炼用户需求，强制其在生成任何代码或计划前，先澄清所有的歧义与假设。子智能体驱动开发 (SDD) 涵盖从意图对齐到代码合并的完整闭环，通过多角色接力确保代码质量。
主智能体首先触发 brainstorming 技能，通过多轮对话澄清用户需求。需求确定后，调用 writing-plans 技能将目标拆解为粒度为 2-5 分钟的原子任务，并输出包含精确文件路径和验证步骤的计划文档至 docs/superpowers/plans/ 目录。
针对计划中的每个任务，主智能体派发一个全新的实现者子智能体 (隔离上下文)。该子智能体必须遵循 test-driven-development 技能，执行“红-绿-重构”循环：先编写失败的测试用例，再编写极简代码使其通过，最后进行提交和自我审查。
实现者提交代码后，系统依次调用两级审查：首先由规范审查子智能体核对代码是否满足原计划需求，无遗漏或过度设计；通过后，再由质量审查子智能体评估代码风格与健壮性。任何阶段发现问题均会打回要求修复。全部任务完成后，触发 finishing-a-development-branch 技能进行最终测试验证与分支合并。
sequenceDiagram
participant User as 用户
participant Orchestrator as 主智能体
participant Subagent as 实现子智能体
participant Reviewer as 审查智能体
User->>Orchestrator: 提出需求
Orchestrator->>Orchestrator: 触发 brainstorming 技能
Orchestrator->>Orchestrator: 生成任务计划 (writing-plans)
loop 每个子任务
Orchestrator->>Subagent: 派发任务 (提供局部上下文)
Subagent->>Subagent: TDD 循环 (编写测试 -> 编写代码 -> 绿灯)
Subagent-->>Orchestrator: 提交代码
Orchestrator->>Reviewer: 触发 spec-reviewer
Reviewer-->>Orchestrator: 规范审查结果
opt 存在规范问题
Orchestrator->>Subagent: 修复规范偏差
end
Orchestrator->>Reviewer: 触发 code-quality-reviewer
Reviewer-->>Orchestrator: 代码质量审查结果
opt 存在质量问题
Orchestrator->>Subagent: 修复代码异味
end
end
Orchestrator->>User: 触发 finishing-a-development-branch，请求合并
本章介绍如何通过测试驱动开发 (TDD) 理念编写和验证技能文档，确保智能体准确执行技能约束。
技能文档开发需遵循红灯、绿灯和重构循环。编写技能前，必须先编写失败的测试用例。
具体流程如下：
项目在 tests/claude-code/ 目录下提供了基于真实交互的自动化集成测试框架，以验证技能有效性。
# 运行针对子智能体驱动开发的集成测试
# 注意：必须在 superpowers 插件目录下运行
cd tests/claude-code
./test-subagent-driven-development-integration.sh
该集成测试会启动真实的 Claude Code 会话，派发多个子智能体执行计划。测试脚本通过断言检查会话的输出日志是否包含预期行为模式，或避免了特定禁忌操作。
本章通过“为项目添加一个新的 markdown-linter 技能”场景，演示如何利用 superpowers 工作流与大模型高效结对编程。
[!IMPORTANT] 环境与安装（简要）
- 已安装 Claude Code CLI（
claude --version可运行）。- 已安装并启用 superpowers 插件（安装与更新见项目 README）。
- 启用本地 dev marketplace：在
~/.claude/settings.json中设置"superpowers@superpowers-dev": true。- 从 superpowers 插件目录运行相关脚本与测试。
快速自检：
# 验证 Claude Code CLI 是否可用 claude --version # 预期输出：形如 1.2.3 的版本号 # 验证本地是否存在 superpowers 插件目录（路径因平台而异，以下为示例） ls ~/.claude/plugins | grep superpowers || echo "未检测到 superpowers 插件" # 预期输出：superpowers # 检查是否已启用本地 dev marketplace grep -n 'superpowers@superpowers-dev' ~/.claude/settings.json || echo "未开启本地 marketplace" # 预期输出：包含 superpowers@superpowers-dev 的行号与配置内容
本实战的目标与成功标准：
skills/markdown-linter/SKILL.md 并完成一个能识别与修复“中英文空格缺失”的端到端流程。skills/markdown-linter/SKILL.md、tests/test-md-linter.sh、测试通过记录与会话概述。编码前须通过多轮对话对齐原始需求，消除歧义。
用户输入：“我想写一个新技能，用来自动检查和修复 Markdown 文档中的格式问题，比如中英文之间必须有空格。”
此时，AI 不会立刻开始写代码，而是匹配到 brainstorming 技能。
AI 的反应：扮演产品架构师，向用户提出关键问题以消除歧义：
markdownlint)？Auto-fix) 功能？code-quality-reviewer 流程中？结果：经过几轮简短对话，双方对齐了目标——基于现有的正则替换写一个独立的技能，支持自动修复。
在需求明确后，AI 调用 writing-plans 技能，将目标拆解为粒度极细的原子任务。
生成的计划 (摘要)：
tests/ 下编写测试脚本 test-md-linter.sh，准备一个包含格式错误的测试用例文档，并断言 AI 能否正确发现问题 (体现了 RED-GREEN-REFACTOR 理念)。skills/markdown-linter/ 下创建 SKILL.md，定义检查规则和修复指令。验收标准：
echo $? 为 0）；PASS、GREEN、修复完成 等）。主智能体按执行计划派发子智能体，并严格执行测试驱动开发循环。
用户输入：“/execute-plan”，触发 subagent-driven-development。
执行 Task 1 (编写测试)：
主智能体派发实现者子智能体 (Implementer)。它只拿到 Task 1 的要求。
tests/test-md-linter.sh。执行 Task 2 (编写技能)： 主智能体派发一个新的实现者子智能体。
skills/markdown-linter/SKILL.md，使用强制性语言规定了 AI 遇到 Markdown 时的处理范式。执行 Task 3 (验证通过)：
主智能体要求子智能体再次运行 tests/test-md-linter.sh。
所有任务完成后，触发 finishing-a-development-branch 技能进入收尾阶段。
markdown-linter 技能，并补充了相应的回归测试”。[!TIP] 常见问题与排查
- 测试长时间无输出：检查是否在插件目录运行、网络与 CLI 可用性。
- 技能未生效：确认
SKILL.mdfrontmatter 的name/description是否存在且描述明确；检查会话是否成功加载技能上下文。- 审查未通过：按 Must Fix → Should Fix → Nice to Have 优先级逐条修正，再次运行测试与审查。
- 扩展练习：将规则扩展到标题语言规范与标点/空格一致性；为新用例加入对应测试脚本或纳入
run-skill-tests.sh，并记录通过日志。
总结：在整个实战过程中，用户只需在最开始参与需求对齐，并在最后确认合并。中间繁杂的测试编写、代码生成、规范核对、自我修复全部由多个被精确控制的子智能体在隔离的上下文中自动完成。
superpowers 面向 AI 编码智能体，提供规范化的软件开发工作流：以声明式 SKILL.md 为核心，通过会话钩子注入上下文并以审查/实现子智能体编排流程，将开发活动产品化；在工程机制上强制 TDD 与双阶段审查，隔离子智能体上下文并支持并行调度，结合隔离的 Git 工作树与基于真实交互的技能验证确保安全、可验证的迭代；落地路径为“写计划 → 在隔离工作树按计划执行 → 运行技能与集成测试验证 → 审查通过后收尾合并”。