企业官网建设流程全解析

Superpowers 编码智能体技能框架快速上手与避坑实践指南

【免费下载链接】superpowersAn agentic skills framework & software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowers

Superpowers 是一套给编码智能体（Claude Code、Codex、Gemini CLI 等）使用的“技能 + 工作流”框架。装好之后，智能体接到任务不会直接写代码，而是先确认需求、产出设计和计划，再按 TDD 与代码评审的节奏推进。本文带你走通安装、验证、测试三步，并列出最常见的失败点。

为什么需要它：智能体“上来就写码”的问题

没有流程时的典型症状

如果你让智能体“实现这个功能”，它通常直接开始输出代码。问题不是模型能力，而是缺一条强制流程：需求没确认就动手、测试补在最后、改完没人评审。结果往往是代码能跑但不符合你的意图，返工成本比一开始多问几句高得多。

Superpowers 改变了哪几个环节

它把一组技能注入你的编码智能体，并按场景自动触发，不需要你手动调用：

• brainstorming：写代码前先用提问把模糊想法收敛成设计文档
• using-git-worktrees：设计确认后创建独立工作区，先跑一遍基线测试
• writing-plans：把工作量拆成 2-5 分钟的小任务，每个任务带文件路径和验证步骤
• test-driven-development：强制 RED-GREEN-REFACTOR 顺序，先写失败测试
• requesting-code-review：任务之间做评审，关键问题会阻断后续进度
• finishing-a-development-branch：全部完成后校验测试，给出合并、提 PR 或丢弃的选项

每个技能都放在skills/目录下，一个技能一个文件夹，你可以直接读它的 SKILL.md 了解触发时机。

最小可跑通路径：安装并确认技能生效

两条命令完成安装

先拿到仓库：

git clone https://gitcode.com/GitHub_Trending/su/superpowers cd superpowers

再按你使用的工具安装。以 Claude Code 为例，可直接从官方插件市场安装：

/plugin install superpowers@claude-plugins-official

如果你同时使用多个编码智能体（比如 Claude Code + Gemini CLI），需要在每个工具里分别安装一次，装一个不等于全部生效。

两种验证方式

最直接的验证：开一个新会话，给一个模糊需求。如果它先反问“要解决什么问题、给谁用、有什么约束”，而不是直接贴代码，说明技能已生效。

也可以用仓库自带的快速测试验证结构是否正常。这条脚本不依赖外部服务，运行很快：

bash tests/opencode/run-tests.sh

它检查插件加载和引导缓存等基础功能。如果通过，再追加--integration参数可跑集成测试，但需要本机已安装 OpenCode。

用项目自带测试套件验证技能行为

运行 Claude Code 技能测试

前提是已安装 Claude Code CLI，否则会直接报错退出。跑全部测试：

bash tests/claude-code/run-skill-tests.sh

只想验证单个技能时，指定测试名并给足超时预算：

bash tests/claude-code/run-skill-tests.sh --test test-subagent-driven-development.sh --timeout 900

单个测试文件的默认超时是 900 秒；加--verbose可以看详细日志。集成测试（--integration）通常耗时 10-30 分钟，建议在本地或夜间跑，不要放进每次提交都执行的流程。

理解两层测试结构

docs/testing.md 把测试分成两层：

• tests/目录：验证非 LLM 的代码，如 brainstorm 服务器、OpenCode 插件加载、codex 插件同步。跑得快，适合接入 CI
• evals/目录：用 drill 测试架驱动真实的 LLM 会话，由裁判判定技能行为是否合规。单场景要 3-30 分钟，且不在 CI 中

如果你的目标是流水线化，建议分层：PR 上只跑tests/里的快速测试，完整 evals 留到每日或按需触发。

常见坑：技能不触发与测试超时排查

• 技能不触发：先确认当前工具是否装上了插件。在 A 工具装好不代表 B 工具可用，逐个检查是最快的排查路径。
• 测试超时：集成套件默认预算有限，超时通常不是故障。用--test只跑一个，或用--timeout加大预算。
• 报 CLI not found：技能测试脚本会先检测 Claude Code CLI，未安装时直接退出。先装 CLI 再重跑。
• evals 跑不起来：它需要配置 API 密钥，且该目录是独立克隆的测试架，不随主仓库自带。新手可以先跳过，专注tests/即可。
• 想关遥测：可视化伴随功能默认会加载一个带版本号的标识图。设置环境变量SUPERPOWERS_DISABLE_TELEMETRY为任意 true 值即可关闭。

适合谁用，以及下一步

适合你，如果：

• 你已经在用 Claude Code、Codex、Gemini CLI、Cursor 等编码智能体，想稳定它的行为而不是逐次叮嘱
• 你希望把 TDD、代码评审这些约定固化进智能体的自主工作流

不太适合，如果：你还没有使用编码智能体，或只想要一次性代码生成工具；这种情况下，单个技能的 SKILL.md 比完整框架更轻量。

下一步可以做的三件事：

1. 读 docs/testing.md，确认哪层测试适合你的 CI
2. 浏览 skills/ 目录，挑一个你最关心的技能读它的 SKILL.md
3. 想扩展自己的技能时，按 skills/writing-skills/SKILL.md 的指南动手

【免费下载链接】superpowersAn agentic skills framework & software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowers