1. 从“会写代码”到“会做工程”superpowers 到底想解决什么问题第一次看到 superpowers 这个词很多人会以为它又是一个新的代码生成工具或者某个大模型的插件合集。但真正翻过它的设计文档、跑过几个完整流程之后你会发现它压根不是“帮你写代码”的东西而是一套给编码智能体coding agents用的工程方法论框架。换句话说它关心的不是“这段代码能不能生成出来”而是“一个智能体在真实项目里能不能像一名靠谱的工程师那样把需求拆清楚、把方案定下来、把代码写对、把测试跑通、把坑填上”。这个定位非常关键。市面上大多数 agentic 工具核心卖点是“自主性”——你给一句话它自己规划、自己写、自己跑。但实际用过的人都知道自主性越强翻车的方式就越离谱它会自信满满地改错文件、会在没有测试的情况下宣布“已完成”、会在需求模糊的时候自己脑补一套逻辑然后一路错到底。superpowers 的出现本质上是给这种“野性自主”套上一副工程化的缰绳。它的核心思路可以概括成一句话把软件开发的完整流程拆成一组可组合、可复用、可被智能体调用的技能composable skills然后用一套方法论把这些技能串起来。这里的“技能”不是指某个具体函数而是像“写一份技术方案”“做一次代码审查”“补一个回归测试”“定位一个线上问题”这样的工程动作。每个技能都有明确的输入、输出和触发条件智能体在合适的时机调用合适的技能整个开发过程就从“随机发挥”变成了“有章法的推进”。这套东西适合谁我的判断是三类人。第一类是正在用 coding agents 做真实项目、但被“不可控”折磨过的开发者第二类是想把 AI 辅助开发引入团队、但苦于没有统一规范的 tech lead第三类是对 agentic skills framework 这个概念本身感兴趣、想研究“智能体工程化”这条路怎么走的技术爱好者。如果你只是想让 AI 帮你写个爬虫脚本、改个正则那 superpowers 这套东西对你来说偏重了但如果你要让智能体参与一个持续数周、有多个模块、需要反复迭代的项目那它提供的价值就非常明显。我自己的体会是superpowers 最反直觉的一点在于它并不追求让智能体“更聪明”而是让它“更守规矩”。聪明是模型本身的事守规矩是框架的事。一个再强的模型如果没有流程约束在复杂项目里也会退化成“高级自动补全”而一个中等能力的模型如果被一套好的技能框架管住反而能稳定产出可用的工程结果。这个认知转变是我理解 superpowers 的起点也是后面所有实操细节的基础。2. superpowers 的技能体系到底有哪些 skills各自管什么2.1 技能不是功能列表而是工程动作的封装很多人第一次接触 superpowers最想问的就是“它到底有哪些 skills”。这个问题看似简单但如果只给一个清单其实会误导人。因为 superpowers 的技能设计逻辑不是“我提供 A、B、C 三个功能”而是“一个完整的开发闭环需要哪些工程动作我就把每个动作封装成一个技能”。所以理解技能体系要先理解这个闭环。一个典型的开发闭环大致是这样的接到需求 → 澄清需求 → 设计方案 → 拆解任务 → 写代码 → 写测试 → 审查代码 → 集成验证 → 处理问题 → 沉淀经验。superpowers 的技能基本就是沿着这条链路分布的。每个技能负责其中一个环节并且明确规定了“什么时候该用”“用了之后产出什么”“产出物交给谁”。这种设计的好处是智能体不会在“该设计方案的时候直接开始写代码”也不会在“该写测试的时候跳过验证”。我实测下来这套技能体系最值钱的地方在于边界清晰。比如“需求澄清”这个技能它的输出不是一段模糊的“我理解了”而是一份结构化的需求说明包含目标、约束、验收标准、待确认项。这份东西会作为后续所有环节的输入。如果需求本身有歧义技能会强制智能体把歧义点列出来而不是自己拍脑袋决定。这一点在真实项目里太重要了——我见过太多 agent 因为“自作主张”把需求理解偏了最后写出来的东西完全不能用。2.2 核心技能分类与典型用途把 superpowers 的技能按用途归类大致可以分成四组。我用一个表格来说明这样更直观技能组典型技能解决的核心问题触发时机需求与方案组需求澄清、方案设计、任务拆解把模糊需求变成可执行计划项目启动、新功能立项实现与验证组代码实现、单元测试、集成验证保证代码写对且可验证方案确定后进入编码审查与质量组代码审查、边界检查、回归测试提前发现问题和遗漏代码提交前、合并前排错与沉淀组问题定位、根因分析、经验记录把踩过的坑变成可复用资产出现 bug、线上异常这张表不是官方文档的照搬而是我根据实际使用场景整理出来的。你会发现每一组技能都对应着开发过程中一个容易出问题的环节。比如“需求与方案组”对应的是“想清楚再动手”“审查与质量组”对应的是“别自己骗自己”。superpowers 把这些环节显式化就是为了让智能体没法跳过。具体到单个技能我挑几个最有代表性的说一下。“需求澄清”技能的核心动作是提问和记录。它不会直接开始干活而是先把需求里不清楚的地方列出来形成一份待确认清单。这个动作看起来简单但它是整个流程的地基。“方案设计”技能则要求智能体给出至少一个可选方案并说明取舍理由而不是直接给一个“标准答案”。“代码审查”技能最有意思它要求审查者站在“挑刺”的立场上主动找问题而不是走过场式地确认“看起来没问题”。提示不同版本的 superpowers 技能命名可能略有差异但底层逻辑是一致的——每个技能都对应一个明确的工程动作而不是一个模糊的“能力”。理解这一点比记住具体技能名更重要。2.3 技能之间的组合关系为什么叫 composable skills“composable”这个词是理解 superpowers 的钥匙。技能不是孤立存在的它们可以像积木一样组合。比如一个完整的“新功能开发”流程可能是“需求澄清 → 方案设计 → 任务拆解 → 代码实现 → 单元测试 → 代码审查 → 集成验证”这样一条链。而一个“线上问题处理”流程可能是“问题定位 → 根因分析 → 修复实现 → 回归测试 → 经验记录”这样另一条链。这种组合能力带来的好处是流程可定制。小项目可以只调用其中几个技能大项目可以把整条链都跑一遍。团队也可以根据自己的规范调整技能的组合顺序或者替换某个环节的实现方式。我见过有团队把“代码审查”技能替换成自己内部的审查清单效果一样好因为框架只规定了“这里要有一个审查动作”具体怎么审是开放的。这里有个实操心得不要一上来就把所有技能都启用。我刚开始用的时候恨不得每个环节都走一遍结果流程变得极其冗长智能体大部分时间都在“走流程”而不是“解决问题”。后来我调整了策略只保留最关键的几个技能——需求澄清、方案设计、代码审查、回归测试——其他环节按需启用。这样既保证了质量底线又不会让流程变成负担。这个取舍逻辑其实和团队管理是一样的制度太松会乱制度太紧会僵找到那个平衡点才是关键。3. 把 superpowers 引入项目安装、配置与第一次跑通3.1 引入前的环境判断你的项目适不适合在动手安装之前有一个问题必须先回答你的项目适不适合引入 superpowers。我的经验是判断标准不是项目大小而是项目的迭代复杂度。如果一个项目是一次性的、写完就扔的脚本那引入这套框架纯属浪费但如果一个项目需要反复迭代、多人协作、有明确的验收标准那它就值得。具体来说我会看三个信号。第一需求是否经常变化。如果需求三天两头改那“需求澄清”和“方案设计”技能的价值就很大。第二代码是否需要长期维护。如果代码写完还要被别人接手那“代码审查”和“经验记录”技能就很有必要。第三是否出现过“智能体自信满满地交付了错误结果”的情况。如果出现过那说明缺乏验证环节superpowers 的“验证组”技能正好补上这个缺口。反过来如果你的项目是探索性的、目标本身就不清晰、还在快速试错阶段那强行套一套工程流程反而会拖慢节奏。这种情况下我建议先只用最轻量的技能比如“问题定位”等方向明确了再逐步引入完整流程。3.2 安装与初始化的关键步骤superpowers 的安装方式取决于你使用的具体 agent 平台。不同平台的接入方式不一样但核心步骤是相通的。我把它拆成四步这样不管用什么平台你都能对上号。第一步是获取框架本体。superpowers 通常以技能包或配置文件的形式存在你需要把它放到 agent 能够读取的位置。这一步最容易踩的坑是路径问题——很多 agent 对技能目录的位置有严格要求放错了就读不到。我的建议是先看官方文档里关于目录结构的说明确认技能文件应该放在哪个层级然后再动手。第二步是注册技能。光把文件放进去还不够还要让 agent 知道“有哪些技能可用”。这一步通常需要在配置文件里声明技能列表或者运行一个初始化命令。我实测下来最容易出问题的地方是技能名的大小写和命名规范——有些平台对技能名是大小写敏感的写错了就注册不上而且报错信息往往很模糊让人摸不着头脑。第三步是配置触发条件。每个技能在什么情况下被调用是需要配置的。比如“需求澄清”技能应该在“接到新需求”时触发“代码审查”技能应该在“代码提交前”触发。这些触发条件如果配得不对技能要么不触发要么在不该触发的时候触发都会影响体验。第四步是跑一个最小验证。不要一上来就拿真实项目试先找一个简单的场景比如“让 agent 用需求澄清技能分析一个小需求”看看它能不能正确调用技能、产出符合预期的结果。这一步的目的是确认“链路是通的”而不是验证“效果好不好”。# 以常见的技能包初始化为例大致流程如下 # 1. 将技能包放到 agent 的技能目录 cp -r superpowers-skills/ ~/.agent/skills/ # 2. 在配置文件中注册技能 # 编辑 agent 配置文件添加技能声明 # skills: # - requirement-clarification # - solution-design # - code-review # - regression-test # 3. 运行初始化命令让 agent 加载技能 agent init --load-skills # 4. 验证技能是否加载成功 agent skills list注意上面的命令是示意性的具体命令取决于你使用的 agent 平台。关键是理解“放置文件 → 注册声明 → 加载生效 → 验证确认”这个流程而不是照抄命令。3.3 第一次跑通从一个小需求开始第一次跑通的目标不是“做出一个完整功能”而是“确认技能能被正确调用”。我建议选一个特别小的需求比如“给一个现有函数加一个参数校验”。这个需求足够简单简单到你能一眼看出结果对不对同时它又涉及“需求理解 → 代码修改 → 验证”这几个环节能覆盖到核心技能。跑的时候重点观察三件事。第一agent 有没有在动手前先做需求澄清。如果它直接开始改代码说明“需求澄清”技能没被触发需要检查触发条件配置。第二agent 改完代码后有没有主动做验证。如果它改完就说“完成了”说明“验证组”技能没生效。第三整个过程的产出物是不是结构化的。如果产出物是一堆零散的自然语言说明技能的输出格式没配好。我第一次跑的时候就遇到了“技能不触发”的问题。排查了半天发现是触发条件里写的是“新需求”而实际输入的关键词是“加个校验”两者对不上。后来我把触发条件改得更宽松一些问题就解决了。这个坑很典型触发条件的措辞要贴近实际输入的表达习惯而不是你自己想象中的“标准说法”。4. 让技能真正发挥作用触发时机与组合策略4.1 触发时机错了再好的技能也白搭技能能不能发挥作用很大程度上取决于“什么时候调用它”。调用早了输入信息不够技能产出质量差调用晚了问题已经发生技能只能事后补救。我踩过的坑里最常见的就是“代码审查”技能调用太晚——等代码都合并了才想起来审查这时候发现问题返工成本已经很高了。正确的做法是把技能触发点前移。代码审查应该在“代码提交前”触发而不是“合并后”。需求澄清应该在“接到需求的第一时间”触发而不是“写了一半发现理解错了”才回头澄清。方案设计应该在“动手写代码之前”触发而不是“写到一半发现方向不对”才补方案。这个“前移”的思路本质上是用流程的确定性来对冲返工的不确定性。还有一个细节是触发条件的粒度。太粗了技能会在不该触发的时候频繁打扰太细了技能又可能漏触发。我的经验是触发条件要绑定到“明确的工程事件”上比如“收到新需求描述”“代码变更完成”“测试失败”这样的具体事件而不是“感觉需要的时候”。事件驱动比感觉驱动可靠得多。4.2 技能组合的三种典型模式在实际使用中技能的组合方式会因场景不同而变化。我总结出三种最常用的组合模式分别对应不同的工作场景。第一种是全流程模式适合新功能开发。从需求澄清开始一路走到集成验证每个环节都不跳过。这种模式最重但产出质量最稳。我一般只在“这个功能很重要、不能出错”的时候用。第二种是轻量验证模式适合小改动。只调用“代码实现 → 单元测试 → 代码审查”三个技能跳过需求澄清和方案设计。因为小改动本身需求就明确不需要额外澄清。这种模式速度快适合日常迭代。第三种是问题驱动模式适合处理 bug 和线上问题。从“问题定位”开始到“根因分析”再到“修复实现”和“回归测试”最后用“经验记录”收尾。这种模式的关键是“根因分析”不能跳过——很多 agent 会直接跳到修复结果治标不治本同样的问题反复出现。组合模式适用场景包含技能特点全流程模式新功能、重要模块需求澄清→方案设计→任务拆解→实现→测试→审查→验证重但稳质量优先轻量验证模式小改动、日常迭代实现→单元测试→代码审查快适合高频操作问题驱动模式bug 修复、线上问题问题定位→根因分析→修复→回归测试→经验记录强调根因防止复发4.3 技能之间的“交接”最容易出问题技能是组合使用的那就存在一个“交接”问题上一个技能的产出怎么变成下一个技能的输入。这个环节看起来是自动的实际上最容易出问题。我遇到过好几次“需求澄清”产出了一份需求说明但“方案设计”技能没有正确读取这份说明导致方案和需求对不上。解决这个问题的关键是统一产出物的格式。superpowers 的技能设计里每个技能的输出都有相对固定的结构比如需求说明包含“目标、约束、验收标准、待确认项”这几个字段。只要格式统一下一个技能就能稳定读取。如果格式不统一每个技能各写各的交接就会出乱子。我的做法是在引入技能之前先花点时间确认每个技能的输入输出格式必要时做一点适配。这个前期投入非常值得因为它决定了整个流程能不能顺畅跑起来。就像搭积木一样接口对不上再好的积木也拼不起来。5. 实测中的坑技能不触发、产出跑偏、流程僵化5.1 技能不触发从现象到根因的排查链路技能不触发是我遇到最多的问题也是新手最容易卡住的地方。现象很明确明明配置了某个技能但 agent 就是不用它。排查这个问题我总结出一条从外到内的链路。先看技能有没有被加载。用agent skills list之类的命令确认技能在列表里。如果不在说明注册环节出了问题回去检查配置文件。这一步能排除掉一半的问题。再看触发条件有没有匹配上。技能加载了但不触发多半是触发条件没匹配。这时候要把触发条件和实际输入对照一下看看措辞、关键词、事件类型是不是对得上。我前面提到的“新需求”对不上“加个校验”就是这类问题。最后看技能优先级有没有冲突。如果同时配置了多个技能可能存在优先级问题——agent 选了另一个技能导致你期望的技能没被调用。这时候要检查技能之间的优先级设置确保在特定场景下期望的技能优先级更高。这条链路我走过很多次基本上按顺序排查都能定位到问题。关键是不要跳步不要一上来就怀疑框架有 bug先从最简单的“加载没加载”开始查。5.2 产出跑偏为什么技能执行了但结果不对技能触发了但产出不符合预期这是第二类常见问题。这种情况通常不是技能本身的问题而是输入信息不足或格式不对。比如“方案设计”技能产出了一个很粗糙的方案原因可能是“需求澄清”技能产出的需求说明太简略方案设计没有足够的输入。解决这类问题我的经验是先检查上游产出。如果下游技能产出不对先看上游技能给了什么。很多时候问题出在链条的起点。另一个常见原因是技能的输出格式被破坏。比如某个技能本该输出结构化数据结果输出了大段自然语言下游技能解析不了产出自然就跑偏了。还有一种情况是技能被“过度使用”。比如一个本来只需要简单修改的任务被套上了完整的方案设计流程结果方案设计技能为了“凑内容”硬生生编出一堆不必要的设计。这种“过度工程化”的产出看起来专业实际上增加了无谓的复杂度。我的应对方法是根据任务复杂度动态调整技能组合简单任务就用轻量模式别硬套全流程。5.3 流程僵化当方法论变成负担用了一段时间之后我遇到过一个更隐蔽的问题流程僵化。所有技能都按部就班地跑每个环节都不跳过结果整个开发过程变得极其缓慢智能体大部分时间都在“走流程”真正解决问题的时间反而少了。这时候superpowers 从“帮手”变成了“负担”。这个问题的根因是把方法论当成了教条。superpowers 提供的是技能和组合方式不是必须全走的固定流程。它的价值在于“在需要的时候提供结构”而不是“在所有时候都强加结构”。意识到这一点之后我调整了策略把技能分成“必选”和“可选”两类必选的是质量底线比如代码审查、回归测试可选的是按需启用比如方案设计、经验记录。这样既保住了质量又保住了效率。提示任何工程方法论都有适用边界。superpowers 解决的是“智能体开发过程不可控”的问题但它不解决“需求本身不合理”的问题。如果需求方向就是错的再规范的流程也救不回来。这一点要想清楚别指望一套框架能包治百病。6. 把 superpowers 用出长期价值从工具到团队规范6.1 从个人使用到团队共享的过渡superpowers 在个人手里是一个提效工具在团队手里可以变成一套开发规范。这个过渡的关键是把技能配置和触发规则沉淀成团队资产。个人使用时配置可以随意调整团队使用时配置需要统一否则每个人跑出来的流程都不一样协作就会出问题。我的做法是先把个人验证过的技能组合固化成一份“团队配置模板”包含技能列表、触发条件、产出格式要求。然后让团队成员基于这份模板使用个别场景可以微调但核心流程保持一致。这样既保留了灵活性又保证了协作的一致性。这个过渡过程中最容易出问题的是产出格式的统一。个人使用时产出格式差一点无所谓团队使用时格式不统一会导致交接困难。所以我会在模板里明确规定每个技能的产出结构比如需求说明必须包含哪几个字段代码审查报告必须包含哪几类问题。这些规定看起来琐碎但它们是团队协作的基础。6.2 技能库的持续演进把踩过的坑变成新技能superpowers 的技能库不是一成不变的。用久了你会发现有些反复出现的问题其实可以封装成一个新技能。比如我们团队经常遇到“配置文件写错导致启动失败”的问题后来就把“配置校验”封装成了一个技能每次改配置后自动触发。这个技能不是框架自带的是我们自己加的但它确实解决了实际问题。这种“把踩过的坑变成新技能”的做法是 superpowers 长期价值的来源。框架提供的是基础能力真正贴合你团队场景的技能需要你自己沉淀。我建议每隔一段时间就回顾一下最近哪些问题反复出现这些问题能不能封装成技能如果能就把它加进去。这样技能库会越来越贴合实际价值也越来越大。6.3 关于“要不要上 superpowers”的个人判断最后说点实在的。superpowers 不是银弹它解决的是特定问题——智能体在复杂项目中的工程化问题。如果你的场景不涉及这个问题那它对你来说就是多余的。我见过有人为了“用上框架”而用框架结果把简单的事情搞复杂了这就本末倒置了。我的判断标准很简单当你开始因为“智能体不守规矩”而头疼的时候就是引入 superpowers 的时候。如果还没到那个阶段先用最简单的工具把事做完别急着上框架。工具是为人服务的不是人为工具服务的。这个道理放在任何方法论上都成立。我自己用下来superpowers 最大的价值不是某个具体技能而是它传递的一种思路让智能体像工程师一样工作而不是像一台随机生成器。这个思路一旦建立起来哪怕你不用它的具体技能你自己设计的流程也会变得更靠谱。这可能比框架本身更有意义。