Superpowers Skills 完整探索

Superpowers Skills 摘要 Superpowers 是一个智能体技能框架和软件开发最佳实践工具包，包含 6 大类核心技能：调试类：强调先调查根因再修复（systematic-debugging）和完成前验证（verification-before-completion）的严谨流程设计规划类：通过头脑风暴（brainstorming）探索多种方案，并使用结构化计划（writing

奋斗者1号

667人浏览 · 2026-03-09 15:48:54

奋斗者1号 · 2026-03-09 15:48:54 发布

Superpowers Skills 完整探索

项目地址： https://github.com/obra/superpowers
项目定位： An agentic skills framework & software development best practices toolkit

1️⃣ 调试类技能 (Debugging)

🔍 1. systematic-debugging（系统调试）

触发条件： 遇到任何 bug、测试失败或意外行为时，在提出修复方案之前使用

核心原则： 永远先找到根本原因再尝试修复

4 阶段流程：

Phase 1: 分析症状 - 收集所有相关信息
    ↓
Phase 2: 生成假设 - 列出可能的根本原因
    ↓
Phase 3: 验证假设 - 通过实验逐个排除
    ↓
Phase 4: 实施修复 - 解决确认的根本原因

关键规则：

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST（没有根因调查就不修复）
创建失败测试用例后再修复
一次只做 ONE CHANGE，不要"顺便改进"
尝试 3 次以上未成功需重新评估架构

软件开发好处：

✅ 避免随机修复浪费时间（15-30 分钟 vs 2-3 小时）
✅ 首次修复成功率从 40% 提升到 95%
✅ 几乎零新 bug 引入
✅ 防止表面修复掩盖深层问题

🔬 2. verification-before-completion（完成前验证）

触发条件： 准备宣称工作已完成、已修复或已通过时，在提交或创建 PR 之前使用

核心原则： 运行命令 → 读取输出 → 然后才宣称成功

关键模式对比：

✅ CORRECT: 
   [运行测试命令] [看到：34/34 通过] "所有测试通过"
   
❌ WRONG:
   "应该通过了" / "看起来正确"（未验证）

验证清单：

Tests: [Run test command] [See: 34/34 pass] "All tests pass"
Regression (TDD Red-Green): Write → Run (pass) → Revert fix → Run (MUST FAIL)
Build: [Run build] [See: exit 0] "Build passes"
Requirements: Re-read plan → Create checklist → Verify each

好处：

✅ 防止虚假的成功声明
✅ 确保修复真正有效
✅ 避免回归问题被忽略
✅ 证据先于断言（evidence before assertions）

2️⃣ 设计与规划类技能 (Design & Planning)

💡 3. brainstorming（头脑风暴）

触发条件： 任何创造性工作之前 - 创建功能、构建组件、添加功能或修改行为

核心原则： 实现前先探索用户意图、需求和设计

使用流程：

1. 理解想法
   └─ 先检查当前项目状态（文件、文档、最近提交）
   
2. 探索方法
   └─ 提出 2-3 种不同方案并分析权衡
   
3. 澄清需求
   └─ 逐个提问，优先使用选择题而非开放式问题
   
4. 设计评审
   └─ 获取用户批准后再进入实施阶段
   
5. 生成计划
   └─ 调用 writing-plans 技能创建详细实施计划

关键原则：

One question at a time - 不要一次问多个问题
Multiple choice preferred - 选择题比开放式更容易回答
YAGNI ruthlessly - 无情地移除不必要功能
Explore alternatives - 在确定方案前提出 2-3 种方法
Incremental validation - 每步获取批准再继续

软件开发好处：

✅ 避免实现错误的需求
✅ 提前发现设计缺陷
✅ 减少返工成本（平均节省 30%+开发时间）
✅ 确保架构合理性

📝 4. writing-plans（编写计划）

触发条件： 有规范或多步骤任务需求时，在接触代码之前使用

核心原则： 为工程师创建详细的实施计划，假设他们对代码库零上下文

文档要求：

# [Feature Name] Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
> **Goal:** [One sentence describing what this builds]
> **Architecture:** [2-3 sentences about approach]
> **Tech Stack:** [Key technologies/libraries]

