1. 从“superpowers”这个标题说起：它到底是什么
第一次看到“superpowers”这个词，很多人脑子里蹦出来的可能是超级英雄电影。但如果你最近在开发者社区、AI 编程工具圈子里混，就会发现这个词已经变成了一个专有名词——它指的是一套面向编码智能体（coding agents）的可组合技能框架，英文叫 agentic skills framework。简单说，它试图解决一个非常现实的问题：我们手上的 AI 编程助手，单个用起来还行，但一旦面对复杂项目、多步骤任务、需要跨工具协作的场景，就开始掉链子。superpowers 想做的，就是给这些智能体装上“超能力”，让它们从单打独斗的散兵游勇，变成能按一套软件工程方法论协同作战的正规军。
我最早接触这个概念是在一个开源项目的讨论区里，当时有人贴了一段配置，说“装上 superpowers 之后，我的编码智能体终于知道先写测试再写实现了”。这句话一下子戳中了我。因为我自己用 AI 辅助写代码快两年了，最大的痛点不是模型不够聪明，而是它太容易“跳步”——你让它改个功能，它上来就改主逻辑，测试也不跑，边界也不管，最后留下一堆隐性 bug。superpowers 这套框架的核心价值，就是把这些工程纪律变成智能体可以调用、可以组合的“技能模块”，让它在执行任务时自动遵循一套靠谱的开发流程。
所以这篇文章适合谁看？如果你是那种已经在用 AI 写代码、但总觉得“差点意思”的开发者，或者你正在搭建自己的智能体工作流、想找一套可复用的方法论，那接下来的内容应该对你有用。我会从设计思路、核心技能拆解、实操配置、常见坑几个角度，把 superpowers 这套东西讲透。需要说明的是，下面涉及的具体配置和参数，一部分来自社区公开的实践总结，一部分是我自己在本地环境里反复试出来的，你可以直接抄作业，也可以按自己的项目特点调整。
2. 核心设计思路：为什么是“可组合技能”而不是“一个大提示词”
2.1 从“万能提示词”的失败说起
刚开始用编码智能体的时候，几乎所有人的第一反应都是写一个超长的系统提示词，恨不得把代码规范、测试要求、架构原则、提交格式全塞进去。我也干过这事，结果就是：提示词越长，模型越容易“选择性失忆”。你写了二十条规则，它执行到第五条就忘了后面还有十五条。更麻烦的是，不同任务需要的规则其实不一样——写新功能时你要它先写测试，改 bug 时你要它先复现问题，重构时你要它保持行为不变。把这些全揉在一个提示词里，等于让智能体每次都在一堆互相干扰的指令里做选择，效果自然好不了。
superpowers 的思路完全不同。它不追求“一个大提示词解决所有问题”，而是把工程实践拆成一个个独立的、可组合的技能单元。每个技能单元只负责一件事，比如“写测试”“跑测试”“做代码审查”“生成提交信息”。智能体在执行任务时，根据当前所处的阶段，动态加载对应的技能。这就像给一个新人配了一本操作手册，手册里每一页只讲一个动作，需要哪页翻哪页，而不是让他背下整本手册再干活。
2.2 技能组合背后的软件工程逻辑
这套框架之所以叫“superpowers”，是因为它把软件工程里那些被验证过的最佳实践，变成了智能体可以调用的“超能力”。我梳理了一下，它主要覆盖了四个维度的能力：
- 规划能力：在动手写代码之前，先让智能体把任务拆解成可执行的步骤，明确每一步的输入输出和验收标准。这一步对应的是软件工程里的“需求分析”和“任务分解”。
- 测试能力：强制智能体在实现功能之前先写测试，并且跑通测试。这是 TDD（测试驱动开发）的核心，也是防止 AI 写出“看起来对但实际跑不通”的代码的最有效手段。
- 执行能力：按照规划好的步骤逐步实现，每一步都要求有明确的完成信号，避免“一口气写完再调试”的混乱局面。
- 审查能力：在代码提交之前，让智能体自己或者另一个智能体做一轮代码审查，检查边界条件、错误处理、命名规范等。
这四个维度不是孤立的，而是可以串成一条流水线。比如你给智能体一个“给用户模块加一个邮箱验证功能”的任务，它会先调用规划技能，把任务拆成“设计数据模型”“写验证逻辑”“写测试”“跑测试”“审查代码”几个步骤；然后依次调用测试技能、执行技能、审查技能。整个过程就像一条装配线，每个工位只干一件事，但合起来就是一个完整的开发流程。
2.3 为什么这种设计更适合当前阶段的编码智能体
这里要解释一个关键问题：为什么现在大家都在往“技能框架”这个方向走，而不是继续卷模型能力？我的观察是，当前编码智能体的瓶颈已经不在“写代码”这个动作本身了。你让 GPT-4 或者 Claude 写一个排序算法，它写得比大部分初级工程师都好。但你要它在一个有几十个文件、依赖关系复杂的项目里加一个功能，它就开始犯迷糊——不是因为它不会写代码，而是因为它不知道“先做什么、后做什么、做到什么程度算完”。
superpowers 这类框架解决的正是这个“流程控制”问题。它把智能体从“代码生成器”变成了“流程执行器”。模型还是那个模型，但有了技能框架的约束，它的行为变得可预测、可复现、可审计。这对团队协作尤其重要——你可以把技能配置提交到代码仓库里，每个团队成员拉下来之后，智能体的行为是一致的。这比每个人自己写一套提示词要靠谱得多。
3. 核心技能模块拆解：每个“超能力”到底怎么用
3.1 规划技能：把模糊需求变成可执行步骤
规划技能是整个框架的入口。没有这一步，后面的测试和执行都是空中楼阁。我见过太多人直接对智能体说“帮我加个登录功能”，然后智能体就开始噼里啪啦写代码，最后写出来的东西跟你想的完全不是一回事。规划技能的作用，就是强制智能体在动手之前，先跟你确认三件事：要做什么、不做什么、怎么算做完。
具体操作上，规划技能通常会要求智能体输出一个结构化的任务清单，每个任务包含：任务描述、预期产出、验收条件。比如“加登录功能”会被拆成：
- 设计用户表结构，包含邮箱、密码哈希、创建时间字段。验收条件：迁移文件能成功执行。
- 实现注册接口，接收邮箱和密码，返回用户 ID。验收条件：单元测试覆盖正常注册和重复邮箱两种情况。
- 实现登录接口，校验密码，返回会话令牌。验收条件：单元测试覆盖正确密码、错误密码、不存在用户三种情况。
- 写集成测试，模拟完整注册登录流程。验收条件：测试全部通过。
这个清单出来之后，你可以直接在上面改，比如“密码哈希用 bcrypt 不用 md5”“会话令牌用 JWT 不用 session”。改完之后，智能体再按这个清单一步步执行。我自己的经验是，这一步花的时间越多，后面返工越少。有时候一个任务规划清楚了，实现就是十分钟的事；规划不清楚，来回改能折腾一整天。
注意：规划技能的输出一定要落到纸面上，不能只在对话里说一遍。最好让智能体把任务清单写到一个 Markdown 文件里，比如
TASKS.md，后续每完成一项就打个勾。这样即使对话中断了，你重新打开也能接着干。
3.2 测试技能：先写测试再写实现，不是建议是纪律
测试技能是 superpowers 里最“硬核”的部分。它要求智能体在写任何功能代码之前，先写测试。而且这个测试必须是可执行的、会失败的——也就是说，你还没实现功能，测试跑起来应该是红的。然后智能体再写实现代码，让测试变绿。这个流程就是经典的 Red-Green-Refactor 循环。
为什么非要这么干？因为 AI 写代码有一个很隐蔽的问题：它特别擅长写“看起来对”的代码。你让它实现一个函数，它三秒钟就写完了，语法没问题，逻辑看起来也没问题。但你一跑，发现边界条件没处理，空输入直接崩了。如果你先写测试，把边界条件、异常情况都覆盖到，智能体在写实现的时候就会被迫考虑这些情况。测试在这里扮演的是“验收标准”的角色，而不是“事后检查”的角色。
具体到操作层面，测试技能通常会要求智能体：
- 为每个功能点写至少一个正常路径测试和一个异常路径测试。
- 测试文件命名和存放位置遵循项目现有规范。
- 测试必须能独立运行，不依赖外部服务（必要时用 mock）。
- 每次修改实现后，必须重新跑全部相关测试。
我自己的做法是，在项目根目录放一个test-command.txt，里面写清楚跑测试的命令，比如pytest tests/ -v或者npm test。智能体每次要跑测试的时候，先读这个文件，确保用的是正确的命令。这个小技巧能避免很多“测试跑不起来”的低级问题。
3.3 执行技能：小步快跑，每步都有反馈
执行技能的核心原则是“小步快跑”。它不允许智能体一次性写几百行代码然后说“我写完了”。相反，它要求智能体把每个任务拆成更小的步骤，每完成一个步骤就停下来，跑一下测试，确认没问题再继续。这就像爬山的时候每走一段就检查一下装备，而不是一口气冲到山顶才发现水壶丢了。
具体执行时，智能体会遵循这样的循环：
- 从任务清单里取出下一个未完成的任务。
- 写测试（如果测试还没写）。
- 跑测试，确认失败。
- 写实现代码。
- 跑测试，确认通过。
- 如果测试没通过，分析原因，修改实现，重复第 5 步。
- 测试通过后，标记任务完成，进入下一个任务。
这个循环看起来很简单，但实际用起来效果非常明显。我试过让智能体用这种方式重构一个旧模块，它每改一个函数就跑一次测试，中间有一次测试挂了，它自己定位到是某个边界条件没处理，然后修好了继续。整个过程我几乎没插手，最后代码质量比我手动改的还高。
实操心得：在执行阶段，一定要让智能体把每次跑测试的输出保存下来，比如写到
test-output.log里。这样如果后面出了问题，你可以回溯是哪一步引入的。我踩过的坑是，智能体跑测试的时候输出太多，它自己看不过来，结果漏掉了某个失败用例。后来我让它只关注“FAILED”和“ERROR”关键字，问题就少多了。
3.4 审查技能：让智能体自己挑自己的毛病
审查技能是在代码提交之前的一道防线。它要求智能体以“审查者”的身份重新审视自己刚写的代码，检查以下几个方面：
- 边界条件：空值、零值、最大值、最小值有没有处理？
- 错误处理：异常有没有捕获？错误信息有没有意义？
- 命名规范：变量名、函数名、文件名是否符合项目约定？
- 重复代码：有没有可以抽取的重复逻辑？
- 安全性：有没有硬编码密钥、SQL 注入风险、XSS 风险？
审查技能的一个关键设计是“角色切换”。智能体在写代码的时候是“实现者”，在审查的时候要切换到“审查者”视角。这两个视角的关注点完全不同。实现者想的是“怎么把功能做出来”，审查者想的是“哪里可能出问题”。让同一个模型切换角色，虽然不如换一个模型来审查那么彻底，但也能发现不少问题。
我自己的经验是，审查技能最好配合一个检查清单使用。比如在项目里放一个REVIEW_CHECKLIST.md，里面列出这个项目特别关注的审查点。智能体每次审查的时候先读这个清单，逐条检查。这样比让它自由发挥要靠谱得多。
4. 实操配置：从零搭建一套可用的 superpowers 工作流
4.1 环境准备与目录结构
在开始配置之前，你需要先确认自己的环境。这套框架本身不依赖特定的编程语言或工具链，但它对目录结构有要求。我建议在项目根目录下建一个.superpowers/文件夹，里面放技能配置和任务清单。目录结构大概长这样：
project-root/ ├── .superpowers/ │ ├── skills/ │ │ ├── planning.md │ │ ├── testing.md │ │ ├── execution.md │ │ └── review.md │ ├── TASKS.md │ ├── REVIEW_CHECKLIST.md │ └── test-command.txt ├── src/ ├── tests/ └── ...每个技能文件里写的是这个技能的“提示词模板”。比如testing.md里可以写：
你是一个测试驱动开发专家。在写任何实现代码之前，你必须先写测试。 测试要求： 1. 每个功能点至少一个正常路径测试和一个异常路径测试。 2. 测试必须能独立运行，不依赖外部服务。 3. 测试文件放在 tests/ 目录下，命名遵循 test_*.py 规范。 4. 跑测试的命令是：pytest tests/ -v 5. 如果测试失败，先分析原因，不要直接改测试来让它通过。这些文件不需要写得很长，关键是清晰、具体、可执行。我见过有人把技能文件写成了一篇论文，结果智能体读完之后反而不知道重点在哪。我的建议是每个技能文件控制在 200 字以内，用列表形式列出关键要求。
4.2 技能加载与触发机制
配置好技能文件之后，下一步是让智能体知道什么时候加载哪个技能。有两种常见的做法：
第一种是显式触发。你在给智能体的指令里直接说“现在进入规划阶段，请读取.superpowers/skills/planning.md并按照里面的要求执行”。这种方式控制权在你手里，适合刚开始用的时候，你可以一步步引导智能体走完整个流程。
第二种是隐式触发。你在系统提示词里写一段路由逻辑，比如“当用户提出新功能需求时，先加载规划技能；当规划完成进入实现阶段时，加载测试技能和执行技能；当所有任务完成后，加载审查技能”。这种方式更自动化，但需要你对智能体的行为有足够的信任。
我自己的做法是混合使用：前期用显式触发，把流程跑顺；等稳定之后，再把路由逻辑写进系统提示词，让它自动切换。这里的关键是，路由逻辑要写得足够简单，不要搞太复杂的条件判断。智能体不是状态机，太复杂的逻辑它执行不了。
4.3 任务清单的编写与维护
TASKS.md是整个工作流的核心文件。它记录了当前项目的所有任务、状态和验收条件。我通常会让智能体在规划阶段生成这个文件，然后在执行阶段逐项更新。一个典型的TASKS.md长这样：
# 任务清单 ## 进行中 - [ ] 实现用户注册接口 - 验收条件：单元测试覆盖正常注册和重复邮箱 - 负责人：agent - 开始时间：2024-01-15 ## 待办 - [ ] 实现用户登录接口 - [ ] 写集成测试 ## 已完成 - [x] 设计用户表结构 - 完成时间：2024-01-15 - 测试结果：迁移文件执行成功这个文件的好处是，你随时打开都能看到项目进展。而且当对话中断后，你只需要把TASKS.md的内容贴给智能体，它就能接着干。我试过好几次，因为网络问题对话断了，重新连上之后把任务清单发过去，智能体无缝继续，省了很多重复沟通。
注意：任务清单里的验收条件一定要写得可验证。不要写“功能正常”这种模糊的话，要写“单元测试覆盖 X、Y、Z 三种情况”或者“接口返回 200 且响应时间小于 500ms”。可验证的验收条件才能让智能体知道什么时候算做完。
4.4 跑通第一个完整流程：一个真实案例
为了让你更直观地理解这套流程，我拿一个真实的小项目来演示。需求很简单：给一个现有的 Python 项目加一个“计算两个日期之间工作日天数”的函数。
第一步，规划。我让智能体读取规划技能，然后输出任务清单。它给出了这样的拆解：
- 写测试：正常日期范围、跨月、跨年、包含周末、开始日期晚于结束日期。
- 实现函数：接收两个日期，返回工作日天数。
- 跑测试，确保全部通过。
- 审查代码：检查边界条件、命名规范、错误处理。
第二步，写测试。智能体在tests/test_workdays.py里写了五个测试用例。跑了一下，全部失败，因为函数还没实现。这符合预期。
第三步，实现。智能体写了一个count_workdays函数，用循环遍历日期范围，跳过周六周日。跑测试，四个通过，一个失败——开始日期晚于结束日期的情况返回了负数。智能体自己分析了一下，加了一个参数校验，抛出自定义异常。再跑，全绿。
第四步，审查。智能体切换到审查者视角，发现两个问题：一是循环效率不高，日期范围大的时候会慢；二是没有处理时区问题。它把这两个问题记下来，但判断当前需求不要求处理时区，所以只优化了循环，改用数学计算。改完再跑测试，依然全绿。
整个流程走下来，从规划到完成大概花了十五分钟。如果是我自己写，可能也要十分钟，但质量不一定有它稳定。关键是，这个过程是可复现的——下次遇到类似任务，智能体还会按同样的流程走，不会因为心情不好就跳过测试。
5. 常见问题与排查技巧实录
5.1 智能体不按技能要求执行怎么办
这是最常见的问题。你明明在技能文件里写了“先写测试”，结果智能体上来就写实现。原因通常有三个：一是技能文件没被正确加载，二是技能文件里的要求不够具体，三是智能体在长对话中“忘了”前面的指令。
排查思路是这样的：先确认技能文件是否被读取。你可以在对话里直接问“你刚才读了哪个技能文件”，看它怎么回答。如果它说没读，那就是加载机制有问题，检查一下文件路径和触发逻辑。如果它说读了但没执行，那就是技能文件写得太模糊。比如你写“要写测试”，它可能理解成“有空再写”。改成“在写任何实现代码之前，必须先写测试文件并运行，确认测试失败后才能开始写实现”，它就清楚了。
还有一个技巧是在技能文件里加一句“如果你没有先写测试就写了实现，请立即删除实现代码，重新从测试开始”。这句话看起来有点狠，但确实能纠正智能体的行为。我试过几次，它真的会把刚写的实现删掉重来。
5.2 测试跑不起来或结果不稳定
测试跑不起来的原因很多，常见的有：依赖没安装、环境变量没设置、测试数据没准备、端口被占用。我的建议是在项目里放一个setup.sh或者Makefile，把跑测试之前需要做的准备工作都写进去。智能体每次跑测试之前先执行这个脚本，能避免大部分环境问题。
测试结果不稳定通常是因为测试之间有依赖，或者用了随机数据。解决方法是让每个测试都独立运行，需要的数据在测试内部创建，测试结束后清理。如果必须用随机数据，就固定随机种子。我踩过的一个坑是，智能体写的测试用了当前时间作为输入，结果白天跑和晚上跑结果不一样。后来我让它把所有时间相关的测试都 mock 掉，问题就解决了。
5.3 任务清单越写越长，智能体开始“迷路”
任务清单太长的时候，智能体的注意力会分散。它可能跳到后面去执行某个任务，或者重复执行已经完成的任务。解决办法是给任务清单加“优先级”和“依赖关系”。比如：
## 待办（按优先级排序） 1. [高] 实现注册接口（依赖：用户表结构已完成） 2. [中] 实现登录接口（依赖：注册接口完成） 3. [低] 写集成测试（依赖：登录接口完成）然后在执行技能里加一条规则：“每次只处理优先级最高的未完成任务，且必须等依赖任务完成后才能开始”。这样智能体就不会乱跳了。
5.4 审查技能发现的问题太多，改不完
审查技能有时候会“过度审查”，把一些不重要的问题也标出来，导致智能体陷入无限修改的循环。我的做法是在审查清单里区分“必须修复”和“建议修复”两类。必须修复的是那些会导致 bug 或安全问题的问题，比如空指针、SQL 注入、硬编码密钥。建议修复的是代码风格、命名优化、注释补充这类。智能体只需要修复“必须修复”的问题，“建议修复”的可以记下来以后再说。
下面这张表是我总结的常见问题速查表，你可以直接拿去用：
| 问题现象 | 可能原因 | 排查方法 | 解决技巧 |
|---|---|---|---|
| 智能体跳过测试直接写实现 | 技能文件未加载或要求模糊 | 问它读了哪个技能文件 | 在技能文件里加“先写测试”的强制语句 |
| 测试跑不起来 | 环境依赖缺失 | 检查报错信息 | 准备 setup 脚本，跑测试前先执行 |
| 测试结果不稳定 | 测试间有依赖或用了随机数据 | 单独跑每个测试 | 固定随机种子，测试内自建数据 |
| 任务清单太长导致迷路 | 缺少优先级和依赖关系 | 观察智能体执行顺序 | 加优先级标记和依赖说明 |
| 审查问题太多改不完 | 审查标准太宽泛 | 看审查输出 | 区分必须修复和建议修复 |
5.5 对话中断后如何恢复上下文
这个问题在实际操作中非常常见。我的做法是养成“定期存档”的习惯。每完成一个任务，就让智能体把当前状态写到TASKS.md里，包括已完成的任务、正在进行的任务、下一步计划。如果对话断了，重新开始的时候，先把TASKS.md的内容贴给智能体，再补一句“请从上次中断的地方继续”。它就能接着干，不需要你从头解释一遍。
还有一个更稳妥的做法是把关键决策也记下来。比如“密码哈希用 bcrypt”“测试框架用 pytest”“数据库用 PostgreSQL”，这些信息写在DECISIONS.md里。恢复上下文的时候一起贴过去，智能体就不会做出跟之前矛盾的选择。
6. 进阶玩法：把 superpowers 用到团队协作里
6.1 技能文件的版本管理
技能文件不是写完就一劳永逸的。随着项目演进，你会不断发现新的要求，比如“所有 API 接口必须加限流”“数据库查询必须走索引”。这些要求应该及时写进对应的技能文件里。我的建议是把.superpowers/目录纳入 Git 管理，每次修改技能文件都走正常的代码审查流程。这样团队里每个人用的都是同一套技能配置，智能体的行为是一致的。
6.2 多人协作时的任务分配
如果团队里有多个人都在用智能体干活，任务清单就需要支持多人协作。可以在TASKS.md里加一个“负责人”字段，每个人只处理分配给自己的任务。智能体在执行的时候，先读当前用户是谁，然后只处理分配给这个用户的任务。这个机制需要一点额外的配置，但能避免两个人同时改同一个文件导致的冲突。
6.3 技能组合的扩展思路
superpowers 的框架本身是可扩展的。除了规划、测试、执行、审查这四个核心技能，你还可以根据自己的项目特点加新的技能。比如：
- 文档技能：要求智能体在完成功能后自动更新 README 和 API 文档。
- 性能技能：要求智能体在实现完成后跑一遍性能测试，确保没有明显退化。
- 安全技能：要求智能体检查代码中是否有常见的安全漏洞。
每个新技能就是一个新的 Markdown 文件，写清楚触发条件和执行要求。加得越多，智能体的行为就越贴近你团队的工程规范。但也要注意不要加太多，否则智能体每次都要读一堆文件，反而影响效率。我的经验是核心技能控制在五到六个，其他的按需加载。
6.4 效果评估与持续改进
用了一段时间之后，你需要评估这套框架到底有没有效果。我通常看三个指标：返工率（智能体写完的代码需要你手动改的比例）、测试覆盖率（智能体写的测试覆盖了多少代码）、任务完成时间（从规划到审查通过花了多久）。如果返工率在下降、覆盖率在上升、完成时间在缩短，说明框架在起作用。如果某个指标变差了，就去检查对应的技能文件，看看是不是要求写得太松或者太紧。
我自己的体会是，这套框架最大的价值不是让智能体写得更快，而是让它写得更稳。以前我用 AI 写代码，经常是“写得快、改得也快”，一天下来真正留下来的代码没多少。用了 superpowers 之后，虽然前期规划花的时间多了，但后面几乎不需要大改，整体效率反而更高。而且因为每一步都有测试和审查兜底，我对代码质量的信心也强了很多。
最后再分享一个小技巧：如果你刚开始用这套框架，不要一上来就配全套技能。先从“测试技能”开始，强制智能体先写测试再写实现。等这个习惯养成了，再加“规划技能”和“审查技能”。一步一步来，智能体和你的配合会越来越顺。我见过有人一次性把所有技能都配上，结果智能体被一堆规则搞得晕头转向，反而什么都干不好。记住，框架是为你服务的，不是给你添堵的。
