1. 从“能跑就行”到“跑得放心”：AI编程的可靠性拐点
用Claude Code写代码这件事，我身边不少朋友已经玩了大半年。刚开始大家的兴奋点都差不多——一句话生成一个组件、三分钟搭出一个接口、十分钟撸完一个爬虫脚本。那种“快”确实上头，感觉像是给键盘装上了涡轮增压。但用久了你会发现一个很尴尬的现象：AI写出来的代码，第一次跑通率其实不低，可一旦进入真实项目、多人协作、长期维护的场景，翻车率就直线上升。变量命名前后不一致、边界条件漏判、错误处理全靠try-catch糊一层、测试用例写得像走过场，这些问题在“玩具项目”里看不出来，到了生产环境就是一颗颗定时炸弹。
Superpowers这套东西，就是冲着这个痛点来的。它不是又一个“让AI写得更快”的工具，而是一套让AI写得更可靠的方法论和技能体系。核心思路很朴素：把资深工程师在真实项目里反复验证过的工作习惯，拆解成一个个可复用、可组合、可审查的Skill，然后让AI在编码过程中主动调用这些Skill，而不是凭感觉自由发挥。你可以把它理解成给AI编程助手配了一本“团队内部编码规范手册”，而且这本手册是活的、可执行的、能自动触发的。
这篇文章适合三类人看。第一类是已经在用Claude Code、Codex这类AI编程工具，但总觉得产出质量不稳定的开发者；第二类是团队里负责代码审查、被AI生成代码搞得头大的Tech Lead；第三类是对Skill机制好奇，想知道怎么把个人经验沉淀成可复用资产的技术人。我会从设计思路、核心机制、实操配置、常见坑四个维度，把Superpowers这套东西拆开揉碎讲清楚，尽量让你看完就能上手，而不是停留在“听起来很厉害”的层面。
2. Superpowers到底解决了什么问题：拆解AI编程的四个可靠性缺口
2.1 缺口一：AI没有“项目记忆”，每次都在重新发明轮子
你肯定遇到过这种情况：同一个项目里，你昨天刚让AI用axios封装了一个请求工具，今天再让它写一个新接口，它转头就用了fetch。你纠正它，它道歉，说“好的我记住了”，然后下一个文件又忘了。这不是AI笨，而是它的工作方式决定的——每次对话本质上是一次独立的推理过程，它没有持久的项目上下文，除非你每次都把规范塞进提示词里。
Superpowers的解法是把项目规范从“提示词”变成“Skill”。Skill是一段结构化的指令，包含触发条件、执行步骤、检查清单和输出格式。当AI识别到当前任务匹配某个Skill的触发条件时，会自动加载并执行。比如你定义一个“API请求封装Skill”，规定所有网络请求必须走统一的request方法、必须带超时和重试、必须统一错误码处理。之后AI每次写相关代码，都会先查这个Skill，而不是自由发挥。这就把“靠记忆”变成了“靠制度”。
2.2 缺口二：代码审查流于形式，AI自己审自己等于没审
很多团队现在的流程是：AI生成代码，人扫一眼，觉得差不多就合并了。问题是人也会疲劳，尤其是面对AI生成的大段代码，看着结构挺完整、注释也挺全，就容易放松警惕。而AI自己审查自己的代码，基本等于让学生自己批改试卷——它倾向于认为自己的解法是对的。
Superpowers里有一套代码审查Skill，核心设计是“角色分离”。它不让生成代码的那个AI实例去审查，而是启动一个独立的审查流程，带着明确的检查清单去逐项核对：命名是否一致、边界条件是否覆盖、错误处理是否完整、是否有硬编码的魔法数字、测试是否覆盖了异常路径。审查结果会以结构化报告的形式输出，每条问题都带严重等级和修改建议。我实测下来，这套机制能抓出不少“看起来没问题”的隐患，尤其是边界条件和并发场景下的问题。
2.3 缺口三：Skill散落各处，没有统一的管理和复用机制
你可能已经在用一些零散的提示词模板，存在备忘录里、Notion里、或者某个prompt.md文件里。用的时候复制粘贴，改改就能用。但这种方式有几个致命问题：版本混乱、无法组合、不能自动触发、团队共享靠口口相传。时间一长，你自己都忘了哪个版本是最新的。
Superpowers提供了一套Skill的组织规范，包括目录结构、元数据格式、依赖声明和版本管理。每个Skill是一个独立目录，里面有SKILL.md描述文件、可选的脚本文件、测试用例和变更日志。Skill之间可以声明依赖关系，比如“数据库迁移Skill”依赖“SQL规范Skill”。这套规范让Skill从“个人笔记”升级成了“团队资产”，可以纳入版本控制、可以Code Review、可以持续迭代。
2.4 缺口四：AI编程的“黑盒感”让人不放心
用AI写代码最让人不安的地方在于：你不知道它为什么这么写。它给你一段能跑的代码，但背后的决策逻辑是隐藏的。这在简单场景下无所谓，但在涉及安全、性能、数据一致性的场景下，这种黑盒感是致命的。
Superpowers通过强制AI输出决策依据来缓解这个问题。在执行关键Skill时，AI需要先输出一段“决策说明”，解释为什么选择这个方案、考虑了哪些替代方案、有哪些已知限制。这段说明会作为代码注释或独立的决策记录保存下来。这样一来，后来的人看代码时，不仅知道“写了什么”，还知道“为什么这么写”。这个习惯一旦养成，代码的可维护性会有质的提升。
3. Skill机制深度解析：从触发到执行的完整链路
3.1 Skill的触发条件设计：什么时候该自动加载
Skill的触发机制是整个体系的核心。设计得不好，要么该触发的时候不触发，要么不该触发的时候乱触发，反而干扰正常工作流。Superpowers的触发条件通常包含三个维度：文件类型匹配、任务关键词匹配、上下文状态匹配。
文件类型匹配最好理解，比如“React组件Skill”只在处理.tsx或.jsx文件时触发。任务关键词匹配稍微复杂一点，需要定义一组触发词和排除词。比如“性能优化Skill”的触发词可能包括“优化”“慢”“性能”“卡顿”，排除词包括“优化注释”“优化命名”这种明显不相关的场景。上下文状态匹配是最微妙的，它依赖AI对当前对话历史的理解，比如“如果用户之前提到过这个项目用了TypeScript严格模式，那么类型定义Skill应该自动激活”。
我自己的经验是，触发条件宁窄勿宽。一开始可以只设置最明确的触发条件，用一段时间后根据实际漏触发的情况逐步放宽。反过来，如果一开始设得太宽，AI频繁加载不相关的Skill，会拖慢响应速度，也会让输出变得啰嗦。
3.2 Skill的执行流程：从加载到输出的五个阶段
一个完整的Skill执行流程通常包含五个阶段，我拿“代码审查Skill”举例说明。
第一阶段是上下文收集。AI会先读取当前文件、相关依赖文件、最近的Git提交记录，以及项目里已有的审查报告。这一步的目的是建立足够的上下文，避免“盲人摸象”式的审查。
第二阶段是检查清单加载。每个Skill都有一份结构化的检查清单，比如代码审查Skill的清单可能包含：命名规范、错误处理、边界条件、并发安全、日志记录、测试覆盖、文档更新等大类，每个大类下面还有具体的检查项。
第三阶段是逐项执行与标记。AI按照清单逐项检查，对每个检查项给出“通过”“警告”“失败”三种标记之一，并附上具体的代码位置和说明。这一步是耗时最长的，但也是最关键的。
第四阶段是结果汇总与分级。所有检查项完成后，AI会按照严重等级对问题进行分类：阻断性问题（必须修复才能合并）、重要问题（建议修复）、次要问题（可以后续处理）。这个分级机制让团队可以根据实际情况决定修复优先级。
第五阶段是输出结构化报告。最终输出一份Markdown格式的报告，包含问题列表、代码片段、修改建议和整体评价。这份报告可以直接贴到PR评论里，也可以存档作为质量记录。
3.3 Skill的组合与依赖：怎么让多个Skill协同工作
单个Skill的能力是有限的，真正强大的是Skill之间的组合。Superpowers支持两种组合方式：串行依赖和并行协作。
串行依赖是指Skill A执行完后，自动触发Skill B。比如“新功能开发Skill”执行完后，自动触发“代码审查Skill”和“测试生成Skill”。这种组合适合有明确先后顺序的场景。
并行协作是指多个Skill同时作用于同一个任务，各自从不同角度给出建议，最后由一个“仲裁Skill”汇总。比如“性能优化Skill”和“可读性优化Skill”可能给出冲突的建议——性能优化建议把循环展开，可读性优化建议保持循环结构。仲裁Skill会根据项目当前的优先级配置来决定采纳哪个建议。
这里有个坑要注意：Skill之间的依赖关系不能形成环。A依赖B，B依赖C，C又依赖A，这种循环依赖会导致无限递归。Superpowers在加载Skill时会做依赖检查，发现环就报错。设计Skill的时候要特别注意这一点。
3.4 Skill的版本管理与团队协作
Skill一旦成为团队资产，版本管理就变得很重要。Superpowers建议每个Skill都遵循语义化版本规范：主版本号变更表示不兼容的修改，次版本号变更表示新增功能，修订号变更表示问题修复。
团队协作方面，Skill可以放在项目的.superpowers/skills/目录下，纳入Git管理。每个Skill的变更都走正常的PR流程，需要至少一个人Review才能合并。这样做的好处是，Skill的演进过程有记录可查，出了问题也能追溯到具体是哪次变更引入的。
我还见过一种做法，是把Skill分成“基础层”和“项目层”。基础层是跨项目通用的Skill，比如“Git提交规范Skill”“代码审查Skill”，放在一个独立的仓库里，通过子模块或包管理工具引入。项目层是项目特有的Skill，比如“业务领域模型Skill”“特定API封装Skill”，放在项目仓库里。这种分层方式让通用能力可以复用，项目特有逻辑又不会污染通用层。
4. 实操配置：从零搭建一套可用的Superpowers环境
4.1 环境准备与基础安装
先说一下基础环境。Claude Code目前支持macOS、Linux和Windows（通过WSL）。我自己的主力环境是macOS，Ubuntu上也跑过一段时间，体验基本一致。安装Claude Code本身不复杂，官方文档写得很清楚，这里不赘述。重点说一下Superpowers的接入方式。
Superpowers本身不是一个独立的可执行程序，而是一套Skill集合和配套的加载机制。它的接入方式取决于你用的AI编程工具。如果是Claude Code，通常是通过配置文件指定Skill目录，然后在项目根目录放一个.superpowers文件夹。如果是VS Code配合Claude Code插件，配置方式类似，但需要在VS Code的设置里额外指定Skill的搜索路径。
我建议的目录结构是这样的：
project-root/ ├── .superpowers/ │ ├── skills/ │ │ ├── code-review/ │ │ │ ├── SKILL.md │ │ │ ├── checklist.md │ │ │ └── examples/ │ │ ├── test-generation/ │ │ │ ├── SKILL.md │ │ │ └── templates/ │ │ └── api-design/ │ │ ├── SKILL.md │ │ └── references/ │ └── config.yaml ├── src/ └── ...config.yaml里配置全局参数，比如默认的审查严格等级、是否启用自动触发、Skill的加载优先级等。这个文件不要提交到Git，因为每个人的本地偏好可能不同。可以提交一个config.example.yaml作为模板。
4.2 编写第一个Skill：从“代码审查”开始
我建议第一个Skill从代码审查开始写，因为它的价值最直观，而且写起来相对简单。一个最小的代码审查Skill包含以下几个部分：
元数据区：定义Skill名称、版本、作者、触发条件、依赖项。触发条件用YAML格式写，支持文件类型、关键词、上下文状态三种匹配方式。
检查清单区：用Markdown列表写清楚要检查哪些项。每项包含检查内容、严重等级、参考示例。严重等级分三级：blocker、major、minor。
执行指令区：用自然语言描述AI应该怎么执行这个Skill。包括先读什么文件、按什么顺序检查、遇到问题怎么记录、最后怎么输出报告。
输出模板区：定义最终报告的结构。通常包含：审查范围、问题统计、详细问题列表、整体评价、建议下一步动作。
我贴一个简化版的示例，你可以直接拿去改：
--- name: code-review version: 1.0.0 trigger: file_types: [".ts", ".tsx", ".js", ".jsx", ".py", ".go"] keywords: ["review", "审查", "检查", "PR"] exclude_keywords: ["review comment", "注释审查"] dependencies: - naming-convention - error-handling --- ## 检查清单 ### 阻断性问题 - [ ] 是否存在未处理的Promise rejection - [ ] 是否存在SQL注入风险（字符串拼接SQL） - [ ] 是否存在硬编码的密钥或密码 ### 重要问题 - [ ] 错误处理是否完整（非空判断、异常捕获） - [ ] 边界条件是否覆盖（空数组、零值、最大值） - [ ] 命名是否一致且有意义 ### 次要问题 - [ ] 是否有可以提取的重复代码 - [ ] 注释是否准确且必要 - [ ] 日志级别是否合理 ## 执行指令 1. 读取当前文件及其直接依赖文件 2. 按检查清单逐项检查，记录问题位置和严重等级 3. 对每个问题给出具体的修改建议 4. 汇总输出报告，按严重等级排序 ## 输出模板 ### 审查报告 **审查范围**：{文件列表} **问题统计**：阻断性 {n} 个，重要 {n} 个，次要 {n} 个 #### 阻断性问题 {逐条列出，包含文件、行号、问题描述、修改建议} #### 重要问题 {同上} #### 次要问题 {同上} **整体评价**：{一句话总结} **建议下一步**：{具体动作}写完这个Skill后，你可以手动触发一次，看看输出是否符合预期。如果不符合，调整检查清单或执行指令，直到满意为止。这个过程可能需要迭代两三次，很正常。
4.3 配置自动触发与优先级
Skill写好后，下一步是配置自动触发。在config.yaml里，你可以为每个Skill设置触发优先级。优先级高的Skill会先加载，优先级低的在后。如果两个Skill的触发条件冲突，优先级高的胜出。
skills: code-review: enabled: true priority: 10 auto_trigger: true test-generation: enabled: true priority: 8 auto_trigger: true api-design: enabled: true priority: 5 auto_trigger: falseauto_trigger: false表示这个Skill不会自动触发，只能手动调用。适合那些执行成本高、或者只在特定场景下才需要的Skill。
优先级的设计有个经验法则：越靠近“质量底线”的Skill，优先级越高。代码审查、安全检查、测试生成这类Skill应该高优先级，因为它们直接关系到代码能不能合并。而代码风格、注释优化这类Skill可以低优先级，甚至设为手动触发。
4.4 与现有工作流的集成
Superpowers不是要取代你现有的工作流，而是要嵌入进去。我自己的做法是在Git hooks里加一道检查：提交前自动运行代码审查Skill，如果发现阻断性问题就阻止提交。这样就把质量把关提前到了提交阶段，而不是等到PR Review。
具体实现方式是在.git/hooks/pre-commit里加一段脚本，调用Claude Code执行审查Skill，根据返回结果决定是否放行。这个脚本不需要很复杂，核心逻辑就是：调用审查、解析报告、检查是否有blocker级别的问题、有则退出码非零。
#!/bin/bash # pre-commit hook RESULT=$(claude-code run-skill code-review --file "$STAGED_FILES" --format json) BLOCKERS=$(echo "$RESULT" | jq '.issues | map(select(.severity == "blocker")) | length') if [ "$BLOCKERS" -gt 0 ]; then echo "发现 $BLOCKERS 个阻断性问题，请修复后再提交" echo "$RESULT" | jq '.issues | map(select(.severity == "blocker"))' exit 1 fi exit 0这个脚本我用了几个月，确实拦住了不少低级错误。但要注意，它会让提交变慢，因为每次提交都要跑一遍审查。如果团队觉得太慢，可以改成只在PR创建时运行，或者只对特定目录的文件运行。
5. 常见问题与排查技巧实录
5.1 Skill不触发怎么办
这是最常见的问题。你明明写了Skill，也配了触发条件，但AI就是不用。排查思路按以下顺序来：
先检查触发条件是否太窄。比如你设了file_types: [".tsx"]，但当前文件是.ts，那肯定不会触发。把条件放宽一点试试。
再检查Skill是否被正确加载。在Claude Code里执行一个诊断命令，看看当前加载了哪些Skill。如果列表里没有你的Skill，说明路径配置有问题，或者SKILL.md的格式有误。
然后检查优先级是否被覆盖。如果有另一个Skill的触发条件更具体、优先级更高，它可能会“抢走”触发机会。调整优先级或者细化触发条件可以解决。
最后检查上下文状态是否满足。有些Skill依赖特定的上下文，比如“如果用户之前提到过项目用了严格模式”。如果上下文不满足，Skill不会触发。这种情况下可以手动触发一次，看看输出是否正常。
5.2 Skill输出太啰嗦或太简略
输出长度不合适，通常是执行指令写得不够明确。如果你觉得输出太啰嗦，可以在指令里加一句“只输出问题列表，不要解释检查过程”。如果觉得太简略，可以要求“每个问题附上代码片段和修改示例”。
另一个调节手段是检查清单的粒度。清单项太粗，输出就会简略；清单项太细，输出就会啰嗦。我一般把清单控制在15到25项之间，这个粒度比较平衡。
5.3 多个Skill给出冲突建议
前面提到过，不同Skill可能给出冲突建议。比如性能优化Skill建议用缓存，可读性优化Skill建议去掉缓存让逻辑更清晰。这种冲突不一定是坏事，它反映了真实的工程权衡。
处理方式有两种。一种是设置仲裁规则，在config.yaml里定义当冲突发生时的优先级。比如“安全 > 性能 > 可读性 > 风格”。另一种是让AI输出权衡说明，把两种方案的利弊都列出来，由人来决定。我倾向于第二种，因为工程决策很多时候没有绝对的对错，取决于具体场景。
5.4 Skill执行太慢影响开发节奏
Skill执行慢通常是因为读取的文件太多或者检查项太细。优化方向包括：限制读取范围（只读当前文件和直接依赖）、缓存重复检查的结果、把非关键检查项设为手动触发。
还有一个技巧是分级执行。把检查清单分成“快速检查”和“深度检查”两组。快速检查在每次保存时运行，只查最关键的几项；深度检查在提交前运行，查全部项。这样既保证了日常开发的流畅性，又保证了提交质量。
5.5 团队协作中的Skill管理问题
团队用Skill最容易出的问题是版本不一致。张三更新了代码审查Skill，李四本地还是旧版本，导致同一份代码两个人审查结果不同。解决办法是把Skill纳入版本控制，并且强制同步。可以在项目启动脚本里加一步“检查Skill版本”，版本不一致就提示更新。
另一个问题是Skill的所有权不清晰。谁负责维护哪个Skill？出了问题找谁？建议每个Skill在元数据里指定一个Owner，Owner负责Review该Skill的变更请求。没有Owner的Skill要么指定一个，要么归档。
6. 我踩过的坑与实战心得
6.1 不要试图一次性把所有规范都写成Skill
我刚开始用Superpowers的时候，恨不得把团队所有的编码规范都写成Skill。结果写了二十多个Skill，配置复杂得要命，AI加载慢，输出也乱。后来砍到五个核心Skill，反而效果好很多。
经验是：先写最痛的那几个。哪个问题最常出现、最影响质量，就先写哪个。用一段时间后，再根据实际需要补充。Skill不是越多越好，而是越精越好。
6.2 检查清单要具体，不要写“代码要写得好”这种废话
我见过一些Skill的检查清单写得很抽象，比如“确保代码质量”“注意性能问题”。这种清单AI没法执行，因为“质量”和“性能”没有可操作的定义。
好的检查项应该是可验证的。比如“所有异步函数必须有错误处理”“循环体内不得有数据库查询”“公共方法必须有JSDoc注释”。这些项AI可以逐条核对，给出明确的通过或失败。
6.3 给Skill留出“例外通道”
再好的规范也有例外。如果Skill太死板，遇到合理例外时反而会阻碍开发。我的做法是在Skill里加一个“例外声明”机制：开发者可以在代码里加一行特殊注释，比如// superpowers-ignore: error-handling，表示这一处不适用错误处理规范。Skill执行时会跳过这一项，但在报告里标注“已声明例外”，提醒审查者注意。
这个机制的关键是例外必须显式声明，不能默默跳过。这样既保留了灵活性，又保证了透明度。
6.4 定期回顾Skill的有效性
Skill写完后不是一劳永逸的。项目在变，团队在变，Skill也需要跟着变。我一般每个月花半小时回顾一下：哪些Skill经常触发但没抓到什么问题？哪些Skill从来没触发过？哪些Skill的检查项已经过时了？
经常触发但没抓到问题的Skill，可能是检查项太宽泛，需要细化。从来没触发过的Skill，可能是触发条件有问题，或者这个Skill根本不需要。过时的检查项要及时删除，否则会让报告变得冗长且不可信。
6.5 不要完全依赖Skill，人的判断永远是最后一道关
Skill能抓出很多问题，但它不是万能的。有些问题需要业务理解、有些问题需要架构视角、有些问题需要权衡取舍，这些都不是Skill能完全覆盖的。我的做法是把Skill定位成“第一道过滤器”，它负责抓出明显的、机械性的问题，让人可以把精力集中在真正需要判断的地方。
说到底，Superpowers这套东西的价值不在于让AI“更聪明”，而在于让AI“更守规矩”。它把资深工程师的工作习惯固化下来，让AI在规矩的框架内发挥能力。这个思路我觉得是对的——AI的能力上限很高，但它的下限也很低。Skill的作用就是抬高下限，让AI的产出稳定在一个可接受的水平之上。至于上限，那还是得靠人。
