superpowers

어떤 스킬인가요?

A complete software development methodology and skill composition system, ported from obra/superpowers. Provides structured, repeatable workflow: brainstorming, design, planning, TDD, subagent-driven dev, code review, finishing branch. Use for coding, building projects, refactoring, bug fixing, or any programming tasks.

설치 방법

프로젝트 폴더에서 아래 명령어를 실행하고, 설치할 에이전트를 선택하세요.

설치 명령을 직접 실행해야 적용됩니다. 지원 에이전트와 필요한 권한·라이선스는 제작자의 안내를 확인하세요.

스킬 원문 파일

{
  "ownerId": "510953",
  "publishedAt": 1779731331954,
  "slug": "superpowers-skill",
  "version": "1.0.1"
}

{
  "slug": "superpowers-skill",
  "name": "Superpowers",
  "version": "1.0.1",
  "installedAt": 1782728946483,
  "source": "skillhub"
}

# Superpowers 最佳实践

## 1. 设计原则

### 1.1 简单性优先
- 选择最简单的可行方案
- 删除不必要的功能
- 避免过度工程化
- 每个功能必须有明确的价值

### 1.2 YAGNI（你不会需要它）
- 不要为未来可能需要的功能写代码
- 只实现当前明确需要的功能
- 当需求变化时再重构

### 1.3 DRY（不要重复自己）
- 重复代码是 bug 的温床
- 提取公共逻辑到函数/类
- 但不要过早抽象

### 1.4 KISS（保持简单）
- 代码应该易于理解
- 避免复杂的逻辑链
- 每个函数只做一件事

## 2. 测试策略

### 2.1 测试金字塔
- 单元测试：70-80% 覆盖率
- 集成测试：20-25% 覆盖率  
- E2E 测试：5-10% 覆盖率

### 2.2 测试命名规范
- 描述性：`test_user_cannot_login_with_wrong_password`
- Given-When-Then 模式：
  - Given：前提条件
  - When：执行操作
  - Then：预期结果

### 2.3 测试反模式
- ❌ 测试实现细节而非行为
- ❌ 测试过于脆弱（依赖具体实现）
- ❌ 测试没有实际价值
- ❌ 测试不独立（有依赖）

## 3. 代码质量

### 3.1 函数设计
- 函数长度 ≤ 20 行
- 参数数量 ≤ 3 个
- 有明确的返回值
- 有清晰的错误处理

### 3.2 命名规范
- 变量：描述性名词 `user_count`
- 函数：动词+名词 `calculate_total`
- 布尔值：`is_`、`has_`、`can_` 前缀
- 常量：全大写 `MAX_USERS`

### 3.3 注释原则
- 解释"为什么"，而不是"是什么"
- 复杂的业务逻辑需要注释
- API 文档必须完整
- 过时的注释比没有注释更糟

## 4. 子代理管理

### 4.1 任务分配
- 每个子代理处理单一职责
- 任务之间无依赖
- 提供完整的上下文
- 设置明确的完成标准

### 4.2 监控与恢复
- 定期检查子代理进度
- 超时自动终止
- 偏离计划时重新派发
- 记录所有子代理活动

### 4.3 结果验证
- 验证输出是否符合预期
- 检查代码质量
- 运行自动化测试
- 生成验证报告

## 5. 错误处理

### 5.1 防御性编程
- 验证所有输入
- 处理边界情况
- 提供有意义的错误信息
- 记录错误上下文

### 5.2 恢复策略
- 重试机制（带指数退避）
- 降级方案
- 优雅失败
- 用户友好的错误提示

## 6. 文档标准

### 6.1 设计文档
- 问题陈述清晰
- 方案对比完整
- 技术决策有依据
- 风险识别全面

### 6.2 API 文档
- 端点描述
- 请求/响应示例
- 错误码说明
- 认证要求

### 6.3 部署文档
- 环境要求
- 安装步骤
- 配置说明
- 故障排除

## 7. 性能考虑

### 7.1 响应时间
- API 响应 < 200ms
- 页面加载 < 2s
- 数据库查询 < 100ms

### 7.2 资源使用
- 内存使用有上限
- 连接数有限制
- 文件大小有控制
- 缓存策略合理

## 8. 安全最佳实践

### 8.1 输入验证
- 所有输入都要验证
- 使用白名单而非黑名单
- 转义特殊字符
- 限制输入长度

### 8.2 认证授权
- 使用标准认证协议
- 最小权限原则
- 定期轮换密钥
- 记录所有访问

### 8.3 数据保护
- 敏感数据加密
- 传输使用 TLS
- 定期备份
- 访问日志完整

# Superpowers 工作流详细指南

## 1. Brainstorming（需求澄清）

### 核心原则
- 永远不要直接跳到写代码
- 先问"你真正想实现什么？"
- 探索至少 3 种方案
- 设计文档每块不超过 200 字

