Superpowers完全实战指南:给 AI 编程助手装上一整套开发方法论,实现工程化编程-夜雨聆风

Superpowers完全实战指南:给 AI 编程助手装上一整套开发方法论,实现工程化编程

前言：AI 编程的“能力-纪律”剪刀差

2025 年，AI 编程工具彻底爆发了。

Claude Code、Cursor、Windsurf、OpenCode…各类 AI 编程助手如雨后春笋般涌现，它们能够根据自然语言描述生成代码，甚至能独立完成整个项目的开发。

但一个尖锐的问题也随之浮现：AI 越来越聪明，代码却越来越“随意”。

这种现象被业内称为“能力-纪律”剪刀差：

• 能力端：AI 能够理解复杂需求，生成高质量代码
• 纪律端：AI 缺乏工程化思维，不懂最佳实践，容易“放飞自我”

具体表现为：

• 不写测试就交付代码
• 不做 Code Review 直接合并
• 忽略项目规范和代码风格
• 不知道何时该重构，何时该止步
• 遇到 Bug 就盲目试错，缺乏系统化调试方法

如何解决这个问题？Superpowers 给出了答案。

第一章：Superpowers 是什么？

1.1 项目简介

Superpowers（GitHub: obra/superpowers）是由 Jesse Vincent 创建的一个代理技能框架和软件开发方法论，专门为 AI 编码代理设计。

截至2026年4月，Superpowers 在 GitHub 上已获得 15.8万+ Star，成为 AI 编程领域最受关注的开源项目之一。

用一句话概括 Superpowers：

它不是让 AI 更快地写代码，而是让 AI 遵循专业的软件工程流程工作。

1.2 核心理念

Superpowers 的核心思路很简单：不要让 AI 直接写代码，而是先让 AI 学会像专业工程师一样思考。

具体体现在：

1. 技能优先：每个工程任务都被分解为可复用的“技能”（Skills），而非一次性的 Prompt
2. 流程强制：通过 SKILL.md 文件定义明确的工作流程和硬性门槛
3. 最佳实践内置：将 decades of software engineering 沉淀为 AI 可执行的指令
4. 可组合性： Skills 可以像乐高积木一样组合使用

1.3 为什么叫“Superpowers”？

这个名字有两层含义：

1. 给 AI 赋予“超能力”：通过预定义的技能库，让 AI 具备专业软件工程师的思维方式和工具使用能力
2. 像超级英雄一样工作：不再是“代码生成器”，而是“有纪律的工程师”

第二章：Superpowers 的三大核心模块

Superpowers 的技能库分为三大类，每类对应不同的工程阶段：

2.1 系统技能（System Skills）

作用：项目管理、任务规划、流程控制

代表技能：

• using-superpowers – 技能调用总则
• brainstorming – 头脑风暴
• systematic-debugging – 系统化调试
• architectural-decision-records – 架构决策记录
• task-planning-and-execution – 任务规划与执行

2.2 写作技能（Writing Skills）

作用：文档撰写、代码生成规范

代表技能：

• writing-code – 代码编写规范
• writing-tests – 测试编写
• writing-plans – 计划撰写
• writing-code-reviews – 代码审查
• improving-readability – 提升代码可读性

2.3 执行技能（Execution Skills）

作用：具体的技术执行

代表技能：

• github-issue-driven-development – GitHub Issue 驱动开发
• systematic-review – 系统化代码审查
• read-before-writing – 写代码前先阅读
• commit-message-conventions – 提交信息规范

第三章：14 项核心技能详解

Superpowers 内置了 14 项核心技能，这是其精髓所在。下面逐一详解：

3.1 using-superpowers（技能调用总则）

这是整个 Superpowers 体系的入口，定义了如何正确调用其他技能。

核心要点：

• 任何任务开始前，先评估需要哪些技能
• 遵循“规划→执行→验证”的工作流
• 每个技能都有明确的触发条件和退出条件

3.2 brainstorming（头脑风暴）

作用：在动手写代码之前，充分讨论需求和方案

工作流程：

1. 明确问题边界
2. 列举可能的解决方案
3. 评估每种方案的优缺点
4. 确定推荐方案

