Superpowers 深度解析：让 AI 编程助手拥有「超能力」的工程化工作流框架——从 TDD 强制执跑到生产级代码交付的完整技术内幕

本文深度解析 GitHub 78,000+ Star 的 AI 编程工程化框架 Superpowers，揭秘其如何通过结构化技能系统将 AI 编码助手从「代码生成器」进化为「软件工程师伙伴」，涵盖架构设计、TDD 工作流、技能系统实现原理及生产级最佳实践。

一、背景介绍：AI 编程助手的「最后一公里」困境

1.1 现状：代码生成 ≠ 软件工程

2024-2026 年，AI 编程工具迎来爆发式增长。从 GitHub Copilot 到 Claude Code，从 Cursor 到 OpenCode，开发者们似乎已经进入了「AI 辅助编程」的新时代。然而，实际使用过这些工具的工程师都会遇到一个尴尬的问题：

AI 能生成代码，但生成不出「工程化」的代码。

具体表现为：

1. 跳过测试：AI 直接生成业务代码，忽略单元测试和集成测试
2. 缺乏设计：没有需求分析、架构设计，直接「拍脑袋」写代码
3. 代码屎山：生成的代码能跑，但不可维护、不可扩展
4. 无代码审查：AI 不会自我审查，错误和不足直接抛给用户
5. 上下文丢失：复杂任务中 AI 容易「忘事」，导致前后矛盾

1.2 根本原因：AI 缺少「工程肌肉记忆」

人类工程师经过长期训练，会形成一系列「肌肉记忆」：

• 写代码前先写测试（TDD）
• 提交前做代码审查（Code Review）
• 遵循 DRY、YAGNI、SOLID 等设计原则
• 拆解复杂问题为可控的小任务

而当前的 AI 编程助手，本质上是一个「下一个 token 预测器」，它没有经过工程化训练，不知道这些隐性的工程实践。

1.3 Superpowers 的破局思路

Superpowers 项目（GitHub: github.com/obra/superpowers）提出了一个颠覆性的解决方案：

不让 AI 「学习」工程实践，而是用工作流框架「强制」AI 遵循工程实践。

Superpowers 不提供新的大模型，也不训练新的 AI。它是一套可组合的工程化技能系统（Skills System），通过结构化提示词和工作流定义，将专业工程师的「肌肉记忆」注入到任意 AI 编程助手（Claude Code、Cursor、OpenCode 等）中。

核心数据：

• GitHub Star 数：78,000+（2026 年 5 月数据）
• 增长速度：日均 +200 Star
• 支持的 AI 平台：Claude Code、Codex、OpenCode、Cursor
• 技能数量：14+ 内置技能，支持自定义扩展

二、核心概念：Superpowers 的架构设计与工作原理

2.1 三层架构设计

Superpowers 采用经典的三层架构，确保跨平台兼容性和可扩展性：

┌─────────────────────────────────────────────────┐
│          可插拔技能层（Skills Layer）              │
│  14+ 内置技能，用户可自定义扩展                     │
└─────────────────────────────────────────────────┘
                         ▲
                         │
┌─────────────────────────────────────────────────┐
│         平台适配层（Platform Adapter Layer）        │
│  Claude Code / Cursor / OpenCode / Codex        │
└─────────────────────────────────────────────────┘
                         ▲
                         │
┌─────────────────────────────────────────────────┐
│         共享核心模块（Shared Core Module）          │
│  技能注册系统、工作流引擎、上下文管理                │
└─────────────────────────────────────────────────┘

2.1.1 共享核心模块

提供框架的基础能力：

• 技能注册系统：统一管理所有技能（Skills）的注册、发现、执行
• 工作流引擎：定义和执行多步骤的软件开发流程
• 上下文管理：维护任务拆解、代码变更、测试结果等状态信息
• Git 集成：自动创建隔离工作树（Worktree），确保主分支安全

2.1.2 平台适配层

针对不同 AI 编程工具进行适配：

2.1.3 可插拔技能层

这是 Superpowers 的核心价值所在。每个技能（Skill）是一个独立的功能模块，包含：

• 触发条件：什么时候应该启用这个技能
• 执行流程：详细的步骤定义（用 Markdown 编写的结构化提示词）
• 输入输出规范：明确的格式要求
• 验证机制：如何确保执行质量

2.2 技能系统（Skills System）详解

Superpowers 的创新之处在于将「工程最佳实践」封装为可组合的技能（Skills）。

2.2.1 内置技能清单

截至 2026 年 5 月，Superpowers 提供以下内置技能：

2.2.2 技能的组合与触发

Superpowers 支持技能的组合使用。例如，一个完整的开发流程可能是：

spec → design → tdd → code-review → integrate

AI 会根据当前任务自动判断需要触发哪些技能。例如：

• 用户说「帮我实现一个用户登录功能」→ 触发 spec + design + tdd
• 用户说「这段代码有 bug」→ 触发 debug + tdd
• 用户说「帮我重构这个函数」→ 触发 refactor + code-review

2.2.3 技能的实现原理

每个技能本质上是一个精心设计的提示词模板（Prompt Template），包含：

1. 角色定义：「你是一个遵循 TDD 原则的资深工程师…」
2. 步骤清单：「第一步：写出会失败的测试；第二步：写最少代码让测试通过…」
3. 输出格式：「测试文件应命名为 test_xxx.py，遵循 pytest 规范…」
4. 验证标准：「所有测试必须通过，代码覆盖率 > 80%…」

这种设计让 Superpowers 可以在不修改 AI 模型的情况下，通过提示词工程（Prompt Engineering）实现工程化约束。

三、架构分析：Superpowers 的技术实现内幕

3.1 工作流引擎设计

Superpowers 的核心是一个声明式工作流引擎，它定义了软件开发的完整生命周期：

# 完整开发工作流（simplified）

## Phase 1: 需求分析（_spec skill_）
1. 与用户澄清需求，提出关键问题
2. 生成规格说明文档（Specification）
3. 等待用户确认

## Phase 2: 技术设计（_design skill_）
1. 根据规格说明，设计技术架构
2. 定义模块划分、接口设计、数据模型
3. 输出设计文档（Design Document）
4. 等待用户确认

## Phase 3: 任务拆解（_plan skill_）
1. 将设计文档拆解为原子任务（Atomic Tasks）
2. 每个任务应该是 1-2 小时可完成的独立单元
3. 生成任务清单（Task List）

## Phase 4: TDD 循环（_tdd skill_）
For each atomic task:
    1. **RED**: 写出会失败的测试用例
    2. **GREEN**: 写最少代码让测试通过
    3. **REFACTOR**: 重构代码，确保质量
    4. 运行所有测试，必须 100% 通过
    5. 触发 code-review 技能进行自我审查

## Phase 5: 集成与交付（_integrate skill_）
1. 所有任务完成后，进行最终集成测试
2. 触发完整的 code-review 流程
3. 生成 Commit Message（遵循 Conventional Commits 规范）
4. 创建 Git 分支，提交代码
5. 输出完成报告

3.1.1 状态管理

工作流引擎需要维护复杂的状态信息：

# 伪代码：工作流状态管理
class WorkflowState:
    def __init__(self):
        self.current_phase = "spec"  # spec → design → plan → tdd → integrate
        self.tasks = []              # 拆解后的原子任务列表
        self.current_task_id = 0    # 当前执行的任务索引
        self.test_results = []       # 测试结果历史
        self.code_reviews = []       # 代码审查记录
        self.git_worktree_path = ""  # 隔离工作树路径
        
    def advance_phase(self):
        # 阶段推进前必须通过的门禁检查
        if not self._check_phase_exit_criteria():
            raise Exception("当前阶段未完成，不能进入下一阶段")
        self.current_phase = next_phase

3.1.2 门禁机制（Gate Mechanism）

Superpowers 的核心设计是门禁机制：每个阶段结束后，必须通过预定义的验证标准，才能进入下一阶段。

3.2 Git 工作树隔离

Superpowers 的一个重要特性是自动创建 Git 工作树（Worktree），确保 AI 生成的代码不会污染主分支。

3.2.1 为什么需要工作树隔离？

AI 生成的代码可能存在以下问题：

• 编译错误
• 逻辑错误
• 不符合团队规范

如果直接在 main 或 master 分支上修改，会造成代码库的不稳定。

3.2.2 工作树隔离的实现

# Superpowers 自动执行的工作流（伪代码）

# 1. 创建隔离的工作树
git worktree add ../superpowers-work-<task-id> -b feature/superpowers-<task-id>

