1. 从“superpowers”这个标题说起：它到底是什么
第一次看到“superpowers”这个词，很多人脑子里蹦出来的可能是超级英雄电影里的超能力。但在软件开发和技术社区里，这个词最近被赋予了全新的含义——它指的是一套面向编码智能体（coding agents）的能力框架，核心思路是把软件开发方法论拆解成可组合、可复用的技能模块，让AI编码助手不再只是一个“你问我答”的聊天工具，而是真正具备结构化工作流的能力体。
我最初接触这个概念的时候，正好在折腾几个自动化编码流程。当时最大的痛点就是：每次让AI帮我写代码，它总是“一口气吃成胖子”——要么直接甩出一大段没有经过验证的代码，要么在复杂任务面前东一榔头西一棒子，缺乏系统性的思考过程。而superpowers这套框架的出现，恰好击中了这个痛点。它本质上是一个agentic skills framework，翻译过来就是“智能体技能框架”，通过把软件开发中的各个环节——需求分析、方案设计、编码实现、测试验证、代码审查——拆解成独立的、可组合的技能单元，让编码智能体能够像人类工程师一样，按部就班地推进工作。
这套框架适合谁来了解？如果你是一名开发者，正在使用或者打算使用AI编码助手来提升日常开发效率，那这套东西值得你花时间研究。如果你是一个技术团队的负责人，正在思考如何把AI编码能力引入团队的开发流程，superpowers提供的这套方法论也能给你不少启发。甚至如果你只是一个对AI辅助开发感兴趣的爱好者，理解这套框架的设计思路，也能帮你更好地驾驭手头的AI工具。
我写这篇东西的目的很简单：把superpowers这套框架的核心逻辑、实操方法、以及我在实际使用中踩过的坑，原原本本地分享出来。网上关于它的资料比较零散，很多都是英文文档的直接翻译，读起来不够接地气。我会尽量用开发者之间交流的方式，把这件事讲清楚。
2. 核心设计思路拆解：为什么要把技能“拆开用”
2.1 传统AI编码助手的三个致命伤
在深入superpowers之前，有必要先聊聊为什么需要这样一套框架。我用过不少AI编码工具，从最早的代码补全插件到后来的对话式编程助手，总结下来，传统方式有三个绕不过去的问题。
第一个问题是上下文漂移。当你让AI帮你实现一个稍微复杂一点的功能时，对话轮次一多，它就开始“忘记”前面的约定。比如你一开始说了用TypeScript的严格模式，聊到第五轮的时候它给你写了个any类型；你要求所有API调用都要有错误处理，它写着写着就只写happy path了。这不是AI故意偷懒，而是它的注意力机制在长对话中会逐渐稀释早期信息。
第二个问题是缺乏验证闭环。大多数AI编码助手的工作模式是“你说需求，我给代码”，至于这段代码能不能跑通、边界情况处理得对不对、有没有引入新的bug，它是不负责的。你得自己复制粘贴、运行测试、发现问题再回去找它。这个来回的过程非常消耗时间。
第三个问题是方法论缺失。人类工程师在做一个功能时，会先理解需求、再设计方案、然后编码、最后测试。但AI助手往往跳过了前面的步骤，直接进入编码阶段。这就导致它写出来的东西可能技术上没问题，但架构上不合理，或者没有考虑到你项目里已有的约定和模式。
superpowers这套框架的设计初衷，就是针对这三个问题给出系统性的解决方案。它的核心思路可以用一句话概括：把软件开发的方法论编码成智能体可以执行的技能模块，让AI按照结构化的流程工作，而不是凭感觉发挥。
2.2 可组合技能（composable skills）到底是什么意思
“可组合技能”这个词听起来有点抽象，我用一个具体的类比来解释。你可以把superpowers想象成一个工具箱，里面有很多不同的工具——有锤子、有螺丝刀、有扳手。每个工具（也就是技能）只负责做好一件事。当你需要完成一个任务时，你不是拿一个万能工具去硬怼，而是根据任务的需要，选择合适的工具组合起来使用。
具体到软件开发场景，这些技能模块可能包括：
- 需求澄清技能：在开始编码之前，先通过提问的方式把模糊的需求变得具体。比如你说“帮我做一个用户登录功能”，这个技能会引导AI追问：登录方式是什么？邮箱还是手机号？要不要支持第三方登录？密码强度要求是什么？需不需要验证码？
- 方案设计技能：在需求明确之后，先输出一个技术方案，包括数据结构设计、接口定义、关键流程等，让你确认之后再进入编码阶段。
- 增量编码技能：把大功能拆成小步骤，每次只实现一小部分，实现完立刻验证，验证通过再继续下一步。
- 测试生成技能：针对刚写完的代码，自动生成单元测试和边界测试用例。
- 代码审查技能：从可读性、性能、安全性等维度审查代码，给出改进建议。
这些技能可以单独使用，也可以串联起来形成一个完整的工作流。比如你可以配置一个“新功能开发”工作流，让它依次执行：需求澄清→方案设计→增量编码→测试生成→代码审查。整个过程就像一条流水线，每个环节都有明确的输入和输出。
这种设计的好处在于，它把AI从一个“什么都懂一点但什么都不精”的通才，变成了一个“在特定环节非常专业”的专才。当AI知道自己当前只需要做好“需求澄清”这一件事时，它的表现会明显好于让它同时考虑需求、设计、编码、测试所有事情。
2.3 为什么这套框架值得关注
从行业趋势来看，AI辅助软件开发正在从“代码补全”向“智能体驱动”演进。早期的工具像GitHub Copilot，主要解决的是“写代码时少敲几个字”的问题。而现在的方向是让AI能够独立完成一个完整的开发任务，人类只需要在关键节点做决策和审核。
superpowers这套框架的价值在于，它提供了一种结构化的方法来管理AI的工作过程。没有这套框架，你用AI编码就像带一个聪明但没经验的实习生——你得时刻盯着，随时纠正。有了这套框架，你更像是在管理一个有一定自主性的初级工程师——你给他明确的任务和流程，他按部就班地完成，你在关键节点验收。
当然，这套框架也不是银弹。它需要你花时间配置和调优，需要你理解每个技能模块的适用场景，需要你在实践中不断调整工作流。但根据我的经验，前期投入的时间在后续的开发中会成倍地省回来。
3. 核心技能模块深度解析与实操要点
3.1 需求澄清技能：把“一句话需求”变成“可执行规格”
需求澄清是整个流程的起点，也是最容易被忽视的环节。我见过太多开发者（包括我自己早期）直接跳过这一步，上来就让AI写代码，结果写出来的东西跟预期差了十万八千里，返工的时间比一开始多花十倍。
superpowers的需求澄清技能，核心机制是结构化提问。当你给出一个初始需求后，这个技能会从几个维度自动生成追问：
- 功能边界：这个功能要做什么？不要做什么？和现有功能的边界在哪里？
- 输入输出：用户提供什么信息？系统返回什么结果？格式是什么？
- 异常情况：网络断了怎么办？输入非法数据怎么办？并发冲突怎么处理？
- 非功能需求：性能要求是什么？安全要求是什么？兼容性要求是什么？
我在实际使用中总结了一个小技巧：不要一次性回答所有问题。先回答最核心的功能边界问题，让AI生成一个初步的方案，然后再针对方案中的模糊点进行第二轮澄清。这样比一次性回答几十个问题效率高得多，因为很多问题在方案明确之后自然就有了答案。
注意：需求澄清阶段不要追求完美。目标是让需求“足够清晰可以开始编码”，而不是“穷尽所有可能性”。过度澄清会导致分析瘫痪，迟迟进入不了编码阶段。
3.2 方案设计技能：先画图纸再盖房子
方案设计技能的作用，是在编码之前先产出一个技术方案文档。这个文档不需要很正式，但必须包含几个关键要素：
- 数据结构：涉及哪些实体？它们之间的关系是什么？
- 接口定义：对外暴露哪些接口？输入输出是什么？
- 关键流程：核心业务逻辑的步骤是什么？
- 技术选型：用到哪些库或框架？为什么选它们？
我特别喜欢这个技能的一点是，它会强制AI在方案中标注假设和风险。比如“假设用户量在初期不超过1万，如果超过需要重新评估数据库选型”或者“这个方案依赖第三方API的可用性，如果对方服务不稳定需要增加降级逻辑”。这些标注在后续开发和运维中非常有用，能帮你提前识别潜在问题。
实操中，我通常会让AI生成两个方案：一个“最小可行方案”，用最简单的方式实现核心功能；一个“完整方案”，考虑更多的边界情况和扩展性。然后根据项目的实际阶段来选择。早期项目用最小方案快速验证，成熟项目用完整方案保证质量。
3.3 增量编码技能：小步快跑，每步验证
增量编码是superpowers框架中最核心的技能之一。它的工作方式是：把方案设计中的任务拆解成一系列小步骤，每个步骤只实现一个可独立验证的功能点。
举个例子，假设你要实现一个“用户注册”功能。传统的做法是让AI一次性写出注册页面、表单验证、API调用、数据库写入、邮件发送所有代码。而增量编码会把它拆成：
- 先实现数据模型和数据库迁移
- 再实现注册API的骨架（接收请求、返回成功）
- 然后加入表单验证逻辑
- 接着实现数据库写入
- 最后加入邮件发送
每一步完成后，都会运行测试或手动验证，确认这一步没问题再进入下一步。这样做的好处是，如果某一步出了问题，你能立刻定位到是哪个环节的代码有问题，而不是在一大堆代码里大海捞针。
我在使用这个技能时的一个心得是：每个步骤的粒度要适中。太粗了起不到隔离问题的效果，太细了会导致步骤过多、管理成本上升。我的经验是，每个步骤的代码量控制在50到200行之间比较合适，实现时间在5到15分钟左右。
提示：增量编码过程中，如果发现某一步的实现比预期复杂，不要硬着头皮继续。停下来，回到方案设计阶段重新评估。这比写了一大堆代码之后再返工要划算得多。
3.4 测试生成技能：让AI自己给自己出考题
测试生成技能会在代码写完之后，自动分析代码逻辑并生成测试用例。它生成的测试通常包括三类：
- 正常路径测试：输入合法数据，验证输出符合预期
- 边界测试：输入边界值（如空字符串、最大值、最小值），验证系统行为
- 异常测试：输入非法数据或模拟异常情况，验证错误处理逻辑
我对比过AI生成的测试和手写测试，发现AI在边界测试方面往往比人类更全面。人类写测试时容易有盲区，比如忘了测试空数组、忘了测试超长字符串、忘了测试并发场景。而AI会系统性地覆盖这些情况。
不过AI生成的测试也有一个常见问题：过度mock。它有时候会把所有依赖都mock掉，导致测试实际上没有验证任何真实逻辑。我在使用时会检查生成的测试，确保至少有一部分是集成测试，真正调用了数据库或外部服务。
3.5 代码审查技能：多一双眼睛看代码
代码审查技能会从多个维度分析代码质量：
| 审查维度 | 检查内容 | 常见问题 |
|---|---|---|
| 可读性 | 命名规范、注释质量、函数长度 | 变量名无意义、函数超过100行 |
| 性能 | 算法复杂度、数据库查询次数 | N+1查询、不必要的循环嵌套 |
| 安全性 | 输入验证、SQL注入、XSS | 直接拼接SQL、未转义用户输入 |
| 可维护性 | 耦合度、重复代码、扩展性 | 硬编码配置、复制粘贴的代码块 |
这个技能的输出不是简单的“通过/不通过”，而是一个分级的问题列表：严重问题必须修复，警告问题建议修复，提示问题可以考虑优化。我在实际使用中会把这个列表当作一个checklist，逐项确认后再提交代码。
4. 完整实操流程：从零搭建一个superpowers工作流
4.1 环境准备与基础配置
在开始搭建工作流之前，你需要准备以下环境：
- 一个支持自定义指令的AI编码助手（具体工具根据你的实际情况选择）
- 一个版本控制仓库（用于管理技能配置和工作流定义）
- 基本的命令行操作能力
配置的核心思路是：把每个技能模块定义为一个独立的配置文件，然后用一个主配置文件把它们串联起来。配置文件的内容包括技能的名称、描述、触发条件、执行步骤、以及与其他技能的依赖关系。
我建议从最简单的配置开始：先只配置“需求澄清”和“增量编码”两个技能，跑通一个完整的小功能开发流程，然后再逐步加入其他技能。一次性配置所有技能容易出错，而且你还没建立起对每个技能行为的直觉，很难判断配置是否正确。
4.2 一个完整的开发流程演示
让我用一个具体的例子来演示整个流程。假设我要开发一个“文章收藏”功能，允许用户把喜欢的文章加入收藏列表。
第一步：需求澄清
我输入初始需求：“帮我实现文章收藏功能”。需求澄清技能开始提问：
- 收藏功能需要用户登录吗？→ 需要
- 收藏列表需要分页吗？→ 需要，每页20条
- 用户可以取消收藏吗？→ 可以
- 需要记录收藏时间吗？→ 需要
- 同一篇文章可以重复收藏吗？→ 不可以
第二步：方案设计
基于澄清后的需求，方案设计技能输出：
- 数据结构：收藏表（id, user_id, article_id, created_at），唯一索引(user_id, article_id)
- 接口：POST /api/favorites（添加收藏）、DELETE /api/favorites/:id（取消收藏）、GET /api/favorites（获取列表，支持分页）
- 关键流程：添加收藏时先检查是否已收藏，已收藏则返回提示；取消收藏时验证收藏记录属于当前用户
第三步：增量编码
任务拆解为：
- 创建数据库迁移文件
- 实现收藏数据模型
- 实现添加收藏接口
- 实现取消收藏接口
- 实现收藏列表接口（含分页）
- 添加接口文档
每个步骤完成后运行测试，确认通过再继续。
第四步：测试生成
针对收藏接口生成测试用例，包括：正常添加收藏、重复添加收藏、取消不存在的收藏、获取空列表、获取分页列表等。
第五步：代码审查
审查生成的代码，检查是否有SQL注入风险、是否有N+1查询问题、错误处理是否完善等。
整个流程走下来，一个完整的功能从需求到可提交的代码，大约需要30到60分钟，具体取决于功能复杂度。相比传统的手动开发方式，效率提升非常明显，而且代码质量更有保障。
4.3 参数调优与个性化配置
superpowers框架提供了一些可调参数，让你根据项目特点进行个性化配置：
- 澄清深度：控制需求澄清阶段提问的数量和详细程度。简单功能用浅层澄清（3-5个问题），复杂功能用深层澄清（10个以上问题）。
- 步骤粒度：控制增量编码时每个步骤的大小。可以用代码行数或预估时间来衡量。
- 测试覆盖率目标：设定测试生成的目标覆盖率，比如核心逻辑要求90%以上，辅助逻辑要求70%以上。
- 审查严格度：控制代码审查的严格程度。原型阶段可以宽松一些，生产环境代码要严格。
我的建议是：新项目从宽松配置开始，随着项目成熟逐步收紧。一开始就设置很高的标准，会导致AI频繁卡在某个环节，反而影响开发效率。
5. 常见问题与排查技巧实录
5.1 技能不触发或触发错误怎么办
这是最常见的问题。你配置了一个技能，但在实际对话中AI没有按照预期执行。排查思路如下：
首先检查触发条件是否明确。如果触发条件写得太模糊，比如“当用户提到功能开发时触发”，AI可能无法准确判断。建议把触发条件写得具体一些，比如“当用户输入包含‘实现’、‘开发’、‘添加’等动词且涉及新功能时触发”。
其次检查技能之间的优先级。如果多个技能同时满足触发条件，AI可能选择了错误的那个。你需要在配置中明确指定优先级顺序。
最后检查上下文长度。如果对话历史太长，AI可能“忘记”了技能配置。这时候需要开启新对话，或者把技能配置放在对话的最前面。
5.2 生成的代码不符合项目规范
AI生成的代码风格和你项目现有的风格不一致，这是很常见的问题。解决方法是在配置中加入项目规范说明，包括：
- 命名约定（驼峰还是下划线，常量全大写等）
- 代码组织方式（按功能分层还是按类型分层）
- 错误处理模式（异常还是返回错误码）
- 注释风格（JSDoc还是普通注释）
我通常会把项目中最具代表性的几个文件作为示例提供给AI，让它参考这些文件的风格来生成代码。这比用文字描述规范要有效得多。
5.3 增量编码过程中卡住不动
有时候AI会在某个步骤反复尝试但无法通过验证。这时候不要一直等它自己解决，而是主动介入：
- 检查验证条件是否过于严格。比如你要求测试覆盖率必须达到100%，但某些代码分支确实难以覆盖，这时候应该适当放宽标准。
- 检查是否有外部依赖问题。比如数据库连接失败、第三方API不可用等，这些不是AI能解决的。
- 考虑回退到方案设计阶段。如果某个步骤反复失败，很可能是方案本身有问题，需要重新设计。
注意：不要让AI在一个问题上无限循环。设置一个重试上限（比如3次），超过上限就人工介入。这能避免浪费大量时间。
5.4 常见问题速查表
| 问题现象 | 可能原因 | 解决方法 |
|---|---|---|
| 技能完全不触发 | 触发条件不明确 | 细化触发条件描述 |
| 触发错误的技能 | 优先级配置缺失 | 明确技能优先级顺序 |
| 代码风格不一致 | 缺少项目规范说明 | 提供示例文件作为参考 |
| 某步骤反复失败 | 方案设计有问题 | 回退到方案设计阶段重新评估 |
| 测试过度mock | 测试生成配置问题 | 调整配置，要求包含集成测试 |
| 审查意见过于苛刻 | 审查严格度设置过高 | 根据项目阶段调整严格度 |
| 对话后期技能失效 | 上下文长度超限 | 开启新对话或精简历史 |
5.5 几个我踩过的坑
第一个坑是过度依赖自动化。刚开始用superpowers的时候，我觉得既然AI能自动完成需求澄清、方案设计、编码、测试，那我就可以当甩手掌柜了。结果发现，如果我不在关键节点做决策，AI会按照它自己的理解推进，最终产出可能偏离我的预期。后来我调整了策略：AI负责执行，我负责在每个阶段的输出上做确认和调整。
第二个坑是技能配置过于复杂。我一开始想把所有能想到的规则都写进配置里，结果配置文件变得非常臃肿，AI执行时经常出现冲突。后来我学会了做减法：只保留最核心的规则，其他细节让AI根据上下文自行判断。
第三个坑是忽视版本管理。技能配置和工作流定义也是代码，也需要版本管理。我有一次修改了配置但没有记录，后来发现新配置效果不好想回退，却找不到之前的版本了。从那以后，我把所有配置都纳入Git管理，每次修改都有记录。
6. 进阶玩法：把superpowers融入团队开发流程
6.1 团队共享技能库的搭建
当团队多人使用superpowers时，建立一个共享的技能库会大幅提升效率。做法是：在团队仓库中创建一个专门的目录存放技能配置，每个技能一个文件，用README说明每个技能的用途和使用方法。
团队共享技能库的好处是：新成员加入时不需要从零配置，直接拉取仓库就能获得一套经过验证的工作流。同时，团队可以定期review技能配置，把好的实践固化下来，把效果不好的配置淘汰掉。
我建议指定一个“技能库维护者”的角色，负责审核技能配置的变更、解决技能之间的冲突、以及定期清理不再使用的技能。这个角色不需要全职，但需要有明确的责任人。
6.2 与CI/CD流程的集成
superpowers生成的代码最终要进入CI/CD流程。你可以在CI配置中加入一些检查项，确保AI生成的代码符合团队标准：
- 代码格式检查（lint）
- 测试覆盖率检查
- 安全扫描
- 代码审查意见的自动检查
如果AI生成的代码没有通过CI检查，可以把CI的输出反馈给AI，让它自动修复。这样就形成了一个闭环：AI编码→CI检查→AI修复→CI再检查，直到通过为止。
6.3 效果度量与持续改进
要判断superpowers是否真的提升了开发效率，需要有一些度量指标。我常用的指标包括：
- 功能交付周期：从需求提出到代码合并的时间
- 返工率：代码合并后需要修复的bug数量
- 测试覆盖率：AI生成的测试覆盖了多少代码
- 开发者满意度：团队成员对这套流程的主观评价
这些指标不需要很精确，但需要持续跟踪。如果发现某个指标在恶化，就要分析原因并调整配置。比如返工率上升，可能是需求澄清不够充分；测试覆盖率下降，可能是测试生成技能的配置需要调整。
我在团队中推行这套框架的经验是：先在小范围试点，验证效果后再推广。选一个2到3人的小团队，用一个月的时间跑通流程，收集反馈，调整配置。等这套流程在小团队中稳定运行后，再逐步推广到更大的团队。这样风险可控，而且小团队的成功案例能说服更多人接受这套新方法。
6.4 技能库的版本管理与迭代
技能库本身也需要迭代。随着项目的发展，你可能会发现某些技能需要调整，或者需要新增一些技能来应对新的场景。我建议采用语义化版本管理：主版本号表示不兼容的变更，次版本号表示新增功能，修订号表示bug修复。
每次技能库更新后，需要在团队中同步变更内容，说明为什么做这个变更、对现有工作流有什么影响。如果变更较大，还需要提供迁移指南，帮助团队成员平滑过渡。
提示：不要频繁变更技能库。每次变更都会带来学习成本，过于频繁的变更会让团队成员感到疲惫。建议把变更集中起来，按季度或按月发布。
7. 我对这套框架的真实看法
用了几个月的superpowers之后，我的整体评价是：它解决了一个真实存在的问题，但不是万能药。
它最大的价值在于把AI编码从“随机发挥”变成了“结构化流程”。以前我用AI写代码，质量波动很大——有时候一次就对，有时候改十遍都不对。用了这套框架之后，质量的下限被显著提高了，虽然上限没有太大变化，但至少不会出现太离谱的结果。
它最大的局限在于配置和维护成本。你需要花时间理解每个技能的行为，需要根据项目特点调整配置，需要在实践中不断优化工作流。如果只是偶尔用AI写几行代码，这套框架的投入产出比并不高。但如果你是重度用户，每天都要用AI辅助开发，那这套框架值得投入时间。
另外，这套框架对AI模型本身的能力有一定要求。如果模型的基础能力不够强，再好的框架也发挥不出效果。我在不同模型上测试过同样的配置，效果差异很明显。所以选择模型时，不要只看价格，也要看它在编码任务上的实际表现。
最后分享一个我个人的使用习惯：我会把superpowers的工作流和手动编码结合起来。对于简单的、重复性的任务，直接用工作流自动完成；对于复杂的、需要创造性思考的任务，我会用工作流做辅助，但关键决策还是自己来做。这样既能享受自动化的效率，又能保证代码的质量和可维护性。
这套框架还在快速演进中，社区里不断有新的技能模块和工作流模板出现。我建议你保持关注，但不要盲目追新。选择那些真正能解决你实际问题的技能，把它们融入到你的日常开发流程中，这才是最有价值的做法。
