第一次在 GitHub 趋势榜上刷到“superpowers”这个名字我以为是哪个中二程序员给项目起的网红名。直到我把它装进 Claude Code让 AI 带着整套 TDD 流程、系统性调试步骤和代码审查清单去独立完成一个 Java 重构任务才发现这个名字背后是实打实的野心——它不是在给编码助手加功能而是在给 AI“上规矩”。简单说superpowers 是一套面向命令行编码智能体的“职业技能培训库”把老师傅们写代码、排故障、做审查时的套路整理成结构化技能文档让 Claude Code、Codex 这类工具不再凭感觉回答而是先定方案、再动手、最后验证。如果你已经受够了 AI“什么都会写、但写出来永远不牢靠”的状态这篇实操记录应该能帮上忙。我会从安装、初始化、核心技能拆解、自定义技能再到真实项目中的排查经验把全流程完整写出来。1. Superpowers 是什么从“智能问答”到“职业素养”1.1 为什么模型越来越聪明项目里却越来越心累现在的编程模型写单点功能真的很强让它写一个排序函数、一个 REST 接口、一段正则表达式基本秒出。可一旦让它完成一个“需要流程支撑”的任务比如“给这个模块补上测试”“帮我排查线上偶发报错”“把这个历史代码安全重构”它就开始飘——最常见的表现是跳过测试直接写实现、改一个 bug 顺手改了三处无关代码、或者重构到一半自己把接口改崩了。问题的根源不是模型不够聪明而是它缺少“工程章法”。人类程序员靠公司规范、Code Review、单元测试这些流程兜底而裸奔的 AI 只有直觉没有流程。一位三年经验的工程师不会在没写测试的情况下说“改完了”但大模型会。superpowers 的思路就是把“流程”本身做成可装载的资产。它不是提示词模板也不是 IDE 插件而是一套由若干“技能”组成的方法论库。每个技能都是一份结构化的操作手册AI 按需加载后严格按手册里的步骤执行而不是自由发挥。1.2 “技能”这套设计到底解决什么问题技能这个词听起来玄实际落地很朴素。打开一个技能目录核心文件 SKILL.md 用 Markdown 写成开头一段 YAML 描述它的名称、适用场景、触发条件正文就是分步骤的执行流程和守则。比如 TDD 技能会告诉 AI先写失败测试跑一遍确认红灯再写最小实现看到绿灯后重构最后全量回归。调试技能则要求 AI先复现、再缩小范围、读完整错误栈、找到根因后带着目的修、最后补回归测试。这个过程和我们常见的“手写一大段 prompt 让它这么做”有什么本质区别区别在于体系化与复用。手写 prompt 是一次性的换个项目、换个会话就没了而技能库是一次安装、全局生效且技能之间能互相调用——AI 可以先加载“写计划”技能把需求拆成步骤再加载 TDD 技能逐条实现遇到问题自动切入“系统性调试”技能。这种组合出来的行为已经接近一个受过训练的中级工程师的做事次序。我见过太多人把希望寄托在“换一个更强的模型”上却忽略了就算换了个聪明人进来没有流程约束他照样能把项目搞乱。1.3 它在工具链里的位置不是替代模型而是替代提示词很多人问superpowers 是替代 Claude Code 还是替代 Codex它哪个都不替代。它站在编码助手之上把“怎么干活”这件事标准化。当前社区里最常见的是把它作为 Claude Code 的技能库来安装但技能本身是纯文本 Markdown只要你的工具能读入这些说明它就能生效。Codex 同样可以用后面第四章我会专门讲怎么把技能搬运给 Codex。为了直观对比我把三种用法的差异放在一张表里用法行为表现可维护性结果稳定性裸聊问一句答一段答对答错全靠模型当天状态无很低手写复杂 prompt能约束方向但每会话都要贴换任务就失效弱中等技能库按需加载标准流程步骤可追溯、可更新强高受底层模型上限约束个人体感最明显的是“结果稳定性”这一列。裸聊模式下同一个需求让 AI 写十次测试它可能只有两三次真的走测试驱动挂上技能库后只要是它判断匹配的场景基本每次都会走完整流程。这个“稳定”比单次惊艳重要得多——因为项目工程化的本质就是让高质量的行为可以重复出现。2. 安装与初始化让编码助手真正“长本事”2.1 前置环境十几分钟能准备好的清单别急着装先确认基础环境避免装到一半发现版本对不上。打开终端逐个跑一遍node -v # 建议 18 以上新版本要求 20 claude --version codex --version git --version如果你的主要战场是 Java额外确认 JDK 和构建工具java -version mvn -v # 或者 gradle -v注意技能库本身不挑语言但如果你主要在 Java 项目上使用JDK 17 Maven 3.8 以上是比较省心的组合。JDK 太老会导致 JUnit 5 跑不起来到时候你会分不清是技能的锅还是环境的锅。这里有个容易忽略的点技能库不是独立运行的程序它依附于编码助手。所以前置环境的核心不是 Node 版本多新而是 Claude Code 或 Codex 本身已经能正常干活。我的习惯是先让助手在项目里完成一次最简单的“读取文件并总结”确认链路通了再装技能省得后面排查问题时分不清是装坏了还是本来就没配好。2.2 安装方式选一种别混着来社区里主流的装法有两种我都试过。第一种是直接在 Claude Code 里装插件/plugin install superpowerslatest装完它会新增一组斜杠命令用来初始化技能、查看技能列表、管理项目级配置。第二种是走 npm 全局安装再在项目目录里执行初始化npm install -g superpowers superpowers install两种方式本质都是把技能文件释放到项目里的.claude/skills目录区别只是入口不同。按你平时习惯选一种就行千万不要混用——混用容易出现双份技能白白占用宝贵的上下文。初始化时插件通常会问几个问题主要编程语言、常用测试框架、完成一个需求的默认流程。这个环节别跳过你的回答会被写进项目级配置之后 AI 会拿着这份“工地守则”开工。我见过有人一路回车跳过结果 AI 默认用 Python 的 pytest 给他测一个 Java 项目闹出不少笑话。2.3 初始化完成后的快速验证装完别急着开工先做一个 5 分钟的冒烟测试。随便建一个空目录初始化 git然后让 AI 做一件事“帮我在这个目录里规划一个带测试的计算器模块先写计划不要直接码代码。”没有技能库时AI 大概率立刻开始创建文件技能库生效时你会看到它先加载 writing-plans 技能输出一份计划文档再按计划一步步来。更直接的验证是查技能文件是否落地ls -la .claude/skills/正常情况下你会看到一堆以技能名命名的目录比如 tdd、systematic-debugging、writing-plans、code-review 等。看到这些目录说明安装这步成功了如果目录是空的多半是插件与 CLI 版本不匹配去核对一下版本再重装。2.4 一个容易忽略的权限细节技能里的很多步骤需要 AI 实际执行命令比如跑测试、查文件、提交代码。因此要让技能库存完整发挥作用需要给助手放行相应的工具权限。如果你习惯全程自动确认那没问题如果用逐条确认模式建议至少把当前项目目录和常用命令mvn、npm、git加入白名单否则每次跑技能都要手动点好几下确认体验很割裂也会打断技能的连续性。权限这块还有一个隐蔽的坑有些项目里 AI 根本没有 bash 权限它就会尝试用伪代码“假装”跑测试。你看到的结果是它汇报“测试通过”实际上什么都没执行。所以冒烟测试时我要求 AI 必须粘贴真实的测试日志而不是让它口头总结。3. 核心技能包拆解与实战3.1 TDD 技能红灯、绿灯、重构一步都不能跳TDD 技能是整套技能库里含金量最高的一个对 AI 行为方式的改观也最明显。加载之后AI 面对一个功能需求不再是“开始写实现代码”而是先做三件事读需求、列出验收条件、把验收条件转成测试用例。然后按红灯—绿灯—重构的节奏推进先写一个注定失败的测试运行并确认它是红的再写最小实现让它变绿最后在绿灯保护下重构。为什么红灯确认对 AI 尤其重要因为模型有“一步到位”的倾向总觉得实现写完顺便补两个测试就叫测试驱动。结果不但测试质量差而且一旦实现有问题你根本说不清是代码错还是测试错。红灯验证这个动作相当于给 AI 上了一道保险测试在写实现之前已经证明了它的“杀伤力”之后的修改都在安全网里进行它敢放手重构。实操里我会专门要求 AI 把每次mvn test或npm test的输出原样粘贴回来而不是让它一句“测试全部通过”带过。看到真实的测试日志你才能确认它真的执行了而不是靠脑补。这一步劳烦一点但长期省下的返工时间远超这点成本。3.2 系统性调试先证明病因再动手修调试技能解决的是 AI 最让人头疼的毛病瞎猜。你丢给它一个报错它经常不看堆栈、不看上下文直接基于“我见过类似的问题”给一个看似合理的修复。运气好一次中运气不好改完引入新问题来回折腾一整天。挂了调试技能后AI 会被要求按固定动作来第一步复现问题通常是用一个失败的测试把 bug 钉死在测试台上第二步完整读错误信息和堆栈而不是只看第一行第三步定位根因而不是表面现象区分“是空指针本身”还是“是数据流上游传了 null”第四步带着理解去修修完跑测试确认第五步扫一遍是否有同类问题最后一步提交时写下根因而不是只写“修复 bug”。一个很典型的 Java 例子Service 层报 NullPointerException没有技能的 AI 可能直接在方法入口加一个if (xxx null) return;。加了调试技能之后它会先去看这个 null 是从哪一层传来的很可能发现是 Controller 层把前端空值透传进来最终修复点落在参数校验上。差别就在这前者把症状盖住后者把病灶挖掉。这两者在一个真实项目里的结局天差地别前者会在下一个接口里再次爆炸。3.3 Java 实例一次完整的技能驱动开发回合我拿一个真实的练习项目演示完整流程。需求很简单订单金额 商品单价 × 数量 × 折扣折扣按档位给满 100 打 9 折满 500 打 8 折其余不打折。先让 AI 用 writing-plans 技能出计划它会列出定义 Order 类、写参数化测试、实现折扣计算、跑 Maven 回归。然后进入 TDD 流程第一批测试长这样class OrderTest { Test void should_apply_no_discount_below_100() { Order order new Order(3, 30.0); // 数量3单价30 assertEquals(90.0, order.total(), 0.001); } Test void should_apply_10_percent_discount_above_100() { Order order new Order(10, 15.0); // 150元 assertEquals(135.0, order.total(), 0.001); } }先跑一次让它确认红灯——此时 Order 类可能还没建编译错误也算一次有效的红灯。然后 AI 实现 Order 类再跑测试确认绿灯mvn test输出里出现Tests run: 2, Failures: 0的时候这个回合才算结束。整个过程我没有手动写一行代码AI 按技能流程把需求拆解、测试先行、实现、回归全部走完。你会明显感觉到它从“给一段代码”变成了“交付一个被验证过的结果”。如果一开始没有技能库同样需求它大概率直接甩给你一个 Order 类加一个 main 方法让你自己去验证。两种结果的工程价值差距不需要我多说。3.4 代码审查与重构让 AI 在交付前当一次守门员写完功能不算完superpowers 里还有两个高频技能code-review 和 refactoring。code-review 技能会让 AI 在自己的 diff 上做一次正式审查重点盯错误处理、边界条件、命名、安全问题——比如拼接 SQL、日志里打敏感字段、重复代码。我在项目里经常把它当“合并前最后一道闸门”实测能拦住不少低级问题尤其是异常被静默吞掉和边界值漏判这两类。refactoring 技能则强调“行为不变”任何重构都必须有测试兜底并且分小步进行每步保持绿灯。这个技能和 TDD 技能配合极好适合对大方法、坏味道代码做整理。别指望它能像人一样做出大规模架构级重构但清理一个 200 行的 God Method 绰绰有余。我建议每个迭代结束前专门抽出一个会话把这两个技能串起来跑一遍成本很低收益却很实在。4. 自定义技能把团队的最佳实践喂给 AI4.1 技能到底长什么样一次 SKILL.md 的解剖如果你来自建技能会发现流程其实很轻。技能就是一个目录目录名就是技能名里面必须有且只有一个 SKILL.md。文件头部是 YAML frontmatter至少要写 name 和 descriptiondescription 里最好带上触发关键词方便 AI 判断什么时候加载这个技能正文则是给 AI 看的操作守则通常用“必须/禁止”句型加编号步骤来写。我见过很多自定义技能写得不好的例子通病是 description 写得太泛比如“帮我写好代码”。AI 拿到这种描述根本不知道什么时候该触发。正确的写法要具体“当项目需要执行发布流程时使用涵盖构建、测试、打包、生成 changelog 四步。”越具体AI 越容易在恰当的时机把它调出来。4.2 手写一个发布检查技能举一个真实可抄的例子。我给前端团队写过 release-checklist 技能目录结构是这样.claude/skills/release-checklist/SKILL.md文件内容如下--- name: release-checklist description: 在 npm 包发布前执行。触发词发布、publish、release、npm version。 --- # 发布检查清单 1. 运行 npm test 并确认全部通过。 2. 运行 npm run build确认产物无错误。 3. 检查 package.json 的 version 字段符合语义化版本规则。 4. 检查 CHANGELOG.md 是否有本次变更记录。 5. 以上任一步失败禁止继续下一步。把这个文件放到项目里之后对 AI 说“准备发布”它就会把这几条当硬性规定执行。团队成员有新的发布要求直接改这一个文件就行——技能库本质上已经变成了团队的“流程仓库”。比起在群里发一份没人看的规范文档这样一个能被 AI 强制执行的文件管用得多。4.3 给 Codex 用户的特别通道技能转 AGENTS.mdCodex CLI 读的是 AGENTS.md而不是 Claude 的 skills 目录。但技能本质是 Markdown完全可以手动合并。我通常用一个简单的 shell 命令把项目里所有技能文件合成一份 AGENTS.mdfor f in .claude/skills/*/SKILL.md; do echo $(basename $(dirname $f)) cat $f echo done AGENTS.md生成之后Codex 读取仓库上下文时就会看到全部技能。这个方案的缺点是所有技能常驻上下文token 占用偏高优点是零依赖、直接生效。项目小完全够用项目大建议只挑两三个核心技能合并进去其余临时按需写。用这个方案把 TDD 技能转给 Codex 之后我实测它在 Java 项目上行为改善很明显至少会先想着跑测试了。5. 常见问题与排查技巧实录5.1 技能装了AI 却“假装没看见”多数情况不是 bug而是触发条件没匹配上。技能库的加载依赖 description 与当前任务的语义匹配如果 AI 没主动加载最直接的办法是显式点名“用 systematic-debugging 技能处理这个报错。”另外检查一下项目根目录的 SUPER.md 或等效配置是否还生效——我有一次改了技能目录的路径配置还指在旧位置AI 每次都想加载但找不到文件表现就是“技能不生效”。还有一种隐蔽情况旧会话里还残留着未加载技能的上下文缓存新装的技能需要新开一个会话才生效。所以装完技能第一件事是重开会话别在旧会话里干等。5.2 多技能打架上下文里全是方法论技能之间偶尔会抢话说一个任务同时触发 TDD 和 code-reviewAI 会把两份流程叠在一起显得非常啰嗦。缓解办法有两个一个是给 description 增加更严格的触发词另一个是在提问时就限定“只用 TDD 技能其他技能不要加载”。更根本的调整是养成“一个会话只做一件事”的习惯任务混杂时技能加载策略会变得不可预测。你想让 AI 又写功能又做审查又重构最后往往什么事情都做得不彻底。5.3 Java 项目特有的几个坑Java 用户多踩的坑也多。我整理成一张速查表现象原因处理mvn test 找不到测试测试类没放在 src/test/java或类名没以 Test 结尾检查目录结构按 Maven 约定放测试JUnit 依赖解析失败项目没配置 surefire 或缺少测试依赖在 pom.xml 加入 JUnit Jupiter 依赖技能要求跑测试但 AI 不跑工具权限没放开 bash 或 mvn在编码助手配置里放行当前项目目录Lombok 报错影响测试编译注解处理器和测试编译期冲突确认 pom 里 lombok 版本或临时避开 Lombok 用法这里我要强调一下第一行。Maven 的测试发现规则是*Test.java结尾的类并且放在src/test/java下。AI 有时会把测试写在src/main/java里编译能过但mvn test一个都不跑整轮 TDD 等于白做。所以技能流程里一定要有“跑一次测试确认用例数大于零”的检查点。5.4 token 焦虑技能太多会挤爆上下文技能文件本身占 token全部常驻的话大项目里很容易触发上下文超限AI 开始“忘记”早前内容。我的经验是默认只保留三到五个核心技能其余技能按需放进临时目录任务结束就清理别让.claude/skills变成垃圾场。自定义技能也要定期合并重复项一个团队有十来个技能已经很多了超过这个数AI 的选择成本会急剧上升。另外一个减轻压力的技巧是尽量精简每个 SKILL.md 的正文。一个技能的核心价值在于“关键步骤”和“强制要求”只要把这两块写清楚就行不要长篇大论解释原理。原理是给人看的AI 只需要知道做什么和禁止做什么。6. 两个月用下来我最想说的几点6.1 上限靠模型下限靠流程踩过几次坑之后我现在的用法很简单保留 writing-plans、tdd、systematic-debugging、code-review 四个核心技能Java 项目再加一个测试习惯配置。最大的体会是这套东西的上限由模型决定下限由流程兜住。模型不够强的时候技能流程照样会出错但它至少错得可追溯——你能清楚看到它是在哪一步开始跑偏的而不是面对一团神秘代码无从下手。这种可追溯性在写正式项目时比什么都重要。6.2 给新用户的最低配置建议最后分享一个小技巧不要一上来就把官方技能全装上。技能越多选择越乱也越耗 token。先装两三个用一周让 AI 的新行为方式适应你的项目再逐步扩展。你不需要让 AI 学会一百种技能先让它把三件事做扎实——写计划、先测试、再验证。这三件事做好了它给你带来的效率提升绝对超过你多装几十个花哨技能的实际收益。技能库这种东西少而精才能变成真正的 superpowers。
第一次在 GitHub 趋势榜上刷到“superpowers”这个名字我以为是哪个中二程序员给项目起的网红名。直到我把它装进 Claude Code让 AI 带着整套 TDD 流程、系统性调试步骤和代码审查清单去独立完成一个 Java 重构任务才发现这个名字背后是实打实的野心——它不是在给编码助手加功能而是在给 AI“上规矩”。简单说superpowers 是一套面向命令行编码智能体的“职业技能培训库”把老师傅们写代码、排故障、做审查时的套路整理成结构化技能文档让 Claude Code、Codex 这类工具不再凭感觉回答而是先定方案、再动手、最后验证。如果你已经受够了 AI“什么都会写、但写出来永远不牢靠”的状态这篇实操记录应该能帮上忙。我会从安装、初始化、核心技能拆解、自定义技能再到真实项目中的排查经验把全流程完整写出来。1. Superpowers 是什么从“智能问答”到“职业素养”1.1 为什么模型越来越聪明项目里却越来越心累现在的编程模型写单点功能真的很强让它写一个排序函数、一个 REST 接口、一段正则表达式基本秒出。可一旦让它完成一个“需要流程支撑”的任务比如“给这个模块补上测试”“帮我排查线上偶发报错”“把这个历史代码安全重构”它就开始飘——最常见的表现是跳过测试直接写实现、改一个 bug 顺手改了三处无关代码、或者重构到一半自己把接口改崩了。问题的根源不是模型不够聪明而是它缺少“工程章法”。人类程序员靠公司规范、Code Review、单元测试这些流程兜底而裸奔的 AI 只有直觉没有流程。一位三年经验的工程师不会在没写测试的情况下说“改完了”但大模型会。superpowers 的思路就是把“流程”本身做成可装载的资产。它不是提示词模板也不是 IDE 插件而是一套由若干“技能”组成的方法论库。每个技能都是一份结构化的操作手册AI 按需加载后严格按手册里的步骤执行而不是自由发挥。1.2 “技能”这套设计到底解决什么问题技能这个词听起来玄实际落地很朴素。打开一个技能目录核心文件 SKILL.md 用 Markdown 写成开头一段 YAML 描述它的名称、适用场景、触发条件正文就是分步骤的执行流程和守则。比如 TDD 技能会告诉 AI先写失败测试跑一遍确认红灯再写最小实现看到绿灯后重构最后全量回归。调试技能则要求 AI先复现、再缩小范围、读完整错误栈、找到根因后带着目的修、最后补回归测试。这个过程和我们常见的“手写一大段 prompt 让它这么做”有什么本质区别区别在于体系化与复用。手写 prompt 是一次性的换个项目、换个会话就没了而技能库是一次安装、全局生效且技能之间能互相调用——AI 可以先加载“写计划”技能把需求拆成步骤再加载 TDD 技能逐条实现遇到问题自动切入“系统性调试”技能。这种组合出来的行为已经接近一个受过训练的中级工程师的做事次序。我见过太多人把希望寄托在“换一个更强的模型”上却忽略了就算换了个聪明人进来没有流程约束他照样能把项目搞乱。1.3 它在工具链里的位置不是替代模型而是替代提示词很多人问superpowers 是替代 Claude Code 还是替代 Codex它哪个都不替代。它站在编码助手之上把“怎么干活”这件事标准化。当前社区里最常见的是把它作为 Claude Code 的技能库来安装但技能本身是纯文本 Markdown只要你的工具能读入这些说明它就能生效。Codex 同样可以用后面第四章我会专门讲怎么把技能搬运给 Codex。为了直观对比我把三种用法的差异放在一张表里用法行为表现可维护性结果稳定性裸聊问一句答一段答对答错全靠模型当天状态无很低手写复杂 prompt能约束方向但每会话都要贴换任务就失效弱中等技能库按需加载标准流程步骤可追溯、可更新强高受底层模型上限约束个人体感最明显的是“结果稳定性”这一列。裸聊模式下同一个需求让 AI 写十次测试它可能只有两三次真的走测试驱动挂上技能库后只要是它判断匹配的场景基本每次都会走完整流程。这个“稳定”比单次惊艳重要得多——因为项目工程化的本质就是让高质量的行为可以重复出现。2. 安装与初始化让编码助手真正“长本事”2.1 前置环境十几分钟能准备好的清单别急着装先确认基础环境避免装到一半发现版本对不上。打开终端逐个跑一遍node -v # 建议 18 以上新版本要求 20 claude --version codex --version git --version如果你的主要战场是 Java额外确认 JDK 和构建工具java -version mvn -v # 或者 gradle -v注意技能库本身不挑语言但如果你主要在 Java 项目上使用JDK 17 Maven 3.8 以上是比较省心的组合。JDK 太老会导致 JUnit 5 跑不起来到时候你会分不清是技能的锅还是环境的锅。这里有个容易忽略的点技能库不是独立运行的程序它依附于编码助手。所以前置环境的核心不是 Node 版本多新而是 Claude Code 或 Codex 本身已经能正常干活。我的习惯是先让助手在项目里完成一次最简单的“读取文件并总结”确认链路通了再装技能省得后面排查问题时分不清是装坏了还是本来就没配好。2.2 安装方式选一种别混着来社区里主流的装法有两种我都试过。第一种是直接在 Claude Code 里装插件/plugin install superpowerslatest装完它会新增一组斜杠命令用来初始化技能、查看技能列表、管理项目级配置。第二种是走 npm 全局安装再在项目目录里执行初始化npm install -g superpowers superpowers install两种方式本质都是把技能文件释放到项目里的.claude/skills目录区别只是入口不同。按你平时习惯选一种就行千万不要混用——混用容易出现双份技能白白占用宝贵的上下文。初始化时插件通常会问几个问题主要编程语言、常用测试框架、完成一个需求的默认流程。这个环节别跳过你的回答会被写进项目级配置之后 AI 会拿着这份“工地守则”开工。我见过有人一路回车跳过结果 AI 默认用 Python 的 pytest 给他测一个 Java 项目闹出不少笑话。2.3 初始化完成后的快速验证装完别急着开工先做一个 5 分钟的冒烟测试。随便建一个空目录初始化 git然后让 AI 做一件事“帮我在这个目录里规划一个带测试的计算器模块先写计划不要直接码代码。”没有技能库时AI 大概率立刻开始创建文件技能库生效时你会看到它先加载 writing-plans 技能输出一份计划文档再按计划一步步来。更直接的验证是查技能文件是否落地ls -la .claude/skills/正常情况下你会看到一堆以技能名命名的目录比如 tdd、systematic-debugging、writing-plans、code-review 等。看到这些目录说明安装这步成功了如果目录是空的多半是插件与 CLI 版本不匹配去核对一下版本再重装。2.4 一个容易忽略的权限细节技能里的很多步骤需要 AI 实际执行命令比如跑测试、查文件、提交代码。因此要让技能库存完整发挥作用需要给助手放行相应的工具权限。如果你习惯全程自动确认那没问题如果用逐条确认模式建议至少把当前项目目录和常用命令mvn、npm、git加入白名单否则每次跑技能都要手动点好几下确认体验很割裂也会打断技能的连续性。权限这块还有一个隐蔽的坑有些项目里 AI 根本没有 bash 权限它就会尝试用伪代码“假装”跑测试。你看到的结果是它汇报“测试通过”实际上什么都没执行。所以冒烟测试时我要求 AI 必须粘贴真实的测试日志而不是让它口头总结。3. 核心技能包拆解与实战3.1 TDD 技能红灯、绿灯、重构一步都不能跳TDD 技能是整套技能库里含金量最高的一个对 AI 行为方式的改观也最明显。加载之后AI 面对一个功能需求不再是“开始写实现代码”而是先做三件事读需求、列出验收条件、把验收条件转成测试用例。然后按红灯—绿灯—重构的节奏推进先写一个注定失败的测试运行并确认它是红的再写最小实现让它变绿最后在绿灯保护下重构。为什么红灯确认对 AI 尤其重要因为模型有“一步到位”的倾向总觉得实现写完顺便补两个测试就叫测试驱动。结果不但测试质量差而且一旦实现有问题你根本说不清是代码错还是测试错。红灯验证这个动作相当于给 AI 上了一道保险测试在写实现之前已经证明了它的“杀伤力”之后的修改都在安全网里进行它敢放手重构。实操里我会专门要求 AI 把每次mvn test或npm test的输出原样粘贴回来而不是让它一句“测试全部通过”带过。看到真实的测试日志你才能确认它真的执行了而不是靠脑补。这一步劳烦一点但长期省下的返工时间远超这点成本。3.2 系统性调试先证明病因再动手修调试技能解决的是 AI 最让人头疼的毛病瞎猜。你丢给它一个报错它经常不看堆栈、不看上下文直接基于“我见过类似的问题”给一个看似合理的修复。运气好一次中运气不好改完引入新问题来回折腾一整天。挂了调试技能后AI 会被要求按固定动作来第一步复现问题通常是用一个失败的测试把 bug 钉死在测试台上第二步完整读错误信息和堆栈而不是只看第一行第三步定位根因而不是表面现象区分“是空指针本身”还是“是数据流上游传了 null”第四步带着理解去修修完跑测试确认第五步扫一遍是否有同类问题最后一步提交时写下根因而不是只写“修复 bug”。一个很典型的 Java 例子Service 层报 NullPointerException没有技能的 AI 可能直接在方法入口加一个if (xxx null) return;。加了调试技能之后它会先去看这个 null 是从哪一层传来的很可能发现是 Controller 层把前端空值透传进来最终修复点落在参数校验上。差别就在这前者把症状盖住后者把病灶挖掉。这两者在一个真实项目里的结局天差地别前者会在下一个接口里再次爆炸。3.3 Java 实例一次完整的技能驱动开发回合我拿一个真实的练习项目演示完整流程。需求很简单订单金额 商品单价 × 数量 × 折扣折扣按档位给满 100 打 9 折满 500 打 8 折其余不打折。先让 AI 用 writing-plans 技能出计划它会列出定义 Order 类、写参数化测试、实现折扣计算、跑 Maven 回归。然后进入 TDD 流程第一批测试长这样class OrderTest { Test void should_apply_no_discount_below_100() { Order order new Order(3, 30.0); // 数量3单价30 assertEquals(90.0, order.total(), 0.001); } Test void should_apply_10_percent_discount_above_100() { Order order new Order(10, 15.0); // 150元 assertEquals(135.0, order.total(), 0.001); } }先跑一次让它确认红灯——此时 Order 类可能还没建编译错误也算一次有效的红灯。然后 AI 实现 Order 类再跑测试确认绿灯mvn test输出里出现Tests run: 2, Failures: 0的时候这个回合才算结束。整个过程我没有手动写一行代码AI 按技能流程把需求拆解、测试先行、实现、回归全部走完。你会明显感觉到它从“给一段代码”变成了“交付一个被验证过的结果”。如果一开始没有技能库同样需求它大概率直接甩给你一个 Order 类加一个 main 方法让你自己去验证。两种结果的工程价值差距不需要我多说。3.4 代码审查与重构让 AI 在交付前当一次守门员写完功能不算完superpowers 里还有两个高频技能code-review 和 refactoring。code-review 技能会让 AI 在自己的 diff 上做一次正式审查重点盯错误处理、边界条件、命名、安全问题——比如拼接 SQL、日志里打敏感字段、重复代码。我在项目里经常把它当“合并前最后一道闸门”实测能拦住不少低级问题尤其是异常被静默吞掉和边界值漏判这两类。refactoring 技能则强调“行为不变”任何重构都必须有测试兜底并且分小步进行每步保持绿灯。这个技能和 TDD 技能配合极好适合对大方法、坏味道代码做整理。别指望它能像人一样做出大规模架构级重构但清理一个 200 行的 God Method 绰绰有余。我建议每个迭代结束前专门抽出一个会话把这两个技能串起来跑一遍成本很低收益却很实在。4. 自定义技能把团队的最佳实践喂给 AI4.1 技能到底长什么样一次 SKILL.md 的解剖如果你来自建技能会发现流程其实很轻。技能就是一个目录目录名就是技能名里面必须有且只有一个 SKILL.md。文件头部是 YAML frontmatter至少要写 name 和 descriptiondescription 里最好带上触发关键词方便 AI 判断什么时候加载这个技能正文则是给 AI 看的操作守则通常用“必须/禁止”句型加编号步骤来写。我见过很多自定义技能写得不好的例子通病是 description 写得太泛比如“帮我写好代码”。AI 拿到这种描述根本不知道什么时候该触发。正确的写法要具体“当项目需要执行发布流程时使用涵盖构建、测试、打包、生成 changelog 四步。”越具体AI 越容易在恰当的时机把它调出来。4.2 手写一个发布检查技能举一个真实可抄的例子。我给前端团队写过 release-checklist 技能目录结构是这样.claude/skills/release-checklist/SKILL.md文件内容如下--- name: release-checklist description: 在 npm 包发布前执行。触发词发布、publish、release、npm version。 --- # 发布检查清单 1. 运行 npm test 并确认全部通过。 2. 运行 npm run build确认产物无错误。 3. 检查 package.json 的 version 字段符合语义化版本规则。 4. 检查 CHANGELOG.md 是否有本次变更记录。 5. 以上任一步失败禁止继续下一步。把这个文件放到项目里之后对 AI 说“准备发布”它就会把这几条当硬性规定执行。团队成员有新的发布要求直接改这一个文件就行——技能库本质上已经变成了团队的“流程仓库”。比起在群里发一份没人看的规范文档这样一个能被 AI 强制执行的文件管用得多。4.3 给 Codex 用户的特别通道技能转 AGENTS.mdCodex CLI 读的是 AGENTS.md而不是 Claude 的 skills 目录。但技能本质是 Markdown完全可以手动合并。我通常用一个简单的 shell 命令把项目里所有技能文件合成一份 AGENTS.mdfor f in .claude/skills/*/SKILL.md; do echo $(basename $(dirname $f)) cat $f echo done AGENTS.md生成之后Codex 读取仓库上下文时就会看到全部技能。这个方案的缺点是所有技能常驻上下文token 占用偏高优点是零依赖、直接生效。项目小完全够用项目大建议只挑两三个核心技能合并进去其余临时按需写。用这个方案把 TDD 技能转给 Codex 之后我实测它在 Java 项目上行为改善很明显至少会先想着跑测试了。5. 常见问题与排查技巧实录5.1 技能装了AI 却“假装没看见”多数情况不是 bug而是触发条件没匹配上。技能库的加载依赖 description 与当前任务的语义匹配如果 AI 没主动加载最直接的办法是显式点名“用 systematic-debugging 技能处理这个报错。”另外检查一下项目根目录的 SUPER.md 或等效配置是否还生效——我有一次改了技能目录的路径配置还指在旧位置AI 每次都想加载但找不到文件表现就是“技能不生效”。还有一种隐蔽情况旧会话里还残留着未加载技能的上下文缓存新装的技能需要新开一个会话才生效。所以装完技能第一件事是重开会话别在旧会话里干等。5.2 多技能打架上下文里全是方法论技能之间偶尔会抢话说一个任务同时触发 TDD 和 code-reviewAI 会把两份流程叠在一起显得非常啰嗦。缓解办法有两个一个是给 description 增加更严格的触发词另一个是在提问时就限定“只用 TDD 技能其他技能不要加载”。更根本的调整是养成“一个会话只做一件事”的习惯任务混杂时技能加载策略会变得不可预测。你想让 AI 又写功能又做审查又重构最后往往什么事情都做得不彻底。5.3 Java 项目特有的几个坑Java 用户多踩的坑也多。我整理成一张速查表现象原因处理mvn test 找不到测试测试类没放在 src/test/java或类名没以 Test 结尾检查目录结构按 Maven 约定放测试JUnit 依赖解析失败项目没配置 surefire 或缺少测试依赖在 pom.xml 加入 JUnit Jupiter 依赖技能要求跑测试但 AI 不跑工具权限没放开 bash 或 mvn在编码助手配置里放行当前项目目录Lombok 报错影响测试编译注解处理器和测试编译期冲突确认 pom 里 lombok 版本或临时避开 Lombok 用法这里我要强调一下第一行。Maven 的测试发现规则是*Test.java结尾的类并且放在src/test/java下。AI 有时会把测试写在src/main/java里编译能过但mvn test一个都不跑整轮 TDD 等于白做。所以技能流程里一定要有“跑一次测试确认用例数大于零”的检查点。5.4 token 焦虑技能太多会挤爆上下文技能文件本身占 token全部常驻的话大项目里很容易触发上下文超限AI 开始“忘记”早前内容。我的经验是默认只保留三到五个核心技能其余技能按需放进临时目录任务结束就清理别让.claude/skills变成垃圾场。自定义技能也要定期合并重复项一个团队有十来个技能已经很多了超过这个数AI 的选择成本会急剧上升。另外一个减轻压力的技巧是尽量精简每个 SKILL.md 的正文。一个技能的核心价值在于“关键步骤”和“强制要求”只要把这两块写清楚就行不要长篇大论解释原理。原理是给人看的AI 只需要知道做什么和禁止做什么。6. 两个月用下来我最想说的几点6.1 上限靠模型下限靠流程踩过几次坑之后我现在的用法很简单保留 writing-plans、tdd、systematic-debugging、code-review 四个核心技能Java 项目再加一个测试习惯配置。最大的体会是这套东西的上限由模型决定下限由流程兜住。模型不够强的时候技能流程照样会出错但它至少错得可追溯——你能清楚看到它是在哪一步开始跑偏的而不是面对一团神秘代码无从下手。这种可追溯性在写正式项目时比什么都重要。6.2 给新用户的最低配置建议最后分享一个小技巧不要一上来就把官方技能全装上。技能越多选择越乱也越耗 token。先装两三个用一周让 AI 的新行为方式适应你的项目再逐步扩展。你不需要让 AI 学会一百种技能先让它把三件事做扎实——写计划、先测试、再验证。这三件事做好了它给你带来的效率提升绝对超过你多装几十个花哨技能的实际收益。技能库这种东西少而精才能变成真正的 superpowers。
