Superpowers 深度实战：让 Claude Code 从「代码生成器」进化为「资深工程师」的完整指南

小编语：AI 编程助手很聪明，但太自由。Superpowers 用 14+ 个结构化技能把软件工程纪律「编译」进 Claude 的大脑，强制走 Brainstorm → Plan → TDD → 执行 → Review 全流程。本文从架构原理、核心技能、安装配置、生产级代码实战到性能调优，全方位深度解析这套方法论，让你真正把 AI 变成靠谱的工程搭档。

引言：AI 编程的「最后一公里」问题

2025 年到 2026 年，AI 编程助手经历了爆发式增长。Claude Code、Cursor、GitHub Copilot、Codex CLI 等工具让「用自然语言写代码」从科幻变成日常。但一个根本性问题始终没有解决：

AI 能写代码，但 AI 能「做工程」吗？

绝大多数开发者使用 AI 编程助手的体验是这样的：

1. 描述需求，AI 立刻开始输出代码
2. 代码看起来很漂亮，但不 work
3. 把报错扔给 AI，它立刻「修复」
4. 修好了 A，B 又坏了
5. 没有测试，没有设计文档，没有代码审查
6. 项目稍微复杂一点，AI 就开始「胡编乱造」

这不是 AI 不够聪明，而是 AI 没有被赋予「工程纪律」。

资深工程师和价值排序是：先想清楚 → 写好计划 → 小步迭代 → 测试驱动 → 代码审查 → 持续重构。而 AI 的默认行为是：拿到需求 → 立刻写代码 → 哪里报错修哪里。

Superpowers 就是来解决这个问题的。

一、Superpowers 是什么：方法论作为代码（Methodology-as-Code）

1.1 核心定位

Superpowers 是由 Jesse Vincent（GitHub 账号 obra）创建的一个开源 Agentic Skills Framework（智能体技能框架）。

它的核心理念只有一句话：

Process over Prompt（流程大于提示词）

这句话的意思是：与其花心思写更复杂的 Prompt，不如把资深工程师的工作流程固化下来，让 AI 必须遵循。

Superpowers 不是给 AI 增加新能力（Claude Code 本身已经能规划、调试、重构），而是 把这些能力组织成有序的、可预测的、不可跳过的工作流。

1.2 它不是什么

在深入之前，必须澄清 Superpowers 的边界：

1.3 它是什么（正解）

Superpowers 是一套 AI 可读、可执行的指令集 + 工作流模板。

你可以把它理解为：

• 给 AI 的「开发 SOP 手册」
• 一套可触发的自动化工作流脚本
• 一种「元编程」：教 AI 如何正确地编程

每个技能都是一个 Markdown 文件（SKILL.md），定义了特定场景下的严格规则。AI 在处理任务时，必须先检查并调用相关技能。

1.4 爆发式增长的数据

• 2025 年 10 月：项目开源
• 2026 年 1 月：被纳入 Anthropic 官方插件市场
• GitHub Stars：超过 17 万（截至 2026 年 6 月）
• 版本：5.0.7（2026 年 3 月，目前稳定版）
• 技能数量：14+ 个结构化技能

二、架构深度解析：Skills Framework 的工作原理

2.1 整体架构

Superpowers 的架构可以分为三层：

┌─────────────────────────────────────────────┐
│           Claude Code / Cursor              │
│         (AI 编程助手宿主环境)                │
└──────────────────┬──────────────────────────┘
                   │ 插件系统注入
┌──────────────────▼──────────────────────────┐
│         Superpowers Plugin                  │
│   ┌─────────────────────────────────────┐   │
│   │     Skills Loader (技能加载器)       │   │
│   │  解析 skills/ 目录下的所有 SKILL.md  │   │
│   └─────────────────────────────────────┘   │
│   ┌─────────────────────────────────────┐   │
│   │     Trigger Engine (触发引擎)        │   │
│   │  根据上下文自动匹配并激活技能         │   │
│   └─────────────────────────────────────┘   │
│   ┌─────────────────────────────────────┐   │
│   │     Workflow Executor (工作流执行器) │   │
│   │  按顺序执行技能中定义的流程           │   │
│   └─────────────────────────────────────┘   │
└─────────────────────────────────────────────┘
         │              │              │
    ┌────▼────┐   ┌────▼────┐   ┌────▼────┐
    │Brainstorm│   │ TDD     │   │ Debug   │
    │技能      │   │技能      │   │技能      │
    └─────────┘   └─────────┘   └─────────┘

