Superpowers：让AI编码助手拥有资深工程师的工作流

传统的 AI 编码：用户 → AI → 代码 → 用户检查
Superpowers：用户 → AI → 规划 → 验证 → 测试 → 代码 → 用户确认

## 任务：添加用户登录功能

### 实现计划
1. 创建 LoginController 处理认证逻辑
2. 添加 JWT token 生成和验证
3. 创建登录页面组件
4. 添加表单验证
5. 编写单元测试
6. 更新 API 文档

### 风险评估
- 需要处理 token 过期场景
- 密码存储需要使用 bcrypt

// AI 先写测试
describe('LoginController', () => {
  it('should return 401 for invalid credentials', async () => {
    const response = await request(app)
      .post('/api/login')
      .send({ username: 'test', password: 'wrong' });
    expect(response.status).toBe(401);
  });

  it('should return token for valid credentials', async () => {
    const response = await request(app)
      .post('/api/login')
      .send({ username: 'test', password: 'correct' });
    expect(response.status).toBe(200);
    expect(response.body.token).toBeDefined();
  });
});

// 然后写实现
class LoginController {
  async login(req, res) {
    const { username, password } = req.body;
    const user = await User.findByUsername(username);
    
    if (!user || !await bcrypt.compare(password, user.password)) {
      return res.status(401).json({ error: 'Invalid credentials' });
    }
    
    const token = jwt.sign({ userId: user.id }, process.env.JWT_SECRET);
    return res.json({ token });
  }
}

# 自动创建功能分支
git checkout -b feature/user-login

# 完成后自动提交
git add .
git commit -m "feat: add user login functionality

- Add LoginController with JWT authentication
- Add login page component with form validation
- Add unit tests for login flow"

# 可选：自动创建 PR
gh pr create --title "Add user login functionality" --body "..."

# 克隆 Superpowers 仓库到 Codex 配置目录
git clone https://github.com/obra/superpowers.git ~/.codex/superpowers

# 创建符号链接（让 Codex 自动发现技能）
ln -s ~/.codex/superpowers/skills ~/.codex/skills/superpowers

# 使用 Codex 原生技能发现
curl -o /tmp/install.sh https://raw.githubusercontent.com/obra/superpowers/main/.codex/INSTALL.md
bash /tmp/install.sh

# 创建技能目录
mkdir -p .vscode/skills

# 下载 Superpowers 技能配置
curl -o .vscode/skills/superpowers.md \
  https://raw.githubusercontent.com/obra/superpowers/main/SKILL.md

我需要添加用户头像上传功能，支持 JPG/PNG 格式，
最大 2MB，上传后自动生成缩略图。

## 用户头像上传功能 - 实现计划

### 技术方案
1. 使用 multer 处理文件上传
2. 使用 sharp 处理图片压缩和缩略图生成
3. 添加文件类型和大小验证
4. 存储到云存储（建议 S3 或兼容服务）

### 文件结构
- controllers/AvatarController.js - 上传接口
- middleware/upload.js - multer 配置
- services/ImageService.js - 图片处理
- tests/avatar.test.js - 单元测试

### API 设计
POST /api/users/:id/avatar
- Content-Type: multipart/form-data
- Body: avatar (file)
- Response: { avatarUrl, thumbnailUrl }

// tests/avatar.test.js
const request = require('supertest');
const app = require('../app');
const path = require('path');