---

## Tasks (bite-sized, 2-5 minutes each)
1. Write the failing test - step
2. Run it to make sure it fails - step
3. Implement the minimal code to make the test pass - step
4. Run the tests and make sure they pass - step
5. Commit - step

必须包含：

目标（Goal）：一句话描述构建内容
架构（Architecture）：2-3 句方法说明
技术栈（Tech Stack）：关键技术/库
文件列表：每个任务修改哪些文件
测试策略：如何验证
文档需求：需要更新的文档

好处：

✅ 新人也能快速上手项目
✅ 任务分解清晰，降低认知负担
✅ 便于并行开发和代码审查
✅ 保存路径：docs/plans/YYYY-MM-DD-.md

3️⃣ 实施类技能 (Implementation)

🧪 5. test-driven-development（测试驱动开发 TDD）

触发条件： 实现任何功能或 bug 修复时，在编写实现代码之前使用

核心原则： 先写测试 → 看它失败 → 写最小代码让它通过

铁律： NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST（没有失败的测试就不生产代码）

3 步循环：

RED:
   ├─ Write test first
   ├─ Run test (must fail)
   └─ Verify failure is expected
   
GREEN:
   └─ Write minimal code to pass
   
REFACTOR:
   └─ Improve design while tests pass

执行流程：

Write Test First - 编写最简单的测试用例
Watch It Fail (RED) - 运行测试确认失败
Minimal Code (GREEN) - 写最小代码使测试通过
Refactor - 重构改进设计（保持测试通过）

TDD 反模式：

❌ Vague name, tests mock not code（模糊名称，测试的是 mock 而非真实代码）
❌ Multiple behaviors in one test（一个测试多个行为）
❌ Test too complicated = Design too complicated（测试太复杂 = 设计太复杂）

好处：

✅ 自动生成文档化的测试用例
✅ 防止过度设计（YAGNI）
✅ 提高代码质量和可维护性
✅ 重构时有安全网保护

🚀 6. executing-plans（执行计划）

触发条件： 有实施计划需要执行时

核心原则： 批量执行与检查点结合，每批报告供架构师审查

流程：

Step 1: Load and Review Plan (加载并审查计划)
   ├─ Read plan file
   ├─ Identify questions or concerns
   └─ If concerns: Raise before starting
   
Step 2: Execute Batch (执行批次 - 默认前 3 个任务)
   ├─ Mark task as in_progress
   ├─ Follow each step exactly
   ├─ Run verifications as specified
   └─ Mark as completed
   
Step 3: Report (汇报进展)
   ├─ Show what was implemented
   ├─ Show verification output
   └─ Say: "Ready for feedback."
   
Step 4: Continue (继续迭代)
   ├─ Apply changes if needed
   ├─ Execute next batch
   └─ Repeat until complete
   
Step 5: Complete Development (完成开发)
   └─ Call finishing-a-development-branch skill

何时停止并询问帮助：

❌ Hit a blocker mid-batch（批次中途遇到阻碍）
❌ Plan has critical gaps（计划有严重缺陷）
❌ Don’t understand an instruction（不理解指令）

好处：

✅ 避免一次性执行过多导致的问题累积
✅ 早期发现计划缺陷
✅ 便于中途调整和审查
✅ 降低认知负担，专注当前批次

👥 7. subagent-driven-development（子代理驱动开发）

触发条件： 在当前会话中执行具有独立任务时

核心原则： 每个任务分发新子代理 + 两阶段审查（规范符合性 → 代码质量）

流程：

1. Read plan, extract all tasks (读取计划，提取所有任务)
   └─ Note context, create TodoWrite
   
2. Dispatch subagent per task (为每个任务创建子代理)
   ├─ Fresh subagent with full context
   └─ Independent work on each task
   
3. Two-stage review after each task (每任务两阶段审查)
   ├─ Stage 1: Spec compliance review（规范符合性）
   └─ Stage 2: Code quality review（代码质量）
   
4. All tasks complete → finishing-a-development-branch

何时使用：

✅ Have implementation plan（有实施计划）
✅ Tasks mostly independent（任务基本独立）
✅ Stay in this session（在当前会话执行）