2.2 技能文件的结构

每个技能都是一个 SKILL.md 文件，结构如下：

---
name: skill-name
description: 技能的简短描述
trigger: 触发条件（上下文关键词）
---

# 技能名称

## 目标
这个技能要解决什么问题

## 强制流程
1. 第一步必须做什么
2. 第二步必须做什么
3. ...（不可跳过）

## 规则
- 规则 1：具体约束
- 规则 2：具体约束

## 示例
（可选）代码示例或对话示例

2.3 触发机制：AI 如何「知道」该用哪个技能

Superpowers 的触发是 上下文感知 的，不需要手动调用（虽然也可以手动调用）。

触发流程：

1. 用户发送消息（例如：「帮我实现一个用户登录功能」）
2. Claude Code 接收到消息
3. Superpowers 插件注入的技能文件已经在 Claude 的上下文中
4. Claude 根据消息内容，自动识别 需要哪些技能
5. 按顺序激活技能，执行强制流程

关键设计：技能的 trigger 字段定义了触发条件，但 Claude 的实际判断更灵活——它会根据整个对话上下文来决定。

2.4 与纯 Prompt 工程的根本区别

三、14+ 核心技能深度详解

Superpowers 包含 14 个以上的结构化技能。下面逐一深度解析。

3.1 brainstorming（头脑风暴）

触发场景：收到新需求，尚未开始设计或编码。

强制流程：

1. 禁止直接写代码——必须先理清需求
2. 通过提问理解需求的「为什么」，而不只是「做什么」
3. 识别边缘情况（edge cases）和潜在陷阱
4. 提出至少两种实现方案
5. 输出设计文档草稿

示例对话：

用户：帮我做一个待办事项应用

普通 Claude Code：
好的！这是完整的 HTML/JS 代码……
（立刻开始写代码）

装上 Superpowers 后：
等一下，让我先问几个问题：
1. 这个应用是 Web 端还是移动端？
2. 数据需要持久化吗？本地存储还是后端？
3. 用户需要注册登录吗？
4. 待办事项需要分类、标签、截止日期吗？
5. 这是一个学习项目还是生产项目？
……
（先 brainstorm，再动手）

为什么这很重要：超过 60% 的项目失败（或需要大规模重构），根源在于需求理解不透彻。brainstorming 技能强制 AI 先「想清楚」。

3.2 writing-plans（编写计划）

触发场景：brainstorming 完成后，即将开始编码之前。

强制流程：

1. 输出结构化计划文档（Markdown 格式）
2. 计划必须包含：
   • 功能模块划分
   • 每个模块的技术选型理由
   • 数据模型设计
   • API 接口设计（如适用）
   • 文件结构规划
   • 测试策略
3. 计划完成后，必须等待用户确认才能进入编码阶段

计划文档模板（技能内置）：

# 实现计划：<功能名称>

## 目标
简明描述本次要实现的功能

## 技术选型
- 语言/框架：XXX，理由：XXX
- 数据存储：XXX，理由：XXX

## 数据模型
（ER 图或结构体定义）

## 模块划分
### 模块 A
- 职责：XXX
- 文件：XXX
- 接口：XXX

## 实现步骤
- [ ] 步骤 1
- [ ] 步骤 2
- [ ] 步骤 3

## 测试策略
- 单元测试：覆盖 XXX
- 集成测试：覆盖 XXX

## 风险与缓解
- 风险 1：XXX → 缓解措施：XXX

3.3 test-driven-development（测试驱动开发）

触发场景：开始编写任何功能代码之前。

