Superpowers - Day 4：阅读核心技能源码Superpowers 学习笔记 - Day 4：阅读核心技能源

Superpowers 学习笔记 - Day 4：阅读核心技能源码

📅 日期

2026-03-22

🎯 今日目标

Day 4-5：学习使用指南（2-3 小时）

阅读 using-superpowers/SKILL.md
了解技能自动触发机制
理解不同场景下会触发哪些技能

核心技能概览

技能	触发时机	作用
brainstorming	项目开始前	需求澄清、探索方案
writing-plans	设计确认后	生成详细实施计划
test-driven-development	实施阶段	TDD 循环（红-绿-重构）
subagent-driven-development	执行阶段	子代理协作完成任务
systematic-debugging	出现问题时	4 阶段根因分析
requesting-code-review	任务之间	代码审查请求
receiving-code-review	收到反馈时	回应审查意见

📖 核心技能深度解析

1️⃣ using-superpowers（使用指南）

技能名称： using-superpowers
描述： 启动任何对话时使用 - 建立如何查找和使用技能

🔴 极其重要的规则

If you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY MUST invoke the skill.

IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.

这不是可协商的
这不是可选项
你不能通过理性化来逃避这个规则

📋 指令优先级

Superpowers 技能覆盖默认系统提示行为，但 用户指令总是具有最高优先级：

用户的显式指令（CLAUDE.md, GEMINI.md, AGENTS.md, 直接请求）— 最高优先级
Superpowers 技能 — 在与默认系统行为冲突时覆盖
默认系统提示 — 最低优先级

例子： 如果 CLAUDE.md 说"不要使用 TDD"而技能说"始终使用 TDD"，遵循用户的指令。用户是控制者。

🔄 技能调用流程

graph TD
    A[用户消息] --> B{任何技能可能适用？}
    B -->|是，甚至1%| C[调用 Skill 工具]
    B -->|绝对不| D[回应包括澄清]
    C --> E[宣布：使用技能来...]
    E --> F{有检查清单？}
    F -->|是| G[为每项创建 TodoWrite]
    F -->|否| H[完全遵循技能]
    G --> H
    H --> I[回应包括澄清]

⚠️ 红旗警示

这些想法意味着停止——你在合理化：

想法	现实
"这只是个简单问题"	问题就是任务。检查技能。
"我需要更多上下文"	技能检查在澄清问题之前。
"让我先探索代码库"	技能告诉你如何探索。先检查。
"我可以快速检查 git/文件"	文件缺少对话上下文。先检查技能。
"让我先收集信息"	技能告诉你如何收集信息。
"这不需要正式技能"	如果技能存在，就使用它。
"我记得这个技能"	技能会演变。阅读当前版本。
"这不算任务"	行动 = 任务。检查技能。
"技能大材小用"	简单的事情会变复杂。使用它。
"我就先做这一件事"	在做任何事情之前先检查。
"这感觉很高效"	不受纪律的行动浪费时间。技能防止这种情况。
"我知道这意味着什么"	知道概念 ≠ 使用技能。调用它。

🎯 技能优先级

当多个技能可能适用时，使用这个顺序：

流程技能优先（brainstorming, debugging）— 这些决定如何处理任务
实现技能其次（frontend-design, mcp-builder）— 这些指导执行

例子：

"让我们构建 X" → brainstorming 优先，然后实现技能
"修复这个 bug" → debugging 优先，然后领域特定技能

📊 技能类型

刚性（TDD, debugging）：完全遵循。不要通过纪律来适应。

灵活（patterns）：根据上下文适应原则。

技能本身会告诉你它是哪种。

2️⃣ brainstorming（头脑风暴）

技能名称： brainstorming
描述： 你必须在任何创造性工作之前使用这个 — 创建功能、构建组件、添加功能或修改行为。在实现之前探索用户意图、需求和设计。

🚪 硬门规则

Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it.

This applies to EVERY project regardless of perceived simplicity.

✅ 检查清单

你必须为这些项目中的每一项创建一个任务并按顺序完成：

探索项目上下文 — 检查文件、文档、最近提交
提供视觉伴侣（如果话题将涉及视觉问题）— 这是它自己的消息，不与澄清问题结合
问澄清问题 — 一次一个，理解目的/约束/成功标准
提出 2-3 种方法 — 包含权衡和你的建议
展示设计 — 按其复杂性缩放的部分，在每部分后获得用户批准
编写设计文档 — 保存到 docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md 并提交
规范审查循环 — 使用精心制作的审查上下文派发 spec-document-reviewer 子代理；修复问题并重新派发直到批准（最多 3 次迭代，然后暴露给人类）
用户审查编写的规范 — 在继续之前请用户审查规范文件
过渡到实施 — 调用 writing-plans 技能创建实施计划

