做AI辅助编程大半年，我最深的感受是：工具越来越强，用起来却越来越散。Codex聊着聊着就忘了上半场的结论，每次新开会话要把项目背景重新讲一遍，团队里各人的Agent配置又五花八门。后来我把一套叫 superpowers 的增强工作流捡起来，才真正解决“AI有记忆、团队有沉淀”这件事。这篇就讲清楚它是什么、怎么装、怎么用，以及我踩过的那些坑。
superpowers不是一个具体模型，也不是某个IDE插件，而是一套围绕AI编码代理的“能力增强框架”。你可以把它理解成给编码代理装上“技能包+记忆库+工作流入口”：技能包负责把高频任务固化成可复用的规则和脚本，记忆库负责让代理在多次会话之间记得住项目上下文，工作流入口负责把人和代理的协作变成一组稳定命令。它解决的痛点很直接：上下文窗口有限、会话容易跑偏、知识无法跨会话沉淀、团队协作时各搞一套。
这篇文章面向两类人：一类是被“AI写完代码但不敢接手”困扰的独立开发者，另一类是想在团队里统一Agent协作方式的Tech Lead。我按实际操作的顺序展开，能直接抄作业的地方直接给步骤，中间会把关键决策背后的理由讲透。开始之前多说一句：这类工具迭代很快，不同版本差异不小，我按最常见的“CLI+配置文件”形态来讲，具体命令以你本机版本为准。
1. 先把问题说透：AI编码代理的四个常见短板
1.1 上下文失忆，是最大的隐性成本
让Codex帮你重构一个Java服务，前三十轮对话里已经确认了“用枚举代替魔法数字、异常统一走BizException”，但新开会话后它又问“你们项目有没有统一的异常基类”。这个场景我遇到过太多次，本质原因是上下文窗口有限，聊天记录越长，旧结论被挤占得越厉害。
更麻烦的是，你很难判断哪些结论值得永久记住，哪些只是本次任务的临时判断。很多人的做法是每次开新会话前手动把“项目背景+技术约定+本次目标”粘一遍。粘一次五分钟，一周下来就是一两个小时，这还不算粘贴过程中漏掉关键信息导致的返工。
superpowers解决这个问题的思路很朴素：把“需要长期记住的东西”从对话里抽出来，放到独立的知识文件里，让每个新会话启动时自动加载。代价是你需要花十分钟把项目的约定整理成结构化文档，收益是从此每个会话都带着完整上下文进场，而不是从零开始培养一个全新智力。
1.2 会话发散，经常答非所问
上下文失忆之外，第二个常见问题是会话发散。任务做到一半，代理突然开始优化无关的代码风格，或者把一个局部问题放大成全局重构。原因不复杂：模型没有稳定的“任务边界感”，尤其当对话轮次变多，原始目标被大量中间过程稀释后，它就容易跑偏。
这类问题靠“在提示词里多强调几句”很难根治。模型不是不听话，而是它记住的优先级会被近期对话影响。superpowers的做法是把任务拆成工作流：先定义清楚输入、输出和验收标准，再定义允许调用的技能和工具，最后才让代理在限定轨道内执行。任务边界一旦固化下来，发散的概率会明显下降。
1.3 个人经验无法沉淀成团队资产
很多团队里，A开发者辛苦调好的一套Java代码规范提示词只存在他自己的对话记录里，B开发者不知道，C开发者踩了同样的坑再调一遍。这种情况单靠文档治标不治本，因为文档不会被代理自动加载，也不会被代理当成执行依据。
superpowers里有个核心概念叫“技能”，本质上就是把提示词、脚本、规则说明打包成一个可版本管理的目录，放在共享仓库里。任何人调用同一个技能，得到的执行标准是一致的。对团队来说，这就把“人肉传承经验”变成了“代码仓库传承经验”，新成员上手时不用再翻几十页聊天记录。
1.4 工具越多，组合越乱
现在很多开发者同时用Codex、各类MCP服务、脚本工具、CI检查，每个工具都有自己的配置和触发方式。它们单个看都不错，组合起来就乱：有的工具要环境变量，有的要特定目录结构，有的版本之间互相不兼容。真正消耗精力的往往不是写代码本身，而是维护这套工具链。
superpowers这类框架的价值在于做一个统一入口：你在一份配置文件里声明项目用哪些技能、接哪些服务、走哪些命令，代理通过这个入口按声明去加载。配置收敛到一处，排查问题时也只要查一处。后面我会专门讲安装和工作流设计。
2. 设计拆解：为什么是“技能+记忆+工作流”三层
2.1 “技能”不是提示词，而是可执行的规则包
很多人第一次接触superpowers时会把“技能”理解成“一个更长的提示词”，这是最常见的误解。技能目录里通常至少包含三部分：说明文档（描述这个技能解决什么问题、什么时候调用）、提示词模板（给模型看的执行规则）、脚本或工具引用（需要实际执行的代码）。三者结合，代理才知道“遇到什么情况、按什么步骤、调什么工具”。
以Java代码审查为例，一个审查技能不只会写“请检查代码质量”，而是会声明：先跑哪些静态检查命令、优先检查哪几类问题（空指针、资源泄漏、事务边界）、发现问题后按什么格式输出。代理被调用时，等于拿到一份完整的执行手册，而不是一句泛泛的叮嘱。这就是“技能”和“普通提示词”的本质区别：前者是可重复、可验证、可维护的执行单元，后者是一次性的口头要求。
2.2 “记忆”解决的是跨会话一致性问题
superpowers的记忆层一般以项目为单位组织，常见做法就是一个MARKDOWN文件或JSON文件，记录项目背景、技术栈、目录结构、编码约定、历史决策。会话启动时，框架负责把这份记忆注入上下文，并在会话结束时把值得沉淀的新决策写回。
这里有个设计细节值得注意：记忆不是“把整个聊天记录存下来”，那样很快就会超过上下文窗口，而是只存“高价值的决策点”。比如“本项目的数据库访问统一走MyBatis-Plus，禁止裸写JDBC”，这就值得记；比如“今天把登录接口改了三版”，这个就不需要记。有没有一套自动筛选机制？目前多数实现还是靠会话结束时的总结模板来提炼，所以你在配置里把“决策记录”的格式定义清楚，比什么都重要。
2.3 “工作流”是防止跑偏的轨道
工作流层是superpowers比较有特色的地方。它把常见任务拆成固定阶段，比如“需求理解→方案设计→编码实现→自测检查→提交总结”，每个阶段限定调用特定技能，阶段之间设置输出格式要求。代理更像是在轨道上跑，而不是漫无目的地自由发挥。
我刚开始觉得这套做法太死板，用久了才明白它的价值：轨道限制的不是能力，而是不确定性。对于搞Java这类强类型项目，清晰的阶段划分本身就能减少大量低级错误。比如“方案设计阶段不允许直接改代码”，这个简单约束就能避免代理在没想清楚接口设计时就贸然动手。
2.4 技术选型与运行环境
先把环境说清楚。superpowers本身一般不需要重型依赖，但为了和Codex等编码代理配合使用，你本机至少要准备好：一个可用的命令行终端环境、Git、对应语言的运行时（做Java开发就装JDK 17以上）、以及编码代理的CLI工具。操作系统方面，Windows、macOS、Linux都能跑，但路径写法上Windows会稍微麻烦一点，建议用WSL或Git Bash统一环境。
如果你要接MCP服务，还需要确保代理CLI支持MCP协议。这部分不同工具差异较大，我的建议是先跑通最小闭环，再逐步加外部服务。别一上来就配一堆插件，出了问题你根本分不清是哪一环在报错。
3. 安装配置的完整实操记录
3.1 安装与初始化的标准步骤
第一步，把superpowers的代码仓库拉下来，放到一个固定的工作目录，比如~/tools/superpowers。然后按项目文档安装依赖，通常是npm install或pip install -r requirements.txt，具体看你用的实现版本。
第二步，进入工作目录执行初始化命令，一般类似superpowers init。这个命令会生成一个配置目录，里面包括主配置文件、技能目录、记忆目录和一个示例技能。我的经验是，初始化完成后的第一件事不是急着写技能，而是先看看示例技能的文件结构，理解每个文件的加载顺序。
第三步，配置编码代理的CLI。以Codex为例，你需要在Codex的配置里指定启动时要加载superpowers的初始化脚本，这样每次进入会话，代理都会先读取技能索引和项目记忆。这一步如果做不好，后面所有技能都调不起来。
3.2 一份最小可用配置文件
下面这份配置是我在实际项目里精简出来的，保留了最核心的几项：
project: name: order-service language: java jdk_version: 17 package_root: com.example.order memory: enabled: true path: ./memory/project-context.md auto_summary: true skills: - name: java-review path: ./skills/java-review trigger: review - name: unit-test path: ./skills/unit-test trigger: test workflow: default: - stage: understand skills: [] - stage: design skills: [] - stage: implement skills: [java-review] - stage: verify skills: [unit-test]这份配置做了三件事：声明项目基本信息、开启记忆功能并指定记忆文件路径、注册两个技能并指定触发词。工作流部分定义了默认流程，implement阶段会自动带上代码审查技能，确保每次实现完都要过一遍检查。
3.3 环境变量与路径相关的坑
配置过程中最容易出问题的就是路径和环境变量。技能目录里的脚本如果用到外部命令，比如Java的mvn或gradle，必须确保这些命令在代理的运行环境里能直接识别。我遇到过的情况是：终端窗口里mvn -v正常，但代理调用技能时报“找不到命令”，原因是代理的环境变量和登录shell不一样。
解决办法不复杂：把JDK和构建工具的路径写进代理运行环境的配置文件里，而不是只写在用户shell里。如果你用Windows，注意路径分隔符和目录权限，建议把整个项目放在一个没有空格的路径下，能省掉很多意想不到的解析问题。
3.4 从零定义技能目录的规范
技能目录的结构我建议统一成这样：
skills/ java-review/ SKILL.md # 技能说明：用途、触发条件、输入输出 prompt.md # 给模型看的详细执行指令 scripts/ # 需要实际执行的脚本 check-style.sh rules.json # 机器可读的规则配置SKILL.md要写得足够清晰，因为它是模型决定“什么时候调用这个技能”的依据。prompt.md则是技能的核心，我后面用Java案例展开。scripts目录放可执行脚本，rules.json放结构化的规则参数，方便不同技能间复用。这个结构不是硬性规定，但团队统一之后，管理成本会低很多。
4. 核心实操：用superpowers跑一个Java项目全流程
4.1 编写一个Java代码审查技能
我来写一个真实用过的Java审查技能核心部分，可以直接参考改造。prompt.md的核心内容大概是：
# Java代码审查执行规则 ## 执行步骤 1. 先运行 `mvn -q compile` 确认编译通过 2. 扫描所有新增和修改的Java文件 3. 按优先级依次检查以下问题： - P0：空指针风险、资源未关闭、事务未提交/回滚 - P1：并发问题、集合遍历时修改、异常被吞掉 - P2：魔法数字、过长方法、重复代码 ## 输出格式 每个问题按统一的模板输出： - 文件路径与行号 - 问题类型与严重级别 - 问题说明（一句话） - 修改建议（可执行的代码片段）这个技能看起来简单，但实际用起来的反馈很好，原因是它把“检查什么”和“怎么报告”都定死了。模型不再自由发挥写一大段模糊的“代码有待优化”，而是像执行检查单一样逐项过，输出结果也方便直接贴到PR评论里。
4.2 把项目记忆初始化到位
第一次用superpowers跑Java项目时，我花了二十分钟整理项目记忆文件，之后的收益非常明显。我会把记忆文件分成几个固定章节：
# 项目上下文 ## 技术栈 - Java 17, Spring Boot 3.x - MyBatis-Plus，禁止裸写JDBC - 统一异常：BizException + GlobalExceptionHandler ## 项目结构 - controller层只做参数接收和结果包装 - service层写业务逻辑，禁止把SQL拼在controller - mapper层只放数据库操作 ## 关键约定 - 所有金额用BigDecimal，禁止double - 分页参数统一用PageQuery对象 - 新接口必须写OpenAPI注解这些内容看起来像普通文档，但关键在于：它是代理每次会话启动时自动加载的，不需要你重复交代。实际效果是，代理写的代码从一开始就符合项目约定，而不是靠你事后review再打回重改。
4.3 一个完整会话的工作流演练
我模拟一次实际场景：让代理给订单模块加一个“取消订单”接口。
会话开始后，代理自动加载项目记忆，知道自己工作在哪个项目、有哪些约定。然后我输入任务：/workflow cancel-order，触发了默认工作流。
第一阶段的understand，代理会先复述需求，并列出它理解的接口入参、出参、异常场景。这一步的产出是一个简短的需求确认清单，我需要在这里纠偏，比如补充“取消订单只允许待支付状态调用”。
第二阶段的design，代理会给出接口路径、请求响应结构、服务层方法签名。因为记忆里已经写了“service层写业务逻辑”，它不会把SQL逻辑塞到controller里，也不需要我反复强调。
第三阶段的implement，代理写完代码后会立刻触发java-review技能，自动检查自己产出的代码，发现并修复潜在问题。这个“自己审自己”的环节看起来有点绕，但实测下来确实能减少不少低级错误。
第四阶段的verify，代理会尝试生成或补全单元测试，并运行相关测试命令，最后输出一份变更总结，包括改了哪些文件、测试结果如何、有没有遗留风险。
4.4 把技能和任务接入WorkBuddy
WorkBuddy这类任务编排工具，解决的是“多任务、多代理、多人协作”时的调度问题。简单说，你可以把superpowers的技能当成可被WorkBuddy调用的执行单元：在WorkBuddy里创建一个任务卡片，关联到某个技能或工作流，再把任务分派给具体执行人或者代理。
我在团队里的做法是：代码审查任务固定在WorkBuddy里建卡片，卡片描述里直接引用java-review技能，执行人一点开就知道要用什么标准来审代码。这样一来，技能不只在对话里能用，还变成了团队工作流的正式组成部分。新成员加入时，不需要“师傅带徒弟”式地口口相传，看任务卡片就知道流程规范。
5. 常见问题与排查技巧实录
5.1 高频问题速查表
| 现象 | 常见原因 | 排查与解决 |
|---|---|---|
| 新会话里代理不记得项目约定 | 记忆文件路径配置错误或未被加载 | 检查配置里memory.path，确认文件存在且初始化脚本已执行 |
| 调用技能时报命令找不到 | 代理环境变量缺少JDK/构建工具路径 | 把环境变量写进代理运行环境配置，重启会话 |
| 技能被调用但不是预期的版本 | 多个技能目录重名或加载顺序冲突 | 检查技能索引，按项目职责拆分目录，避免通用技能覆盖专用技能 |
| 工作流执行到一半卡住 | 某个阶段输出格式不满足后续解析要求 | 检查代理日志，确认阶段输出是否严格按模板格式 |
| 记忆文件越来越大导致上下文膨胀 | 没有做内容裁剪 | 定期整理历史决策，把过时的约定标记为“已废弃” |
这张表是我实际使用中最常碰到的情况。你会发现大多数问题不是工具本身坏，而是配置层面的不对齐，尤其是环境变量和路径，占了故障原因的一半以上。
5.2 我把“记忆”当垃圾桶，结果吃了大亏
第一次用记忆功能时，我把什么都往里写，包括“今天修改了登录接口的验证逻辑”这种临时信息。很快问题就出现了：记忆文件越来越长，代理每次加载要占掉大量上下文窗口，反而挤占了真正重要的信息。
后来我调整了策略：记忆只写“新代理必须知道才能正常工作”的长期信息，临时信息一律不写入。每次会话结束后会花一分钟判断，哪些内容值得沉淀。这个动作听起来简单，但直接影响记忆功能有没有价值。
5.3 技能触发词太宽泛，经常误触发
另一个高频问题出在触发词的设置上。一开始我给单元测试技能设置了test做触发词，结果代理在聊到“需要测试一下接口通不通”时会莫名加载单元测试技能，执行一套完整的测试流程，纯粹浪费时间。
正确的做法是让触发词尽量具体，比如generate-unit-test或run-all-tests。触发规则设计的原则是“宁可少触发，也不要乱触发”，因为漏掉一次调用可以靠手动补，误触发导致的上下文混乱和操作偏差更难挽回。
5.4 版本更新后行为漂移，怎么快速定位
这类工具更新频率很高，有时候升级一个版本后，同一个技能的调用效果就变了。遇到这种情况，我建议在技能目录里固定记录“当前验证过的版本号”，升级前先跑一遍冒烟用例，确认关键技能没坏再继续用。
如果升级后技能失效，优先检查三件事：配置格式是否兼容、技能目录结构是否有变化、依赖命令是否有新版本要求。有时候只是一个小字段改名，就能让整个工作流静默失效，排查时按顺序来，别一上来就重装。
6. 长期使用下来的几点心里话
用superpowers这套思路大半年，我的结论是：它不会让AI突然从“能用”变成“神奇”，但会让AI的可控性上一个台阶。真正解决问题的不是某一个技能写得多好，而是“技能+记忆+工作流”这套机制逼着我把项目梳理得足够清楚。整理记忆文件的过程，同时也把团队里的隐性约定显性化了，这算是意外收获。
实操中我建议你从最小闭环开始：先装好框架，配置一份项目记忆，写一个你最常用的技能，跑通一次完整工作流，再逐步扩展。不要一开始就追求技能库又大又全，因为维护技能本身也是成本，技能越多，索引和冲突管理越复杂。
最后分享一个小技巧：把技能说明文档当成代码来维护，有版本记录、有变更日志、有review流程。我见过很多团队刚上手时热情很高，写了几十个技能，三个月后没人维护，最后全都失效了。真正能坚持下来的用法，是把技能看得和代码一样重要，给它们相同的工程纪律。做到这一步，你的AI编码代理才真正配得上“superpowers”这个名字。