### 执行流程
1. 理解用户表面需求
2. 追问深层目标："这个功能最终要解决什么问题？"
3. 提出 3+ 替代方案，分析各方案优劣
4. 推荐最优方案并解释原因
5. 生成设计文档 `design.md`，分块展示
6. 逐块确认用户理解并签字

### 设计文档模板
```markdown
# 项目名称：设计文档

## 1. 问题陈述
[一句话描述要解决的问题]

## 2. 目标用户
[谁会使用这个功能？]

## 3. 设计方案
### 方案 A：[名称]
- 优点：
- 缺点：
- 复杂度：

### 方案 B：[名称]
- 优点：
- 缺点：
- 复杂度：

### 推荐方案：[名称]
- 理由：

## 4. 技术架构
- 前端：
- 后端：
- 数据库：
- API 设计：

## 5. 关键风险
- [风险 1]
- [风险 2]

## 6. 成功标准
- [标准 1]
- [标准 2]
```

## 2. Implementation Planning（实现计划）

### 任务分解原则
- 每个任务 2-5 分钟完成
- 必须是可独立验证的原子单元
- 包含精确文件路径
- 包含完整验证步骤
- 遵循 YAGNI 和 DRY

### 计划文档模板
```markdown
# 实现计划

## 任务列表

### 任务 1：[名称]
- 文件：[完整路径]
- 描述：[具体要实现什么]
- 验证：[如何确认完成]
- 依赖：[前置任务]
- 预计时间：[分钟]

### 任务 2：[名称]
...
```

## 3. TDD（测试驱动开发）

### 红-绿-重构循环
1. **RED**：写一个失败的测试
2. **GREEN**：写最少代码让测试通过
3. **REFACTOR**：重构代码保持整洁
4. **COMMIT**：提交代码

### 关键规则
- 永远不写没有对应测试的代码
- 先跑测试看它失败，再写实现代码
- 删除任何在测试前写的实现代码
- 每次提交只包含一个循环

## 4. Subagent-Driven Development（子代理驱动开发）

### 两阶段审查
- **第一阶段：规范符合性**
  - 是否严格遵循计划？
  - 文件路径是否正确？
  - API 签名是否匹配？
  
- **第二阶段：代码质量**
  - 是否遵循编码规范？
  - 是否有足够测试？
  - 是否有性能问题？

### 批量执行规则
- 3-5 个任务一批
- 每批完成后设置人工检查点
- 子代理偏离计划时立即停止

## 5. Code Review（代码审查）

### 问题分级
- **关键**：安全漏洞、数据丢失风险、核心功能缺失 → 阻塞
- **主要**：性能问题、不正确的错误处理、可维护性问题
- **次要**：命名建议、注释改进、代码风格

### 审查清单
- [ ] 代码是否符合设计文档？
- [ ] 是否遵循实现计划？
- [ ] 是否有完整测试覆盖？
- [ ] 是否处理了错误情况？
- [ ] 是否有明显的性能问题？
- [ ] 是否有硬编码或魔法数字？

## 6. Finishing（完成分支）

### 完成检查清单
- [ ] 所有测试通过
- [ ] 无未处理的 lint 错误
- [ ] 文档已更新
- [ ] 代码审查已完成

### 选项
1. **合并**：合并到主分支
2. **创建 PR**：创建拉取请求等待审查
3. **保留分支**：保留工作分支
4. **丢弃**：放弃所有更改

---
name: superpowers
description: "A complete software development methodology and skill composition system, ported from obra/superpowers. Provides structured, repeatable workflow: brainstorming, design, planning, TDD, subagent-driven dev, code review, finishing branch. Use for coding, building projects, refactoring, bug fixing, or any programming tasks."
---

# Superpowers

## Overview

Superpowers is a complete software development methodology that provides AI agents with a structured, repeatable workflow. Ported from the obra/superpowers project, it breaks down the software development process into 7 core phases, each with dedicated skills and checkpoints to ensure high-quality, maintainable code output.

## Core Workflow

Superpowers follows a strict 7-phase workflow. Each phase is mandatory and cannot be skipped:

### 1. Brainstorming
**Trigger**: Automatically activates at the start of any development task.
**Goal**: Clarify the user's real needs through questioning, explore alternatives, and produce a verifiable design document.
**Key Actions**:
- Ask what the user really wants to achieve (not just surface requirements)
- Explore multiple design approaches and trade-offs
- Break design into readable chunks (max 200 words each)
- Generate design document and save to `design.md`
- Get user sign-off on the design

### 2. Design Validation
**Trigger**: After Brainstorming completes.
**Goal**: Ensure the design is complete, feasible, and meets user expectations.
**Key Actions**:
- Present design chunks for user review
- Ask "Is this section clear?"
- Confirm technical feasibility and constraints
- Record feedback and update design

### 3. Implementation Planning
**Trigger**: After design validation passes.
**Goal**: Decompose the design into executable, fine-grained development tasks.
**Key Actions**:
- Create detailed task list, each task taking 2-5 minutes
- Each task includes: exact file paths, complete code, verification steps
- Follow YAGNI (You Aren't Gonna Need It) and DRY (Don't Repeat Yourself)
- Generate plan document and save to `plan.md`