🔄 流程图

graph TD
    A[探索项目上下文] --> B{有视觉问题？}
    B -->|是| C[提供视觉伴侣]
    B -->|否| D[问澄清问题]
    C --> D
    D --> E[提出 2-3 种方法]
    E --> F[展示设计部分]
    F --> G{用户批准设计？}
    G -->|否| F
    G -->|是| H[编写设计文档]
    H --> I[规范审查循环]
    I --> J{规范审查通过？}
    J -->|发现问题| H
    J -->|批准| K{用户审查规范？}
    K -->|要求更改| H
    K -->|批准| L[调用 writing-plans]

🎯 关键原则

一次一个问题 — 不要用多个问题压倒用户
多选优先 — 如果可能，比开放式更容易回答
YAGNI 残酷 — 从所有设计中移除不必要的功能
探索替代方案 — 在确定之前总是提出 2-3 种方法
增量验证 — 展示设计，在继续之前获得批准
灵活 — 当某些事情没有意义时，回去澄清

💡 视觉伴侣

用于在头脑风暴期间显示模拟图、图表和视觉选项的基于浏览器的伴侣。可用作工具 — 不是模式。

提供伴侣： 当你预计即将到来问题将涉及视觉内容（模拟图、布局、图表）时，一次征求同意：

"我们要做的一些事情如果我可以在这个网页浏览器中展示给你，可能会更容易解释。我可以在进行过程中整理模拟图、图表、比较和其他视觉效果。这个功能仍然很新，可能会很消耗令牌。想试试吗？（需要打开本地 URL）"

此提供必须是它自己的消息。 不要将它与澄清问题、上下文摘要或任何其他内容结合。

3️⃣ writing-plans（编写计划）

技能名称： writing-plans
描述： 在接触代码之前，当你有规范或多步骤任务的需求时使用

📋 概述

编写全面的实施计划，假设工程师对我们的代码库零上下文，品味可疑。记录他们需要知道的一切：每个任务要接触哪些文件、代码、测试、他们可能需要检查的文档、如何测试它。将整个计划作为小任务给他们。DRY。YAGNI。TDD。频繁提交。

宣布开始时： "我正在使用 writing-plans 技能创建实施计划。"

上下文： 这应该在专用工作树中运行（由 brainstorming 技能创建）。

保存计划到： docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md

🎯 范围检查

如果规范涵盖多个独立子系统，它应该在头脑风暴期间分解为子项目规范。如果不是，建议将其分解为单独的计划 — 每个子系统一个。每个计划应该自己产生可工作的、可测试的软件。

📁 文件结构

在定义任务之前，映射将创建或修改哪些文件以及每个文件负责什么。这是分解决策被锁定的地方。

设计具有清晰边界和定义良好接口的单元。每个文件应该有一个明确的职责。
你推理最好的代码是你可以在上下文中一次性理解的代码，当文件专注时你的编辑更可靠。更喜欢更小、专注的文件而不是做太多事情的大文件。
一起改变的文件应该在一起。按职责分割，而不是按技术层。
在现有代码库中，遵循既定模式。如果代码库使用大文件，不要单方面重构 — 但如果你正在修改的文件变得笨拙，包括计划中的拆分是合理的。

📦 小任务粒度

每个步骤是一个动作（2-5 分钟）：

"编写失败的测试" — 步骤
"运行它以确保失败" — 步骤
"编写最小代码通过测试" — 步骤
"运行测试并确保它们通过" — 步骤
"提交" — 步骤

📄 计划文档结构

### Task N: [Component Name]

**Files:**
- Create: `exact/path/to/file.py`
- Modify: `exact/path/to/existing.py:123-145`
- Test: `tests/exact/path/to/test.py`

- [ ] **Step 1: Write failing test**

