在AI编程助手刚火起来那阵子我一度以为自己拿到了某种superpowers——只要把需求往对话框里一贴代码就出来了。但用了一周之后现实很快教做人小项目、单文件、一两百行的小函数AI确实能打一旦涉及多模块、既有代码结构、测试基线、依赖管理它就开始表演薛定谔的修改——你说改A模块它偷偷动B模块还编出一个不存在的方法名测试跑红了它又开始反向修复断言。我一度怀疑是模型不够聪明。后来才意识到问题根本不在模型而在工作流。代码生成能力再强没有一个流程骨架把它约束住就跟你把一位顶尖工程师丢进一个没有需求文档、没有代码规范、没有评审流程的团队一样他也会把项目搞成一锅粥。这篇文章想分享的是我在Java/Maven项目里落地一套名为superpowers的开发工作流方案的真实体验。它不是某个厂商的官方插件也不是什么神秘框架而是一组提示词模板结合任务状态文件组成的AI结对编程协议。它的核心思路很简单让AI代理比如Codex这类工具在动手写代码之前先经历定向→规划→拆解→执行→验证的完整周期像资深工程师而非自动补全器那样工作。如果你手头有AI编程工具但用起来总觉得智商不稳定或者正在找一套可复制的工程化用法这篇文章应该能给你不少可以直接抄作业的东西。1. 别急着让AI写代码为什么多数人把AI编程助手用成了高级补全1.1 你可能也遇过的AI越帮越忙时刻先还原一个我实测过的场景。假设你有一个Spring Boot项目需要新增一个金额格式化工具类。传统用法你大概会这么干把需求粘进对话框加上一句请实现一个金额格式化工具AI唰唰给你输出一个MoneyFormatter.java看起来逻辑挺完整还有NumberFormat调用。你很满意直接复制进项目跑测试结果要么Locale没指定导致断言失败要么它引用了项目里根本不存在的依赖要么它顺手改了你的pom.xml——而你根本不知道它动了这个文件。这是最常见的第一层坑AI编程工具默认是单次请求-单次响应的模型它没有能力维护你对项目的全局理解。你给它一个点状需求它就给你一个点状答案你希望它有工程师的全局判断它却只有语言模型的模式补全。换句话说它不是能力不行是你没有给它一个能发挥能力的操作协议。1.2 根因拆解上下文碎片化、缺状态机、验证缺位我后来认真复盘过发现AI越帮越忙背后其实是三个问题而不是一个。第一个上下文碎片化。对话式AI的上下文窗口再大也有边界。当项目文件很多、依赖很杂的时候AI只看得到你贴给它的那几段代码对整体结构、既有约定、测试惯例一无所知。它给出的方案往往是在真空中最优雅的方案而不是在你的项目里最合适的方案。第二个缺少显式的任务状态机。工程师写代码是分阶段推进的先理解需求再设计实现路径然后拆任务、写测试、跑构建、看结果、回头修。每一步都有当前处于什么状态的明确认知。但AI代理天生没有这个——你问它一句它就答一句它不会主动告诉你我现在在规划阶段还没开始写代码也不会在测试失败时自动停下来反思。没有状态机就没有节奏感工作自然就乱。第三个验证环节缺位。我见过太多人让AI直接写代码然后人肉编译、人肉跑测试甚至跳过测试直接上线的勇士操作。AI生成的代码从概率上看起来对很容易但真正是否正确必须靠构建、测试、静态检查来验证。没有把验证内置进工作流AI很容易自己骗自己——它会自信地推荐一个BigDecimal用法但实际上精度陷阱一堆。这三个根因指向同一个结论你需要的不只是更强的模型而是一套让模型按工程节奏工作的流程脚手架。2. superpowers的真实机制一份提示词文件如何变成开发流程编排器2.1 它不是插件而是一套可移植的协议先澄清一个误区superpowers并不是某个IDE里点一下就能装的插件虽然社区里有各种安装脚本和配置工具但它的本质是一组提示词模板和任务管理文件的组合。你可以把它理解为给AI代理看的SOP标准作业程序——就像餐厅后厨会把操作规范贴在墙上新来的厨师照着做就不会出错。你把这套SOP放进项目的特定目录AI代理启动时会自动读取并按照其中的规则行动。这套方案之所以在圈子里被反复讨论是因为它解决了一个很本质的问题如何把人的工程方法论翻译成模型能执行的指令序列。它不像传统提示词那样只写你是一个资深工程师而是把工程师的行为拆成了可执行的阶段、可检查的产出物、可回溯的状态记录。2.2 六阶段管线从Orient到Reconcile我在实际使用中把superpowers最常见的流程归纳为六个阶段。这六个阶段不是我想出来的而是社区方案里普遍出现的结构我按自己的使用习惯做了些调整定向OrientAI先读项目的README、工程结构、构建文件、测试基线形成一个项目心智模型。它会输出一段对项目的理解摘要让你确认它有没有理解对。规划PlanAI产出一份PLAN.md明确目标、约束条件、风险点、验收标准。规划不直接落到代码而是先落到文档。拆解Slice把计划拆成一系列可独立验证的小任务每个任务都有明确的输入输出和验收条件。这一步很像敏捷开发里的Story拆分。执行Act按任务列表逐个实现每个任务都遵循先写失败测试→再写实现→跑测试的红绿循环。验证Verify跑单测、跑构建、跑静态检查所有环节通过后才算任务完成。回顾Reconcile对照验收标准检查全局清理临时代码更新文档记录与计划的偏差。这六阶段里最重要的并不是执行而是前三者。很多AI工具用得不好问题都出在还没有定向和规划就直接进入执行。你想想一个工程师空降到一个陌生项目如果连项目结构都没摸清就上手改代码你敢让他动生产仓库吗superpowers要做的就是强制AI先当观察者和规划者然后才当执行者。2.3 为什么写计划文件比口头说计划更管用有人可能会问我直接在对话框里跟AI说你先计划一下再动手不行吗我也试过效果很差。原因有两个。第一对话历史是易失的。上下文窗口里塞的东西多了之后早期的指令会被逐渐稀释AI越聊越容易忘事。但落成PLAN.md文件就不一样它成为项目的固定资产AI每次读取都能拿到完整、不变的规划文本相当于把约定从易失的内存搬到了持久化的硬盘。第二文件是可审查、可追溯的。口头计划说完就没了但文件形式让计划进入了版本控制你可以看到AI在规划阶段是怎么想的哪里跑偏了哪里和需求不一致甚至可以在评审阶段就推翻重来。这个价值怎么强调都不为过——在代码被写出来的前一刻拦截错误修正成本是最低的。3. 从零搭建一套superpowers工作台目录结构、文件模板与AI代理接入3.1 最小可用的目录结构网上关于superpowers的配置版本很多有的项目叫SYSTEM.md有的叫AGENTS.md有的叫CLAUDE.md具体名字取决于你用的是哪家AI代理工具。我自己的经验是抓住核心思想就好不要过分纠结文件名。以下是我用过的一套比较顺手的结构.superpowers/ SYSTEM.md PLAN.md TASKS.md CHECKLIST.md REFLECT.md AGENTS.md如果你的AI代理支持指定额外的指令文件比如Codex的codex.md可以在项目根的AGENTS.md里写一行引用让AI启动时自动加载.superpowers/SYSTEM.md。如果你用的工具不支持自定义指令文件也可以直接把SYSTEM.md的内容在首轮对话里粘贴进去随后把PLAN.md等文件路径明确告诉AI让它自行读取。3.2 SYSTEM.md给AI的入职培训手册SYSTEM.md是这套方案的大脑它定义AI在项目中的角色定位、工作阶段和产出要求。我建议模板大致覆盖这几个模块下面给出一份我自己改过的精简版你可以直接复制改名使用# AI代理工作协议 ## 角色定位 你是一名参与本项目开发的资深工程师不是代码生成器。 你的目标不是给出答案而是与人类协作完成可交付的工程变更。 ## 工作阶段 遵循以下顺序未完成上一阶段不得进入下一阶段 1. Orient阅读 README、构建文件、核心源码与测试输出项目理解摘要。 2. Plan产出或更新 PLAN.md包含目标、约束、风险、验收标准。 3. Slice将计划拆分为 TASKS.md 中的任务列表每项含验收条件。 4. Act逐项实现每个任务先写失败测试再写实现。 5. Verify运行项目声明的全部验证命令不得跳过任何失败项。 6. Reconcile更新 REFLECT.md记录偏差、清理临时代码、更新文档。 ## 硬性约束 - 不得修改 PLAN.md 中已由人工确认过的目标与验收标准。 - 不得自行升级或新增依赖版本依赖变更必须先征求人工同意。 - 所有代码变更必须在对应 TASK 的测试全部通过后才能声明完成。这里的核心是硬性约束。我踩过的最深的一个坑就是AI自作主张升级了pom.xml里的依赖版本理由是修复一个潜在的CVE。听起来很有道理对不对结果那一次升级直接破坏了项目里另一个模块的二进制兼容CI挂了整整半天。所以后来我在SYSTEM.md里写死了依赖变更必须先征求人工同意这条规则救了我很多次。3.3 PLAN.md与TASKS.md任务文件的状态管理技巧PLAN.md和TASKS.md是执行过程中的活文档需要不断更新。AI代理和人都要遵守同一个约定每个任务的状态必须是显式可读的。我喜欢用这样的状态标签## TASK-001实现 MoneyFormatter 空值安全 - 状态进行中 - 验收条件MoneyFormatterTest 中空值用例通过 - 依赖无状态字段只保留三种待开始、进行中、已完成。不要允许AI自创状态词汇比如基本完成差不多好了否则会把你逼疯。每次AI开始或结束一个任务都必须更新这个文件。这样你就拥有了一个实时可看的任务看板配合git diff整个开发过程完全透明。3.4 接入AI代理三步走接入AI代理没有统一标准但大致三步可以覆盖绝大多数工具把SYSTEM.md的内容配置为工具的全局指令或项目指令。Codex类的工具一般读取项目根的AGENTS.md在这一行引用即可请先阅读 .superpowers/SYSTEM.md并严格按照其中的工作协议执行任务。在首轮对话中不要直接给需求而是先给项目入口信息例如项目根目录在 /workspace/demo请先执行Orient阶段读完核心文件后向我汇报项目理解。这一步很重要它让AI有足够时间构建上下文而不是急着输出代码。收到项目理解摘要后人工确认无误再让它进入Plan阶段生成PLAN.md。越界动作比如直接写代码一旦出现立即在对话里纠正并更新SYSTEM.md的约束。4. Java/Maven项目实测从需求拆分到红绿测试的完整流程4.1 一个可复现的任务金额工具类为了让你直观地看到这套流程跑起来的样子我拿一个真实的Java/Maven小任务走一遍。假设需求如下项目里需要一个金额工具类能把BigDecimal格式化为千分位字符串要求空值安全、不丢失精度、不依赖系统默认Locale。放到普通用法里你大概会直接让AI写一个工具类然后得到一段代码。但走superpowers流程正确的打开方式是先让AI完成Orient——它需要读取项目现有的工具类位置、测试框架版本、编码规范。AI可能汇报项目采用JUnit 5工具类放在com.example.util包下既有工具类多使用静态方法pom中已存在commons-lang3。这份汇报的价值在于你可以在动手前就发现它有没有读懂项目。然后进入Plan阶段AI生成的PLAN.md大致会包含# PLAN实现金额格式化工具类 ## 目标 提供一个新的工具类 MoneyFormatter支持千分位格式化与空值安全。 ## 约束 - 使用 BigDecimal禁止 double/float - 不修改既有方法签名 - 不新增依赖 ## 风险 - 依赖系统 Locale 可能导致断言不稳定需显式指定 Locale.ROOT - BigDecimal 的 scale 设置需要与需求方确认 ## 验收标准 - MoneyFormatterTest 全绿 - 格式化结果等于 1,234,567.89 的字面值使用 Locale.ROOT看到这份计划后你该检查的重点是约束和风险两条。AI主动提出Locale问题说明它在规划阶段确实思考了边界条件这比直接给你代码然后让你发现Locale问题要高效得多。4.2 TASK拆分与红绿循环计划获批后AI会根据TASKS.md生成任务列表典型拆分是TASK-001编写MoneyFormatterTest覆盖空值、千分位、负数、精度保留TASK-002实现MoneyFormatter类使TASK-001的测试通过TASK-003运行mvn -q test补充边界用例这里有个关键体验要分享让AI先写测试再写实现看起来多此一举但对AI编程来说是巨大的质量杠杆。因为测试是验收标准的具象化第一时间把验收标准变成代码后续实现就有明确的靶子。如果先写实现再补测试AI往往会反向合理化——写一个跟实现完全一致的测试测了个寂寞。实际执行时AI会在TASK-001中写出类似这样的JUnit 5测试class MoneyFormatterTest { Test void shouldReturnEmptyStringWhenInputIsNull() { assertEquals(, MoneyFormatter.format(null)); } Test void shouldFormatWithThousandsSeparator() { String result MoneyFormatter.format(new BigDecimal(1234567.89)); assertEquals(1,234,567.89, result); } Test void shouldKeepNegativeSign() { String result MoneyFormatter.format(new BigDecimal(-1234.5)); assertEquals(-1,234.5, result); } }然后TASK-002实现TASK-003跑构建验证。这三步走完一个功能点的正确性被测试牢牢锁定。4.3 Java项目特有的三个坑AI不会主动告诉你就是在这样一次看似简单的流程里Java项目特有的问题还是暴露了不少这些问题我统称为AI默认值陷阱。第一个是Locale问题。AI如果不刻意处理NumberFormat.getInstance()会使用JVM默认Locale一旦你机器或CI容器的Locale不同比如中文环境、德语环境千分位符号可能变成小数点1.234.567,89。不是AI不知道这个原理是它默认你没有这个需求除非你的验收标准里明确写了Locale.ROOT。第二个是BigDecimal的精度语义。AI生成的格式化逻辑如果直接toString()遇到new BigDecimal(1.2300)会丢掉尾随零而如果需求要求保留两位小数需要用setScale(2, RoundingMode.HALF_UP)。这类精度细节不落在测试用例里AI根本不会意识到。第三个是Maven Surefire的测试发现规则。AI生成测试类时如果命名不符合*Test.java的约定比如MoneyFormatterUtilTest其实是符合的但TestMoneyFormatter就不行测试会被静默跳过。CI依然绿但你的新代码根本没有被验证过。所以我的习惯是每当AI新增测试类人工盯一眼命名是否符合*Test约定这个动作只需要三秒钟但可能省掉后续几小时的排查时间。5. 实测三个月后的边界感哪些任务值得用、哪些不值得5.1 值得走全套流程的四类场景superpowers不是万能的也不是所有任务都值得走完整六阶段。根据三个月的实测我总结出四类非常值得动用这套流程的场景第一类跨文件的模块级改动。比如重构一个既有服务类牵涉接口、实现、测试三个文件。AI如果没有规划阶段很容易改了一处忘了一处导致编译错漏。走完整流程后TASKS列表让每一步都有据可查。第二类测试补全任务。比如一个遗留模块测试覆盖率严重不足你可以让AI先Orient读代码然后Plan列出所有需要补测的分支再逐个红绿实现。最后你拿到的是一份带分支覆盖报告的测试增量而不是一坨零散断言。第三类依赖升级的前置分析。注意我不是说让AI自动升级依赖而是让它产出一份升级影响分析报告梳理当前版本、目标版本、破坏性变更点、受影响的模块。这份报告进入PLAN.md后人类再做决策。这一步做完升级操作的确定性会大增。第四类文档与代码同步。很多项目的README、接口文档、架构说明严重滞后于代码。你可以让AI走一遍Orient把项目现状梳理成文档草稿再人工审核。这个场景里AI不会涉及太多风险操作但流程保证它不会漏掉关键模块。5.2 不建议使用的三类场景反面案例同样重要。以下三类任务我劝你别套superpowers流程否则只会徒增摩擦。其一探索性原型。你只是想确认一下某个技术方案可不可行五分钟想要个结果。这时候走规划→拆解→验证流程AI写PLAN的时间都够你拿到原型了。探索性任务的核心是快速获得反馈不是工程规范性流程太重反而拖慢迭代。其二需求完全模糊的任务。如果需求方只说把页面优化一下连业务目标都说不清楚superpowers的Plan阶段会让AI硬编出一份计划这份计划通常看起来逻辑自洽实则建立在空中楼阁上。先跟需求方把验收标准梳理清楚再上这套流程。其三涉及生产数据变更或敏感操作的任务。这类场景的决策权必须留在人手里AI再强的规划能力也无法替代合规审查。如果非要AI参与也只让它生成到待人工执行这一步为止不要把变更动作交给AI直接执行。5.3 协作边界让AI提交之前先设置护栏我在使用过程中还踩过一个不算代码问题但很致命的坑AI代理默认有完成感。它做完TASK-003跑完测试全绿就直接在自己的输出里宣告任务已完成。如果你允许它顺带git commit -m feat: add MoneyFormatter并且推到远程分支那就有意思了——它可能把PLAN.md、TASKS.md和其他临时文件一股脑提交进去或者把target/目录给提交了。我的护栏方案有两层。第一层在SYSTEM.md里明确AI不得直接执行git commit、git push或任何写操作命令需要提交时请列出变更文件清单等待人工执行。第二层在工程侧给AI代理只读的代码仓库权限或者只允许它在feature分支工作主分支的写权限永远握在人手里。虽然多了一个人工执行git commit的步骤但换来的是提交历史的可控性。跟AI协作宁可慢一点不要失控一点。6. 最后一个我私藏的精简工作流产出型开发者的最小配置如果你觉得上面整套结构还是太重我最后分享一个自己在临时小项目里用的最小配置它保留了superpowers最核心的三个阶段但把重量压到很低。你只需要两份文件项目根目录的AGENTS.md以及一份PLAN.md。AGENTS.md的内容只有这几行请严格遵循以下工作流 1. 读README与关键源码输出一段200字以内的项目理解摘要。 2. 生成PLAN.md包含目标、约束、验收标准。 3. 等待人工确认后按TASKS逐项实现每个任务先写失败测试再写实现。 4. 所有任务完成后运行项目声明的验证命令并汇报结果。然后你只要在首轮对话里让AI按AGENTS.md执行它就会自己开始Orient。整个过程中你只需要做两个动作确认计划、审查最终的diff。这套精简版我现在在个人工具类项目里一直都在用它砍掉了REFLECT.md、CHECKLIST.md这些对个人项目价值没那么大的部分但保留了最关键的先计划后动手先测试后实现验收入口明确三个要点。说真的自从习惯这种工作方式之后我再看那些把AI当超能力一句需求生成一整个项目的用法心态已经完全变了。superpowers这个名字取得其实很贴切——它不给你生成代码的超能力而是帮你把已有的AI能力真正组织成一套可控的开发流程。AI从聪明的实习生变成靠谱的结对程序员中间差的不是模型参数就是你有没有给它一套流程。你把它当自动补全用它就还你一段概率正确的代码你把它当工程师带它也能回你一份经得起测试和评审的工程变更。区别不在模型在你的工作流。