夜雨聆风
AI 编程铁三角:01 Superpowers 入门
让 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 定义了一套完整的开发流程:
|
|
|
|
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
3. 能力分片 —— 14 个 Skills
每个环节都是一个独立的 Skill(技能),组合起来形成完整工作流:
|
|
|
|---|---|
| 协作 |
|
| 测试 |
|
| 调试 |
|
安装
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 列表。
|
|
|
|
|---|---|---|
|
|
|
|
|
|
|
|
实战演示:第一个 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 initInitialized 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.mdREADME.md # 包含安装、使用、参数、示例关键点:每个子代理独立完成任务,自带测试和提交,互不干扰。
第五步:test-driven-development(测试驱动开发)
以 Task 2(掘金数据获取器)为例,展示完整TDD流程:
阶段1:RED(红灯)—— 先写失败的测试
# tests/test_fetcher.pyfrom unittest.mock import Mock, patchfrom src.fetcher import JuejinFetcherfrom src.models import Article@patch('src.fetcher.requests.post')deftest_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)assertlen(articles)==1assert articles[0].title =='测试文章1'assert articles[0].author =='作者1'assert articles[0].views ==1000运行测试:❌ 失败
$ pytest tests/test_fetcher.py -vImportError while importing test moduleModuleNotFoundError: No module named 'src.fetcher'✅ 预期失败:因为 fetcher.py 还不存在
阶段2:GREEN(绿灯)—— 写最小代码让测试通过
# src/fetcher.pyimport requestsfrom typing import Listfrom src.models import ArticleclassJuejinFetcher:"""掘金热榜数据获取器"""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 = limitdeffetch_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 inenumerate(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 -vtests/test_fetcher.py::test_fetcher_initialization PASSEDtests/test_fetcher.py::test_fetcher_with_custom_params PASSEDtests/test_fetcher.py::test_fetch_hot_trends_success PASSEDtests/test_fetcher.py::test_fetch_hot_trends_failure PASSED4 passed in0.16s阶段3:COMMIT(提交)
$ gitadd 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/ -vtests/test_fetcher.py::test_fetcher_initialization PASSEDtests/test_fetcher.py::test_fetcher_with_custom_params PASSEDtests/test_fetcher.py::test_fetch_hot_trends_success PASSEDtests/test_fetcher.py::test_fetch_hot_trends_failure PASSEDtests/test_filter.py::test_default_keywords PASSEDtests/test_filter.py::test_custom_keywords PASSEDtests/test_filter.py::test_is_ai_related_by_title PASSEDtests/test_filter.py::test_is_ai_related_by_tags PASSEDtests/test_filter.py::test_not_ai_related PASSEDtests/test_filter.py::test_case_insensitive PASSEDtests/test_filter.py::test_filter_articles PASSEDtests/test_output.py::test_save_json PASSEDtests/test_output.py::test_save_markdown PASSEDtests/test_output.py::test_print_table PASSED==============================14 passed in0.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 --onelinef8f509e 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 Request3. 保留分支继续开发4. 放弃更改请选择:关键点:完整验证后才考虑合并,确保代码质量。
有了 Superpowers 后的变化
Before vs After
|
|
|
|
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
适合什么项目
适合:
-
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 社区