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 定义了一套完整的开发流程:

步骤	阶段 (英文/中文)	关键动作
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

---

安装

参考官网说明 Superpowers GitHub

Claude Code/OpenAI Codex CLI/OpenAI Codex App/Cursor/OpenCode/GitHub Copilot CLI/Gemini CLI 官方有详细的说明

• Claude Code 为例:

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.

其他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. 探索项目上下文:检查当前目录结构(空目录)
2. 提出澄清问题(一次一个):
   • ❓ 问题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:国内网络访问 GitHub 慢,安装插件失败?

解决:

# 方式一:配置 Git 代理
git config --global http.proxy http://127.0.0.1:7890

# 方式二:使用镜像
# 部分插件市场在国内有镜像,具体见各插件文档

Q2:安装后没效果?

检查清单:

• 是否重启了 Claude Code / Cursor
• 插件是否安装成功(/plugin list 查看)
• 是否在新项目中使用(Superpowers 对现有项目需要手动触发)

Q3:可以跳过某些步骤吗?

可以,但不推荐。Superpowers 的价值就在于强制流程。

如果确实需要,可以:

/skip-review  # 跳过代码审查(不推荐)

Q4:国内开发者能用哪些 AI 编程工具搭配 Superpowers?

Superpowers 支持大多数主流 AI 编程工具,以下在国内均可正常使用:

• Claude Code(通过 API)
• Cursor
• GitHub Copilot
• 通义灵码(阿里,国内原生支持)
• 文心快码(百度)
• CodeGeeX(智谱)

Q5:和 CLAUDE.md 的关系?

CLAUDE.md = 项目级约束(代码风格、架构规范)
Superpowers = 流程级约束(开发步骤、质量保障)

两者互补,可以一起使用。

---

下一步

你已经学会了 Superpowers 的基本使用,知道它如何让 AI 按7步流程写代码。

但 Superpowers 只是「铁三角」的第一角。当一个项目需要:

• 标准化的执行流程 → Superpowers ✅ 已学
• 规范化的需求定义 → OpenSpec
• 系统化的行为约束 → Harness Engineering

三者结合,才是完整的 AI 编程工程化体系。

下一篇,我们来讲 OpenSpec:在 AI 写代码前先对齐需求。

---

扩展阅读

• Superpowers GitHub
• Claude Code 官方插件市场
• Superpowers Discord 社区