describe('Avatar Upload', () => {
  const validJpg = path.join(__dirname, 'fixtures', 'valid.jpg');
  const largeFile = path.join(__dirname, 'fixtures', 'large.jpg');
  const invalidFile = path.join(__dirname, 'fixtures', 'invalid.txt');

  it('should upload valid JPG avatar', async () => {
    const response = await request(app)
      .post('/api/users/123/avatar')
      .attach('avatar', validJpg);
    
    expect(response.status).toBe(200);
    expect(response.body.avatarUrl).toMatch(/^https:\/\//);
    expect(response.body.thumbnailUrl).toBeDefined();
  });

  it('should reject files larger than 2MB', async () => {
    const response = await request(app)
      .post('/api/users/123/avatar')
      .attach('avatar', largeFile);
    
    expect(response.status).toBe(400);
    expect(response.body.error).toContain('2MB');
  });

  it('should reject non-image files', async () => {
    const response = await request(app)
      .post('/api/users/123/avatar')
      .attach('avatar', invalidFile);
    
    expect(response.status).toBe(400);
    expect(response.body.error).toContain('JPG or PNG');
  });
});

// middleware/upload.js
const multer = require('multer');
const path = require('path');

const storage = multer.memoryStorage();

const fileFilter = (req, file, cb) => {
  const allowedTypes = ['image/jpeg', 'image/png'];
  if (!allowedTypes.includes(file.mimetype)) {
    return cb(new Error('Only JPG and PNG files are allowed'), false);
  }
  cb(null, true);
};

const upload = multer({
  storage,
  fileFilter,
  limits: {
    fileSize: 2 * 1024 * 1024 // 2MB
  }
});

module.exports = upload.single('avatar');

// services/ImageService.js
const sharp = require('sharp');

class ImageService {
  async processAvatar(buffer) {
    // 原图压缩到 500x500
    const avatar = await sharp(buffer)
      .resize(500, 500, { fit: 'cover' })
      .jpeg({ quality: 85 })
      .toBuffer();

    // 缩略图 100x100
    const thumbnail = await sharp(buffer)
      .resize(100, 100, { fit: 'cover' })
      .jpeg({ quality: 80 })
      .toBuffer();

    return { avatar, thumbnail };
  }
}

module.exports = new ImageService();

// controllers/AvatarController.js
const upload = require('../middleware/upload');
const ImageService = require('../services/ImageService');
const S3Service = require('../services/S3Service');

class AvatarController {
  async uploadAvatar(req, res) {
    try {
      const { id } = req.params;
      
      if (!req.file) {
        return res.status(400).json({ error: 'No file uploaded' });
      }

      // 处理图片
      const { avatar, thumbnail } = await ImageService.processAvatar(req.file.buffer);

      // 上传到 S3
      const [avatarUrl, thumbnailUrl] = await Promise.all([
        S3Service.upload(`avatars/${id}.jpg`, avatar),
        S3Service.upload(`avatars/${id}_thumb.jpg`, thumbnail)
      ]);

      res.json({ avatarUrl, thumbnailUrl });
    } catch (error) {
      res.status(500).json({ error: error.message });
    }
  }
}

module.exports = new AvatarController();

# 自动运行测试
npm test

# 自动运行 lint
npm run lint

# 自动类型检查（如果使用 TypeScript）
npm run type-check

git checkout -b feature/avatar-upload
git add .
git commit -m "feat: add user avatar upload functionality

- Add multer middleware for file upload handling
- Add ImageService for image processing with sharp
- Add validation for file type (JPG/PNG) and size (2MB max)
- Add unit tests for upload scenarios
- Add avatar and thumbnail generation"

用户指令 > 技能规则 > 项目默认行为

<!-- .superpowers/skills/custom-review.md -->
---
name: code-review
description: 在提交前自动进行代码审查
triggers:
  - "完成"
  - "提交"
  - "review"
---

## 代码审查清单

在提交代码前，检查以下项目：

1. [ ] 是否有未处理的 TODO
2. [ ] 是否有 console.log 或 debugger 语句
3. [ ] 错误处理是否完整
4. [ ] 是否有安全风险（SQL 注入、XSS 等）
5. [ ] 性能是否有潜在问题

# 技能触发示例
用户说: "帮我实现用户登录功能，要写测试"
触发技能: 
  - planning (包含"实现")
  - tdd (包含"测试")

用户说: "这个 bug 怎么修"
触发技能:
  - debugging
  - planning

<!-- .superpowers/skills/team-standards.md -->
---
name: team-standards
description: 团队编码规范
always_active: true
---

## 必须遵守的规范

### API 设计
- 所有 API 返回统一格式: `{ success, data, error, message }`
- 使用 RESTful 命名约定
- 错误码使用标准 HTTP 状态码

### 代码风格
- 使用项目配置的 ESLint 规则
- 函数必须有 JSDoc 注释
- 变量命名使用 camelCase，常量使用 UPPER_SNAKE_CASE

### 测试要求
- 新功能必须有单元测试，覆盖率 > 80%
- Bug 修复必须有回归测试
- 使用 Jest 测试框架

### 安全要求
- 所有用户输入必须验证和清理
- 敏感数据必须加密存储
- API 必须有速率限制

# LangChain 方式 - 需要自己定义链
from langchain.chains import LLMChain

code_chain = LLMChain(
    llm=llm,
    prompt=code_prompt,
    # 需要手动添加验证、测试等步骤
)

# Superpowers 方式 - 技能自动处理
你: "实现用户登录功能"
AI: [自动触发 planning -> tdd -> verification -> git workflow]

# 1. 确认技能目录正确
ls ~/.codex/skills/superpowers
# 应该看到多个 .md 文件

# 2. 检查符号链接
ls -la ~/.codex/skills/superpowers
# 应该指向正确的目录

# 3. 重启编码工具
# Claude Code: 重新打开终端
# VS Code: 重新加载窗口 (Cmd+Shift+P -> Reload Window)

用户明确指令 > 项目配置文件 (AGENTS.md) > Superpowers 技能

# AGENTS.md
## 开发规范
- 不使用 TDD（项目处于快速原型阶段）
- 优先功能实现，测试在稳定后补充

"先实现功能，不用写测试"

# 启用调试日志
export SUPERPOWERS_DEBUG=true

# 运行编码工具，查看日志
claude-code "实现用户登录" 2>&1 | grep superpowers

team-skills/
├── skills/
│   ├── team-standards.md
│   ├── security-review.md
│   └── api-design.md
├── SKILL.md          # 技能索引
└── README.md         # 使用说明

git clone git@github.com:yourteam/team-skills.git
ln -s team-skills ~/.codex/skills/team

---
# 元数据
name: skill-name
description: 技能描述
triggers:           # 触发条件
  - "关键词1"
  - "关键词2"
priority: 10        # 优先级，数字越大越优先
always_active: false # 是否始终激活
---

# 技能内容

## 目标
描述这个技能要达成什么目标

## 规则
- 规则1
- 规则2

## 检查清单
- [ ] 检查项1
- [ ] 检查项2

用户输入
    ↓
[关键词匹配] → 找到候选技能
    ↓
[优先级排序] → 选择最高优先级技能
    ↓
[上下文检查] → 确认技能适用
    ↓
[执行技能规则] → AI 按规则生成响应
    ↓
[后续技能触发] → 检查是否需要触发其他技能

用户: "实现一个安全的用户认证系统，要有完整测试"

触发链:
1. planning-skill (检测到"实现")
   → 生成实现计划

2. security-skill (检测到"安全")
   → 添加安全审查清单

3. tdd-skill (检测到"测试")
   → 强制先写测试

4. verification-skill (检测到"完成")
   → 验证代码质量

5. git-workflow-skill (检测到"完成")
   → 自动提交

# 新项目初始化
mkdir my-project && cd my-project
git init

# 安装 Superpowers
git clone https://github.com/obra/superpowers.git .superpowers

# 创建项目级技能配置
mkdir -p .superpowers/custom-skills

# .superpowers/team-config.yaml
shared_skills:
  - team-standards
  - security-review
  - api-design

individual_skills:
  - personal-preferences

disabled_skills:
  - experimental-feature  # 团队统一禁用实验性技能

# 优先级示例
skills:
  planning:
    priority: 100    # 最高优先级，首先执行
    
  tdd:
    priority: 80    # 规划后执行
    
  verification:
    priority: 60    # 代码生成后执行
    
  git-workflow:
    priority: 40    # 最后执行

# 伪代码示例
def should_trigger_skill(user_input, context):
    # 检查关键词
    if contains_keyword(user_input, skill.triggers):
        # 检查上下文适用性
        if is_applicable(context, skill.requirements):
            return True
    return False

# .superpowers/project.yaml
project:
  name: "my-app"
  type: "nodejs"
  
language:
  typescript: true
  linter: "eslint"
  test_framework: "jest"
  
coding_standards:
  max_line_length: 100
  require_types: true
  min_test_coverage: 80