```python
def test_specific_behavior():
    result = function(input)
    assert result == expected

Step 2: Run test to verify it fails

Run: pytest tests/path/test.py::test_name -v Expected: FAIL with "function not defined"

Step 3: Write minimal implementation

def function(input):
    return expected

Step 4: Run test to verify it passes

Run: pytest tests/path/test.py::test_name -v Expected: PASS

Step 5: Commit

git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific feature"


---

#### 🔍 计划审查循环

编写完整计划后：

1. 派发单个 plan-document-reviewer 子代理，使用精心制作的审查上下文 — 从不是你的会话历史。这使审查者专注于计划，而不是你的思维过程。
   - 提供：计划文档路径，规范文档路径
2. 如果 ❌ 发现问题：修复，为整个计划重新派发审查者
3. 如果 ✅ 批准：继续执行交接

---

#### 🚀 执行交接

保存计划后，提供执行选择：

> "计划已完成并保存到 `docs/superpowers/plans/<filename>.md`。两种执行选项："
> 
> "**1. 子代理驱动（推荐）** — 我为每个任务派发一个新的子代理，任务之间审查，快速迭代"
> 
> "**2. 内联执行** — 使用 executing-plans 在此会话中执行任务，带检查点的批量执行"
> 
> "**哪种方法？**"

---

### 4️⃣ test-driven-development（测试驱动开发）

**技能名称：** `test-driven-development`  
**描述：** 在编写实现代码之前实施任何功能或 bug 修复时使用

---

#### 📋 概述

先写测试。看着它失败。编写最小代码通过。

**核心原则：** 如果你没有看到测试失败，你就不知道它是否测试正确的事情。

**违反规则的文字就是违反规则的精神。**

---

#### 🚪 铁律

没有失败测试没有生产代码


在测试之前写代码？删除它。重新开始。

**没有例外：**
- 不要保留它作为"参考"
- 不要在编写测试时"适应"它
- 不要看它
- 删除意味着删除

从测试开始实现。就这样。

---

### 5️⃣ subagent-driven-development（子代理驱动开发）

**技能名称：** `subagent-driven-development`  
**描述：** 在当前会话中使用独立任务执行实施计划时使用

---

#### 📋 概述

通过为每个任务派发新的子代理来执行计划，每个任务后进行两阶段审查：首先是规范合规性审查，然后是代码质量审查。

**为什么使用子代理：** 你将任务委托给具有隔离上下文的专业代理。通过精确制作它们的指令和上下文，你确保它们保持专注并成功完成任务。它们不应继承你会话的上下文或历史 — 你构建它们确切需要的内容。这也为协调工作保留了你自己的上下文。

**核心原则：** 每个任务的新子代理 + 两阶段审查（规范然后质量）= 高质量，快速迭代

---

#### 🔄 完整流程

每个任务循环：
1. **派发实现者子代理** - 实现功能
2. **实现者问问题？** - 回答并重新派发
3. **实现者实现、测试、提交、自审查**
4. **派发规范审查者子代理** - 检查是否符合规范
5. **规范审查通过？** - 否：修复并重新审查；是：继续
6. **派发代码质量审查者子代理** - 检查代码质量
7. **代码质量通过？** - 否：修复并重新审查；是：任务完成

所有任务完成后：
1. **派发最终代码审查者** - 审查整个实现
2. **使用 finishing-a-development-branch** - 完成分支

---

#### 🎯 模型选择

使用能处理每个角色的最弱模型以节省成本并提高速度。

- **机械实现任务**（独立函数、清晰规范、1-2 个文件）：使用快速、便宜的模型
- **集成和判断任务**（多文件协调、模式匹配、调试）：使用标准模型
- **架构、设计和审查任务**：使用最可用的 capable 模型

---

#### 📊 子代理状态处理

**DONE**：继续进行规范合规性审查

**DONE_WITH_CONCERNS**：实现者完成了工作但标记了疑虑。在继续之前阅读疑虑。

**NEEDS_CONTEXT**：实现者需要未提供的信息。提供缺失的上下文并重新派发

**BLOCKED**：实现者无法完成任务。评估阻塞性：
1. 如果是上下文问题，提供更多上下文并使用相同模型重新派发
2. 如果任务需要更多推理，使用更 capable 模型重新派发
3. 如果任务太大，将其分解为更小的部分
4. 如果计划本身错误，升级到人类

---

### 6️⃣ systematic-debugging（系统化调试）

**技能名称：** `systematic-debugging`  
**描述：** 在遇到任何 bug、测试失败或意外行为时，在提出修复之前使用

---

#### 📋 概述

随机修复浪费时间并创建新的 bug。快速补丁掩盖潜在问题。

**核心原则：** 在尝试修复之前始终找到根本原因。症状修复就是失败。

**违反此流程的文字就是违反调试的精神。**

---

#### 🚪 铁律

没有根本原因调查就没有修复


如果你没有完成第 1 阶段，你就不能提出修复。

---

#### 🔄 四个阶段

**阶段 1：根本原因调查**
1. 仔细阅读错误消息
2. 一致地重现
3. 检查最近的更改
4. 在多组件系统中收集证据

**阶段 2：模式分析**
1. 找到工作示例
2. 与参考比较
3. 识别差异
4. 理解依赖关系

**阶段 3：假设和测试**
1. 形成单个假设
2. 最小化测试
3. 在继续之前验证
4. 当你不知道时说"我不理解 X"

**阶段 4：实现**
1. 创建失败的测试用例
2. 实现单个修复
3. 验证修复
4. 如果修复不起作用且已尝试 3+ 次：质疑架构

---

#### ⚠️ 红旗警示

- "现在快速修复，稍后调查"
- "试试改变 X 看看是否有效"
- "添加多个更改，运行测试"
- "跳过测试，我会手动验证"
- "这可能是 X，让我修复那个"
- "我不完全理解但这可能有效"

**所有这些都意味着：停止。返回阶段 1。**

---

### 7️⃣ requesting-code-review（请求代码审查）

**技能名称：** `requesting-code-review`  
**描述：** 在完成任务、实现主要功能或合并之前使用，以验证工作满足需求

---

#### 📋 概述

派发 superpowers:code-reviewer 子代理在问题级联之前捕获它们。审查者获得精确制作的上下文进行评估 — 从不是你会话的历史。这使审查者专注于工作产品，而不是你的思维过程，并为持续工作保留你自己的上下文。

**核心原则：尽早审查，经常审查。**

---

#### 🔄 何时请求审查

**强制要求：**
- 子代理驱动开发中的每个任务后
- 完成主要功能后
- 合并到主分支之前

**可选但有价值：**
- 卡住时（新鲜视角）
- 重构之前（基准检查）
- 修复复杂 bug 后

---

#### 📋 如何请求

1. **获取 git SHA**
```bash
BASE_SHA=$(git rev-parse HEAD~1)  # 或 origin/main
HEAD_SHA=$(git rev-parse HEAD)