这是 Superpowers 最重要的技能之一。

强制流程：

1. 红：先写失败测试（测试先于实现）
2. 绿：写最少代码使测试通过
3. 重构：优化代码，测试必须全程通过
4. 每个功能函数必须有对应的单元测试
5. 测试覆盖率要求：核心逻辑 ≥ 80%

代码示例：

# ❌ 没有 Superpowers：AI 直接写实现
def add(a, b):
    return a + b

# ✅ 有 Superpowers：AI 先写测试
import unittest

class TestAdd(unittest.TestCase):
    def test_add_positive(self):
        self.assertEqual(add(1, 2), 3)
    
    def test_add_negative(self):
        self.assertEqual(add(-1, -2), -3)
    
    def test_add_zero(self):
        self.assertEqual(add(0, 0), 0)

# 然后才写实现
def add(a, b):
    return a + b

对 AI 输出的革命性改变：

没有 TDD 约束时，AI 写的代码：

• 往往没有测试
• 边界情况不处理
• 函数职责不单一

有 TDD 约束后，AI 必须：

• 先想清楚函数的输入输出
• 考虑正常情况和异常情况
• 写出可测试的代码（依赖注入、纯函数优先）

3.4 systematic-debugging（系统化调试）

触发场景：代码出现 bug，或测试失败。

强制流程（4 阶段）：

阶段 1：复现

• 必须找到稳定的复现步骤
• 不能「看起来修好了」就了事

阶段 2：定位

• 使用二分法缩小问题范围
• 添加日志/断点，而不是靠「猜」

阶段 3：根因分析

• 区分症状（symptom）和根因（root cause）
• 问「为什么」至少 3 次（5 Whys 方法）

阶段 4：修复 + 回归测试

• 修复后必须添加回归测试（防止同一个 bug 再次出现）
• 提交信息必须包含 root cause 说明

示例：

Bug：用户登录后，refresh token 偶尔失效

❌ 普通做法：
「可能是 token 过期了，我帮你把过期时间改长一点」
→ 这是治标不治本，还引入了安全隐患

✅ systematic-debugging 技能：
阶段 1：复现 → 发现只在分布式部署时出现
阶段 2：定位 → 日志显示不同实例的时钟有偏差
阶段 3：根因 → refresh token 的过期判断用了本地时钟，
                多实例部署时时钟不同步导致误判
阶段 4：修复 → 改用统一的时间服务（如 NTP 或 Redis 时间），
                并添加时钟偏差的单元测试

3.5 subagent-driven-development（子代理驱动开发）

触发场景：任务可以并行处理，或需要独立验证。

核心思想：把大任务拆成小任务，每个子任务用一个独立的 Claude 会话（sub-agent）处理，最后整合。

强制流程：

1. 分析任务是否可以并行化
2. 可以并行 → 启动多个 sub-agent
3. 每个 sub-agent 有独立的上下文和任务
4. 所有 sub-agent 完成后，主 agent 整合结果
5. 关键：sub-agent 的输出必须被验证，不能直接信任

适用场景：

• 实现多个独立的 API 端点
• 前端 + 后端并行开发
• 写测试（让一个 sub-agent 专门写测试，另一个写实现）
• 代码审查（让 sub-agent 扮演「挑剔的 code reviewer」）

示例命令（在 Claude Code 中）：

用户：实现用户管理模块（增删改查）

Claude（装上 Superpowers 后）：
这个任务可以拆成 4 个并行子任务：
- Sub-agent 1：实现 CREATE 接口 + 测试
- Sub-agent 2：实现 READ 接口 + 测试
- Sub-agent 3：实现 UPDATE 接口 + 测试
- Sub-agent 4：实现 DELETE 接口 + 测试

我现在启动这 4 个 sub-agent……
（每个 sub-agent 独立工作，互不干扰）

3.6 requesting-code-review（请求代码审查）

触发场景：完成一段代码后，提交前。

强制流程：