### 4. Test-Driven Development (TDD)
**Trigger**: Automatically activates during implementation.
**Goal**: Enforce the Red-Green-Refactor cycle.
**Key Actions**:
- Write a failing test first (Red)
- Write minimal code to pass the test (Green)
- Refactor to keep code clean
- Delete any code written before tests
- Follow this cycle for every feature

### 5. Subagent-Driven Development
**Trigger**: After plan approval.
**Goal**: Use subagents to execute tasks in parallel or sequentially.
**Key Actions**:
- Create fresh subagent per task
- Two-stage review: spec compliance, then code quality
- Set human checkpoints during batch execution
- Stop and report immediately if subagent deviates from plan

### 6. Code Review
**Trigger**: Between tasks or upon completion.
**Goal**: Ensure code meets plan and quality standards.
**Key Actions**:
- Review code against the plan
- Report issues by severity: Critical (blocking), Major, Minor
- Critical issues must be fixed before proceeding
- Generate review report and save to `review.md`

### 7. Finishing Development Branch
**Trigger**: After all tasks complete.
**Goal**: Cleanly finish the development cycle.
**Key Actions**:
- Verify all tests pass
- Present options: merge, create PR, keep branch, discard
- Clean up workspace
- Generate final report

## Core Principles

### 1. Test-Driven Development
- Always write tests first
- Red-Green-Refactor cycle
- Tests serve as documentation and design tools

### 2. Systematic over Ad-Hoc
- Follow process rather than guessing
- Every decision has a rationale
- Document all assumptions and decisions

### 3. Complexity Reduction
- Simplicity is the primary goal
- Remove unnecessary code
- Prefer the simplest viable solution

### 4. Evidence over Claims
- Verify rather than declare success
- Use tests to prove functionality
- Use data to support decisions

## Skill Trigger Mechanism

Superpowers is a mandatory workflow, not an optional suggestion. When any of the following is detected, the corresponding skill must activate:

1. **User mentions development/programming** -> Start Brainstorming
2. **Design complete** -> Start Implementation Planning
3. **Starting to write code** -> Start TDD
4. **Tasks need parallelism** -> Start Subagent-Driven Development
5. **Code complete** -> Start Code Review
6. **Project complete** -> Start Finishing

## Deliverables

Each phase produces documentation to ensure traceability:

| Phase | Output File | Purpose |
|-------|------------|---------|
| Brainstorming | `design.md` | Complete design document |
| Planning | `plan.md` | Detailed implementation plan |
| Development | `code/` | Source code |
| Review | `review.md` | Code review report |
| Finish | `final_report.md` | Project summary |

## Example Workflow

**User Request**: "Build me a todo app"

1. **Brainstorming**: Ask about requirements (Web/Mobile? Auth needed? Data storage?)
2. **Design**: Generate UI design, architecture diagram, API design
3. **Planning**: Break down into: create project structure, implement auth, build CRUD, add frontend
4. **TDD**: Write tests for each feature first
5. **Subagent**: Dispatch subagents to develop different modules in parallel
6. **Review**: Review code quality of each module
7. **Finish**: Merge code, generate deployment docs

## Troubleshooting

**Issue**: Subagent deviates from plan
**Solution**: Stop immediately, analyze the deviation, adjust plan or re-dispatch

**Issue**: Tests failing
**Solution**: Return to Red phase, analyze failure cause, fix tests or code

**Issue**: Requirements change
**Solution**: Return to Brainstorming phase, re-evaluate design

## Reference Resources

For detailed workflow guides and best practices, see `references/workflow.md` and `references/best_practices.md`.

## Resources

This skill includes bundled resource directories for organizing different types of content:

### scripts/
Executable code (Python/Bash/etc.) that can be run directly to perform specific operations.

**Examples from other skills:**
- PDF skill: `fill_fillable_fields.py`, `extract_form_field_info.py` - utilities for PDF manipulation
- DOCX skill: `document.py`, `utilities.py` - Python modules for document processing

**Appropriate for:** Python scripts, shell scripts, or any executable code that performs automation, data processing, or specific operations.

### references/
Documentation and reference material intended to be loaded into context to inform the agent's process and thinking.

**Examples from other skills:**
- Product management: `communication.md`, `context_building.md` - detailed workflow guides
- BigQuery: API reference documentation and query examples
- Finance: Schema documentation, company policies

**Appropriate for:** In-depth documentation, API references, database schemas, comprehensive guides, or any detailed information to reference while working.

### assets/
Files not intended to be loaded into context, but rather used within the output produced.

**Examples from other skills:**
- Brand styling: PowerPoint template files (.pptx), logo files
- Frontend builder: HTML/React boilerplate project directories
- Typography: Font files (.ttf, .woff2)

**Appropriate for:** Templates, boilerplate code, document templates, images, icons, fonts, or any files meant to be copied or used in the final output.

---

Any unneeded directories can be deleted. Not every skill requires all three types of resources.