最近在终端里折腾 AI 编码代理“superpowers”这个词在 Codex、Claude Code 的圈子里出现频率越来越高。起初我以为它又是一个代码生成插件真正用下来才意识到它改变的是 AI 的工作方式而不是换一个生成代码的工具。superpowers 本质上是一套开源技能框架围绕 SKILL.md 组织给终端型 AI 代理装上“测试驱动开发”“调试定位”“小步重构”“深度研究”这类可复用方法论。安装很轻上手门槛不高前提是你已经在用 Codex CLI、Claude Code 这类能读文件、能跑命令的命令行 AI 工具。这篇文章我会从机制原理、安装配置、核心技能、Java 场景、实测踩坑几个角度把完整过程写出来给想尝试的人一份可以直接照做的参考。1. 为什么要把“技能”教给 AI 编码代理1.1 “生成代码”和“做工程”是两回事我见过太多人把 AI 编码工具当成高级搜索框需求丢进去代码贴出来复制进 IDE一跑报错再把报错丢回去。这套流程在新项目原型阶段很爽但一旦进入一个已经存在半年、有几百个类的项目问题就全来了AI 生成的类名、分层、异常处理方式跟项目惯例对不上没有任何测试谁都不敢保证改动不破坏老逻辑一次会话里塞的需求越多AI 写出来的代码越接近“一次性脚本”。问题的本质在于多数 AI 编码工具在默认状态下是一个“代码生成器”不是一个“软件工程师”。让它遵守测试驱动、先调研再动手、小步重构光靠提示词是压不住的。上下文稍微一长AI 就会忘记你的约束回到“直接输出实现代码”的老路上。superpowers 的价值恰恰在这里它不试图在提示词层面说服 AI而是把工程规范变成 AI 主动读取并执行的文件用流程对抗遗忘。1.2 一套显式技能胜过一万句隐含要求superpowers 做的事情其实很朴素把软件工程里的最佳实践写成结构化、可复用的“技能”文件让 AI 在执行任务时按文件里的步骤走。你可以把它理解成给 AI 发了一本《员工工作手册》而不是只丢给它一句“好好干”。带过新人的都会懂几乎没有人能靠一句口号就让新人理解项目规范和开发流程但我们在提示 AI 时却一直在用“请遵循最佳实践”“请写高质量代码”这种模糊指令。技能的思路是把这些模糊要求显性化该先干什么、该检查什么、什么情况下停止、产出物是什么全部写清楚。AI 读一遍 SKILL.md再按步骤执行结果的可控性会高很多。这里说的“技能”不是给模型增加知识而是约束它的工作过程。代码生成器知道怎么写 TDD 测试但只有在被明确要求时才愿意这么做技能化之后AI 会默认按这个路径走因为它是任务的一部分而不是一个可以被忽略的建议。1.3 这个工具解决了什么适合谁一句话概括superpowers 让 AI 编码代理按照真实的软件工程流程工作。适合的人群很明确——已经在用 Codex CLI、Claude Code、Gemini CLI 这类终端 AI 工具并且希望 AI 产出可维护、有测试、符合项目惯例代码的开发者。如果你只是想要一个快速跑通原型、随手生成脚本的工具那没必要上这套技能体系反而会觉得它啰嗦。我自己的判断是superpowers 不是给“想少写代码”的人用的是给“想让 AI 写完后自己不用返工”的人用的。它把一部分工作转移到了流程设计上换来的却是 AI 输出质量的稳定和可预测。这一点在团队协作和多模块项目里尤其值钱因为别人的 AI 生成的代码你也能看得懂、跑得通。2. Superpowers 的核心机制SKILL.md 与技能工作流2.1 技能不是插件是“工作手册”superpowers 里最基本的单元叫 Skill中文可以理解成“技能”。每个技能是一个目录目录里最关键的文件是 SKILL.md用 Markdown 编写。这个文件描述了三件事这个技能解决什么问题、前置条件是什么、执行步骤是什么。举个例子一个 TDD 技能目录大致长这样test-driven-development/ ├── SKILL.md ├── examples/ │ └── java-spring/ │ └── ... └── references/ └── ...SKILL.md 是入口references 和 examples 放参考资料和示例。AI 在执行任务时会先找到匹配的 SKILL.md读取里面的步骤然后像拿着菜谱做饭一样干活。这套设计跟传统 IDE 插件有本质区别插件是外部程序技能是文本约定插件的运行依赖软件实现技能的运行依赖模型理解和执行。好处是技能极其轻量改一个字就是改一次行为不需要编译、不需要发布放进 Git 就能分享。2.2 SKILL.md 是怎么“教”AI 的拿 TDD 技能来说它内部几乎一定会写这样几步红先写一个会导致失败的测试。运行测试确认失败原因与预期一致。绿用最小改动让测试通过。跑完整测试套件确认没有引入回归。重构在不改变外部行为的前提下优化代码。再次运行测试确保重构后仍然全绿。这六步对开发者来说再熟悉不过但对 AI 来说不是天生的。没有技能约束时AI 的默认行为是“一次性生成测试加实现”而且常常先写实现、后补测试甚至不补测试。技能的作用就是强制它把顺序反过来并且在每一步执行真实命令去验证而不是靠想象力判断“应该能过”。有些技能还会定义“不要做什么”和“何时停止”。比如调试技能会告诉 AI不要在没有充分证据的情况下修改代码先读错误堆栈再缩小复现范围每次只改一处。这些约束比提示词里写一百句“请谨慎修改”都管用因为它们是 AI 主动加载的方法论而不是被动接收的请求。2.3 技能是怎么被触发的触发方式可以分为三类用户显式指定在对话里直接说“使用 TDD 技能完成这个功能”。这是最可控的方式尤其适合刚刚接入、还在熟悉技能的阶段。任务自动匹配AI 根据用户描述判断当前涉及哪个技能领域自动加载。这个依赖 CLI 的 agent 能力和技能描述写得是否清晰有一定不确定性。项目级默认链路可以在项目说明文件比如 CLAUDE.md、AGENTS.md里声明默认工作流例如“所有新功能必须走 TDD 技能”“接口变更前必须跑 Research”。我自己的使用感受是前期建议多用显式指定等理解了技能内容、也把项目说明写好了再切换到自动匹配。否则 AI 可能会跳过技能直接按聊天惯性生成代码。2.4 和“系统提示词”的本质区别很多人会问这不就是把一段长提示词保存下来吗区别很大。我整理过一个对比表维度普通 PromptSuperpowers Skill可复用性每次都要手写或隐式依赖模型记住一次安装持续生效结构自然语言混杂在对话里容易被稀释独立 Markdown结构性步骤清晰可维护性修改后影响所有对话无法隔离按技能文件独立修改、独立版本化可测试性无法验证 AI 是否遵守检查 AI 输出是否匹配技能步骤团队共享靠口头传递或复制聊天记录放进 Git项目即代码技能即文档运行方式模型凭空“理解”模型先读文件再执行命令验证这个差异在实际项目里非常明显。以前我在提示词里写“请先写测试再实现”AI 偶尔会照做但上下文一长、任务一多它必然跑偏。改成技能文件之后AI 在每次任务开始时都会读取一次步骤犯错概率低很多。3. 安装与配置从 Codex 到 Claude Code 的实战路径3.1 前置准备安装 superpowers 之前你的终端环境最好满足几点一个能正常使用的终端macOS、Linux 都行Windows 建议上 WSL因为很多命令在原生 Windows 下会有权限和路径问题。Git 已经装好。至少装了 Codex CLI、Claude Code 或 Gemini CLI 中的任意一个。部分安装路径依赖 Node.js/npm建议顺手装一下。这些条件其实大多数开发者都有了不用专门准备。唯一要注意的是版本CLI 工具迭代很快老版本未必支持技能目录扫描建议先把 Codex 或 Claude Code 更新到较新的稳定版再装。3.2 安装命令和目录结构superpowers 的安装逻辑是“复制技能文件到 CLI 的 skills 目录”。官方 README 推荐的安装方式是在项目根目录执行# Claude Code 用户 claude install superpowers # Codex CLI 用户 codex install superpowers如果你的 CLI 版本还不支持这类安装命令更稳妥的办法是直接从 GitHub 仓库克隆下来手动把技能目录复制到对应位置git clone https://github.com/obra/superpowers.git cp -r superpowers/skills/* .claude/skills/安装完成后检查一下ls -la .claude/skills/正常你会看到 test-driven-development、debugging、refactoring、research、project-brief 这样的目录不同版本目录名会有差异以实际为准。这里我想特别说明复制目录这个动作本身并没有魔法真正关键的是 CLI 能否读取到SKILL.md这个文件。很多“装上没用”的问题最后都出在路径不对或者文件名写错上。3.3 项目级安装还是全局安装我建议绝大多数人选择项目级安装也就是把技能目录放到当前项目的.claude/skills/、.codex/skills/这类目录里。理由有三个技能跟项目走换机器、换同事都不用重新配置。可以提交进 Git团队共享一份工作流逐步沉淀项目自己的技能。项目级配置优先于全局配置改起来不担心影响别的项目。全局安装适合自己长期使用、跟任何项目都无关的通用水方法论。但全局技能的维护成本高容易和项目级技能产生“都想管但方向不一致”的冲突。刚开始用的时候先做项目级安装等明确了自己需要什么再决定要不要全局化。3.4 第一次启动时的验证方法装完之后怎么确定真的生效了我的做法是在项目根目录启动 Claude Code 或 Codex然后直接问一句list available skills如果 AI 列出了 superpowers 相关的技能目录说明加载成功。如果没有优先检查当前工作目录是不是项目根目录以及技能目录是否被 CLI 扫描到。有些 CLI 只扫描项目根目录下的技能目录你在子目录启动对话它就看不到了。这件事和“配置改了但没重启服务”一样经典每次都要提醒自己。3.5 升级与版本管理superpowers 迭代速度不慢我建议每隔一段时间拉一次上游更新。但有一个坑必须提前注意到如果你手改过内置技能直接覆盖安装会把你的修改冲掉。我的处理方式是所有自定义技能都放在单独的目录里命名加上项目前缀内置技能尽量不碰实在要改就 fork 一份管理。技能其实也是代码既然你是程序员就别让它成为不可回溯的孤儿配置。4. 默认技能拆解TDD、重构、调试与深度研究到底怎么用4.1 TDD 技能把测试放在实现前面superpowers 里最容易被低估、也最值得先用的技能就是 TDD。我最初觉得“AI 也需要 TDD 吗”后来发现它比人类更需要。人类至少知道“不改老代码”这种基本谨慎AI 默认的行为是拿到需求立刻输出完整实现完全不考虑测试。用 TDD 技能约束之后AI 的行为会发生明显变化先写一个失败的测试运行一次确认失败再写最小实现让测试通过最后重构回归测试。在具体项目里这一步会真实执行命令行。比如 Maven 项目AI 会自己运行mvn test -DtestYourTest看到失败输出之后才开始写实现。如果你发现 AI 跳过了运行测试这一步多半是技能没被加载或者它被上下文里“快速完成”这类指令带偏了。这时候回到显式调用“使用 TDD 技能按步骤执行。”4.2 调试技能先缩小范围再动手改代码第二个很实用的技能是调试。没有技能的 AI 遇到 bug往往看一眼报错就开始猜甚至直接把整个方法重写。调试技能扭转了这个习惯先读完整堆栈定位第一个错误点然后用二分法缩小范围可能涉及注释代码块、加日志或跑局部测试定位后再动手而且在修改前先记录“假设-验证-结论”。这看起来慢实际很快。有一次 AI 在一个 Java 服务里遇到了空指针按技能流程它先用最小复现找到真正为 null 的对象再回溯到上层调用发现是接口层少传了字段。如果按之前的习惯它大概会把整个方法体重构一遍改完说不定引入更多问题。这个案例让我意识到调试技能省的不是时间是“猜错方向”的成本。4.3 重构技能小步前进保持绿灯重构技能的核心原则是“每次改动都要有测试兜底”它要求 AI 在重构前确保测试套件是绿的重构中每一步都足够小比如只改一个方法、只调整一个类每走一步都重新运行测试。宁可多跑几次测试也不要一口气改完再验证。这个技能最适合做技术债清理和老代码维护。以前让 AI 帮忙重构最担心的就是它改到一半把行为改变了。有了技能约束AI 会自己守着测试这条安全线行为更像一个谨慎的老工程师。对大型系统维护来说这种“慢即是快”的节奏才是可持续的。4.4 Research 技能动手前先做功课Research 技能在大型升级和技术选型时特别有用。它的工作流程大致是明确研究问题检索项目内外的资料读取相关代码确认现状输出一份结构化的研究简报列出选项、权衡和推荐。说白了就是让 AI 先做功课再动手。我试过一次把“我们想把配置中心从 A 迁到 B需要梳理影响面”这种任务扔给它它在动手前先扫了一遍所有读取配置的地方包括测试代码最后输出的迁移清单比我自己整理得还全。这就是 Research 技能的典型价值它让 AI 的“调研能力”不再是随口百度的结果而是围绕项目代码展开的证据链。4.5 技能组合从单点使用到流程编排单个技能能解决局部问题组合起来就能形成完整工程流。我在一个中等规模项目里的常用组合是Research先摸清现状产出简报。Project Brief把项目关键约束沉淀成简报。TDD新功能开发按红绿重构推进。Debugging异常定位按证据链走。这种组合不一定要写在技能文件里你可以在对话里指定顺序。用得多了AI 会自己形成路径依赖越来越贴近团队的工作方式。真正的元技能其实是“如何选择技能”这个习惯养成之后工具本身反而退到幕后了。5. Java 与多语言场景下的实际使用心得5.1 为什么 Java 项目尤其适合技能化Java 社区可能是最适合这套工具落地的场景之一。原因很直接Java 项目的工程纪律强测试文化成熟构建体系复杂。一个标准 Maven/Gradle 项目里AI 直接生成代码时最容易忽略的就是测试依赖、Surefire 配置、JUnit 版本这些细节。而技能化流程要求 AI 在写测试之前先确认测试框架可用大大降低了“代码能编译但测试跑不了”的概率。如果你是 Java 开发者搜 superpowers java 时大概率是想知道这套东西在 Java 项目里能不能真的落地我的答案是可以但需要把构建工具、测试框架这些基础信息提前喂给 AI或者写一个 Java 专属技能把项目里的 Maven 生命周期、测试命令、Java 版本约束都固化进去。5.2 一个 Java 功能的完整实践过程我在一个 Maven 多模块项目里实践过一次功能是“用户状态校验”。整体过程大概是我先让 AI 列出可用技能确认 TDD 技能被加载。我明确要求“使用 TDD 技能实现这个功能”。AI 先检查了 pom.xml确认 JUnit 5 依赖存在。AI 写了失败测试调用 UserStatusValidator断言某个非法状态抛出异常。AI 运行mvn test -DtestUserStatusValidatorTest确认失败信息符合预期。AI 补实现代码再次运行测试直到全绿。最后 AI 做了个小重构抽出常量再跑一次完整测试套件。整个过程中最有价值的是第 5 步。以前的 AI 不会真的去跑测试只会“觉得自己写得对”。技能化的流程让它必须拿运行结果说话。单次效率看似低了但产出的代码可维护性和可信度完全不同。5.3 Gradle、多模块与微服务场景的注意点在 Gradle 项目里命令通常从mvn test换成./gradlew test --tests xxx技能本身不用改但你需要在项目说明里写清楚命令路径。多模块项目要特别注意AI 可能跑到根目录执行测试导致忽略了某个模块的上下文建议在项目技能里明确“每个模块有独立的测试命令”。微服务场景我也有一个观察superpowers 并不关心你用的是 Spring Boot 还是 Quarkus它关心的是“你有没有一套能执行的验证手段”。只要项目里有测试技能就能发挥作用。真正困难的反而是老项目没有测试、构建脚本又混乱这种情况下先让 AI 用 Research 技能梳理现状再加一层冒烟测试然后再考虑功能开发。5.4 多语言扩展与自定义技能最后说一句superpowers 的框架本身是语言无关的。SKILL.md 里的指令可以用自然语言描述AI 负责理解并转换成具体语言或构建工具的命令。你可以直接用社区里别人写好的技能也可以针对 Python、Go、TypeScript 写自己的技能。自定义技能其实不复杂本质就是“把团队规范写成 Markdown 放进技能目录”。比如你们团队要求所有 Controller 层必须有参数校验、所有对外接口必须有契约测试这些都可以写进一个自定义技能。写完之后 AI 每次接手相关任务都会主动遵守等于把团队文化沉淀进了代码库。6. 实测中的坑与规避思路6.1 技能文件没被 AI 发现这是我最常被问到的问题也是我自己踩过最多次的坑。现象是 AI 完全不按技能走甚至问你“什么是 superpowers”。排查顺序如下当前工作目录是否是项目根目录技能目录是否在这个目录下目录名和文件名是否精确匹配注意大小写SKILL.md不要写成skill.md。你的 CLI 是否读取了这个路径不同工具的 skills 目录约定不一样Claude Code 看.claude/skills/Codex 看.codex/skills/确认没有装反。首次启动会话时是否在新会话中有些 CLI 只在会话启动时扫描技能目录中途安装需要重启会话。这四步排查完九成问题都能解决。6.2 AI 跳过 TDD 直接写实现第二个常见问题技能装好了但 AI 在新功能对话里直接输出实现代码没有先写测试。原因往往不是技能没生效而是 AI 没有被明确要求使用技能。解决方法有两条在任务描述里直接写“使用 TDD 技能按技能步骤执行”。在项目说明文件比如 CLAUDE.md 或 AGENTS.md里声明默认工作流。我个人强烈建议两条都做。靠项目说明兜底对话里再显式强调AI 跑偏的概率会降到很低。别指望 AI 自己“悟到”应该用技能它默认的路径就是直接干活。6.3 手动安装时的权限问题手动复制技能目录时如果目标目录属于 root 或者其他账户复制可能会失败。千万不要用 sudo 强行操作这会污染文件权限。正确做法是把技能目录放到用户可写的项目路径下或者调整目录权限后再操作。权限问题处理起来不难但一旦被 sudo 搅过后面会出现各种莫名其妙的无权限报错排查成本不低。6.4 升级覆盖自定义内容内置技能升级时如果你的自定义技能恰好和内置技能同名大概率会被覆盖。为了避免血泪教训自定义技能统一用项目名-技能名命名。把内置技能和自定义技能分开目录管理。定期用 Git 提交技能目录方便回溯。技能其实也是代码既然你是程序员就别让它成为不可回溯的孤儿配置。6.5 上下文窗口被技能文件吃满技能文件多、项目上下文大、模型窗口有限这个问题在高频使用后一定会出现。我的处理思路是不要一次性把所有技能都堆进项目按需安装任务大就拆小一次只让 AI 处理一个功能研究类任务和开发类任务分开会话避免把研究简报和代码改动挤在同一个上下文里。技能是越用越精的不是越多越好。6.6 我的习惯与建议最后分享一点我自己的习惯。新项目接入 superpowers 时我不会急着让 AI 开发功能。我会先让 AI 用 Research 技能研究整个项目结构然后写一个项目专属技能把构建命令、测试框架、代码风格、目录约定全部固化进去。这一步花费大概十几分钟但之后 AI 的产出质量和一致性会明显上一个台阶。这样的流程跑起来后AI 在我项目里的角色基本从一个“代码生成器”变成了“懂得测试、懂得重构、懂得先研究的结对程序员”。它还是会有失误还写不出完美的架构但工作方式终于像人了。如果只能留一条经验我会说别把它当生成器用把它当干活规范用。让 AI 先跑一个带有测试的小功能你全程盯着它是否按技能步骤执行远比一次丢大需求让它自由发挥有用。superpowers 不是魔法它只是把你自己知道但没空写下来的最佳实践变成 AI 愿意遵守的手册。习惯之后你会发现项目里的代码不只会变多还会变稳。