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 常见问题速查表

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 这个名字，说到底只是个代号，真正重要的是它背后那套把工程方法论技能化的思路——这套思路，你自己也能攒出来。