何时使用 executing-plans：

❌ Manual execution or brainstorm first（手动执行或先头脑风暴）
❌ Need to dispatch subagent（需要分发子代理）

好处：

✅ 并行开发加速
✅ Fresh context per task（每个任务独立上下文，无污染）
✅ Two-stage review提高质量
✅ 快速迭代

4️⃣ 协作与代码审查类技能 (Collaboration & Review)

📋 8. requesting-code-review（请求代码审查）

触发条件： 完成实现需要他人审查时

核心原则： 提供完整上下文，便于审查者理解改动

模板要求：

## What Was Implemented
{WHAT_WAS_IMPLEMENTED} - 刚构建的内容

## Plan or Requirements
{PLAN_OR_REQUIREMENTS} - 应该做什么

## Base SHA
{BASE_SHA} = git log --oneline | grep "Task X" | head -1 | awk '{print $1}'

## Head SHA
{HEAD_SHA} = git rev-parse HEAD

## Description
{DESCRIPTION} - Brief summary of the implementation

集成场景：

Subagent-driven Development: 每完成一个任务后审查，防止问题累积
Executing Plans: 每个批次（3 个任务）完成后审查
Ad-hoc Development: 合并前或卡住时审查

好处：

✅ 提高审查效率和质量
✅ 早期发现问题，避免累积
✅ 促进知识共享和团队协作
✅ 减少返工成本

🔄 9. receiving-code-review（接收代码审查）

触发条件： 收到代码审查反馈时，在实施建议之前使用

核心原则： 技术评估而非情绪表演 - 验证后再实施

响应模式（5 步法）：

1. READ (完整阅读)
   └─ Complete feedback without reacting
   
2. UNDERSTAND (理解重述)
   └─ Restate requirement in own words or ask
   
3. VERIFY (对照现实)
   └─ Check against codebase reality
   
4. EVALUATE (技术评估)
   └─ Technically sound for THIS codebase?
   
5. RESPOND (回应)
   ├─ Technical acknowledgment 或
   └─ Ask for clarification

场景处理：

From human partner:
- Trusted → implement after understanding
- Still ask if scope unclear
- No performative agreement
From External Reviewers:
- Before implementing: Check technical correctness, verify context
- If suggestion seems wrong: Push back with reasoning
- If can’t verify: Say so explicitly

好处：

✅ 避免盲目实施错误建议
✅ 提高审查讨论质量
✅ 保护代码完整性
✅ 促进技术对话而非情绪化争论

5️⃣ Git 与工作流类技能 (Git & Workflow)

🌳 10. using-git-worktrees（使用 Git Worktrees）

触发条件： 开始需要与当前工作区隔离的功能工作时，或执行实施计划之前

核心原则： 系统化目录选择 + 安全验证 = 可靠隔离

目录选择优先级：

1. Check existing directories (检查现有目录)
   ├─ .worktrees/ - First choice（首选）
   └─ Any project-local directory
   
2. Check CLAUDE.md (查看文档)
   └─ Look for preferred location guidance
   
3. Ask human partner if ambiguous (不确定时询问)

创建流程：

# 1. Verify .worktrees/ is ignored (验证被忽略)
git check-ignore .worktrees/

# 2. Create worktree (创建工作区)
git worktree add .worktrees/<branch-name> -b <branch-name>

# 3. Run setup and verify tests (运行设置和测试)
cd .worktrees/<branch-name>
npm install  # or project setup
npm test     # Verify baseline passes

# Result: Worktree ready at /project/.worktrees/<branch-name>

好处：

✅ 并行开发多分支无需切换
✅ 保持工作区整洁隔离
✅ 便于实验和临时分支管理
✅ 与 finishing-a-development-branch 配合自动清理

🔚 11. finishing-a-development-branch（完成开发分支）

触发条件： 实现完成，所有测试通过，需要决定如何集成工作时使用

核心原则： 验证测试 → 提供选项 → 执行选择 → 清理

流程：

Step 1: Verify Tests (验证测试)
   ├─ npm test / cargo test / pytest / go test ./...
   └─ If fail: Stop, cannot proceed
   
Step 2: Determine Base Branch (确定主分支)
   └─ git merge-base HEAD main/master