# 2. 在隔离工作树中进行所有代码修改
cd ../superpowers-work-<task-id>
# ... AI 生成代码、运行测试 ...

# 3. 所有检查通过后，合并回主分支
git checkout main
git merge feature/superpowers-<task-id>

# 4. 清理工作树
git worktree remove ../superpowers-work-<task-id>

这种设计让开发者可以放心地让 AI 自由发挥，因为所有的实验都在隔离环境中进行。

3.3 上下文压缩与窗口管理

AI 编程助手面临的一个核心技术挑战是上下文窗口限制（Context Window Limit）。例如：

• Claude 3.5 Sonnet：200K tokens
• GPT-4o：128K tokens
• Gemini 1.5 Pro：1M tokens

在复杂的软件开发任务中（例如实现一个完整的用户系统），上下文窗口很容易被耗尽。

Superpowers 通过以下策略解决这一问题：

3.3.1 任务原子化

将大任务拆解为多个原子任务（Atomic Task），每个任务的上下文需求控制在 5-10K tokens 以内。

3.3.2 增量上下文加载

不是一次性将所有上下文加载到提示词中，而是按需加载：

# 伪代码：增量上下文加载
def load_context_for_task(task):
    context = {
        "project_overview": read_file("PROJECT_OVERVIEW.md"),
        "relevant_files": find_relevant_files(task),
        "test_examples": load_test_examples(task),
        "coding_standards": read_file("CODING_STANDARDS.md")
    }
    return context

3.3.3 上下文摘要

对于已经完成的任务，不再保留完整的对话历史，而是保留摘要（Summary）：

# 任务 1 完成摘要

- 功能：实现用户注册 API
- 文件变更：`api/user.py`, `tests/test_user.py`, `models/user.py`
- 测试结果：15 个测试全部通过
- 代码审查结果：通过（无阻塞性问题）
- 已知限制：未实现邮箱验证（将在任务 3 中完成）

四、代码实战：使用 Superpowers 完整开发一个功能

本节将通过一个完整的实例，演示如何使用 Superpowers 开发一个「用户注册 API」功能。

4.1 环境准备

4.1.1 安装 Superpowers

# 方式一：作为 Claude Code 插件安装
# 在 Claude Code 中执行：
/plugin install obra/superpowers

# 方式二：手动安装（适用于其他平台）
git clone https://github.com/obra/superpowers.git ~/.superpowers
ln -s ~/.superpowers ~/.claude/plugins/superpowers  # Claude Code
ln -s ~/.superpowers ~/.cursor/plugins/superpowers  # Cursor

4.1.2 项目初始化

# 创建一个新项目
mkdir user-registration-api && cd user-registration-api
git init
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install fastapi pytest httpx

4.2 Phase 1：需求分析（触发 spec 技能）

用户输入：

帮我实现一个用户注册 API，需要支持邮箱注册，密码要加密存储。

Superpowers（通过 AI）的响应：

我已启动 `spec` 技能进行需求分析。

在开始设计之前，我需要澄清以下关键问题：

1. **邮箱验证**：注册后是否需要发送验证邮件激活账号？
2. **密码策略**：对密码复杂度有什么要求（最小长度、特殊字符等）？
3. **数据存储**：使用什么数据库（SQLite/PostgreSQL/MySQL）？
4. **API 框架**：使用 FastAPI / Flask / Django REST Framework？
5. **错误处理**：注册失败时的错误提示方式（HTTP 状态码 + 错误信息）？

请逐一回答上述问题，我将根据您的回答生成详细的规格说明文档。

用户回答：

1. 不需要邮箱验证（简化版）
2. 密码至少 8 位，必须包含字母和数字
3. 使用 SQLite（简化版）
4. 使用 FastAPI
5. 返回 400 Bad Request + JSON 错误信息

Superpowers 生成规格说明：

# 用户注册 API 规格说明

## 功能描述

实现一个用户注册 API，允许新用户通过邮箱和密码注册账号。

## 接口定义

- **URL**: `/api/register`
- **Method**: `POST`
- **Content-Type**: `application/json`

## 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| email | string | 是 | 用户邮箱，必须是有效邮箱格式 |
| password | string | 是 | 密码，至少 8 位，必须包含字母和数字 |

## 响应

### 成功响应（201 Created）