1. 不能自己审查自己的代码——必须启动一个独立的 sub-agent 做 reviewer
2. Reviewer 必须从以下维度审查：
   • 正确性（逻辑是否有 bug）
   • 可读性（命名、注释、结构）
   • 性能（是否有明显的性能问题）
   • 安全性（是否有 SQL 注入、XSS 等漏洞）
   • 测试覆盖（是否有足够的测试）
3. Reviewer 提出意见后，必须逐条回应（修改 or 说明理由不修改）
4. 审查完成后才能提交

为什么需要独立 sub-agent 做 review：

Claude 在审查自己写的代码时，会有「确认偏差」（confirmation bias）——它倾向于认为自己写的代码是对的。独立的 sub-agent 没有这个偏差，能更客观地审查。

3.7 git 相关技能（未公开细节）

Superpowers 还包含多个 Git 工作流技能，例如：

• 分支管理：强制使用 feature 分支，不能直接提交 main/master
• 提交规范：提交信息必须遵循 Conventional Commits 规范
• PR 流程：提交前必须创建 PR，不能直推 main

（注：这部分的具体实现细节在技能的 SKILL.md 中定义，因篇幅限制不逐一展开。）

3.8 其他技能（概览）

四、安装与配置实战

4.1 环境准备

确保已安装并配置 Claude Code。

# 检查 Claude Code 是否已安装
claude --version

# 如果未安装，参考官方文档安装
# https://docs.anthropic.com/claude-code

4.2 安装方式一：官方插件市场（推荐）

这是最简单的方式，适合绝大多数用户。

步骤：

1. 打开 Claude Code
2. 在对话框中输入：

/plugin marketplace add obra/superpowers-marketplace

3. 注册市场后，安装插件：

/plugin install superpowers@superpowers-marketplace

4. 重启 Claude Code（或开启新会话）

5. 验证安装：

/help

你应该能看到以 superpowers: 开头的命令，例如：

• /superpowers:brainstorm
• /superpowers:write-plan
• /superpowers:review

4.3 安装方式二：Anthropic 官方市场（更简便）

2026 年 1 月起，Superpowers 被纳入 Anthropic 官方插件市场，安装更简单：

/plugin install superpowers@claude-plugins-official

4.4 验证安装是否成功

安装完成后，进行一次测试：

用户：帮我写一个计算斐波那契数列的函数

（观察 Claude 是否先提问需求，而不是直接写代码）

成功的标志：

• Claude 先问你：「这个函数有什么用途？性能要求高吗？需要处理大数吗？」
• 然后输出设计计划
• 然后先写测试
• 最后写实现

失败的标志（没有正确加载技能）：

• Claude 直接输出代码
• 没有测试
• 没有提问

五、生产级代码实战：从零实现一个 REST API

这一部分，我们用一个完整的实战案例，展示 Superpowers 如何改变开发流程。

5.1 需求描述

我们要实现一个简单的博客系统 REST API，功能包括：

• 创建文章（POST /posts）
• 获取文章列表（GET /posts）
• 获取单篇文章（GET /posts/:id）
• 更新文章（PUT /posts/:id）
• 删除文章（DELETE /posts/:id）

技术栈：Python + FastAPI + SQLAlchemy + SQLite

5.2 没有 Superpowers 的开发流程

先看看「普通 AI 编程」是怎么做的：

用户：帮我用 FastAPI 写一个博客 API