为什么重要：AI 经常“急于求成”，跳过思考直接写代码。brainstorming 强制 AI 先思考再动手。

3.3 systematic-debugging（系统化调试）

作用：将调试工作系统化，避免盲目试错

核心步骤：

1. 复现问题：确保能稳定复现 Bug
2. 定位根因：通过二分法快速缩小范围
3. 提出假设：基于证据而非猜测
4. 验证修复：确保修复不引入新问题

口诀：复现→定位→假设→验证

3.4 writing-code（代码编写）

核心规范：

• 先读代码再写代码（read-before-writing）
• 遵循项目的代码风格
• 保持函数短小、职责单一
• 添加有意义的注释

硬性门槛：

• 代码必须通过 lint 检查
• 必须包含基本的错误处理
• 必须考虑边界情况

3.5 writing-tests（测试编写）

测试金字塔：

• 单元测试：覆盖核心业务逻辑
• 集成测试：验证模块间协作
• 端到端测试：确保用户流程正常

Superpowers 的测试哲学：

• 测试不仅是验证，更是文档
• 测试应该表达意图，而非仅仅检查结果
• 测试覆盖率是结果，不是目标

3.6 systematic-review（系统化代码审查）

审查清单：

1. 功能正确性：代码是否实现了预期功能？
2. 代码质量：是否遵循项目规范？
3. 安全性：是否存在安全漏洞？
4. 性能：是否存在性能问题？
5. 可维护性：代码是否易于理解和修改？

3.7 read-before-writing（写前先读）

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

工作流程：

1. 找到相关的现有代码
2. 理解其设计思路和实现细节
3. 理解其与目标功能的关联
4. 再开始编写新代码

为什么重要：AI 经常“闭眼写代码”，忽略与现有代码的整合，导致大量返工。

3.8 architectural-decision-records（ADR）

作用：记录架构决策的上下文和理由

ADR 模板：

# ADR N: [决策标题]## 状态[Proposed | Accepted | Deprecated | Superseded]## 背景[描述需要解决的问题]## 决策[描述最终选择的方案]## 后果[描述决策的影响]

3.9 github-issue-driven-development（GitHub Issue 驱动开发）

工作流：

1. 从 Issue 中提取任务
2. 创建分支
3. 开发并提交
4. 创建 PR 并关联 Issue
5. 等待 Code Review

3.10 commit-message-conventions（提交规范）

格式：

<type>(<scope>): <subject><body><footer>

Type 类型：

• feat: 新功能
• fix: Bug 修复
• docs: 文档更新
• style: 代码格式
• refactor: 重构
• test: 测试
• chore: 维护

3.11 improving-readability（提升可读性）

关注点：

• 变量命名是否清晰
• 函数是否过长
• 是否有重复代码
• 注释是否有用
• 是否遵循 SOLID 原则

3.12 task-planning-and-execution（任务规划与执行）

步骤：

1. 分解大任务为小任务
2. 估算每个小任务的复杂度
3. 确定依赖关系
4. 按序执行
5. 验收每个任务

3.13 writing-plans（撰写计划）

计划模板：

## 目标[清晰定义要完成的事情]## 范围[明确包含和不包含的内容]## 方案[详细描述实现方案]## 风险[识别潜在风险和应对措施]## 验收标准[如何判断任务完成]

3.14 writing-code-reviews（代码审查）

审查者 checklist：

• [ ] 代码是否正确实现了需求？
• [ ] 是否有潜在的 Bug？
• [ ] 代码是否可读易懂？
• [ ] 是否有安全风险？
• [ ] 性能是否满足要求？
• [ ] 测试是否充分？

第四章：安装与配置

4.1 环境要求

• Node.js 18+
• npm 或 yarn
• Claude Code / Cursor / Codex 等 AI 编程工具

4.2 安装步骤

方式一：Claude Code 插件安装

# 在 Claude Code 中安装/plugin install superpowers@claude-plugins

方式二：直接克隆仓库

# 克隆 Superpowers 仓库git clone https://github.com/obra/superpowers.git# 进入目录cd superpowers# 查看可用的 skillsls skills/

4.3 配置 CLAUDE.md

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

