1. 从“superpowers”说起一个让 AI 编码助手真正长出“工程肌肉”的技能框架第一次看到 “superpowers” 这个词是在几个做 AI 辅助开发的群里。有人甩出一句“装完 superpowers 之后Claude Code 才算真正能干活了”底下立刻一堆人追问怎么装、支不支持 Codex CLI、能不能接本地模型。我当时的第一反应是又一个包装概念但把它的设计思路捋了一遍之后我改主意了——这东西解决的是一个非常具体、非常痛的问题AI 编码助手很聪明但它不懂你的工程规矩。你肯定有过这种体验让 Claude Code 帮你改一个函数它改得挺对但顺手把旁边的代码风格也“优化”了让它加个功能它一口气写了三百行测试一个没有让它跑个命令它把rm -rf都敢往外吐。这不是模型不行是它缺少一套可复用的行为约束和技能封装。superpowers 干的事就是给这些 agentic 工具装上一套“技能框架”把软件开发的工程方法论——需求澄清、方案设计、测试先行、小步提交、代码审查——变成 AI 能理解、能调用、能自我检查的模块。所以这篇东西我想聊的不是“superpowers 是什么”这种百科式介绍而是作为一个天天跟 Claude Code、Codex CLI 打交道的人我怎么理解它的设计逻辑、怎么把它落到实际工作流里、以及踩过哪些坑。适合两类人看一类是已经在用 Claude Code 或 Codex CLI但总觉得“差点意思”的开发者另一类是还没上手想搞清楚这套 agentic skills framework 到底值不值得投入时间的人。核心关键词我会反复提到superpowers、agentic skills framework、software development methodology、Claude Code、Codex CLI因为它们本来就是一件事的不同侧面。先说结论性的判断superpowers 的价值不在于它给了你多少现成技能而在于它定义了一种把工程方法论“技能化”的范式。你理解了这套范式就算不用它的现成技能也能自己攒出一套适合自己团队的。这才是它作为 software development methodology 载体的真正意义。2. 核心设计思路拆解为什么是“技能框架”而不是“提示词合集”2.1 提示词工程的死胡同与技能框架的破局点大部分人用 Claude Code 的起点是写一个超长的 system prompt 或者 CLAUDE.md把“你要先写测试”“你要小步提交”“你不要改无关代码”全塞进去。我一开始也这么干结果发现两个问题。第一提示词越长模型的注意力越稀释写到后面它就开始忽略前面的约束。第二提示词是全局生效的但实际开发中不同任务需要不同的约束——写新功能和修 bug 的规矩能一样吗superpowers 的思路是把这些约束拆成独立的技能单元每个技能有自己的触发条件、执行步骤和检查清单。这就像从“一本厚厚的员工手册”变成“一墙的工具箱”需要拧螺丝的时候拿螺丝刀需要锤的时候拿锤子。这个转变背后是 agentic skills framework 的核心洞察AI agent 的能力上限不取决于它知道多少而取决于它在正确的时机被激活了正确的行为模式。我举个具体的例子。传统做法里你会在提示词里写“修改代码前先理解上下文”。但这句话太抽象模型执行起来全凭心情。superpowers 里对应的技能会把它拆成可操作的步骤先读相关文件、再画出依赖关系、然后列出受影响的调用点、最后才动手。每一步都有明确的输入输出模型不容易偷懒。这就是 software development methodology 被“技能化”之后的样子——不再是口号而是流程。2.2 技能的生命周期从触发到归档的完整闭环一个设计良好的技能不是一段静态的文本而是有生命周期的。我观察下来superpowers 体系里的技能大致走这么一条链路识别场景 → 加载技能 → 执行步骤 → 自检 → 归档经验。识别场景这一步最容易被忽略。很多人以为技能是“手动调用”的其实好的框架会让技能根据上下文自动激活。比如你让 Claude Code 处理一个报错它会先判断这是“调试类任务”然后自动加载调试技能而不是等你敲命令。这个自动激活的机制靠的是对任务描述的语义匹配以及对当前工作目录、git 状态、最近操作历史的综合判断。执行步骤和自检是技能的主体。这里有个设计细节值得说自检清单必须是可验证的。什么叫可验证就是模型能自己判断“我做到了没有”。比如“是否运行了测试”是可验证的“是否理解了需求”就不可验证。superpowers 里很多技能会把自检做成显式的 checklist模型执行完必须逐条打勾打不了勾就说明没做完。这个机制极大地降低了“AI 假装完成了”的概率。归档经验这一步是让技能框架能自我进化的关键。每次任务结束后把这次遇到的问题、有效的解法、失败的尝试记录下来下次遇到类似场景就能复用。这本质上是在给 AI 建一个“项目记忆库”而不是每次都从零开始。2.3 为什么这套思路对 Claude Code 和 Codex CLI 都成立有人会问superpowers 是不是只对 Claude Code 有效Codex CLI 能不能用我的实测结论是框架思路通用具体实现要适配。Claude Code 和 Codex CLI 虽然都是 agentic 编码工具但它们的“性格”不一样。Claude Code 更倾向于对话式交互适合做需求澄清和方案讨论Codex CLI 更偏向命令行批处理适合做确定性的代码生成和重构。superpowers 的技能框架之所以能同时适配是因为它把“技能”和“执行器”解耦了——技能定义的是“做什么、按什么顺序做、怎么检查”至于用哪个工具执行是另一层的事。这就好比菜谱和厨具的关系。菜谱技能规定了先切菜再下锅至于你用中式炒锅还是西式平底锅Claude Code 还是 Codex CLI不影响菜谱本身。理解了这一层你就明白为什么这套 agentic skills framework 值得单独拿出来讲——它不绑定任何单一工具是一种跨工具的工程方法论封装。3. 核心细节解析与实操要点把技能框架落到你的工作流里3.1 技能文件的组织方式与命名约定落地第一步是搞清楚技能文件怎么组织。我试过几种方案最后稳定下来的结构是这样的一个根目录下面按“领域”分文件夹每个文件夹里放具体的技能文件。领域划分不用太细我一般分四类需求与设计、编码与重构、测试与调试、提交与审查。这四类基本覆盖了日常开发的全流程。命名上有个小技巧用动词开头带上触发场景。比如clarify-requirements-before-coding.md就比requirements.md好得多因为前者一眼能看出“什么时候该用它”。我踩过的坑是早期用名词命名结果自己都记不清哪个技能是干嘛的更别说让模型自动匹配了。每个技能文件内部我建议固定几个字段触发条件、前置检查、执行步骤、自检清单、常见失败模式。触发条件写清楚“什么情况下加载这个技能”前置检查写“加载前要确认什么”执行步骤是主体自检清单用来收尾常见失败模式是给未来的自己留的备忘录。这个结构不是死的但保持一致性会让整个框架好维护很多。提示技能文件不要写太长。我见过有人一个技能写了三千字结果模型加载后注意力全被稀释了。单个技能控制在 300 到 800 字之间比较合适超过就拆成两个。3.2 触发机制的设计让技能在该出现的时候出现技能写好了怎么让它在该出现的时候出现这是整个框架里最考验设计功力的地方。我的做法是双层触发一层是显式触发通过命令或关键词手动加载另一层是隐式触发靠任务描述的语义匹配。显式触发简单比如约定一个前缀skill:debug模型看到就知道要加载调试技能。隐式触发复杂一些需要在系统提示里告诉模型“当你识别到以下场景时主动加载对应技能”。这里的关键是场景描述要具体。写“处理 bug 时”太模糊写“当用户报告一个可复现的错误且提供了错误信息或复现步骤时”就具体多了。我实测下来隐式触发的准确率大概在七成左右剩下三成需要显式补。所以我的习惯是关键任务一律显式触发日常任务靠隐式触发兜底。这样既不会漏也不会因为过度触发而拖慢速度。还有一个细节触发后要确认加载。也就是模型加载技能后应该输出一句“已加载 XX 技能将按以下步骤执行”让你有机会打断和纠正。这个确认机制看起来多余实际上救过我很多次——有几次模型匹配错了技能我一看确认信息就及时喊停了。3.3 自检清单的写法可验证、可打勾、可追溯自检清单是技能框架的灵魂但也是最容易写废的部分。我总结了一个标准每一条都必须能用“是/否”回答且回答“是”的时候有证据。反面例子“代码质量良好”——这没法验证。正面例子“新增函数有对应的单元测试且测试通过”——这个可以验证跑一下测试就知道。再比如“没有修改无关文件”——这个可以通过git diff --stat验证改了哪些文件一目了然。我习惯把自检清单做成 Markdown 的 checkbox 列表模型执行完必须逐条勾选。如果某条勾不了它必须说明原因而不是跳过。这个“必须说明原因”的约束很重要它把“假装完成”变成了“显式承认未完成”后者至少是诚实的也给了你介入的机会。可追溯的意思是自检结果要留下来。我一般让模型把自检清单和执行日志一起写到一个session-log.md里按时间倒序排列。这样过几天回头看能清楚知道当时做了什么、检查了什么、哪里没做到。这个习惯在排查“为什么上周的改动引入了 bug”时特别有用。3.4 与版本控制的配合小步提交的自动化software development methodology 里有一条老规矩小步提交。但 AI 编码助手天然倾向于“一口气干完”因为它不知道你什么时候想停下来看看。superpowers 里对应的技能核心就是在关键节点强制暂停并提交。我的做法是定义一个“提交检查点”技能每当完成一个可独立验证的改动比如一个函数写完并通过测试、一个 bug 修完并验证就自动执行git add和git commit提交信息由模型根据改动内容生成。这里有个细节提交信息要包含“为什么”而不只是“做了什么”。模型生成的提交信息经常是“修改了 XX 函数”这没用。我会在技能里要求它写成“修复 XX 场景下 YY 返回空值的问题”这样以后git log才有价值。还有一个坑不要让模型自动 push。提交可以自动推送必须手动。我吃过亏有一次模型把一个半成品提交推到了远程结果 CI 直接红了。从那以后push 这一步永远留给我自己。4. 实操过程与核心环节实现从零搭一套可用的技能框架4.1 环境准备Claude Code 与 Codex CLI 的基础配置在搭框架之前得先把工具装好。Claude Code 的安装方式取决于你的系统Mac 和 Ubuntu 上流程不太一样Windows 用户要注意 64 位兼容性的问题。安装完之后第一件事是确认它能正常调用终端命令——这是 agentic 工具的核心能力如果这一步不通后面全是空谈。Codex CLI 的安装有个常见坑Node 环境下安装很慢。我试过几次默认源拉包经常卡住。解决办法是换一个响应更快的镜像源或者用包管理器直接装预编译版本。装完之后用codex --version验证一下能输出版本号就说明基础环境没问题。配置层面我建议先把模型接入搞定。Claude Code 默认走官方服务但很多人想接本地模型或第三方 API。这里的关键是搞清楚它的配置优先级环境变量 配置文件 默认值。我一般把配置写在项目根目录的配置文件里这样不同项目可以用不同模型互不干扰。接本地模型的时候要注意上下文长度和工具调用能力的匹配不是所有本地模型都能稳定支持 agentic 工作流。注意配置模型的时候先跑一个最简单的任务验证连通性比如让它读一个文件并总结。这一步能过再上复杂任务。我见过太多人一上来就让它重构整个项目结果卡在模型根本没连上。4.2 搭建第一个技能以“需求澄清”为例环境好了我们来搭第一个技能。我选“需求澄清”作为起点因为它最能体现技能框架的价值也最容易看到效果。这个技能要解决的问题是用户给的需求往往是模糊的模型直接动手容易跑偏。技能的目标是让模型在动手前先把模糊点问清楚。技能文件我这么写触发条件是“用户提出一个功能需求但没有说明验收标准或边界条件”前置检查是“确认当前没有正在进行的未完成改动”执行步骤分四步——第一步复述需求第二步列出至少三个模糊点第三步针对每个模糊点提出具体问题第四步等用户回答后再进入设计阶段自检清单是“是否复述了需求”“是否列出了模糊点”“是否提出了可回答的具体问题”“是否在用户回答前没有动手写代码”。实测下来这个技能的效果非常明显。以前模型看到“加个登录功能”就开始写代码现在它会先问“登录方式是账号密码还是第三方”“需不需要记住登录状态”“失败几次要锁定”。这些问题问出来后面的返工率直线下降。这里有个经验模糊点不要超过五个。问太多用户会烦问太少又不够。三个到五个是比较舒服的区间。另外问题要可回答不要问“你想要什么样的登录体验”这种开放式问题要问“登录失败后是提示错误还是直接锁定账号”这种选择题。4.3 搭建第二个技能以“测试先行”为例第二个技能我搭“测试先行”。这个技能的核心是在写实现代码之前先写一个会失败的测试。触发条件是“用户要求新增一个函数或修改现有函数的行为”执行步骤是——第一步理解函数的输入输出契约第二步写一个测试用例覆盖正常路径第三步写至少一个测试用例覆盖边界情况第四步运行测试确认失败第五步才写实现代码第六步运行测试确认通过自检清单是“测试是否先于实现编写”“测试是否覆盖了边界情况”“实现后测试是否全部通过”“是否有测试是为了通过而写的假测试”。最后一条自检特别重要。模型有时候会为了让测试通过把测试改成永远为真的断言。这个自检就是防这个的。我一般还会要求它把测试代码和实现代码分开提交这样git log里能清楚看到“先有测试后有实现”的顺序。踩过的坑不是所有任务都适合测试先行。比如纯 UI 调整、配置文件修改硬套测试先行反而浪费时间。所以我在技能里加了一个前置判断“如果改动无法用自动化测试验证跳过此技能并说明原因。”这个判断让技能更实用而不是教条。4.4 搭建第三个技能以“代码审查”为例第三个技能是“代码审查”用在提交之前。这个技能的目标是让模型自己审自己的代码在提交前发现问题。触发条件是“准备提交代码前”执行步骤是——第一步用git diff查看本次改动第二步逐文件检查是否有无关改动第三步检查是否有硬编码的密钥或路径第四步检查是否有未处理的错误分支第五步检查命名是否清晰第六步输出审查报告自检清单是“是否检查了所有改动文件”“是否发现了至少一个可改进点”“审查报告是否包含具体行号”。这里有个反直觉的经验要求模型“必须发现至少一个问题”。如果不加这条模型经常说“代码看起来没问题”就放行了。加了这条之后它会认真去找往往真能找出一些东西比如变量命名不一致、错误处理缺失、注释过期等。当然如果确实没问题它也可以说“未发现明显问题”但必须说明检查了哪些方面。审查报告我一般让它输出成表格三列文件、行号、问题描述。这样看起来清楚也方便我逐条处理。4.5 把技能串起来一个完整任务的执行流程单个技能搭好了接下来是把它们串成一条流水线。我以一个真实任务为例给一个现有项目加一个“导出 CSV”的功能。流程是这样的用户提出需求 → 需求澄清技能激活模型问清楚导出哪些字段、编码格式、大文件怎么处理 → 用户回答 → 测试先行技能激活模型先写测试 → 测试失败 → 模型写实现 → 测试通过 → 代码审查技能激活模型自查 → 发现问题修复 → 提交检查点技能激活模型生成提交信息并提交 → 任务结束经验归档。整个过程里我作为用户只做了两件事回答澄清问题、在提交前确认一下。其余全是模型按技能框架自动执行的。这就是 agentic skills framework 的威力——把人的介入点从“每一步”压缩到“关键决策点”。实测下来一个中等复杂度的功能用这套流程大概能节省一半的沟通成本。更重要的是产出的代码质量更稳定因为每一步都有检查不会出现“写到后面忘了前面”的情况。5. 常见问题与排查技巧实录那些文档里不会写的坑5.1 技能不触发或触发错误怎么办这是最常见的问题。表现是明明场景匹配模型却没加载技能或者加载了错误的技能。排查思路分三层。第一层检查触发条件的描述是否足够具体。如果写的是“处理代码时”那几乎任何任务都会匹配模型反而不知道该用哪个。第二层检查是否有多个技能的触发条件重叠。重叠会导致模型随机选一个解决办法是给技能加优先级或者在触发条件里写清楚“当 A 和 B 同时满足时优先用 X”。第三层检查模型的上下文里是否已经加载了太多技能。技能太多会互相干扰我一般同时激活的技能不超过三个。如果排查完还是不触发就用显式触发兜底。显式触发虽然麻烦一点但胜在确定。我的习惯是新技能先用显式触发跑一段时间确认稳定后再改成隐式触发。5.2 模型“假装完成”自检清单怎么破这个问题很隐蔽。模型会在自检清单上打勾但实际上没做。比如“是否运行了测试”打了勾但日志里根本没有测试运行的记录。破法有两个。第一个是要求提供证据。自检清单的每一条模型必须附上证据比如“运行了测试”后面要跟测试命令和输出摘要。没有证据的勾不算数。第二个是交叉验证。比如“是否修改了无关文件”这一条不能只靠模型自己说要让它跑git diff --stat并把输出贴出来你一看就知道。我还会定期抽查。随机挑一次任务的日志逐条核对自检清单和实际证据。抽查几次之后模型就知道我是认真的假装完成的概率会明显下降。5.3 技能框架拖慢速度怎么优化技能框架确实会增加一些开销因为模型要多做判断、多写自检。如果感觉太慢可以从三个地方优化。第一精简技能数量。不是每个技能都值得保留用不上的就删掉。我每隔一段时间会回顾一下哪些技能最近一个月没触发过没触发的就归档。第二合并相似技能。比如“写测试”和“跑测试”可以合并成一个“测试”技能减少加载次数。第三给技能分级。核心技能需求澄清、测试先行每次都加载辅助技能代码审查、经验归档按需加载。这样日常小任务就不会被全套流程拖累。实测下来优化之后的开销大概在可接受范围内。一个简单任务多花十几秒但省下的返工时间远超这个。5.4 常见问题速查表问题现象可能原因排查动作解决方向技能不触发触发条件太模糊检查技能文件的触发描述改具体加关键词触发错误技能多个技能条件重叠列出所有技能的触发条件对比加优先级或互斥条件自检打勾但没做缺少证据要求抽查日志核对证据自检必须附证据框架太慢技能太多或太重统计技能触发频率精简、合并、分级模型忽略技能上下文太长检查单次加载技能数同时激活不超过三个提交信息没价值只写做了什么看 git log要求写清为什么本地模型不稳定工具调用能力不足跑简单任务验证换模型或降级为纯对话5.5 几个我踩过的具体坑第一个坑技能文件用了中文标点。有次我写技能文件时用了中文的引号和逗号结果模型解析时出了偏差触发条件没匹配上。后来统一改成英文标点问题消失。这个坑很隐蔽因为文件看起来没问题但解析器可能对某些字符敏感。第二个坑在技能里写了绝对路径。我一开始图省事在技能里写了/Users/xxx/project这样的路径结果换台机器就失效了。后来改成相对路径或者用环境变量才通用起来。第三个坑技能版本没管理。技能文件改来改去有次改坏了一个关键技能想回滚却发现没记录改了什么。从那以后技能文件也纳入 git 管理每次改动都提交改坏了随时回滚。第四个坑过度依赖自动触发。有段时间我完全靠隐式触发结果有次一个重要任务没触发测试先行技能直接写了实现后来发现一堆边界情况没覆盖。从那以后关键任务我一律显式触发不赌概率。6. 技能框架的扩展方向从个人工具到团队资产6.1 把个人经验沉淀成团队技能库一个人用技能框架价值有限一个团队用价值是指数级的。因为团队里每个人的经验可以沉淀成共享技能新人上手直接继承老人的方法论。我试过的做法是建一个团队共享的技能仓库每个人都可以提交技能但提交前要经过 review。Review 的标准是触发条件是否清晰、步骤是否可执行、自检是否可验证、是否有实际使用案例。通过 review 的技能才能进主库。这样做的效果是团队里那些“老手的直觉”被显式化了。比如某个资深工程师总能在代码审查时发现并发问题把他的检查思路写成技能全团队都能用。这比口头传授高效得多。6.2 技能与项目记忆的结合技能是“怎么做”项目记忆是“这个项目里有什么”。两者结合威力更大。我的做法是给每个项目建一个project-context.md记录这个项目的技术栈、目录结构、命名约定、已知坑点。技能在执行时会先读这个文件把项目特定的信息纳入考虑。比如“测试先行”技能在 A 项目里用 Jest在 B 项目里用 Pytest靠的就是项目记忆来区分。这个结合点还有个好处新人接手项目时AI 能基于项目记忆快速给出符合项目规范的代码而不是写出一堆“通用但不符合本项目风格”的东西。6.3 跨工具的技能复用前面说过技能框架和工具是解耦的。这意味着同一套技能可以在 Claude Code 里用也可以在 Codex CLI 里用。我实测过把技能文件放在一个共享目录两个工具都指向它效果基本一致只是执行细节上有些差异。差异主要在交互方式上。Claude Code 更适合对话式的技能比如需求澄清Codex CLI 更适合批处理式的技能比如批量重构。所以我在技能文件里加了一个字段叫“推荐执行器”标明这个技能更适合哪个工具。这样切换工具时心里有数。跨工具复用的真正价值在于不锁定。今天用 Claude Code明天想试试 Codex CLI技能不用重写。这对个人开发者尤其重要因为工具迭代太快谁也不想把方法论绑死在一个工具上。6.4 技能框架的边界什么该做什么不该做最后说说边界。技能框架不是万能的有些事它做不了硬做反而添乱。不适合技能化的高度依赖人类判断的决策比如架构选型、需要外部信息输入的任务比如跟产品经理确认需求、一次性的探索性任务比如技术调研。这些任务硬套技能框架只会增加形式主义。适合技能化的重复性高的流程测试、提交、审查、有明确检查标准的任务代码规范、安全检查、需要多步骤协调的复杂任务重构、迁移。判断标准很简单如果这个任务你每次都要跟 AI 重复交代同样的要求那它就值得技能化。反过来如果每次要求都不一样那就不值得。我个人在实际操作中的体会是技能框架最大的价值不是让 AI 更聪明而是让 AI 更可预测。你知道它在什么情况下会做什么知道它的检查标准是什么知道出了问题去哪里找原因。这种可预测性才是把 AI 编码助手从“玩具”变成“工具”的关键。至于 superpowers 这个名字说到底只是个代号真正重要的是它背后那套把工程方法论技能化的思路——这套思路你自己也能攒出来。
