1. 为什么“能跑”和“可靠”之间隔着一整套工程习惯我最早用 Claude Code 写代码的时候心态跟大多数人一样能自动补全、能生成函数、能跑通测试就觉得已经赚到了。直到有一次我让它在同一个项目里连续改了三个文件结果它把上周刚修好的一个边界条件又改回去了而且没有任何提示。那一刻我才意识到AI 编程真正的问题从来不是“写得快不快”而是“改完之后你还敢不敢发版”。Superpowers 这套东西本质上就是在解决这个断层。它不是又一个代码补全插件也不是单纯的提示词合集而是一套把 AI 编程从“随机发挥”拉回到“有流程、有约束、有验收”的工程化框架。核心载体是 Skill——你可以把它理解成给 AI 装上的“操作手册 检查清单 角色设定”让它在特定任务里按照你定义的规则干活而不是每次靠运气。这篇文章适合三类人一是已经在用 Claude Code、Codex 这类工具但总觉得输出不稳定的开发者二是想把 AI 编程引入团队、但担心代码质量失控的技术负责人三是刚接触 Skill 概念、不知道从哪下手的新手。我会把 Superpowers 的定位、Skill 的引入方式、实际编码流程、常见坑和排查方法全部拆开讲尽量做到你看完就能在自己机器上复现。先说结论性的判断Superpowers 的价值不在于让 AI 写得更快而在于让 AI 写得更“可预期”。快是副产品可靠才是主产品。这个定位决定了它和普通提示词工程的区别——提示词是临场发挥Skill 是固化流程。2. Superpowers 到底是什么把提示词升级成可复用的工程资产2.1 从“一次性提示词”到“可版本管理的 Skill”大部分人用 AI 编程的方式是这样的打开对话框敲一段需求拿到代码复制粘贴跑一下不行再改提示词。这个过程里提示词是一次性的经验留在脑子里换个人、换个项目就归零。Superpowers 的思路完全不同。它把“怎么让 AI 干好某类活”这件事沉淀成一个个 Skill 文件。每个 Skill 通常包含几个部分触发条件什么时候用这个技能、角色设定AI 在这个任务里扮演谁、操作步骤按什么顺序做、约束规则什么不能做、验收标准怎么算做完。这些内容以结构化文本存在可以放进 Git 仓库可以 review可以迭代。我自己的项目里现在有十几个 Skill覆盖代码审查、单元测试生成、数据库迁移、API 设计、文档同步等场景。每次让 AI 干活之前先选对应的 Skill输出的稳定性比裸提示词高出一个量级。原因很简单裸提示词依赖你临场表达而 Skill 是你状态最好时写下来的规则每次都在替你兜底。2.2 Superpowers 和普通 Skill 插件的区别市面上叫 Skill 的东西不少Claude Code 本身也支持 Skill 机制Codex 有类似概念还有一些第三方插件市场。Superpowers 的差异点在于它的组织方式更偏向“工程流程”而不是“功能堆叠”。普通 Skill 插件往往是单点能力比如“帮你写 commit message”“帮你生成测试”。Superpowers 更像一套方法论它强调 Skill 之间的协作先有需求澄清 Skill再有方案设计 Skill然后是编码 Skill、审查 Skill、测试 Skill最后是文档 Skill。每个环节的输出是下一个环节的输入形成闭环。这个区别在实际使用中非常明显。单点 Skill 用多了会碎片化你还是得自己串流程Superpowers 式的组织方式让你一开始就按流水线走减少“AI 写完我忘了检查”的情况。2.3 为什么“可靠”比“快”更难做到AI 写代码快是天然优势但可靠是反直觉的。因为 AI 没有记忆连续性它不知道你上周为什么改了那行代码也不知道你们团队的命名规范是怎么演化的。它每次都在“重新理解”你的项目。Superpowers 通过 Skill 把项目上下文、团队约定、历史决策固化下来让 AI 每次开工前先读规则。这就像新员工入职先看 onboarding 文档而不是直接上手改代码。慢一点但错得少。我做过一个粗略统计在没有 Skill 约束的情况下AI 生成的代码大约有 30% 需要我手动调整逻辑引入 Skill 之后这个比例降到 10% 以下而且剩下的问题多是风格偏好不是逻辑错误。这个差距在长期项目里会被放大很多倍。3. 环境准备Claude Code 与 Skill 的安装配置3.1 Claude Code 的安装路径选择Claude Code 目前有几种使用形态命令行版、VS Code 扩展、桌面版。我的建议是主力用命令行版编辑器里用扩展做辅助。原因是命令行版对 Skill 的支持最完整执行终端命令、读写文件、调用外部工具都更顺。安装方式按平台分macOS / Linux官方推荐用包管理器或安装脚本装完之后claude --version能输出版本号就算成功。Windows建议在 WSL 里装原生 Windows 版本虽然能用但路径处理和权限模型容易出问题尤其是涉及文件批量操作时。VS Code 用户可以直接装 Claude Code 扩展然后在设置里配置 API 或订阅方式。注意如果你在公司网络里遇到订阅权限相关的提示先确认账号类型和网络策略不要盲目改配置很多问题其实是账号层面的。3.2 Skill 目录结构与引入方式Skill 的引入方式取决于你用的工具。Claude Code 一般会在项目根目录或用户目录下找特定文件夹比如.claude/skills/或类似的约定路径。每个 Skill 是一个独立文件或文件夹包含描述文件和具体规则。我习惯的项目结构是这样的project-root/ .claude/ skills/ code-review/ SKILL.md test-gen/ SKILL.md db-migration/ SKILL.md src/ tests/SKILL.md里写清楚这个技能的用途、触发词、执行步骤和约束。文件名和目录名尽量用英文短横线避免空格和特殊字符不然某些工具解析会出问题。引入之后你可以在对话里显式调用比如“用 code-review 技能检查这次改动”也可以配置成自动触发。我建议前期手动调用等你确认这个 Skill 的输出稳定了再考虑自动化。3.3 第三方模型接入的注意事项很多人会想把 Claude Code 接到本地模型或其他厂商的模型上比如通过 cc switch 这类工具切换后端。这条路能走通但有几个坑要提前知道。第一不同模型对 Skill 格式的理解能力差异很大。有些模型能严格按步骤执行有些会自由发挥把约束当建议。第二本地模型的上下文窗口和推理稳定性通常弱一些复杂 Skill 容易执行到一半跑偏。第三工具调用能力参差不齐涉及终端命令执行时尤其明显。我的做法是核心流程用官方模型跑实验性任务再用其他模型试。不要一上来就把所有 Skill 都迁到第三方后端否则排查问题时你分不清是 Skill 写得不好还是模型不给力。4. 核心 Skill 类型拆解哪些技能真正值得引入4.1 代码审查类 Skill把 review 标准固化下来代码审查是最值得做成 Skill 的场景之一。因为 review 的标准往往是隐性的老员工知道要看什么新人不知道。把它写进 SkillAI 就能按同一套标准检查。一个可用的 code-review Skill 通常包含这些检查项检查维度具体内容严重级别逻辑正确性边界条件、空值处理、异常分支高安全性输入校验、敏感信息泄露、权限判断高性能循环嵌套、重复查询、大对象拷贝中可维护性命名、函数长度、重复代码中风格一致性与项目现有代码风格是否一致低我自己的 review Skill 里还加了一条要求 AI 对每个问题给出“为什么这是问题”的解释而不是只列出来。这样我在判断是否采纳时更有依据也能顺便学习。实操心得review Skill 不要写得太长超过 500 行的规则 AI 会开始漏项。宁可拆成多个小 Skill比如“安全审查”“性能审查”分开。4.2 测试生成类 Skill让覆盖率真正有意义AI 生成测试很容易陷入一个陷阱生成一堆断言很弱的测试覆盖率数字好看但抓不到 bug。测试 Skill 的核心不是“生成测试”而是“生成有价值的测试”。我的 test-gen Skill 里有几条硬约束每个测试必须对应一个明确的失败场景禁止只断言“不抛异常”边界值必须覆盖mock 要说明为什么 mock。这几条加上之后生成的测试质量明显提升。具体执行时我会让 AI 先列出“这个函数可能出错的 5 种情况”再针对每种情况写测试。这个顺序很重要先想失败再写测试比先写测试再补断言有效得多。4.3 文档同步类 Skill解决“代码改了文档没改”文档滞后是团队通病。文档 Skill 的思路是每次代码改动后自动检查相关文档是否需要更新并给出修改建议。这个 Skill 的关键是建立代码和文档的映射关系。我一般会在 Skill 里维护一个简单的映射表比如某个模块对应哪个文档文件。AI 改完代码后按映射表去检查对应文档发现不一致就提示。实测下来这个 Skill 能拦住大概 70% 的文档滞后问题。剩下的 30% 是文档结构本身需要调整那种情况 AI 判断不了还是得人来。4.4 流程编排类 Skill把多个技能串起来单个 Skill 解决单点问题编排 Skill 解决流程问题。比如一个“功能开发”编排 Skill可以定义这样的顺序需求澄清 → 方案设计 → 编码 → 自测 → 审查 → 文档更新。每个环节调用对应的子 Skill。编排 Skill 的价值在于防止跳步。人容易在赶进度时跳过审查或测试编排 Skill 会强制走完流程。我现在的习惯是任何超过 50 行的改动都必须走编排流程小改动才允许直接改。5. 实操全流程从零跑通一个带 Skill 的编码任务5.1 任务定义与 Skill 选择假设我要给一个用户服务加“账号锁定”功能连续登录失败 5 次锁定 30 分钟。这个任务涉及数据库改动、业务逻辑、接口调整、测试和文档。我先选 Skill 组合db-migration加锁定字段、coding写业务逻辑、test-gen写测试、code-review审查、doc-sync更新文档。五个 Skill 按顺序执行。这里有个经验不要一次性把所有 Skill 都激活而是按阶段激活。因为 AI 同时处理太多规则会顾此失彼。我一般一次激活一到两个。5.2 数据库迁移 Skill 的执行记录第一步是加字段。我调用 db-migration Skill输入需求“users 表增加 failed_login_count 和 locked_until 两个字段”。Skill 的输出包括迁移脚本、回滚脚本、字段说明。我特别检查了回滚脚本因为很多 AI 生成的迁移只写正向不写反向出问题就麻烦了。生成的迁移大致是这样ALTER TABLE users ADD COLUMN failed_login_count INT NOT NULL DEFAULT 0, ADD COLUMN locked_until TIMESTAMP NULL; -- rollback ALTER TABLE users DROP COLUMN failed_login_count, DROP COLUMN locked_until;注意locked_until用 NULL 表示未锁定不要用 0 或空字符串语义会混乱。这个约定我写进了 Skill 的约束里AI 每次都会遵守。5.3 业务逻辑编码与自测第二步是写业务逻辑。coding Skill 里我定义了项目的分层规范controller 只做参数校验和转发service 放业务逻辑repository 管数据访问。AI 按这个结构生成代码不会把逻辑堆在 controller 里。核心逻辑是登录失败时累加计数达到阈值设置锁定时间登录成功时清零。AI 生成后我重点检查了三个地方并发情况下计数会不会丢、锁定时间判断用的是服务器时间还是数据库时间、锁定期间是否所有入口都被拦住。这三个点都是我踩过坑的地方所以写进了 Skill 的检查清单。AI 这次都处理对了省了我不少 review 时间。5.4 测试生成与审查闭环第三步用 test-gen 生成测试。我要求覆盖失败 1 到 4 次不锁定、第 5 次锁定、锁定期间登录被拒、锁定过期后恢复、成功登录清零计数。五个场景AI 生成了对应的测试用例。第四步用 code-review 审查。审查发现一个中等问题锁定判断逻辑在 service 和 middleware 里各写了一遍有重复。我让 AI 抽成一个公共方法重新审查通过。这个闭环很关键。如果没有 review Skill这个重复代码很可能就进主干库了后面改逻辑要改两处迟早出问题。5.5 文档同步与提交最后用 doc-sync 更新接口文档和数据库设计文档。AI 对比代码改动发现接口文档里没写锁定相关的错误码补上了数据库文档里字段说明也同步了。整个流程走下来从需求到可提交状态大概花了 40 分钟其中我人工介入的时间不到 15 分钟。对比没有 Skill 的时候同样的任务我要花一个多小时而且经常漏掉测试或文档。6. 常见问题与排查技巧实录6.1 Skill 不生效或输出不符合预期这是最常见的问题。排查顺序建议这样确认 Skill 文件路径和命名是否符合工具约定很多“不生效”其实是路径不对。检查 Skill 是否被正确加载有些工具需要重启或重新索引。看 Skill 内容是否太长或太模糊AI 抓不住重点。确认调用方式是显式调用还是自动触发自动触发条件是否满足。我遇到过一次Skill 写得好好的就是不生效最后发现是文件名里有个中文空格工具解析失败。这种问题很隐蔽建议文件名只用英文和短横线。6.2 AI 执行到一半跑偏长流程任务里AI 容易在中途忘记前面的约束。解决办法有两个一是把长流程拆成多个短 Skill每个只做一件事二是在 Skill 里加“阶段检查点”要求 AI 每完成一步就复述当前状态和下一步计划。我现在的编排 Skill 里都有检查点机制AI 每步结束会输出“已完成 X下一步 Y约束 Z”。这个习惯让跑偏率下降很多。6.3 多个 Skill 冲突当两个 Skill 的规则矛盾时AI 会随机选一个执行结果不可预期。比如一个 Skill 要求“函数不超过 20 行”另一个要求“所有逻辑内联不抽函数”这就冲突了。解决办法是建立 Skill 的优先级或者在编排 Skill 里明确哪个阶段用哪个 Skill。我一般会在项目根目录放一个 Skill 索引文件说明每个 Skill 的适用范围和优先级。6.4 第三方模型下 Skill 行为异常前面提过第三方模型对 Skill 的理解能力参差。如果发现 Skill 在某个模型下行为异常先做最小复现用一个最简单的 Skill 测试该模型是否能正确执行。如果简单 Skill 都不行那就是模型能力问题换模型如果简单 Skill 行、复杂 Skill 不行那就是 Skill 写得太复杂需要拆分。6.5 常见问题速查表现象可能原因排查动作Skill 完全不生效路径错误、未加载检查目录、重启工具输出部分符合Skill 太长、约束模糊拆分 Skill、明确规则中途跑偏流程太长、无检查点拆流程、加检查点多 Skill 冲突规则矛盾建优先级、分阶段第三方模型异常模型能力不足最小复现、换模型测试质量差约束太弱加失败场景要求避坑技巧每次改完 Skill用一个固定的小任务回归测试一遍。我管这叫“Skill 冒烟测试”能快速发现改动引入的问题。7. 把 Skill 用出复利团队协作与长期维护7.1 Skill 的版本管理Skill 是代码资产应该进 Git。我建议每个 Skill 独立提交commit message 写清楚改了什么规则、为什么改。这样出问题时能追溯也能看到规则的演化过程。团队里可以指定一个人负责 Skill 的维护但规则内容应该由实际使用的人提 PR。因为只有天天用的人才知道哪里不顺手。7.2 新人上手与知识传递Skill 对新人的价值特别大。新人入职第一天不用问“我们代码审查看什么”直接看 review Skill 就知道了。这比口头传授准确得多也不会因为老人忙就漏讲。我现在的做法是每个 Skill 文件开头写一段“这个技能解决什么问题、什么时候用”让新人能快速判断该不该用。7.3 持续迭代的判断标准Skill 不是写完就完了。判断一个 Skill 该不该改我一般看两个信号一是 AI 执行时频繁需要我纠正说明规则不清晰二是同类问题反复出现说明 Skill 缺了对应检查项。改 Skill 的原则是“小步快跑”一次只改一两条规则改完立刻验证。一次性大改容易引入新问题还不好定位。7.4 从个人使用到团队规范个人用 Skill 和团队用 Skill 是两回事。个人可以随意团队需要统一。团队推广时我建议先从一两个高频场景开始比如代码审查和测试生成跑顺了再扩展。一上来就搞十几个 Skill大家会抵触。另外团队 Skill 要有“退出机制”。某个 Skill 如果长期没人用或者维护成本高于收益就该删掉。Skill 库不是越大越好是越精越好。8. 我踩过的几个真实坑第一个坑是 Skill 写太细。我一开始把代码风格规则写了 200 多条结果 AI 执行时顾此失彼反而经常漏掉重要的。后来砍到 30 条核心规则效果反而更好。规则要抓大放小细节交给 linter。第二个坑是过度依赖自动触发。有段时间我配置了全自动 Skill 触发结果 AI 在不该审查的时候审查、不该生成测试的时候生成测试干扰很大。后来改回手动调用为主只在固定流程里自动触发。第三个坑是忽略 Skill 的维护成本。Skill 多了之后改一个项目约定要同步改好几个文件容易漏。现在我尽量把公共规则抽到一个基础 Skill 里其他 Skill 引用它减少重复。第四个坑是拿 Skill 当万能药。有些问题根本不是 Skill 能解决的比如需求本身不清楚、架构设计有缺陷。这种时候应该先解决上游问题而不是指望 Skill 让 AI 猜对。9. 关于 Skill 编码的一些补充观察热词里提到的“skill 编码 247”“skill 编码 193”这类说法我理解是指 Skill 的编号管理。当 Skill 数量多起来之后确实需要一套编号或命名规范不然找起来很痛苦。我的做法是按领域前缀加序号比如review-001、test-002一眼能看出用途和顺序。还有“book to skill”这个方向也很有意思就是把书里的方法论转成 Skill。比如把《重构》里的手法转成重构 Skill把《代码整洁之道》的规则转成风格 Skill。这个思路能大幅降低方法论的落地门槛值得试试。至于“去 AI 味的 Skill”我的理解是让 AI 生成的代码和文档更接近人类风格减少那种模板化的表达。这个需求真实存在但要注意别为了去 AI 味牺牲准确性。风格是次要的正确性是第一位的。最后说一句实在话Superpowers 这类框架的价值取决于你愿不愿意花时间把经验沉淀下来。它不会自动让你的 AI 编程变可靠它只是给了你一个把可靠变成可复用的容器。容器是空的还是满的取决于你自己往里装什么。我装了半年现在回头看最值钱的不是那些 Skill 文件本身而是写 Skill 过程中被迫想清楚的那些工程约定。