# 项目配置## 开发规范- 使用 TypeScript- 遵循 Airbnb JavaScript Style Guide- 必须编写测试## Superpowers 配置- 启用所有系统技能- 启用所有写作技能- 启用所有执行技能## 工作流1. 任何任务开始前进行 brainstorming2. 写代码前先 read-before-writing3. 完成后进行 systematic-review

第五章：实战案例

5.1 案例一：开发一个 REST API

需求：开发一个用户管理的 REST API

错误方式（没有 Superpowers）：

用户：帮我写一个用户管理的 APIAI：直接开始写代码...- user.controller.ts- user.service.ts- user.model.ts- ...

结果：代码没有测试、不符合规范、难以维护

正确方式（使用 Superpowers）：

第一步：brainstorming

用户：帮我写一个用户管理的 APIAI：让我先进行头脑风暴，明确以下问题：1. 需要哪些端点？（CRUD）2. 数据模型是什么？3. 认证方式？4. 错误处理策略？5. 分页/过滤需求？在明确这些问题之前，我无法开始编写代码。

第二步：task-planning-and-execution

AI：基于讨论，我制定如下计划：任务 1：创建数据模型任务 2：实现 CRUD 端点任务 3：添加认证中间件任务 4：编写单元测试任务 5：编写集成测试开始执行...

第三步：read-before-writing

AI：开始编写代码前，我先查看项目现有的代码结构和模式- 现有的 controller 风格- 现有的 service 层设计- 现有的测试模式...

第四步：writing-code

AI：按照项目规范编写代码...编写 user.model.ts编写 user.service.ts编写 user.controller.ts

第五步：writing-tests

AI：编写测试...单元测试：user.service.test.ts集成测试：user.api.test.ts

第六步：systematic-review

AI：代码审查...✓ 功能正确✓ 遵循项目规范✓ 有错误处理✓ 测试通过可以合并

5.2 案例二：修复一个 Bug

场景：用户报告登录功能有时候会失败

错误方式：

用户：登录有时候失败AI：我来帮你修...（然后盲目修改代码）

正确方式（systematic-debugging）：

第一步：复现问题

AI：让我先尝试复现这个问题...1. 检查登录相关的代码2. 查看错误日志3. 尝试各种场景

第二步：定位根因

AI：通过日志分析，问题可能出在...让我进一步验证...

第三步：提出假设

AI：我的假设是：token 过期时间计算错误

第四步：验证修复

AI：修复后，测试各种登录场景...✓ 正常登录✓ token 过期✓ 刷新 token✓ 并发登录问题已修复

第六章：Superpowers 的工程哲学

6.1 从“Vibe Coding”到“Disciplined Engineering”

Vibe Coding（氛围编程）：

• 告诉 AI 要做什么
• AI 直接生成代码
• 不关心过程，只关心结果
• 适合：快速原型、简单项目

Disciplined Engineering（有纪律的工程）：

• 先理解需求和上下文
• 制定计划并评估风险
• 按流程执行并验证
• 适合：生产项目、团队协作

Superpowers 正是推动 AI 编程从 Vibe Coding 走向 Disciplined Engineering 的框架。

6.2 技能 vs. Prompt

Prompt 的问题：

• 难以复用
• 难以版本控制
• 难以测试
• 质量参差不齐

Skill 的优势：

• 标准化：每个 Skill 有明确的输入输出
• 可复用：一次定义，多次使用
• 可测试：可以验证 Skill 的效果
• 可组合：多个 Skill 可以组合使用
• 可演进：可以持续优化

6.3 强制流程的好处

Superpowers 强制 AI 遵循流程，但这不是限制，而是赋能：

1. 减少返工：通过提前思考，避免写到一半发现方向错误
2. 提高质量：通过 Code Review 和测试，确保代码质量
3. 便于协作：通过文档和 ADR，让团队成员理解决策
4. 易于维护：通过规范和测试，让代码易于修改

第七章：常见问题与解决方案

7.1 Superpowers 适合哪些项目？

• 适合：生产级项目、团队协作、需要长期维护的项目
• 不适合：快速原型、一次性脚本、简单任务

7.2 如何平衡效率与流程？

策略：

1. 对于简单任务，可以跳过某些 Skill
2. 对于关键任务，严格执行所有流程
3. 根据项目风险级别调整流程复杂度

