从代码补全到技能化工作流：superpowers如何让编码代理真正“收尾”

实话说我最初是被“代码补全”这个标签吸引来的。第一次用 Codex CLI 跑一个前后端联调的小需求它噼里啪啦几分钟就写完了完整页面我当时差点以为从此可以告别写业务代码。直到交付前我盯着没有一行单测的代码又花了三个多小时补测试、修回归、处理浏览器兼容问题才意识到问题不在“会不会写”而在“写完怎么收尾”。这个执念后来让我遇见了一个开源项目——superpowers。安装配置完之后我发现它的价值不在于让模型变得“更聪明”而是给编码代理配上了一套标准工作流先拆计划、再动手、写完自动跑测试、跑完自己看结果。这篇文章不是什么“AI 末日论”也不是吹捧某个工具无所不能而是记录我从“让代理写代码”到“给代理训练技能包”的完整转变过程尤其是对一个 Java 后端项目踩过的坑。1. 别急着让它写代码被“没有验收流程”折磨的编码代理1.1 快写代码、慢收尾的三个典型症状如果你也在用 Codex 或类似 CLI 编码代理一定有这种感觉初次生成的代码质量相当能打可你把需求稍微绕几圈它就开始“快写代码、慢收尾”。我总结了三个典型症状不写测试或者只写“看起来像测试”的测试。代理会生成一个xxx.test.ts文件断言覆盖得非常浅甚至不跑因为生成完毕没有触发任何验证动作。改了 A 模块不知道 B 模块会坏。代码生成是“一批一批”的第二批生成时并不一定记得第一批的接口契约。尤其是 Java 项目里修改一个类的签名下游十几个文件能同时编译失败。遇到报错就无限重试。常见套路是编译失败 → 重新生成整个文件 → 又失败 → 再重新生成整个文件。上下文窗口很快被“代码块翻来覆去”占满真正的约束条件早就被冲掉了。这些症状的本质是什么不是模型能力不够而是代理没有“做事的流程”开始前没有拆解需求完成后没有验收标准出错后没有收敛策略。你让它写一个函数它就真的只写一个函数你让它写一个系统它也只是写一堆函数。工作流缺失再强的模型也只是个打字飞快但不带脑子的实习生。1.2 为什么“提示词工程”救不了这个顽疾很多人会建议把验收标准写进 system prompt 不就行了我试过短期有效长期会漏。因为项目里的测试命令、构建方式、代码风格、目录结构每个仓库都不同塞进 prompt 里不仅占空间而且很快过期。一个真实项目的约束条件可能散落在一百个文件里靠提示词描述注定不完整。更好的做法是把“验收”变成体系的可触发动作。比如进度到了某个节点自动调用测试技能改动涉及某个公共模块自动触发mvn -q test前端页面改完自动启动本地服务器做一次浏览器验证。superpowers 这个项目做的正是这件事。它把“拆计划、列任务、跑测试、看结果、自我纠错”固化成了一套技能目录代理发现满足触发条件时就会去调用对应技能而不是凭“直觉”直接写代码。提示如果你只把 superpowers 理解为“一套更多 prompt 的插件”那方向就偏了。它的核心是让代理在行为层级上形成标准工作流——这是它和普通提示词仓库最大的区别。2. 超能力的本体一套可以复用的“技能化工作流”2.1 三层结构认知循环、技能动作、底层工具我拆开读过这个项目的目录发现它其实不复杂核心是三层。第一层是认知循环也就是代理面对一个任务时的思维框架。默认流程大致是理解需求 → 产出一份计划 → 拆成多个可并行或串行的子任务 → 逐个执行 → 运行验证 → 根据反馈修正 → 直到满足退出条件。这个过程有点像我们平时做迭代开发先排期再开发再联调再回归而不是一上来就写代码。第二层是技能动作每一个技能就是一份带元信息的执行方案。它们不全是“告诉代理怎么做”很多技能还包括实际起服务、跑脚本、解析输出文件的工具。以我经常用到的几个为例技能文件通常包含metadata.yaml和运行入口。metadata.yaml里写清楚技能触发条件、输入参数和输出产物运行入口可以是 Python 脚本也可以是 shell 命令。代理看到任务类型后会先匹配技能名然后按技能里的步骤去执行。第三层是底层工具比如浏览器自动化、HTTP 服务、测试运行器、文件监视器等。这些工具主要用来给代理创造“动手反馈”的环境让它能看到真实输出而不是只靠模型想象项目会怎么样。2.2 用“实习生 标准作业程序”来理解它我在团队里常把 superpowers 比喻成一套“SOP 工具包”模型相当于一个聪明但缺乏经验的实习生仓库的 README、测试脚本、CI 配置相当于公司制度superpowers 相当于贴在工位旁的“办事流程卡”。实习生拿到任务后不会直接乱写而是先查流程卡“第一步确认需求第二步找同类实现第三步写测试第四步跑构建第五步提交”。这套流程不依赖于实习生本身的经验积累而是把老师傅平时的做事习惯显式化、脚本化。这也是为什么很多用过的人都会说上了 superpowers 之后代理生成的代码风格突然变得更像团队了。原因是技能文件本身是团队约定的具象化。你可以把自家项目的规范缝进去比如“函数必须有 Javadoc”“单元测试必须命名成shouldXXX_whenYYY”。它不是模型脑子里的普遍规则而是你这一个项目的硬约束。2.3 它不会替换模型而是替换模型“不知道下一步该干嘛”的状态需要讲清楚一个概念superpowers 并不是另一个 Codex也不是一个独立的编程模型。它是挂在 Codex 等 CLI 代理之上的一层外部工具与流程编排。代理本身就是那个“大脑”superpowers 给大脑提供了双手和标准作业卡。所以在使用它之前你仍然需要按官方文档装好 Codex CLI配好模型供应商、密钥和本地环境。superpowers 安装之后会在会话里生成一个“引导技能”告诉代理“你有这些技能碰到对应情况请调用。”然后代理才真正拥有超能力。3. 安装流水账从零到第一次跑通全自动任务3.1 环境准备中最容易忽略的三个点安装过程其实不复杂只要把下面三样东西提前准备好第一Node.js 和 Python。技能目录里有大量脚本依赖它们我的建议是 Node 20 以上、Python 3.11 以上。版本太老会出现脚本直接崩溃的现象而且报错并不友好。第二Codex CLI 本体。用官方文档安装并完成登录保证在终端里直接输入 codex 能唤起对话。这一步很多人会跳过结果 superpowers 装完才发现根本没地方挂载。第三git 和 ssh key。不是所有项目都必须在本地 clone 才能工作但技能里常用到 git 操作比如生成 diff、回滚、查询历史没配好会因为权限问题卡住。3.2 安装命令和目录规划我推荐先用 clone 的方式安装而不是直接跑远程脚本。不是说官方脚本不安全而是你既然要长期用它最好把目录结构搞清楚后面定制技能时能少走弯路。# 方案 A官方安装脚本我之前执行时先保存下来读了一遍 curl -fsSL https://superpowers.dev/install.sh | bash # 方案 B手动 clone 到用户目录我最后选择了这个 git clone https://github.com/Superpowers-Dev/Superpowers.git ~/.superpowers如果你选方案 B接着要在 shell 配置里加载启动文件。以 zsh 为例echo source ~/.superpowers/superpowers.sh ~/.zshrc source ~/.zshrc一个建议是不要把.superpowers放在某个项目的node_modules同级目录里。它应该是一个独立于项目的全局工具后续升级、回滚都能单独管理。团队里多人协作时可以约定统一目录减少每个人路径不一致带来的脚本兼容烦恼。3.3 第一次跑通给自己设一个“可验收的小任务”装完之后先别急着把公司项目扔给它找一个三小时以内的练习任务跑一遍全流程。我当时用的是“在本地写一个带增删改查的 REST API并且要求它有单元测试”这种级别。我的实际命令流程大概是这样# 进入一个空目录 mkdir -p ~/demo-api cd ~/demo-api # 起一个 codex 会话并说明要使用 superpowers codex在会话里自然语言描述任务然后代理会主动加载 superpowers 的引导技能。接下来你观察它是不是做了这几件事生成计划而不是立刻写第一个文件拆解任务把“设计接口、实现、测试、构建”分成几步每一步执行前确认输入输出最后自己跑测试而不是交完代码就闭嘴。如果它在计划阶段就开始写代码多半是安装没生效或者引导技能没被正确加载。可以检查一下配置文件的skill路径是否指向了.superpowers目录。注意安装完不要直接下生产需求。先在练习目录里确认整套循环工作正常再迁到真实项目里。否则代理一旦在仓库里乱跑哭的是你自己。4. 核心循环拆解计划、执行、测试、自我纠错4.1 计划先行的价值让代理知道自己不知道很多人问直接让 Codex 写代码不是更省事吗为什么非要先拆计划我的理解是计划是代理把“用户需求”翻译成“机器约束”的唯一机会。比如你做一个电商后端需求写的是“下单时要校验库存”。如果代理不先拆计划它很可能只校验一张表里的库存字段但真实项目里库存可能分“锁定库存”和“可用库存”还要考虑订单状态变化后的回滚。这两者的复杂度完全不一样。superpowers 的计划技能会要求代理在动手前生成目标列表要做到什么程度风险点哪些模块会被影响文件级改动计划新增哪些、修改哪些、删除哪些验收条件用什么命令、什么结果算通过有了这份计划执行阶段就不容易飘。代理有了一份“操作清单”每一轮生成代码时都在和清单对照而不是凭上下文自由发挥。4.2 执行阶段允许代理反复改但每轮都有边界执行阶段的重点不是一次成功而是小步快跑。我观察 superpowers 在任务拆分上做得比较细一个完整的登录接口可能被拆成“DTO 定义”“Service 逻辑”“Controller 访问层”“集成测试”四个步骤。代理每完成一个步骤就对自己的产物做一次编译或测试通过后再进入下一步。这和我们平时写代码的节奏很像。它带来的好处是报错不会堆积到最后一个文件才爆发而是在每个中间节点都被拦截。如果出现问题代理会回退到当前步骤只修改当前任务范围内的代码而不是重新生成整个项目。当然也有一些需要人工介入的时刻。比如代理连跑五次测试都不过它可能会陷入同一个错误这时候我一般会介入检查通常是依赖版本冲突或环境变量缺失代理很难自己猜出来。4.3 测试技能是如何被触发的superpowers 里测试不是“可选项”而是循环里的一环。代理完成一组代码改动后会调用测试技能来验证。比如 TypeScript 项目会生成一个 jest 测试文件Java 项目会生成 JUnit 测试文件然后执行对应的构建命令。这里有一个容易被忽略的小点代理生成测试文件时会参考项目里已有的测试命名风格和断言风格。所以你事先把测试工具配好、示例测试写好能让后面的生成质量高很多。如果你的仓库里一行测试都没有代理就只能按“最大常识”来写不一定契合你的老项目。4.4 自我纠错的退出条件整条循环里我最欣赏的部分是“退出条件”。代理不会永远自我感觉良好它会在执行完任务后检查三件事所有目标是否完成所有验收命令是否通过是否存在未处理的 side effect比如改动了无关文件。只有这三点都满足它才会把最终结果交给你。这个机制和精神胜利法完全不同它不靠代理“自信”来判断而是靠命令执行的真实输出来判断。5. Java 项目里我反复用的几个 superpowers 套路5.1 先把“Java 项目约束”喂给技能Java 项目最痛的其实是约束太多包名规则、分层结构、Lombok 使用习惯、Spring 注解的空指针风险、JUnit 版本选择……这些约束如果不在计划阶段说明代理生成的代码十有八九要返工。我的做法是在项目根目录放一个PROJECT.md把项目规范和常用命令写清楚并在会话开始时让代理先读它。比如- 构建命令mvn -q clean package - 单元测试命令mvn -q test - 编码规范Controller 只做参数校验Service 放业务逻辑禁止在 Controller 里直接调用 Mapper - 测试要求新方法必须补单元测试命名遵循 shouldXXX_whenYYY加入 superpowers 后这些约束会被技能里的“项目扫描”环节反复参考代理在规划阶段就把约束翻译成任务的一部分而不是临时从代码里猜。5.2 用测试先行逼出可重构的代码Java 旧项目最让人头疼的是“脱离测试重构”。我也不建议让代理一上来就重构核心业务类风险太大。我通常的做法是先让代理选中一个类调用测试生成技能写一批单元测试跑绿之后再开始重构。这个流程看起来慢其实非常稳。有一次我对一个老订单服务做重构原计划是两个小时superpowers 帮我把行为验证成本压缩到了四十分钟左右。关键是代理在生成测试时会把旧类的所有公共方法都覆盖到哪些方法返回 null、哪些方法会抛异常全部作为行为快照记录下来。重构时只要保证测试不红内部逻辑改得再狠也不怕。5.3 和 Maven/Gradle 的衔接别让构建失败变成连环核爆superpowers 的测试技能不会假设你已经把整个 Maven 仓库下载好。第一次跑测试时如果依赖还没下载构建过程会普遍超时。我踩过一次坑代理连续重试三次都因为下载 Spring Boot 依赖太慢而失败最后它甚至打算把依赖版本往下降。解决方案其实很简单先手动跑一次mvn -q test把依赖拉到本地缓存再让 superpowers 介入。另外不要让代理直接修改pom.xml里的依赖版本尤其是公共依赖。技能可以把pom.xml设置为“只读观察对象”但依赖变化必须由人工确认。5.4 Java 项目里的一组典型会话节奏我最近一次用 superpowers 加“库存扣减异常处理”功能时的会话节奏是这样的让代理先输出计划重点标注涉及哪些类和表代理生成 Service 层代码和异常处理类代理自动补齐 JUnit 测试覆盖“库存不足”“并发扣减”“重复扣减”三个场景执行mvn -q test第一个版本就全部绿了最后让我做代码审查代理把改动文件清单和测试报告一起提交。整个流程下来我大部分时间在审“计划”和“验收报告”较少盯着每一行业代码。它把一个我再也不想碰的“老模块改动”变成了可复盘的标准化流程。6. 跨脚本排查安装、恢复和不该交给代理的部分6.1 安装时最容易出现的“环境插队”问题我见过最多的问题不是安装失败而是多个语言环境互相覆盖。比如你系统里可能有多个 Node 版本superpowers 的脚本用node命令时选到了老版本 Node跑起来直接语法错误。还有一种情况是 shell 环境变量被覆盖代理调起 Python 时用了 conda 的旧版本。这种问题排查起来非常考验耐心。我的建议是先用which node、python3 --version、echo $SHELL三条命令把环境基线稳住再去安装。环境隔离做得干净后面九成的问题都不会发生。6.2 长任务中断后怎么恢复代理跑长任务时最怕网络抖动把会话打断。开了本地服务器或者浏览器自动化任务尤其容易残留进程。超级技能里有一个恢复机制能让你在下次会话时接着上一次的状态继续但我实际操作时的经验是不要盲目按“继续执行”。正确做法一般是先查看任务生成的状态文件确认当前进度到哪一步了再让代理基于状态文件继续。如果不看状态就直接让代理“接着干”它可能把已经完成的步骤又重新执行一遍造成重复代码或分支冲突。6.3 千万别把这两类任务交给它第一类是涉及数据库迁移的敏感任务。superpowers 倾向于稳妥但它对线上数据库没有敬畏如果给它的信息不完整生成的 SQL 可能带来不可逆影响。我一般只让它生成 migration 草稿预览没问题后再手动执行。第二类是需要业务决策的代码审查。技能包能帮你跑测试、查 diff、找内存问题但它无法判断“这个业务规则到底该不该这样”尤其当需求和代码规范本身就矛盾时。这些判断必须留在人手里。注意把 superpowers 当成“自动生成工具”没问题但在关键路径上一定要把它当成“配合工具”由人定方向由技能包保证执行力。7. 把它当团队的 SOP 而不是“编程外挂”如果让我用一句话总结 superpowers 的价值它降低了编码代理在真实项目里的“收尾成本”。这不是因为它有什么魔法而是它把人类的工程习惯——拆计划、补测试、跑构建、看回归——变成了一套可复用的技能文件。任何团队只要维护好技能包和项目约定即便是换一个人来操作代理产出物质量也不会剧烈波动。我现在的工作方式已经变了接到需求先写好约束文件再让代理进入计划-执行-验证循环最后我做代码评审和业务判断。它没有把我从程序员变成项目经理反而让我有了更多精力去盯真正的难点设计。如果你也打算上手我的建议是从最小的练习项目开始让代理完整跑一遍计划、测试、纠错循环亲眼看看它明明写错了还能自己发现问题。那一步给我带来的体验震撼远比它一次写出几百行代码要大得多。