派发 code-reviewer 子代理
- WHAT_WAS_IMPLEMENTED：你刚刚构建了什么
- PLAN_OR_REQUIREMENTS：它应该做什么
- BASE_SHA：开始提交
- HEAD_SHA：结束提交
- DESCRIPTION：简要摘要
对反馈采取行动
- 立即修复关键问题
- 在继续之前修复重要问题
- 稍后记录次要问题
- 如果审查者错误则推回（带推理）

8️⃣ using-git-worktrees（使用 Git 工作树）

技能名称： using-git-worktrees
描述： 在开始需要与当前工作空间隔离的功能工作时，或在执行实施计划之前使用 — 创建具有智能目录选择和安全验证的隔离 git worktrees

📋 概述

Git worktrees 创建共享同一存储库的隔离工作空间，允许在不切换的情况下同时在多个分支上工作。

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

🔄 目录选择过程

按优先级顺序：

检查现有目录
- .worktrees/（首选，隐藏）
- worktrees/（替代）
- 如果两者都存在，.worktrees/ 获胜
检查 CLAUDE.md
- 如果指定了偏好，使用它而不问
询问用户
- 如果没有目录存在且没有 CLAUDE.md 偏好：
  - .worktrees/（项目本地，隐藏）
  - ~/.config/superpowers/worktrees/<project-name>/（全局位置）

✅ 安全验证

对于项目本地目录（.worktrees 或 worktrees）： 必须在创建 worktree 之前验证目录被忽略：

git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null

如果未被忽略：

将适当行添加到 .gitignore
提交更改
继续工作树创建

为什么关键： 防止意外将工作树内容提交到存储库。

🔄 创建步骤

检测项目名称

project=$(basename "$(git rev-parse --show-toplevel)")

创建 worktree

git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"

运行项目设置 自动检测并运行适当设置：

Node.js：npm install
Python：pip install -r requirements.txt
Rust：cargo build
Go：go mod download

验证清洁基线 运行测试以确保 worktree 以清洁状态开始
报告位置

Worktree ready at <full-path>
Tests passing (<N> tests, 0 failures)
Ready to implement <feature-name>

🔄 RED-GREEN-REFACTOR 循环