7.3 如何自定义 Skills？

创建 skills/my-custom-skill/SKILL.md：

# My Custom Skill## When to use当需要...## What it does1. 第一步...2. 第二步...## Hard constraints- 必须...- 不能...## Output输出...

第八章：Superpowers 与其他工具的对比

8.1 vs. Claude Code 原生能力

方面	Claude Code 原生	Superpowers
代码生成	✓	✓
测试生成	✓	✓
流程强制	✗	✓
技能复用	✗	✓
ADR 支持	✗	✓

8.2 vs. Cursor

方面	Cursor	Superpowers
AI 补全	✓	需要配合其他工具
流程控制	弱	强
技能系统	✗	✓
自定义程度	中	高

8.3 vs. 传统 CI/CD

方面	传统 CI/CD	Superpowers
时机	提交后	开发中
焦点	自动化检测	主动规范
粒度	粗	细
成本	高	低

第九章：进阶使用技巧

9.1 自定义工作流

根据项目需求，创建自定义的技能组合：

# 我的项目工作流1. brainstorming → 需求讨论2. task-planning → 任务规划3. read-before-writing → 读代码4. writing-code → 写代码5. writing-tests → 写测试6. systematic-review → 代码审查

9.2 团队协作

最佳实践：

1. 将 Superpowers 集成到项目模板
2. 团队成员统一安装
3. 定期回顾和改进技能
4. 共享自定义技能

9.3 与其他工具集成

GitHub Actions 集成：

# .github/workflows/ci.ymlname: CIon: [push, pull_request]jobs:  build:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v2      - name: Run Superpowers checks        run: npx superpowers check

第十章：总结与展望

10.1 Superpowers 的价值

Superpowers 的核心价值在于：

1. 将工程纪律引入 AI 编程
2. 让 AI 从“代码生成器”变为“工程师伙伴”
3. 提供可复用、可测试、可组合的技能系统

10.2 未来展望

随着 AI 编程工具的普及，工程化将成为核心竞争力。Superpowers 代表了 AI 编程的正确方向：

• 从“能写”到“会写”
• 从“快速”到“稳健”
• 从“个人”到“团队”

10.3 如何开始

1. 立即尝试：安装 Superpowers，在一个简单项目中体验
2. 理解核心技能：重点掌握 brainstorming、systematic-debugging、read-before-writing
3. 逐步集成：将流程融入日常开发
4. 持续优化：根据实际使用反馈，调整技能配置

附录

A. 14 项核心技能速查表

技能名	作用	重要程度
using-superpowers	技能调用总则	⭐⭐⭐⭐⭐
brainstorming	头脑风暴	⭐⭐⭐⭐⭐
systematic-debugging	系统化调试	⭐⭐⭐⭐⭐
read-before-writing	写前先读	⭐⭐⭐⭐⭐
writing-code	代码编写	⭐⭐⭐⭐⭐
writing-tests	测试编写	⭐⭐⭐⭐⭐
systematic-review	代码审查	⭐⭐⭐⭐
commit-message-conventions	提交规范	⭐⭐⭐⭐
task-planning-and-execution	任务规划	⭐⭐⭐⭐
architectural-decision-records	架构决策	⭐⭐⭐⭐
writing-plans	计划撰写	⭐⭐⭐
improving-readability	提升可读性	⭐⭐⭐
github-issue-driven-development	Issue 驱动	⭐⭐⭐
writing-code-reviews	代码审查（发起）	⭐⭐⭐

B. 安装命令汇总

# 安装 Claude Code 插件/plugin install superpowers@claude-plugins# 克隆完整仓库git clone https://github.com/obra/superpowers.git# 查看可用技能ls skills/

C. 相关资源

• GitHub：https://github.com/obra/superpowers
• 官方文档：https://github.com/obra/superpowers/blob/main/README.md
• Claude Code：https://claude.com/code
• Anthropic Agent Skills：https://docs.anthropic.com/en/docs/claude-code/agent-skills

既然看到这里了，如果觉得不错，随手点个赞、在看、转发三连吧，如果想第一时间收到推送，也可以给我个星标⭐～

谢谢你看我的文章，我们，下次再见