先说明一下这里的superpowers不是我说的某款超级英雄游戏模组而是当前 AI 编程助手圈子里很火的一个开源技能库项目。简单说它是一套给 Claude Code、Codex CLI 这类终端 AI 编程工具加 buff 的“技能包”通过标准化的 skills 机制让 AI 不再只会泛泛地回答“你想怎么改”而是能按一套经过验证的工作流去拆任务、写代码、跑测试、做复盘。如果你已经受够了跟 AI 对话时它总是“一次性回答、改一处崩三处”如果你想让 AI 助手真的像一个有经验的结对程序员那样干活这个项目值得你花一个下午折腾一遍。这篇文章会从设计思路讲到实际安装再拆解几个核心技能的运作机制最后把我踩过的坑和排查经验一并打包给你。文章内容以目前开源社区常见的 superpowers 实现为参考面向的是想深度定制 AI 编程工作流的开发者。1. 项目定位与核心设计思路1.1 它到底解决什么问题用过 Claude Code 或者 Codex CLI 的人应该都有过这种体验AI 很聪明但它的“聪明”往往是片段式的。你跟它说“帮我重构这个模块”它可能直接甩给你一大段新代码既不先分析现状也不考虑测试怎么改更不会在改完以后回头检查是否引入了回归。这不能全怪模型因为模型本身没有一套“干活的方法论”——它只是在续写最可能的下一段文本。superpowers 的切入点就在这里。它用一套结构化的skills技能体系把“软件开发中那些老手会下意识做的事”固化成可执行的步骤和模板。比如write-spec这个核心技能会强制 AI 在动手写代码之前先写一份规格说明把需求拆清楚、把接口定明白然后才进入实现阶段。这本质上是在复现一个资深工程师的工作习惯先想清楚再动手。这个项目的设计目标不是教 AI 更多编程语法而是给它安装一套“行为框架”。框架里每个技能都包含三个要素说明文档SKILL.md、可选的脚本文件、以及触发条件。AI 读取技能文档后会按照文档中描述的流程去执行任务。换句话说你给 AI 的不是答案而是一套做事的流程。1.2 为什么选择“技能”而不是“提示词模板”可能有人会问这不就是写一堆提示词模板吗差别很大。提示词模板是一次性的、静态的文本AI 每次都要从头理解你的意图而 superpowers 的技能是存放在项目本地目录中的结构化文件AI 可以在需要的时候反复读取、引用、组合。更深层的区别在于“状态”。superpowers 的技能体系允许 AI 在项目里留下中间产物比如specs/目录下的规格文档、research/目录下的调研记录。这些文件不仅当前这次会话能用下次会话、换个工具比如从 Claude Code 切到 Codex也依然在。这等于给了 AI 一个“长期记忆”而不是每次对话都从零开始。关于 Codex 的适配superpowers 很早就对 Codex CLI 做了兼容可以通过配置让 Codex 也能加载这套技能体系。实际用下来两种工具加载同一套技能时行为略有差异——Claude Code 更擅长遵循长流程文档Codex 对子技能的组合调用更自然。如果你主要用 Codex建议把 superpowers 的默认技能列表精简一下优先保留write-spec、tdd和debugging这几个核心技能避免上下文被挤占。2. 安装方式与使用前配置2.1 先用三分钟装好核心库superpowers 的安装目前有两条主流路径取决于你用的是 Claude Code 还是 Codex CLI。如果你用的是 Claude Code最直接的方式是从 GitHub 克隆模板仓库git clone https://github.com/obra/superpowers.git cd superpowers cp -r .claude /path/to/your/project/这里会把skills目录复制到你的项目根目录下Claude Code 启动时会自动扫描.claude/skills下的所有技能。如果你用的是 Codex CLI安装方式会稍微不同通常需要将技能目录放到 Codex 能识别的位置并在配置里声明技能路径。具体路径取决于你安装的 Codex 版本建议看一眼项目 README 里的说明。这里有一个常见误区有人认为把技能放到全局目录~/.claude/skills就能对所有项目生效但实际上这会让技能中的路径失效。superpowers 的技能大量依赖相对路径来读写项目内的文件一旦放到全局目录AI 生成的规格文档会写到莫名其妙的位置。所以我的建议是每个项目单独复制一份 superpowers 技能目录或者维护一个脚手架模板新建项目时自动带上。2.2 初始化技能库的隐藏细节装完技能文件后很多人会直接开始对话结果发现 AI 完全不理睬这些技能。这是因为技能体系还需要“引导文件”来告诉 AI 它们的存在。在项目根目录下你需要确认存在这样的引导入口通常是.claude/commands/superpowers.md或类似文件它会在每次会话开始时被自动加载列出当前可用的技能清单。引导文件的实际作用有点像一本书的目录。AI 每次会话都不会主动把所有技能文档读一遍那是极大的 token 浪费它只读引导文件然后根据任务性质决定是否深入某个技能文档。所以引导文件里对每个技能的描述是否精准直接影响 AI 调用技能的准确率。我见过有人把技能描述写得很模糊比如“用于改进代码”结果 AI 在遇到任何问题时都想调用它上下文被大量无关技能说明占满主任务的质量反而下降了。2.3 目录结构到底长什么样理解目录结构是使用 superpowers 的关键。一个标准技能库包含以下核心部分superpowers/ ├── skills/ │ ├── write-spec/ │ │ ├── SKILL.md │ │ └── templates/ │ ├── tdd/ │ │ ├── SKILL.md │ │ └── scripts/ │ ├── debugging/ │ │ ├── SKILL.md │ │ └── ... │ └── ... └── commands/ └── superpowers.md每个技能目录下的SKILL.md是整个技能的核心它用 Markdown 描述技能的触发条件、执行步骤、输出要求。AI 在决定调用某个技能后会完整读取这个文件并按照其中的指令逐步执行。这里要特别提醒技能目录的命名和SKILL.md中的名称必须一致。如果你把write-spec技能目录改名为spec-writing但文档内部仍自称write-specAI 调用时会出现混乱。我自己就犯过这个错结果 AI 一边说“好的我将使用 write-spec 技能”一边看着不存在的目录发愣。3. 核心技能机制深度拆解3.1 write-spec 技能一切从写规格开始这个技能值得单独拎出来讲因为它体现了 superpowers 最核心的理念——写代码前先写规格。技能会引导 AI 完成以下几步与用户对话澄清需求、输出一个需求分析文档、定义功能变更点、识别受影响范围、最后形成一个规格文档草案。我在实际项目里试过这个流程最有价值的产出不是最后的规格文档而是AI 与用户之间的多轮澄清对话。比如我让 AI“给博客系统加一个标签功能”如果不走 superpowersAI 可能直接就开写数据库 migration 了。而走了 write-spec 流程AI 会先问我标签是自由输入还是预定义标签和文章的关系是多对多吗标签页需要列表页吗这些问题任何一个遗漏后续返工的成本都远超多花这几分钟对话。write-spec 生成的规格文档也不是给你存档用的它是后续tdd技能编写测试时的“需求来源”。这从机制上保证了测试和需求是一一对应的而不是测试跟着实现走。3.2 tdd 技能把测试驱动开发的节奏硬编码传统 TDD 依赖人自己的纪律性而 superpowers 的tdd技能把这种纪律性固化到了行为流程中。AI 在实现一个新功能之前会被要求先从规格文档中拆出测试点然后跑一次测试确认失败才开始写实现代码最后再跑测试确认通过。这个技能的巧妙之处在于它把“红-绿-重构”这个循环做成了强制步骤AI 不能跳过。我在 Codex 上跑过几次发现 Codex 对这个技能的遵循度比预期高但它有一个倾向喜欢在测试失败后直接重写整个测试文件而不是精确修改实现代码。所以你需要监督它在执行tdd时不要跳步测试失败后的第一步永远是读报错而不是猜。另外如果你主要使用 Java 生态这次热搜里也出现了一些用户搜索建议在 SKILL.md 的测试命令配置里直接写死 Maven 或 Gradle 的命令形式比如test_command: mvn test -DtestYourTest -q否则 AI 可能会默认项目用 pytest。3.3 debugging 技能让 AI 有耐心地排查问题debugging 技能是另一个高频核心。它把调试过程拆成了复现问题、检查相关日志、阅读相关源码、形成假设、验证假设、修复、回归测试七步。每一步都要求 AI 输出中间结果而不是一次性给答案。这个技能对抗的是 LLM 最常见的“傲慢”——面对报错模型有时会凭印象给出一个看似合理的修复实际上根本没弄清楚根因。debugging 技能强制 AI 先输出“我对这个问题的假设”然后写一个最小验证脚本去证实或证伪这个假设。我印象最深的一次是 AI 面对一个偶发性的 NPE 报错本能地猜是某个对象未初始化。但在 debugging 技能约束下它先去查了日志发现空指针只发生在多线程并发场景于是把排查方向转向了线程安全最后定位到是一个共享的 SimpleDateFormat 导致的竞态问题。如果没有这个流程约束这种问题可能来回耗半天。4. 实操记录从零到跑通全套工作流4.1 我用一个 Web 项目验证整个链路为了确认这套体系不是玩具我特地搭了一个最小但完整的 Web 服务来跑整个流程。项目结构是Python FastAPI SQLite pytest。环境是 macOS 终端AI 工具用的是 Codex CLI。整个流程分四步走初始化 superpowers、用 write-spec 定义需求、用 tdd 推动实现、用 debugging 处理一个刻意留下的 bug。初始化阶段我把技能目录复制到项目根目录然后在引导文件里只保留了三个技能write-spec、tdd、debugging。这种“只开需要的技能”的做法是我强烈推荐的技能不是越多越好因为每个技能的说明文档都会占用上下文窗口。接着我向 AI 提出一个需求“实现一个待办事项 API支持增删查改数据存 SQLite提供健康检查接口。”AI 按 write-spec 流程先向我追问了四个问题然后生成了规格文档。这个过程大约消耗了 12k token比直接让 AI 写代码多花了 5k token。很多人嫌这步浪费但我算过后续返工的成本这 5k token 花得很值。4.2 从规格到红绿循环规格文档确定后我让 AI 调用 tdd 技能开始实现。它首先创建了一个测试文件test_todo_api.py里面包含了四个测试用例创建待办、查询列表、更新状态、删除待办。然后 AI 主动跑了一次测试看着它们全部失败红才开始创建main.py和应用骨架。这里出现了一个小插曲AI 在实现 SQLite 持久化时直接用了全局连接对象。测试跑完一轮之后确实全绿了但我意识到这种写法在并发场景会有问题。我故意不纠正想看看 debugging 技能面对“测试通过但代码有隐患”这种问题时如何反应。结果让我满意——AI 在对代码做 review 时主动提出了“全局 sqlite3 connection 不是线程安全的建议改为每次请求创建连接”并给出了修改示例。这说明当流程约束到位后AI 的“代码嗅觉”也能够被激发出来。4.3 刻意埋雷后的调试演练为了测试 debugging 技能我在update_todo接口里故意埋了一个类型转换 bug把is_done字段的值当成整数比较而不是先做布尔转换。结果前端传true时接口返回 500。我让 AI 用 debugging 技能排查它没有立刻改代码而是先要求在本地包一个 curl 命令复现问题然后查看了main.py中对应路由的源码再输出假设“前端传的字符串与后端布尔类型比较时抛 TypeError”最后才动手修复。整个过程大约花了 8 分多钟但每一步都有明确的输出我全程能知道它在想什么、下一步要做什么。这种“可视化推理过程”的价值在排障场景中超过任何代码补全。5. 常见问题与排查技巧实录5.1 技能被忽略引导文件永远是第一个排查点如果你跟 AI 对话发现它完全无视技能永远在自由发挥九成问题出在引导文件没被正确加载。排查方法很简单在对话中直接问 AI“当前项目有哪些可用技能”。如果它答不上来或者只给出泛泛的回答说明引导文件没生效。常见原因有三种一是引导文件放在错误的位置应该在其中.claude/commands/下检查二是引导文件内容用了太多嵌套标题导致 AI 只读了前半段三是技能名称在引导文件和实际目录之间不一致。逐一排除后基本都能解决。5.2 token 消耗变得离谱上下文被技能描述吃满了我遇到过一种情况对话进行到一半AI 开始重复忘记刚才的决策。打开调试一看上下文里塞满了各个技能的 SKILL.md 全文。原因是在一次任务中 AI 连续调用了多个技能且每个技能的 SKILL.md 都很长导致历史信息被挤出窗口。应对办法有两个。第一精简每个 SKILL.md控制在 50 行以内只保留流程骨架和验收标准把细节放到templates/目录的附件里让 AI 按需读取。第二在对话中主动切分任务不要在一个会话里既写规格又写实现又做调试干完一个阶段就/clear一次重新加载上下文。实测下来第二种方法对 Codex CLI 尤其有效。5.3 技能和实际工具不匹配改这一处就行superpowers 默认技能模板里很多测试命令和脚本预设的是 Claude Code 或通用 Shell 命令。你用的是 Codex 或 JetBrains AI Assistant 时这些命令可能不适用。解决方式是在SKILL.md开头增加一个“运行环境”段落明确写出当前项目使用的语言和包管理器。下面是我在 Java 项目里给 tdd 技能加的配置示例## 环境 - 语言Java 17 - 构建工具Maven - 测试命令mvn test -Dtest类名 -q - 运行命令mvn spring-boot:run加了这几行以后AI 在 tdd 过程中就再也没有瞎猜过测试命令。这个改法成本极低收益极高。5.4 多技能协作时互相打架设置技能优先级当项目同时存在 write-spec 和 tdd 技能时AI 可能在写代码的中途又回头要求“先写规格”导致流程卡顿。处理方式是在引导文件里明确技能的执行顺序和触发边界。比如写明“只有新功能开发时调用 write-spectdd 只对已有规格的功能生效”。这种约束 AI 是认的但你必须写得清楚。含糊的表述才会导致它的行为漂移。6. 一些真正值得记住的经验我前后在三个项目里用了 superpowers最早的体会是“它确实把 AI 从答题机器变成了流程执行者”。这个变化不是模型能力带来的而是行为约束带来的。同样的模型、同样的代码库有没有技能库加持表现出来的专业度差一个档次。但也要泼一盆冷水这套体系不适合所有场景。如果你只是临时让 AI 帮忙写个脚本、改个正则套上完整的技能流程反而笨重。它的价值在“长期项目、多文件改动、需要持续维护”的场景里才会完全释放。我现在的习惯是正经项目都会带一份精简过的 superpowers 技能库但遇到一次性小任务就干脆卸掉保持轻装。如果你准备上手我的建议是从 Claude Code 开始体验它建议把引导和技能目录都放在项目内只保留 write-spec、tdd、debugging 三件套跑一个完整的小功能试试。等你熟悉了技能编写的套路再自己去写适合团队风格的自定义技能。这个项目最迷人的地方不在于它自带的技能而在于它提供了一套“把你自己的工作方法论变成 AI 可执行流程”的框架。就冲这一点它值得你在下一个项目里给它一次机会。