AI：
```python
from fastapi import FastAPI

app = FastAPI()

@app.post("/posts")
def create_post(title: str, content: str):
    # 直接写，没有数据库，没有验证，没有测试
    return {"title": title, "content": content}

（然后继续写其他端点……）

用户：加个数据库吧

AI：（修改代码，但仍然没有测试，没有错误处理……）

**问题**：
- 没有设计阶段，代码随意
- 没有测试，不知道对不对
- 没有数据模型设计，数据库 schema 混乱
- 没有错误处理，生产环境会崩

### 5.3 有 Superpowers 的开发流程

现在看看装上 Superpowers 后的完整流程。

#### 步骤 1：Brainstorming（需求澄清）

用户：帮我用 FastAPI 写一个博客 API

Claude（Superpowers 已启用）：
等一下，让我先问几个问题，确保我理解你的需求：

1. 这个 API 是个人项目还是团队协作项目？
2. 需要用户认证吗？还是公开的？
3. 文章需要支持标签、分类吗？
4. 需要分页吗？每页多少条？
5. 需要搜索功能吗？
6. 这是生产项目吗？需要部署到服务器吗？
7. 数据库有偏好吗（SQLite/PostgreSQL/MySQL）？

用户：个人项目，不需要认证，需要标签和分页，
每页 20 条，不需要搜索，用 SQLite

Claude：
好的，我理解了。让我整理一下需求：

• 博客 API，支持 CRUD
• 文章有标题、内容、标签、创建时间
• 列表接口支持分页（每页 20 条）
• 使用 SQLite 数据库
• 不需要用户认证

接下来，让我写一份设计计划。

#### 步骤 2：Writing Plans（输出设计计划）

```markdown
# 实现计划：博客系统 REST API

## 目标
实现一个基于 FastAPI + SQLAlchemy 的博客系统 REST API，
支持文章的 CRUD 操作，带分页和标签功能。

## 技术选型
- **Web 框架**：FastAPI
  - 理由：原生支持异步、自动生成 OpenAPI 文档、数据验证强大
- **ORM**：SQLAlchemy
  - 理由：成熟稳定、支持迁移、与 FastAPI 集成良好
- **数据库**：SQLite
  - 理由：个人项目、无需独立数据库服务、文件型数据库易于部署
- **测试框架**：pytest + httpx
  - 理由：FastAPI 官方推荐、异步支持好

## 数据模型

### Post（文章）
| 字段 | 类型 | 约束 |
|------|------|------|
| id | Integer | 主键，自增 |
| title | String(200) | 非空 |
| content | Text | 非空 |
| tags | String(500) | 逗号分隔的标签 |
| created_at | DateTime | 默认当前时间 |
| updated_at | DateTime | 自动更新 |

## API 设计

| 方法 | 路径 | 描述 | 请求体 | 响应 |
|------|------|------|--------|------|
| POST | /posts | 创建文章 | {title, content, tags} | 201 + 文章对象 |
| GET | /posts | 获取列表 | ?page=1&page_size=20 | 200 + 分页数据 |
| GET | /posts/{id} | 获取单篇 | - | 200 + 文章对象 |
| PUT | /posts/{id} | 更新文章 | {title?, content?, tags?} | 200 + 文章对象 |
| DELETE | /posts/{id} | 删除文章 | - | 204 |

## 项目结构

blog_api/
├── app/
│ ├── init.py
│ ├── main.py # FastAPI 应用入口
│ ├── models.py # SQLAlchemy 模型
│ ├── schemas.py # Pydantic 请求/响应 schema
│ ├── crud.py # 数据库操作函数
│ └── database.py # 数据库连接
├── tests/
│ ├── init.py
│ ├── test_posts.py # 文章 API 测试
│ └── conftest.py # pytest 固件
├── requirements.txt
└── README.md

## 实现步骤
- [ ] 步骤 1：搭建项目结构，配置 FastAPI + SQLAlchemy
- [ ] 步骤 2：定义数据模型（models.py）
- [ ] 步骤 3：定义 Pydantic schemas（schemas.py）
- [ ] 步骤 4：实现 CRUD 操作（crud.py）
- [ ] 步骤 5：实现 API 端点（main.py）
- [ ] 步骤 6：编写测试（tests/）
- [ ] 步骤 7：手动测试 + 调试

## 测试策略
- 单元测试：测试 crud.py 中的每个数据库操作函数
- 集成测试：测试每个 API 端点的请求-响应 cycle
- 边界测试：测试分页边界、无效 ID、重复创建等

## 风险与缓解
- 风险 1：SQLite 不支持并发写入 → 缓解：个人项目，并发量低
- 风险 2：tags 字段用逗号分隔，查询效率低 → 缓解：个人项目，
            数据量小；后续可拆成独立标签表

---

请确认这个计划，我再开始编码。
如果有需要调整的地方，请告诉我。

关键差异：没有 Superpowers，AI 直接写代码；有了 Superpowers，AI 先输出计划，等你确认后再动手。

步骤 3：用户确认后，开始 TDD 流程

用户：计划看起来不错，开始吧

Claude：
好的，按照 test-driven-development 技能的要求，
我先写测试，再写实现。

先从数据模型开始测试……

测试代码（Claude 先输出）：

# tests/test_posts.py
import pytest
from fastapi.testclient import TestClient
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker
from app.main import app
from app.database import Base, get_db

# 使用独立的测试数据库
SQLALCHEMY_DATABASE_URL = "sqlite:///./test.db"
engine = create_engine(SQLALCHEMY_DATABASE_URL, 
                       connect_args={"check_same_thread": False})
TestingSessionLocal = sessionmaker(bind=engine)

def override_get_db():
    db = TestingSessionLocal()
    try:
        yield db
    finally:
        db.close()

app.dependency_overrides[get_db] = override_get_db

@pytest.fixture
def client():
    Base.metadata.create_all(bind=engine)
    with TestClient(app) as c:
        yield c
    Base.metadata.drop_all(bind=engine)

def test_create_post(client):
    """测试创建文章"""
    response = client.post("/posts", json={
        "title": "测试文章",
        "content": "这是测试内容",
        "tags": "测试,Python"
    })
    assert response.status_code == 201
    data = response.json()
    assert data["title"] == "测试文章"
    assert "id" in data

def test_get_posts_empty(client):
    """测试获取空文章列表"""
    response = client.get("/posts")
    assert response.status_code == 200
    data = response.json()
    assert data["total"] == 0
    assert len(data["items"]) == 0

def test_get_posts_with_pagination(client):
    """测试分页"""
    # 先创建 25 篇文章
    for i in range(25):
        client.post("/posts", json={
            "title": f"文章 {i}",
            "content": f"内容 {i}",
            "tags": "测试"
        })
    
    # 获取第一页
    response = client.get("/posts?page=1&page_size=20")
    assert response.status_code == 200
    data = response.json()
    assert len(data["items"]) == 20
    assert data["total"] == 25
    
    # 获取第二页
    response = client.get("/posts?page=2&page_size=20")
    data = response.json()
    assert len(data["items"]) == 5

# ... 更多测试

然后才写实现代码：

# app/models.py
from sqlalchemy import Column, Integer, String, Text, DateTime
from sqlalchemy.sql import func
from app.database import Base

class Post(Base):
    __tablename__ = "posts"
    
    id = Column(Integer, primary_key=True, index=True)
    title = Column(String(200), nullable=False)
    content = Column(Text, nullable=False)
    tags = Column(String(500), nullable=True)
    created_at = Column(DateTime(timezone=True), server_default=func.now())
    updated_at = Column(DateTime(timezone=True), onupdate=func.now())

# app/main.py
from fastapi import FastAPI, Depends, HTTPException
from sqlalchemy.orm import Session
from typing import List
from app import crud, models, schemas
from app.database import engine, get_db

models.Base.metadata.create_all(bind=engine)

app = FastAPI(title="博客 API")

@app.post("/posts", response_model=schemas.PostResponse, status_code=201)
def create_post(post: schemas.PostCreate, db: Session = Depends(get_db)):
    return crud.create_post(db, post)

@app.get("/posts", response_model=schemas.PostListResponse)
def get_posts(page: int = 1, page_size: int = 20, 
              db: Session = Depends(get_db)):
    skip = (page - 1) * page_size
    posts = crud.get_posts(db, skip=skip, limit=page_size)
    total = crud.count_posts(db)
    return {"items": posts, "total": total, "page": page, "page_size": page_size}

# ... 其他端点

步骤 4：运行测试，确保全部通过

pytest tests/ -v

# 输出：
# tests/test_posts.py::test_create_post PASSED
# tests/test_posts.py::test_get_posts_empty PASSED
# tests/test_posts.py::test_get_posts_with_pagination PASSED
# ...
# ===================== 12 passed in 2.34s =====================