```json
{
  "message": "Registration successful",
  "user_id": 123
}

失败响应（400 Bad Request）

{
  "error": "Invalid email format"
}

可能的错误信息：

• Invalid email format：邮箱格式不正确
• Password too short：密码少于 8 位
• Password must contain both letters and numbers：密码必须包含字母和数字
• Email already registered：邮箱已被注册

数据存储

• 使用 SQLite 数据库
• 表名：users
• 字段：
  • id: INTEGER PRIMARY KEY AUTOINCREMENT
  • email: TEXT UNIQUE NOT NULL
  • password_hash: TEXT NOT NULL
  • created_at: TIMESTAMP DEFAULT CURRENT_TIMESTAMP

密码存储

• 使用 bcrypt 对密码进行加密存储
• 存储的是 bcrypt(password) 的哈希值，不存储明文密码

边界条件

• 邮箱不区分大小写（存储时转换为小写）
• 同一邮箱只能注册一次
• 密码传输使用 HTTPS（由部署环境保证，API 层不做处理）

**等待用户确认...**

用户回复：「确认，开始设计。」

### 4.3 Phase 2：技术设计（触发 `design` 技能）

**Superpowers 生成设计文档：**

```markdown
# 用户注册 API 技术设计文档

## 系统架构

采用简单的分层架构：

┌─────────────────┐
│ API Layer │ FastAPI Routes
├─────────────────┤
│ Service Layer │ 业务逻辑（注册、密码加密等）
├─────────────────┤
│ Repository Layer│ 数据访问（数据库操作）
├─────────────────┤
│ Database │ SQLite
└─────────────────┘

## 模块划分

### 1. `main.py`
- FastAPI 应用入口
- 注册路由

### 2. `models/user.py`
- User 数据模型
- Pydantic 模型（请求/响应验证）

### 3. `services/auth_service.py`
- 注册业务逻辑
- 密码加密

### 4. `repositories/user_repository.py`
- 用户数据访问
- 数据库操作

### 5. `database.py`
- SQLite 连接管理
- 表初始化

## 接口详细设计

### POST /api/register

#### 请求验证（Pydantic）

```python
from pydantic import BaseModel, EmailStr, validator

class RegisterRequest(BaseModel):
    email: EmailStr
    password: str
    
    @validator('password')
    def password_must_be_strong(cls, v):
        if len(v) < 8:
            raise ValueError('Password must be at least 8 characters')
        if not any(c.isalpha() for c in v) or not any(c.isdigit() for c in v):
            raise ValueError('Password must contain both letters and numbers')
        return v

业务逻辑

# services/auth_service.py

import bcrypt
from models.user import User

def register_user(email: str, password: str) -> User:
    # 1. 检查邮箱是否已注册
    if user_repository.exists_by_email(email.lower()):
        raise EmailAlreadyRegisteredError(email)
    
    # 2. 密码加密
    password_hash = bcrypt.hashpw(password.encode('utf-8'), bcrypt.gensalt())
    
    # 3. 创建用户
    user = User(email=email.lower(), password_hash=password_hash.decode('utf-8'))
    user_repository.save(user)
    
    return user

错误处理

# 自定义异常

class EmailAlreadyRegisteredError(Exception):
    pass

class InvalidEmailError(Exception):
    pass

# FastAPI 异常处理器

@app.exception_handler(EmailAlreadyRegisteredError)
async def email_already_registered_handler(request, exc):
    return JSONResponse(
        status_code=400,
        content={"error": "Email already registered"}
    )

数据库设计

users 表

CREATE TABLE IF NOT EXISTS users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    email TEXT UNIQUE NOT NULL,
    password_hash TEXT NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_users_email ON users(email);

测试策略

• 单元测试：覆盖 auth_service.py 的所有分支
• 集成测试：覆盖 API 端到端流程
• 测试框架：pytest + httpx（FastAPI 测试客户端）

文件结构

user-registration-api/
├── main.py
├── models/
│   ├── __init__.py
│   └── user.py
├── services/
│   ├── __init__.py
│   └── auth_service.py
├── repositories/
│   ├── __init__.py
│   └── user_repository.py
├── database.py
├── tests/
│   ├── __init__.py
│   ├── test_auth_service.py
│   └── test_api.py
├── requirements.txt
└── README.md

**等待用户确认...**

用户回复：「设计通过，开始拆解任务。」

### 4.4 Phase 3：任务拆解（触发 `plan` 技能）

**Superpowers 生成任务清单：**

```markdown
# 任务拆解清单

