让 AI 不只是「写代码」,而是「按流程写代码」
你是不是也遇到过这些问题
用AI编程工具写代码时,有没有被这些情况折磨过:
问题一:AI 想到哪写到哪
你:帮我加个登录功能
AI:好的,我来实现 OAuth + 本地登录 + 手机验证码 + 找回密码...
你:等等,我只是要个简单的登录...
AI:已经写了 8 个文件,现在改回来很麻烦
问题二:AI 写完就跑,留下一堆坑
你:功能写完了吗?
AI:写完了!
你:测试呢?
AI:呃...没写
你:代码审查呢?
AI:没做
你:现在跑一下测试...报错了?
AI:应该没问题的,我看过代码了
问题三:复杂项目无法持续推进
你:这个项目有 20 个功能要实现
AI:好的,开始写第一个
(2 小时后)
你:进行到哪了?
AI:第四个功能写了一半,但是第一个功能的测试挂了
而且我发现架构设计有问题,需要重构...
你:...
这些问题的本质是:AI 会写代码,但不懂工程流程。
Superpowers 就是为了解决这个问题而生的。
Superpowers 是什么
一句话定义:
Superpowers = AI 编程的工程化流程框架
它不是新的编程工具,而是给现有的AI编程工具装上一套「工程大脑」。
核心理念
没有 Superpowers 的 AI 编程:
需求 → 直接写代码 → 可能对可能错 → 返工
有 Superpowers 的 AI 编程:
需求 → 澄清需求 → 设计方案 → 写测试 → 写代码
→ 代码审查 → 验证通过 → 交付
三个关键特性
1. 自动触发 —— 不是建议,是强制执行
传统方式:
你:帮我写代码,记得先写测试
AI:好的...(直接开始写代码)
Superpowers 方式:
你:实现登录功能
AI:检测到新功能开发,自动进入 brainstorming 流程
先让我理解一下你的需求...
(强制走完需求澄清 → 设计 → 测试 → 代码流程)
2. 标准流程 —— 7 步工作流
Superpowers 定义了一套完整的开发流程:
| 步骤 | 阶段 (英文/中文) | 关键动作 | | :-- | :-- | :-- | | 1 | brainstorming (需求澄清) | 澄清需求、设计方案 | | 2 | using-git-worktrees (准备工作区) | 创建隔离分支、验证测试基线 | | 3 | writing-plans (编写计划) | 拆分任务、明确步骤 | | 4 | subagent-driven (执行计划) | 分任务执行、自动审查 | | 5 | test-driven-development (TDD) | 红灯 → 绿灯 → 重构 | | 6 | requesting-code-review (代码审查) | 对比计划、发现问题 | | 7 | finishing-branch (完成分支) | 验证测试、合并/PR |
3. 能力分片 —— 14 个 Skills
每个环节都是一个独立的 Skill(技能),组合起来形成完整工作流:
| 分类 | Skills | | --- | --- | | 协作 | brainstorming、writing-plans、executing-plans、subagent-driven-development、requesting-code-review、receiving-code-review | | 测试 | test-driven-development | | 调试 | systematic-debugging、verification-before-completion |
安装
1.参考官网说明
Superpowers 支持 Claude Code、OpenAI Codex CLI、Cursor、GitHub Copilot CLI 等主流工具。 官方有详细的说明
- Claude Code 为例:
/plugin install superpowers@claude-plugins-official
安装后,你应该看到类似提示:
/plugin install superpowers@claude-plugins-official
⎿ ✓ Installed superpowers. Run /reload-plugins to activate.
2.其他IDE
拷贝 Superpowers GitHub 下 skills 到 IDE 的目录下
- Lingma IDE 为例:
手动将目标 Skill 文件拷贝到下述路径后,重启 IDE,即可在对话框内通过 / 查看已加载的 Skills 列表。
| 位置 | 路径 | 作用域 | | --- | --- | --- | | 用户级 | ~/.lingma/skills/{skill-name}/SKILL.md | 当前用户的所有项目 | | 项目级 | .lingma/skills/{skill-name}/SKILL.md | 仅当前项目 |
实战演示:第一个 Superpowers 项目
让我们通过一个真实案例来体验 Superpowers 的 7 步工作流。
场景
我们要实现一个 CLI 工具:hot-trends —— 抓取掘金热榜上的AI相关文章。
选择掘金是因为它在国内开发者社区广泛使用,API 稳定、数据真实。
第一步:brainstorming(需求澄清)
输入:
我要实现一个 CLI 工具:hot-trends
功能是抓取掘金热榜上的AI相关文章
Superpowers 自动介入:
-
探索项目上下文:检查当前目录结构(空目录)
-
提出澄清问题(一次一个):
❓ 问题1:技术栈选择?
选项:Python / Go / Node.js
你选择:Python(推荐)✓
❓ 问题2:输出格式?
选项:终端表格 / JSON文件 / 两者都要
你选择:两者都要 ✓
❓ 问题3:AI筛选范围?
选项:所有AI相关 / 仅大语言模型 / 仅机器学习
你选择:所有AI相关 ✓
3. 提出3种方案:
方案1:直接API请求(推荐)→ 速度快、数据结构清晰、实现简单 ✓
方案2:网页爬取 + HTML解析 → 不依赖API但易失效
方案3:浏览器自动化 → 功能最强但复杂度过高
你确认:方案1 ✓
4. 呈现设计方案并等待确认
你确认后,AI 生成设计文档:
保存到:docs/superpowers/specs/2026-02-03-hot-trends-cli-design.md
# Hot-Trends CLI 工具设计文档
## 概述
一个用于抓取掘金热榜上AI相关文章的CLI工具,支持终端表格展示和文件导出。
## 架构设计
- 数据获取层:调用掘金API获取热榜文章
- 数据过滤层:根据AI关键词筛选文章
- 输出层:终端表格 / JSON / Markdown
- CLI入口:命令行参数解析
## 核心组件
1. JuejinFetcher:调用掘金API(https://api.juejin.cn/content_api/v1/content/article_rank)
2. AIFilter:25+个AI关键词,支持自定义
3. OutputFormatter:rich库实现终端美化输出
4. CLI参数:--limit, --output, --format, --keywords, --category, --verbose
## AI关键词(默认)
基础:AI、人工智能
大模型:LLM、GPT、ChatGPT、GPT-4
框架:LangChain、Transformer、PyTorch
技术:机器学习、深度学习、NLP、计算机视觉
新兴:AIGC、Stable Diffusion、多模态
## 技术方案
- Python 3.8+, requests, rich, argparse
- 错误处理:网络重试、数据验证、友好提示
关键点:Superpowers 强制 AI 在写代码前先想清楚设计,并展示给你确认。
第二步:using-git-worktrees(准备工作区)
说明:在这个实际案例中,我们从零创建项目,直接在当前目录初始化。如果是现有项目的新功能,应该使用 using-git-worktrees 创建隔离工作区。
AI 自动执行:
$
mkdir
-p
hot-trends/src hot-trends/tests
$
cd
hot-trends
$
git
init
Initialized empty Git repository
in
aicoding/hot-trends/.git/
创建项目基础结构:
-
src/- 源代码目录
-
tests/- 测试文件目录
-
初始化Git仓库
关键点:如果是现有项目,会创建隔离分支,确保不影响主分支,验证测试基线干净。
第三步:writing-plans(编写计划)
AI 生成实施计划:
保存到:docs/superpowers/plans/2026-02-03-hot-trends-cli-plan.md
# Hot-Trends CLI 工具实现计划
## 任务拆分(6个Task)
### Task 1: 项目初始化和数据模型
- 文件:pyproject.toml, src/__init__.py, src/models.py
- 内容:项目配置 + Article数据类(dataclass)
- 验证:python -c "from src.models import Article" 导入成功
### Task 2: 掘金数据获取器
- 文件:src/fetcher.py, tests/test_fetcher.py
- 内容:JuejinFetcher类,调用掘金API
- TDD:4个测试(初始化、自定义参数、成功、失败)
- 验证:pytest tests/test_fetcher.py -v 全部通过
### Task 3: AI关键词过滤器
- 文件:src/filter.py, tests/test_filter.py
- 内容:AIFilter类,25+默认关键词,支持自定义
- TDD:7个测试(默认关键词、自定义、标题匹配、标签匹配、非AI、大小写、过滤列表)
- 验证:pytest tests/test_filter.py -v 全部通过
### Task 4: 输出格式化器
- 文件:src/output.py, tests/test_output.py
- 内容:OutputFormatter类,终端表格/JSON/Markdown
- TDD:3个测试(JSON导出、Markdown导出、终端输出)
- 验证:pytest tests/test_output.py -v 全部通过
### Task 5: CLI入口和完整集成
- 文件:src/main.py
- 内容:parse_args() + main(),集成所有组件
- 验证:hot-trends --help 显示帮助信息
### Task 6: 创建README文档
- 文件:README.md
- 内容:安装、使用、参数说明、示例
关键点:计划明确每个任务的文件路径、代码内容、测试要求、验证步骤。
第四步:subagent-driven-development(分任务执行)
执行策略:为每个Task分派独立的子代理执行,执行后进行两阶段审查。
Task 1 执行:
# 创建文件
pyproject.toml
# 项目配置
src/__init__.py
# 包初始化
src/models.py
# Article数据模型
# 验证
$ python
-c
"from src.models import Article; print('模型导入成功')"
模型导入成功
# 提交
$
git
commit
-m
"feat: 初始化项目并创建Article数据模型"
[
main cf0b24a
]
feat: 初始化项目并创建Article数据模型
3
files changed,
58
insertions
(
+
)
Task 2-4 执行(遵循TDD流程,见第五步详细说明)
Task 5 执行:
# 创建 CLI 入口
src/main.py
# 验证
$ python
-m
src.main
--help
🔥 抓取掘金热榜上的AI相关文章
options:
-l
LIMIT,
--limit
LIMIT 获取文章数量
(
默认50
)
-o
OUTPUT,
--output
OUTPUT 输出文件路径
-f
{
json,markdown
}
输出格式
-k
KEYWORDS,
--keywords
自定义AI关键词
-c
CATEGORY,
--category
文章分类
-v,
--verbose
显示详细日志
Task 6 执行:
# 创建 README.md
README.md
# 包含安装、使用、参数、示例
关键点:每个子代理独立完成任务,自带测试和提交,互不干扰。
第五步:test-driven-development(测试驱动开发)
以 Task 2(掘金数据获取器)为例,展示完整TDD流程:
阶段1:RED(红灯)—— 先写失败的测试
# tests/test_fetcher.py
from
unittest
.
mock
import
Mock
,
patch
from
src
.
fetcher
import
JuejinFetcher
from
src
.
models
import
Article
@patch
(
'src.fetcher.requests.post'
)
def
test_fetch_hot_trends_success
(
mock_post
)
:
"""测试成功获取数据"""
mock_response
=
Mock
(
)
mock_response
.
status_code
=
200
mock_response
.
json
.
return_value
=
{
'data'
:
[
{
'content'
:
{
'title'
:
'测试文章1'
,
'content_url'
:
'https://juejin.cn/post/123'
}
,
'author'
:
{
'nickname'
:
'作者1'
,
'user_url'
:
'https://juejin.cn/user/123'
}
,
'article_info'
:
{
'view_count'
:
1000
,
'digg_count'
:
100
,
'comment_count'
:
50
}
,
'tags'
:
[
{
'title'
:
'AI'
}
,
{
'title'
:
'机器学习'
}
]
}
]
}
mock_post
.
return_value
=
mock_response
fetcher
=
JuejinFetcher
(
)
articles
=
fetcher
.
fetch_hot_trends
(
limit
=
1
)
assert
len
(
articles
)
==
1
assert
articles
[
0
]
.
title
==
'测试文章1'
assert
articles
[
0
]
.
author
==
'作者1'
assert
articles
[
0
]
.
views
==
1000
运行测试:❌ 失败
$ pytest tests/test_fetcher.py
-v
ImportError
while
importing
test
module
ModuleNotFoundError: No module named
'src.fetcher'
✅ 预期失败:因为 fetcher.py 还不存在
阶段2:GREEN(绿灯)—— 写最小代码让测试通过
# src/fetcher.py
import
requests
from
typing
import
List
from
src
.
models
import
Article
class
JuejinFetcher
:
"""掘金热榜数据获取器"""
def
__init__
(
self
,
category
:
str
=
"all"
,
limit
:
int
=
50
)
:
self
.
base_url
=
"https://api.juejin.cn/content_api/v1/content/article_rank"
self
.
category
=
category
self
.
default_limit
=
limit
def
fetch_hot_trends
(
self
,
category
:
str
=
None
,
limit
:
int
=
None
)
-
>
List
[
Article
]
:
category
=
category
or
self
.
category
limit
=
limit
or
self
.
default_limit
headers
=
{
'Content-Type'
:
'application/json'
,
'User-Agent'
:
'Hot-Trends CLI Tool'
}
payload
=
{
'category_id'
:
category
,
'type'
:
'hot'
,
'cursor'
:
'0'
,
'limit'
:
str
(
limit
)
}
try
:
response
=
requests
.
post
(
self
.
base_url
,
headers
=
headers
,
json
=
payload
,
timeout
=
10
)
response
.
raise_for_status
(
)
return
self
.
_parse_response
(
response
.
json
(
)
)
except
requests
.
RequestException
as
e
:
print
(
f"❌ 网络请求失败: {e}"
)
return
[
]
def
_parse_response
(
self
,
data
:
dict
)
-
>
List
[
Article
]
:
articles
=
[
]
for
idx
,
item
in
enumerate
(
data
[
'data'
]
,
1
)
:
article
=
Article
(
title
=
item
.
get
(
'content'
,
{
}
)
.
get
(
'title'
,
''
)
,
author
=
item
.
get
(
'author'
,
{
}
)
.
get
(
'nickname'
,
''
)
,
author_url
=
item
.
get
(
'author'
,
{
}
)
.
get
(
'user_url'
,
''
)
,
url
=
item
.
get
(
'content'
,
{
}
)
.
get
(
'content_url'
,
''
)
,
views
=
item
.
get
(
'article_info'
,
{
}
)
.
get
(
'view_count'
,
0
)
,
likes
=
item
.
get
(
'article_info'
,
{
}
)
.
get
(
'digg_count'
,
0
)
,
comments
=
item
.
get
(
'article_info'
,
{
}
)
.
get
(
'comment_count'
,
0
)
,
tags
=
[
tag
.
get
(
'title'
,
''
)
for
tag
in
item
.
get
(
'tags'
,
[
]
)
]
,
rank
=
idx
)
articles
.
append
(
article
)
return
articles
运行测试:✅ 通过
$ pytest tests/test_fetcher.py
-v
tests/test_fetcher.py::test_fetcher_initialization PASSED
tests/test_fetcher.py::test_fetcher_with_custom_params PASSED
tests/test_fetcher.py::test_fetch_hot_trends_success PASSED
tests/test_fetcher.py::test_fetch_hot_trends_failure PASSED
4
passed
in
0
.16s
阶段3:COMMIT(提交)
$
git
add
src/fetcher.py tests/test_fetcher.py
$
git
commit
-m
"feat: 实现掘金数据获取器"
[
main b89b1b0
]
feat: 实现掘金数据获取器
2
files changed,
168
insertions
(
+
)
Task 3-4 同样遵循TDD流程:
-
Task 3: 7个测试全部通过 ✅
-
Task 4: 3个测试全部通过 ✅
关键点:Superpowers 强制「测试先行」,杜绝「写完代码再补测试」的坏习惯。
第六步:requesting-code-review(代码审查)
每个任务完成后,自动触发审查:
Task 2 审查报告:
# 代码审查报告 - Task 2: 掘金数据获取器
## 符合计划 ✓
- [x] 文件路径正确(src/fetcher.py, tests/test_fetcher.py)
- [x] JuejinFetcher 类实现完整
- [x] API 端点正确(https://api.juejin.cn/content_api/v1/content/article_rank)
- [x] 测试通过(4/4 tests)
- [x] 错误处理完善(网络异常、解析异常)
## 代码质量
- [x] 类型注解完整(List[Article], dict等)
- [x] 文档字符串清晰
- [x] 异常处理友好(中文提示)
- [x] 超时设置合理(10秒)
## 测试覆盖
- [x] 正常流程测试(mock API响应)
- [x] 异常流程测试(网络失败)
- [x] 边界条件测试(初始化参数)
## 结论
✅ 审查通过,符合计划要求
Task 3 审查报告:
# 代码审查报告 - Task 3: AI关键词过滤器
## 符合计划 ✓
- [x] AIFilter 类实现完整
- [x] 25+个默认关键词覆盖全面
- [x] 支持自定义关键词追加
- [x] 测试通过(7/7 tests)
## 代码质量
- [x] 不区分大小写匹配(.lower())
- [x] 标题和标签双重检查
- [x] 关键词去重逻辑正确
## 结论
✅ 审查通过
Task 4 审查报告:
# 代码审查报告 - Task 4: 输出格式化器
## 符合计划 ✓
- [x] OutputFormatter 类实现完整
- [x] 三种输出格式(终端/JSON/Markdown)
- [x] 测试通过(3/3 tests)
## 代码质量
- [x] rich 表格格式化美观
- [x] JSON 导出格式规范(ensure_ascii=False)
- [x] Markdown 包含链接和时间戳
- [x] 目录自动创建(os.makedirs)
## 结论
✅ 审查通过
关键点:发现问题立即修复,不让债务累积。每个任务都经过独立审查。
第七步:finishing-branch(完成分支)
所有任务完成并通过验证后,执行最终检查:
1. 运行完整测试套件
$ pytest tests/
-v
tests/test_fetcher.py::test_fetcher_initialization PASSED
tests/test_fetcher.py::test_fetcher_with_custom_params PASSED
tests/test_fetcher.py::test_fetch_hot_trends_success PASSED
tests/test_fetcher.py::test_fetch_hot_trends_failure PASSED
tests/test_filter.py::test_default_keywords PASSED
tests/test_filter.py::test_custom_keywords PASSED
tests/test_filter.py::test_is_ai_related_by_title PASSED
tests/test_filter.py::test_is_ai_related_by_tags PASSED
tests/test_filter.py::test_not_ai_related PASSED
tests/test_filter.py::test_case_insensitive PASSED
tests/test_filter.py::test_filter_articles PASSED
tests/test_output.py::test_save_json PASSED
tests/test_output.py::test_save_markdown PASSED
tests/test_output.py::test_print_table PASSED
==
==
==
==
==
==
==
==
==
==
==
==
==
==
==
14
passed
in
0
.24s
==
==
==
==
==
==
==
==
==
==
==
==
==
==
==
✅ 14个测试全部通过
2. 验证项目结构
hot-trends/
├── pyproject.toml # 项目配置
├── README.md # 使用文档
├── src/
│ ├── __init__.py # 包初始化
│ ├── models.py # Article数据模型
│ ├── fetcher.py # 掘金API数据获取器
│ ├── filter.py # AI关键词过滤器
│ ├── output.py # 输出格式化器
│ └── main.py # CLI入口
└── tests/
├── test_fetcher.py # 数据获取器测试(4个测试)
├── test_filter.py # 过滤器测试(7个测试)
└── test_output.py # 输出格式化器测试(3个测试)
3. 检查Git提交历史
$
git
log
--oneline
f8f509e docs: 添加项目README文档
da38548 feat: 实现CLI入口和完整集成
b0a7e27 feat: 实现输出格式化器
0c721a4 feat: 实现AI关键词过滤器
b89b1b0 feat: 实现掘金数据获取器
cf0b24a feat: 初始化项目并创建Article数据模型
✅ 6次提交,遵循约定式提交规范,每次独立可工作
4. 功能验证
# 测试CLI帮助
$ python
-m
src.main
--help
🔥 抓取掘金热榜上的AI相关文章
options:
-l
LIMIT,
--limit
LIMIT 获取文章数量
(
默认50
)
-o
OUTPUT,
--output
OUTPUT 输出文件路径
-f
{
json,markdown
}
输出格式
-k
KEYWORDS,
--keywords
自定义AI关键词
-c
CATEGORY,
--category
文章分类
-v,
--verbose
显示详细日志
5. 完成检查清单
# 完成检查
## 测试状态
- ✅ 单元测试:14个测试全部通过
- ✅ 功能验证:CLI 帮助信息正常
- ✅ 代码审查:6个任务全部通过审查
## 代码质量
- ✅ 遵循TDD流程(先测试后实现)
- ✅ 类型注解完整
- ✅ 错误处理友好
- ✅ 文档字符串清晰
## Git 规范
- ✅ 6次提交,每次独立可工作
- ✅ 提交信息遵循约定式(feat/docs)
- ✅ 无未提交的修改
## 文档完整性
- ✅ README.md 包含安装、使用、参数、示例
- ✅ 设计文档:docs/superpowers/specs/2026-02-03-hot-trends-cli-design.md
- ✅ 实施计划:docs/superpowers/plans/2026-02-03-hot-trends-cli-plan.md
## 下一步选项
1. 合并到主分支
2. 创建 Pull Request
3. 保留分支继续开发
4. 放弃更改
请选择:
关键点:完整验证后才考虑合并,确保代码质量。
有了 Superpowers 后的变化
Before vs After
| 场景 | 没有 Superpowers | 有 Superpowers | | --- | --- | --- | | 需求理解 | AI 自己猜 | 强制澄清并确认(3个问题) | | 方案设计 | 直接开写 | 先出设计方案,用户确认 | | 开发流程 | 想到哪写到哪 | 标准化7步流程 | | 测试 | 写完代码再说 | 强制 TDD,14个测试全部通过 | | 代码质量 | 靠自觉 | 每任务独立审查 | | 复杂项目 | 容易失控 | 任务拆分 + 分步验证 | | Git 提交 | 一次大提交 | 6次小提交,每次独立可工作 | | 文档 | 经常遗漏 | 自动生成 README + 设计文档 |
适合什么项目
适合:
-
50行以上的功能开发
-
需要测试保障的项目
-
多功能持续迭代
-
团队协作项目
-
复杂 CLI 工具开发(如本例 hot-trends)
不适合:
-
简单脚本(<50行)
-
一次性验证想法
-
快速原型
常见问题
Q1:可以跳过某些步骤吗?
可以,但不推荐。Superpowers 的价值就在于强制流程。
如果确实需要,可以:
/skip-review # 跳过代码审查(不推荐)
Q2:和 CLAUDE.md 的关系?
CLAUDE.md = 项目级约束(代码风格、架构规范)Superpowers = 流程级约束(开发步骤、质量保障)
两者互补,可以一起使用。
下一步
你已经学会了 Superpowers 的基本使用,知道它如何让 AI 按7步流程写代码。
但 Superpowers 只是「铁三角」的第一角。当一个项目需要:
-
标准化的执行流程
→ Superpowers ✅ 已学
-
规范化的需求定义
→ OpenSpec
-
系统化的行为约束
→ Harness Engineering
三者结合,才是完整的 AI 编程工程化体系。
下一篇,我们来讲 OpenSpec:在 AI 写代码前先对齐需求。
扩展阅读
-
Superpowers GitHub
-
Claude Code 官方插件市场
-
Superpowers Discord 社区