步骤 5：Code Review（启动独立 sub-agent）

Claude：
所有测试通过了。现在让我启动一个独立的 sub-agent 
来做代码审查……

（启动 sub-agent）

Sub-agent (reviewer)：
我审查了代码，发现以下问题：

1. 【安全性】删除文章接口没有确认机制，容易误删
2. 【性能】分页查询没有对 created_at 建索引，大数据量会慢
3. 【可读性】crud.py 中的函数命名不一致（有的用 get，有的用 fetch）

Claude：
好的，我来逐条回应：

1. 接受，添加软删除机制（is_deleted 字段）
2. 接受，在 models.py 中添加索引
3. 接受，统一用 get_ 前缀

（修改代码，并运行测试确保没破）

六、性能优化与高级技巧

6.1 如何让 Superpowers「更懂你的项目」

Superpowers 的技能是通用的，但你可以通过项目级的 CLAUDE.md 文件让它更懂你的项目。

在项目根目录创建 CLAUDE.md：

# 项目规范

## 技术栈
- Python 3.11+
- FastAPI + SQLAlchemy
- 使用 async/await（全异步）

## 代码规范
- 使用 black 格式化代码
- 使用 ruff 做 lint
- 类型注解必须完整（mypy 检查）

## 测试规范
- 测试覆盖率必须 ≥ 80%
- 每个 API 端点至少有 3 个测试（正常、边界、异常）

## 提交规范
- 遵循 Conventional Commits
- 每个 commit 必须关联 issue

## 禁止事项
- 禁止在生产代码中使用 print（必须用 logging）
- 禁止硬编码配置（必须用环境变量）

Superpowers 会自动读取 CLAUDE.md，并将其作为额外上下文。

6.2 自定义技能（进阶）

如果 Superpowers 内置的 14+ 技能不能满足你的需求，你可以写自定义技能。

在项目根目录创建 .claude/skills/my-skill/SKILL.md：

---
name: api-security-check
description: API 安全审查技能
trigger: 当涉及 API 端点实现时触发
---

# API 安全审查

## 目标
确保实现的 API 端点不存在常见安全漏洞。

## 强制检查清单
- [ ] 所有用户输入都用 Pydantic 验证
- [ ] 查询参数有最大长度限制
- [ ] 数据库查询使用参数化（防止 SQL 注入）
- [ ] 敏感数据不出现在日志中
- [ ] 错误响应不暴露内部实现细节

## 流程
1. 实现 API 端点后，暂停
2. 逐项检查 above 清单
3. 发现问题 → 修复 → 重新检查
4. 全部通过 → 继续

6.3 与 CI/CD 集成

Superpowers 本身是在开发时生效的，但你可以通过 CI/CD 确保 AI 生成的代码符合规范。

示例 .github/workflows/check.yml：

