★ FEATURED ARTICLE 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 之后虽然前期规划花的时间多了但后面几乎不需要大改整体效率反而更高。而且因为每一步都有测试和审查兜底我对代码质量的信心也强了很多。最后再分享一个小技巧如果你刚开始用这套框架不要一上来就配全套技能。先从“测试技能”开始强制智能体先写测试再写实现。等这个习惯养成了再加“规划技能”和“审查技能”。一步一步来智能体和你的配合会越来越顺。我见过有人一次性把所有技能都配上结果智能体被一堆规则搞得晕头转向反而什么都干不好。记住框架是为你服务的不是给你添堵的。
阅读完成 · 觉得有帮助？