## Task 1：项目初始化与依赖安装
- 创建项目目录结构
- 创建 `requirements.txt`（fastapi, uvicorn, pydorn, bcrypt, pytest, httpx）
- 创建 `database.py`（SQLite 连接 + 表初始化）
- **预估时间**：30 分钟

## Task 2：实现 User 数据模型
- 创建 `models/user.py`
- 定义 `User` 数据库模型（使用 SQLAlchemy 或原生 sqlite3）
- 定义 `RegisterRequest` Pydantic 模型（带验证器）
- 编写单元测试 `tests/test_user_model.py`
- **预估时间**：1 小时

## Task 3：实现用户数据仓库
- 创建 `repositories/user_repository.py`
- 实现 `save(user)` 方法
- 实现 `exists_by_email(email)` 方法
- 编写单元测试 `tests/test_user_repository.py`
- **预估时间**：1 小时

## Task 4：实现认证服务
- 创建 `services/auth_service.py`
- 实现 `register_user(email, password)` 方法
- 实现密码 bcrypt 加密
- 编写单元测试 `tests/test_auth_service.py`
- **预估时间**：1.5 小时

## Task 5：实现 API 路由
- 修改 `main.py`
- 实现 `POST /api/register` 路由
- 添加异常处理
- 编写集成测试 `tests/test_api.py`
- **预估时间**：1.5 小时

## Task 6：最终集成测试与代码审查
- 运行所有测试
- 代码审查（遵循 PEP 8、类型注解等规范）
- 更新 README.md
- **预估时间**：1 小时

**总预估时间**：6.5 小时

等待用户确认...

用户回复：「任务清单通过，开始执行。」

4.5 Phase 4：TDD 循环（触发 tdd 技能）

现在进入最核心的 TDD 循环。Superpowers 会逐任务执行「红-绿-重构」循环。

Task 1：项目初始化与依赖安装

Step 1: RED（写出会失败的测试）

# tests/test_database.py（先写测试，再写实现）

import pytest
from database import init_db, get_db_connection

def test_init_db_creates_users_table():
    # 准备：使用内存数据库
    conn = init_db(":memory:")
    
    # 验证：users 表已创建
    cursor = conn.cursor()
    cursor.execute("SELECT name FROM sqlite_master WHERE type='table' AND name='users'")
    result = cursor.fetchone()
    
    assert result is not None
    assert result[0] == 'users'

def test_init_db_users_table_schema():
    conn = init_db(":memory:")
    cursor = conn.cursor()
    cursor.execute("PRAGMA table_info(users)")
    columns = {row[1] for row in cursor.fetchall()}
    
    assert 'id' in columns
    assert 'email' in columns
    assert 'password_hash' in columns
    assert 'created_at' in columns

运行测试（预期失败）：

$ pytest tests/test_database.py -v
============================= test session starts ==============================
collected 2 items

tests/test_database.py::test_init_db_creates_users_table FAILED
tests/test_database.py::test_init_db_users_table_schema FAILED

================================= FAILURES ==================================
___________________ test_init_db_creates_users_table ____________________
ModuleNotFoundError: No module named 'database'

Step 2: GREEN（写最少代码让测试通过）

# database.py

import sqlite3

def init_db(db_path=":memory:"):
    conn = sqlite3.connect(db_path)
    cursor = conn.cursor()
    cursor.execute("""
        CREATE TABLE IF NOT EXISTS users (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            email TEXT UNIQUE NOT NULL,
            password_hash TEXT NOT NULL,
            created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
        )
    """)
    conn.commit()
    return conn

def get_db_connection(db_path="users.db"):
    return sqlite3.connect(db_path)

运行测试（预期通过）：

$ pytest tests/test_database.py -v
============================= test session starts ==============================
collected 2 items

tests/test_database.py::test_init_db_creates_users_table PASSED
tests/test_database.py::test_init_db_users_table_schema PASSED

============================== 2 passed in 0.12s ==============================

Step 3: REFACTOR（重构，确保代码质量）

# database.py（重构后）

import sqlite3
from pathlib import Path

SCHEMA = """
    CREATE TABLE IF NOT EXISTS users (
        id INTEGER PRIMARY KEY AUTOINCREMENT,
        email TEXT UNIQUE NOT NULL,
        password_hash TEXT NOT NULL,
        created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
    )
"""