graph LR
    A[RED<br/>编写失败的测试] --> B{验证失败<br/>正确}
    B -->|是| C[GREEN<br/>最小代码]
    B -->|否| A
    C --> D{验证通过<br/>全部绿色}
    D -->|是| E[REFACTOR<br/>清理]
    D -->|否| C
    E --> D
    D --> F[下一个]
    F --> A

RED - 编写失败的测试

编写一个最小的测试展示应该发生什么。

要求：

一种行为
清晰的名称
真实代码（除非不可避免否则没有模拟）

验证 RED - 看着它失败

强制要求。从不跳过。

npm test path/to/test.test.ts

确认：

测试失败（不是错误）
失败消息是预期的
失败因为功能缺失（不是拼写错误）

GREEN - 最小代码

编写最简单的代码通过测试。

不要添加功能、重构其他代码或超越测试"改进"。

验证 GREEN - 看着它通过

强制要求。

npm test path/to/test.test.ts

确认：

测试通过
其他测试仍然通过
输出 pristine（没有错误、警告）

REFACTOR - 清理

绿色之后：

移除重复
改进名称
提取辅助函数

保持测试绿色。不要添加行为。

🧪 良好测试

质量	良好	不好
最小	一件事。名称中有"and"？拆分它。	`test('validates email and domain and whitespace')`
清晰	名称描述行为	`test('test1')`
显示意图	展示所需 API	掩盖代码应该做什么

❌ 红旗 - 停止并重新开始

测试之前的代码
实现后的测试
测试立即通过
无法解释为什么测试失败
测试"稍后"添加
合理化"就这一次"
"我已经手动测试过它"
"测试后达到相同目标"
"这是关于精神不是仪式"
"保留为参考"或"适应现有代码"
"已经花了 X 小时，删除是浪费"
"TDD 是教条的，我是务实的"
"这是不同的因为..."

所有这些都意味着：删除代码。用 TDD 重新开始。

📊 技能触发时机总结

场景	应该触发的技能	说明
用户说"帮我规划这个项目"	brainstorming	需要澄清需求和设计
用户说"帮我实现这个功能"	brainstorming → writing-plans	先设计，再规划
开始写代码时	test-driven-development	必须 TDD 循环
开始实施前	using-git-worktrees	创建隔离工作空间
有实施计划且任务独立	subagent-driven-development	子代理执行 + 两阶段审查
发现 bug	systematic-debugging → test-driven-development	先调试，再修复
完成任务/功能/合并前	requesting-code-review	派发代码审查者
收到代码审查反馈	receiving-code-review	回应审查意见
多个任务需要并行执行	dispatching-parallel-agents	派发并行子代理
任务全部完成	finishing-a-development-branch	完成分支管理

💡 核心收获

1. 技能调用的严格性

✅ 1% 规则：如果技能可能适用，必须调用
✅ 优先级明确：用户指令 > Superpowers 技能 > 默认系统
✅ 流程技能优先：先确定如何处理，再确定如何实施

2. brainstorming 的严谨性

✅ 硬门规则：设计批准前不能写任何代码
✅ 逐步验证：每部分设计都需要用户批准
✅ 规范审查循环：派发子代理审查设计文档

3. writing-plans 的详细性

✅ 小任务粒度：每个步骤 2-5 分钟
✅ 完整信息：包括文件路径、代码、命令、预期输出
✅ 审查循环：派发子代理审查实施计划

4. TDD 的强制性

✅ 铁律：没有失败测试没有生产代码
✅ 完整循环：RED → 验证 RED → GREEN → 验证 GREEN → REFACTOR
✅ 无例外：违反规则 = 删除代码重新开始

🎯 Day 4 总结

✅ 完成情况

阅读 using-superpowers/SKILL.md
阅读 brainstorming/SKILL.md
阅读 writing-plans/SKILL.md
阅读 test-driven-development/SKILL.md
理解技能自动触发机制
理解技能优先级

🌟 核心发现

技能调用的严格性 — 1% 规则确保不会遗漏适用的技能
设计优先原则 — brainstorming 的硬门规则确保先设计再实现
计划详细性 — writing-plans 要求 2-5 分钟的小任务粒度
TDD 强制性 — 铁律确保测试先行开发

🎓 学到的经验

Superpowers 的工作流程非常严谨和系统化
每个技能都有明确的触发条件和工作流程
用户指令始终具有最高优先级
技能之间有清晰的优先级和协作关系

🚀 准备进入 Day 5

明天学习重点：

继续阅读核心技能源码
理解更多技能的工作流程
深入理解技能的激活条件

记录时间：2026-03-22 状态：Day 4 完成 ✅