97 lines
5.2 KiB
Markdown
97 lines
5.2 KiB
Markdown
# Superpowers 仓库介绍
|
||
|
||
Superpowers 是一个为编码代理(Coding Agent)打造的完整软件开发工作流框架,核心基于可组合的“技能(Skills)”体系和标准化执行指令,让 AI 编码代理能按照专业的软件工程实践自主完成开发任务。
|
||
|
||
## 核心定位
|
||
|
||
为 Claude Code、Cursor、Codex、OpenCode、Gemini 等主流编码代理提供标准化的开发工作流能力,替代“直接写代码”的简单模式,引入专业的软件工程实践(TDD、YAGNI、DRY、系统化调试、代码评审等),让 AI 代理能自主规划、执行、评审、调试开发任务,甚至可自主运行数小时而不偏离计划。
|
||
|
||
## 核心特性
|
||
|
||
### 1. 标准化工作流
|
||
|
||
- **需求梳理**:代理不会直接写代码,而是先提取清晰的需求规格,分块展示给用户确认;
|
||
|
||
- **实现规划**:生成符合“初级工程师可执行”的详细实现计划,强调 TDD(测试驱动开发)、YAGNI(按需开发)、DRY(避免重复);
|
||
|
||
- **子代理驱动开发**:核心的“Subagent-Driven Development”模式,由主代理调度子代理完成各任务,自动评审、校验工作成果;
|
||
|
||
- **全生命周期覆盖**:从需求分析、方案设计、编码实现、测试验证、代码评审,到分支收尾、发布准备全流程覆盖。
|
||
|
||
### 2. 可组合的技能体系
|
||
|
||
仓库核心是丰富的“技能(Skills)”集合,每个技能对应一类标准化开发行为,例如:
|
||
|
||
- `systematic-debugging`:系统化调试(四阶段调试法,聚焦根因而非表面症状);
|
||
|
||
- `requesting-code-review`:代码评审(标准化评审清单、子代理评审流程);
|
||
|
||
- `finishing-a-development-branch`:开发分支收尾(合并、PR、清理等结构化选项);
|
||
|
||
- `writing-plans`:编写标准化实现计划(精确路径、命令、预期输出);
|
||
|
||
- `subagent-driven-development`:子代理驱动开发(任务拆分、并行执行、质量门禁);
|
||
|
||
- 还有测试反模式识别、TDD 实践、技能编写最佳实践等数十个细分技能。
|
||
|
||
### 3. 多平台适配
|
||
|
||
支持主流编码代理平台,且为不同平台提供适配方案:
|
||
|
||
|平台|接入方式|
|
||
|---|---|
|
||
|Claude Code|官方插件市场直接安装|
|
||
|Cursor|插件市场搜索/命令安装|
|
||
|Codex|拉取并执行指定安装脚本|
|
||
|OpenCode|原生 JS/TS 插件 + 共享核心模块|
|
||
|Gemini CLI|扩展安装命令|
|
||
### 4. 可复用的核心模块
|
||
|
||
为适配多平台,提取了共享核心模块 `lib/skills-core.js`,包含技能发现、Frontmatter 解析、版本更新检查等通用逻辑,避免各平台重复开发,同时保证行为一致性。
|
||
|
||
## 仓库结构
|
||
|
||
核心目录/文件说明:
|
||
|
||
```Plain Text
|
||
|
||
superpowers/
|
||
├── .codex/ # Codex 平台适配(安装脚本、CLI 逻辑)
|
||
├── .opencode/ # OpenCode 平台适配(插件、安装指南)
|
||
├── .claude-plugin/ # Claude 插件配置
|
||
├── lib/ # 共享核心模块(skills-core.js)
|
||
├── skills/ # 核心技能集合(各技能对应独立目录,含 SKILL.md 定义)
|
||
├── docs/ # 设计文档、实现计划、平台适配指南
|
||
├── tests/ # 测试用例(子代理开发、各平台兼容性测试)
|
||
├── README.md # 核心说明、多平台安装指南
|
||
└── gemini-extension.json # Gemini 扩展配置
|
||
```
|
||
|
||
## 关键设计理念
|
||
|
||
1. **渐进式披露(Progressive Disclosure)**:技能相关的文档/资源按需加载,避免上下文token浪费(例如按领域组织参考文件,仅加载当前任务需要的内容);
|
||
|
||
2. **标准化验证**:每个任务都有明确的“做什么”和“验证方式”,确保成果可校验;
|
||
|
||
3. **错误容灾**:例如调试技能中“3次修复失败则质疑架构”、代码评审中“显式文件读取指令避免文件找不到”;
|
||
|
||
4. **跨平台复用**:通过共享核心模块,让 Codex/OpenCode 等平台复用同一套技能逻辑,仅保留平台特定的封装层。
|
||
|
||
## 安装与验证
|
||
|
||
- 各平台安装方式在 [README.md](README.md) 中有详细说明(例如 Claude 用 `/plugin install`、Cursor 用 `/add-plugin`、Gemini 用 `gemini extensions install`);
|
||
|
||
- 验证方式:启动新会话,触发任意技能(如“帮我规划这个功能”),若代理自动调用对应技能逻辑,则安装成功。
|
||
|
||
## 维护与支持
|
||
|
||
- 作者:Jesse Vincent([jesse@fsck.com](mailto:jesse@fsck.com));
|
||
|
||
- 赞助:支持通过 GitHub Sponsors 赞助([https://github.com/sponsors/obra](https://github.com/sponsors/obra));
|
||
|
||
- 问题反馈:通过仓库 Issues 提交([https://github.com/obra/superpowers/issues](https://github.com/obra/superpowers/issues));
|
||
|
||
- 迭代规划:文档中包含明确的平台适配计划(如 2025 年 OpenCode 支持)、技能改进计划(基于用户反馈优化评审、测试逻辑)。
|
||
|
||
综上,Superpowers 本质是“AI 编码代理的软件工程方法论落地框架”,将人类成熟的开发流程和最佳实践固化为 AI 可执行的“技能”,大幅提升 AI 编码代理的产出质量和自主工作能力。
|
||
> (注:文档部分内容可能由 AI 生成) |