def init_db(db_path: str = ":memory:") -> sqlite3.Connection:
    """Initialize database and create tables."""
    conn = sqlite3.connect(db_path)
    conn.execute(SCHEMA)
    conn.commit()
    return conn

def get_db_connection(db_path: str = "users.db") -> sqlite3.Connection:
    """Get a database connection."""
    Path(db_path).parent.mkdir(parents=True, exist_ok=True)
    return sqlite3.connect(db_path)

触发代码审查（Code Review）：

Superpowers 自动执行 code-review 技能：

# Code Review 报告

## 通过的检查项
✅ 函数有文档字符串（docstring）
✅ 使用类型注解（type hints）
✅ 遵循 PEP 8 命名规范
✅ 无硬编码敏感信息

## 建议改进
⚠️ 建议使用 context manager（`with` 语句）管理数据库连接
⚠️ 建议添加 `PRAGMA journal_mode=WAL` 提升并发性能

## 结论
代码质量良好，建议改进项不阻塞合并。

修复建议的问题：

# database.py（最终版本）

import sqlite3
from pathlib import Path
from contextlib import contextmanager

SCHEMA = """
    CREATE TABLE IF NOT EXISTS users (
        id INTEGER PRIMARY KEY AUTOINCREMENT,
        email TEXT UNIQUE NOT NULL,
        password_hash TEXT NOT NULL,
        created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
    )
"""

@contextmanager
def get_db_connection(db_path: str = "users.db"):
    """Get a database connection with context manager."""
    Path(db_path).parent.mkdir(parents=True, exist_ok=True)
    conn = sqlite3.connect(db_path)
    conn.execute("PRAGMA journal_mode=WAL")  # 提升并发性能
    try:
        yield conn
        conn.commit()
    finally:
        conn.close()

def init_db(db_path: str = ":memory:") -> sqlite3.Connection:
    """Initialize database and create tables."""
    conn = sqlite3.connect(db_path)
    conn.execute(SCHEMA)
    conn.commit()
    return conn

所有测试重新通过，Task 1 完成！

（因篇幅限制，Task 2-6 的执行过程类似，均遵循 RED → GREEN → REFACTOR → Code Review 的循环）

4.6 Phase 5：集成与交付（触发 integrate 技能）

所有任务完成后，Superpowers 执行最终集成：

# 1. 运行所有测试
$ pytest tests/ -v --tb=short
============================= test session starts ==============================
collected 23 items

tests/test_database.py::test_init_db_creates_users_table PASSED
tests/test_database.py::test_init_db_users_table_schema PASSED
tests/test_user_model.py::test_register_request_valid PASSED
tests/test_user_model.py::test_register_request_invalid_email PASSED
tests/test_user_model.py::test_register_request_weak_password PASSED
# ... 共 23 个测试全部通过

============================== 23 passed in 2.1s ==============================

# 2. 最终代码审查
$ pylint main.py models/ services/ repositories/
Your code has been rated at 9.5/10

# 3. 生成 Conventional Commit Message
git commit -m "feat: implement user registration API with TDD workflow

- Add user model with Pydantic validation
- Add bcrypt password hashing
- Add SQLite database with WAL mode
- Add comprehensive test suite (23 tests)
- Achieve 92% code coverage

Closes #123"

Superpowers 输出完成报告：

# 开发任务完成报告

## 功能
用户注册 API

## 文件变更
- `main.py`（新增 45 行）
- `models/user.py`（新增 32 行）
- `services/auth_service.py`（新增 38 行）
- `repositories/user_repository.py`（新增 28 行）
- `database.py`（新增 35 行）
- `tests/test_*.py`（新增 156 行）

## 测试结果
- 总测试数：23
- 通过率：100%
- 代码覆盖率：92%

## 代码审查结果
- Pylint 评分：9.5/10
- 无阻塞性问题
- 2 个建议改进项（已记录在 TODO.md）

## Git 信息
- 分支：`feature/user-registration-api`
- Commit：`feat: implement user registration API with TDD workflow`
- 建议：直接合并到 `main` 分支

五、性能优化与最佳实践

5.1 提升 Superpowers 的效果

5.1.1 编写高质量的 PROJECT_OVERVIEW.md

在项目根目录创建 PROJECT_OVERVIEW.md，帮助 AI 理解项目上下文：

# 项目概述

## 项目名称
用户注册 API