name: Check AI-Generated Code
on: [push, pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run tests
        run: pytest tests/ -v --cov=app --cov-fail-under=80
      - name: Type check
        run: mypy app/
      - name: Lint
        run: ruff check app/

七、Superpowers 的哲学：为什么「流程」比「智能」更重要

7.1 资深工程师的思维模式

Superpowers 的作者 Jesse Vincent 本人是一位有数十年经验的资深工程师。他在设计 Superpowers 时，把自己多年来积累的「工程直觉」固化成了技能文件。

这些直觉包括：

1. 先想清楚，再动手——brainstorming 技能
2. 写代码之前先写计划——writing-plans 技能
3. 测试先行——TDD 技能
4. 调试要系统化，不能靠猜——systematic-debugging 技能
5. 代码写完后必须审查——requesting-code-review 技能

7.2 AI 的「自信陷阱」

AI 有一个人类工程师没有的问题：它看起来很自信，但实际上经常犯错。

Claude 在输出代码时，往往不会说「我不确定，需要查一下」——它会直接输出一个看起来很合理的答案，即使这是错的。

Superpowers 通过强制流程，让 AI 「慢下来」，在每一步都进行验证。

7.3 Process over Prompt 的深层含义

这句话不仅仅是一个口号，它反映了软件工程的一个核心真理：

优秀的软件不是由「最聪明的程序员」写出来的，而是由「最遵守纪律的程序员」写出来的。

AI 已经足够聪明了。它需要的不是更聪明的 Prompt，而是更严格的纪律。

八、与其他工具的对比

8.1 Superpowers vs. Cursor Rules

Cursor 也有类似的功能：Cursor Rules（在项目根目录创建 .cursorrules 文件）。

8.2 Superpowers vs. GitHub Copilot

GitHub Copilot 是「代码补全工具」，它没有「工程流程」的概念。

Superpowers + Claude Code 是「AI 工程助手」，它覆盖从需求到部署的完整流程。

8.3 Superpowers vs. 手写 Prompt

很多开发者会手写很长的 Prompt，试图让 AI 遵循工程规范。

问题：

• Prompt 太长，每次对话都要粘贴
• AI 仍然可以选择忽略
• 难以维护和版本管理

Superpowers 的优势：

• 一次安装，永久生效
• 技能文件可以用 Git 管理
• 社区可以贡献和改进技能

九、常见问题与解决方案

9.1 Claude 还是「直接写代码」，没有触发技能

可能原因：

1. 插件没有正确安装
2. Claude Code 版本太旧
3. 插件的技能文件没有被正确加载

解决方法：

1. 运行 /plugin list 检查插件是否已安装
2. 更新 Claude Code 到最新版本
3. 运行 /plugin reload superpowers 重新加载

9.2 技能触发太「积极」，导致开发变慢

这是正常现象。Superpowers 的设计哲学就是「慢一点，但更可靠」。

如果你在某个场景下不需要强制流程（例如写一个一次性脚本），可以手动禁用技能：

/plugin disable superpowers

9.3 如何贡献新的技能

Superpowers 是开源项目，欢迎贡献。

步骤：

1. Fork obra/superpowers 仓库
2. 在 skills/ 目录下创建新的技能文件夹
3. 编写 SKILL.md（参考现有技能的格式）
4. 提交 PR

十、总结与展望

10.1 Superpowers 的核心价值

1. 让 AI 遵循工程纪律——这是 AI 辅助编程的「最后一公里」
2. 方法论作为代码——把资深工程师的经验固化下来
3. 跨平台——同一套技能可以在多个 AI 编程工具中使用
4. 开源——社区可以共同改进这套方法论

10.2 AI 编程的未来

Superpowers 的成功，揭示了一个重要趋势：

未来的 AI 编程工具，核心竞争力不是「模型有多聪明」，而是「谁能把最好的工程实践固化进 AI 的工作流」。

类似的框架还会不断涌现。Superpowers 是先驱，但绝不是终点。

10.3 给开发者的建议

如果你正在使用 AI 编程助手，我强烈建议：

1. 装上 Superpowers——它免费，开源，且能显著提升代码质量
2. 不要跳过 AI 的提问——当 AI 问你需求时，认真回答，这比直接写代码效率高
3. 重视测试——让 AI 先写测试，这是最容易被忽视但最有价值的部分
4. 做 code review——即使 AI 写了代码，你也要看一遍，确保理解每一行

参考资料

• Superpowers GitHub：https://github.com/obra/superpowers
• Anthropic 官方插件市场：https://docs.anthropic.com/claude-code/plugins
• Conventional Commits：https://www.conventionalcommits.org/
• Test Driven Development：https://martinfowler.com/bliki/TestDrivenDevelopment.html

本文写于 2026 年 6 月，基于 Superpowers 5.0.7 版本。如果你发现版本更新导致内容过时，欢迎在评论区指出。

作者注：这篇文章本身就是用 AI 辅助写的，但我（人类作者）遵循了 Superpowers 的理念：先 brainstorm 大纲，再写计划，然后分章节撰写，每写完一章都做 self-review。AI 是工具，工程纪律是灵魂。