在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最常见的流程归纳为六个阶段。这六个阶段不是我想出来的，而是社区方案里普遍出现的结构，我按自己的使用习惯做了些调整：
- 定向（Orient）：AI先读项目的README、工程结构、构建文件、测试基线，形成一个"项目心智模型"。它会输出一段对项目的理解摘要，让你确认它有没有理解对。
- 规划（Plan）：AI产出一份
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从"聪明的实习生"变成"靠谱的结对程序员"，中间差的不是模型参数，就是你有没有给它一套流程。你把它当自动补全用，它就还你一段概率正确的代码；你把它当工程师带，它也能回你一份经得起测试和评审的工程变更。区别不在模型，在你的工作流。
)