## 技术栈
- 语言：Python 3.11+
- 框架：FastAPI
- 数据库：SQLite（开发）、PostgreSQL（生产）
- 测试：pytest + httpx

## 编码规范
- 遵循 PEP 8
- 使用类型注解（type hints）
- 所有函数必须有 docstring
- 使用 `black` 进行代码格式化

## 架构原则
- 分层架构（API → Service → Repository）
- 依赖注入（使用 `dependencies` 模式）
- 所有数据库操作使用 context manager

## 测试策略
- 单元测试覆盖率 > 80%
- 使用 `pytest.mark.parametrize` 进行参数化测试
- 使用 `unittest.mock` 隔离外部依赖

5.1.2 自定义技能（Custom Skills）

如果内置技能不能满足需求，可以编写自定义技能：

# .superpowers/skills/security-check.md

# Security Check Skill

You are a security expert reviewing code for common vulnerabilities.

## Steps

1. Check for SQL injection vulnerabilities
2. Check for XSS vulnerabilities
3. Check for insecure password storage
4. Check for missing input validation
5. Check for insecure direct object references (IDOR)

## Output Format

For each check:
- ✅ PASS: <description>
- ⚠️ WARNING: <description> - <recommendation>
- ❌ FAIL: <description> - <recommendation>

## Example

✅ PASS: Password is hashed using bcrypt
⚠️ WARNING: CSRF protection not implemented - consider adding CSRF tokens
❌ FAIL: SQL query uses string formatting - use parameterized queries instead

5.2 常见陷阱与规避方法

陷阱 1：AI 「跳过」TDD 循环

现象：AI 直接生成业务代码，没有先写测试。

原因：提示词不够强制。

解决方案：在 PROJECT_OVERVIEW.md 中明确写明「必须严格遵循 TDD 工作流，先写测试再写实现」。

陷阱 2：上下文窗口溢出

现象：执行到一半，AI 报错「上下文长度超出限制」。

解决方案：

• 将大任务拆解为更小的原子任务（每个任务 < 2 小时）
• 使用 Git 工作树隔离，每个任务独立执行
• 定期清理上下文（让 AI 总结已完成的工作）

陷阱 3：生成的代码质量不稳定

现象：有时生成的代码很好，有时很差。

原因：AI 模型的「随机性」。

解决方案：

• 在提示词中明确编码规范（参考 5.1.1）
• 使用 code-review 技能进行强制审查
• 设置「最低代码质量门禁」（例如 Pylint 评分 > 8.0 才能合并）

六、总结与展望

6.1 Superpowers 的核心价值

Superpowers 的最大价值不在于「让 AI 生成更好的代码」，而在于将工程化最佳实践「固化」到 AI 的工作流中。

通过强制 TDD、代码审查、设计文档等流程，Superpowers 让 AI 编程助手从「代码生成器」进化为「工程化伙伴」。

适合使用 Superpowers 的场景：

• ✅ 新功能开发（从 0 到 1）
• ✅ 复杂系统的模块化拆解
• ✅ 测试覆盖率提升
• ✅ 代码重构与技术债务清理

不太适合的场景：

• ❌ 非常简单的脚本（Hello World 级别）
• ❌ 一次性工具（用完即扔）
• ❌ 对性能要求极致的场景（需要手动优化）

6.2 与同类工具的对比

6.3 未来展望

随着 AI 编程工具的普及，未来的竞争焦点将从「谁的模型更强」转向「谁的工作流更工程化」。

Superpowers 开辟了一个新方向：不是训练更好的模型，而是设计更好的工作流。

预计未来会出现：

1. 领域专用技能包：例如 superpowers-webdev、superpowers-mlops
2. 团队协作模式：多人协同使用 Superpowers 进行代码审查和质量把控
3. 与 CI/CD 集成：将 Superpowers 的审查门禁集成到 GitHub Actions / Jenkins

七、参考资料

1. Superpowers GitHub 仓库：https://github.com/obra/superpowers
2. TDD 大师级教程：Kent Beck,《Test Driven Development: By Example》
3. FastAPI 官方文档：https://fastapi.tiangolo.com/
4. pytest 最佳实践：https://docs.pytest.org/en/stable/how-to/index.html
5. Conventional Commits 规范：https://www.conventionalcommits.org/

本文撰写时间：2026 年 5 月
作者：程序员茄子
转载请注明出处