Step 3: Present Options (提供选项)
   ├─ Option 1: Merge back to <base> locally（本地合并）
   ├─ Option 2: Push and create a Pull Request（推送并创建 PR）
   ├─ Option 3: Keep the branch as-is（保持现状）
   └─ Option 4: Discard this work（丢弃工作，需确认）

Step 4: Execute Choice (执行选择)
   └─ Based on user decision

Step 5: Cleanup Worktree (清理工作区)
   ├─ For Options 1, 2, 4: Remove worktree
   └─ For Option 3: Keep worktree preserved

选项对比表：

选项	本地合并	推送 PR	保持工作区	清理分支
1. Merge locally	✓	-	-	✓
2. Create PR	-	✓	✓	-
3. Keep as-is	-	-	✓	-
4. Discard	-	-	-	✓ (force)

好处：

✅ 防止合并失败代码到主分支
✅ 提供明确的选择路径
✅ 自动清理临时工作区，避免堆积
✅ 需要 typed confirmation 才删除，防止误操作

⚡ 12. dispatching-parallel-agents（分发并行代理）

触发条件： 面对 2+ 个独立任务，无需共享状态或顺序依赖时

核心原则： 每个问题域一个代理，并发工作

使用决策树：

Multiple failures? (多个失败？)
   ├─ No → Single agent investigates all
   └─ Yes: Are they independent?（相互独立？）
         ├─ No → Investigate together first
         └─ Yes: Can work in parallel?（可并行？）
               ├─ No → Sequential agents（顺序代理）
               └─ Yes → Parallel dispatch（并行分发）

使用场景：

✅ 3+ test files failing with different root causes（多个测试文件失败，根本原因不同）
✅ Multiple subsystems broken independently（多个子系统独立损坏）
✅ Each problem can be understood without context from others（问题可独立理解）
❌ Fixing one might fix others（修复一个可能修复其他）
❌ Need to understand full system state（需要理解完整系统状态）

好处：

✅ 大幅缩短调试时间（从顺序到并行）
✅ 充分利用并行计算能力
✅ 避免重复上下文加载
✅ 每个问题获得 fresh context

6️⃣ 元技能 (Meta Skills)

✍️ 13. writing-skills（编写技能）

触发条件： 创建新技能、编辑现有技能或部署前验证技能时

核心原则： 技能写作是过程文档的测试驱动开发

技能描述书写规范：

# ❌ BAD: Summarizes workflow - Claude may follow this instead of reading skill
description: Use when executing plans - dispatches subagent per task with code review between tasks

# ✅ GOOD: Just triggering conditions, no workflow summary  
description: Use when executing implementation plans with independent tasks in the current session

关键规则：

description 字段只描述触发条件，不要总结工作流程
测试揭示：当 description 包含流程摘要时，Claude 可能直接遵循 description 而跳过阅读完整技能内容
通过压力场景测试技能有效性（使用 subagents）
观察 agent 在没有技能时的失败行为

好处：

✅ 创建高质量可复用的过程文档
✅ 避免 AI 跳过关键步骤
✅ 持续改进工作流质量
✅ Personal skills 保存在 ~/.claude/skills（Claude Code）或 ~/.agents/skills/（Codex）

🧭 14. using-superpowers（使用 Superpowers）

触发条件： 开始任何对话时，建立如何查找和使用技能的方式

核心原则： 如果技能有 1% 可能适用，必须调用该技能检查

规则强度：

“IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.”
This is not negotiable. This is not optional. You cannot rationalize your way out of this.

流程：

digraph skill_flow {
    "User message received" [shape=doublecircle];
    "Might any skill apply?" [shape=diamond];
    "Invoke Skill tool" [shape=box];
    "Announce: Using [skill] to [purpose]" [shape=box];
    "Has checklist?" [shape=diamond];
    "Create TodoWrite todo per item" [shape=box];
    "Follow skill exactly" [shape=box];
}

User → Might apply? -- 1%+ chance --> Invoke Skill tool
Skill tool → Announce usage → Has checklist? -- yes --> Create TodoWrite
Has checklist? -- no --> Follow skill exactly

访问方式：