最近我被问得最多的一个问题Codex CLI 这类编程 Agent 到底能不能在真实项目里稳定输出我的回答是——能但前提是你别把它当成一个“万能问答机器人”而是给它配一套像 superpowers 这样的技能框架。你可能也发现过同一个模型同一个仓库别人跑出来的任务又稳又准你跑出来的就是一团浆糊差别往往不在模型而在任务有没有被结构化。superpowers 从名字就能看出来它想干的事情是给编程 Agent“加超能力”。它不是一个独立的大模型也不是什么云端服务而是一套开源的能力增强框架把常见的开发动作拆成可复用的 skills再把多个 skill 串成 workflows让 Agent 在干活时按你定义的步骤来。Codex superpowers 这个搭配在社区里讨论得很多尤其是在 Java 这种工程结构复杂、环节繁多的项目里效果差距非常直观。这篇文章适合三类人已经用 Codex CLI 或其他编程 Agent 写过代码但对结果可控性不满意的人想在 Java 项目里用 Agent 做重构、审查、测试等具体环节的人正在用 worbuddy 这类编排工具想知道怎么把 superpowers 挂进去的人。我会从设计思路讲起到安装、实战、排障最后教你写自己的技能包全程都是可以直接落地的操作。1. 为什么需要 superpowers给编程 Agent 补上“作业标准”1.1 模型能力不差差的是操作结构先说一个我自己的观察。把 Codex CLI 直接扔进一个多模块 Java 项目里让它“把这个类重构一下”它大概率会这样做先改文件、再跑测试、发现问题、再回头改。听起来很合理但实际执行时它经常会在不同文件之间反复横跳改完 A 忘了 B或者用了一种看似很现代化、实际完全不合项目风格的写法。原因很简单模型不是不会写代码而是不知道你期望的“标准操作流程”是什么。你当然可以在 prompt 里写“先分析、再改、再测试”但这类临时指令是一次性的换个任务又要重新写而且每次写的质量还不一样。更麻烦的是prompt 里的指令和模型自己“临场发挥”混在一起你根本分不清它哪一步是在执行你的要求哪一步是在自由发挥。superpowers 的做法是把这些“作业标准”固化成独立的技能文件Agent 每次执行前先读取技能说明再按说明里的步骤走这就把一个依赖临场发挥的问题变成了一个可以复用、可以审查、可以迭代的问题。打个比方你招了一个很聪明的实习生第一天就扔给他一套复杂的报表任务他大概率会做得乱七八糟。但如果你先给他一本 SOP告诉他第一步做什么、第二步做什么、遇到什么情况怎么处理、什么不能做他很快就能上手。superpowers 就是编程 Agent 的 SOP 手册而且这本手册可以被团队持续维护。1.2 核心设计skills、workflows 与可复用的“能力单元”superpowers 的核心概念并不复杂就三个skills、workflows还有一个常被忽略的“脚本层”。skills 是最小的能力单元一般用 SKILL.md 描述。里面写清楚这个技能解决什么问题、输入是什么、输出是什么、执行步骤有哪些、禁止事项有哪些。一个技能只做一件事比如“分析代码变更影响”“生成单元测试”“执行代码审查”。workflows 则是把多个技能按顺序串起来形成一个完整的任务线比如“代码变更循环”就是先分析需求再生成实现再写测试最后审查。至于脚本层是技能附带的 scripts 目录用来放一些需要真正执行的命令或脚本比如解析 git diff、统计类依赖、自动替换 API 调用避免让 Agent 用文本生成的方式去硬算。我用一个典型目录结构举例不同版本可能略微不同但思路是通用的superpowers/ ├── skills/ │ ├── analyze_codebase/ │ │ ├── SKILL.md │ │ └── scripts/ │ ├── java_refactor/ │ │ ├── SKILL.md │ │ └── scripts/ ├── workflows/ │ ├── code_change_loop.md │ └── migrate_java_time.yaml ├── config.json └── README.md为什么要分层因为模型擅长的是理解和生成不擅长的是稳定地完成机械操作。你把“分析文件依赖”这种活交给脚本把“基于分析结果决定改哪里”这种判断交给模型各干各擅长的出错率会直线下降。这也是我后来才想明白的一点superpowers 的价值不只在提示词写得好而在于把“人要做判断的地方”和“机器要执行的地方”分得清清楚楚。到这儿你可能已经理解它的理念了接下来最关心的就是怎么装怎么让它跟 Codex CLI 跑起来2. 安装与初始化把 superpowers 接到 Codex CLI2.1 环境准备与克隆先说环境。superpowers 本身不是一个独立运行的程序它更像一个“技能包仓库”需要配合 Codex CLI 这类编程 Agent 来使用。所以安装前你要确认三件事一是 Codex CLI 能正常在终端里跑起来二是本机有 Node.js 或 Python 运行时具体看对应版本要求一般 Node 18 或 Python 3.10 都够用三是你的项目目录没有被特殊权限限制技能文件需要能被 Agent 读取。安装的第一步是把项目 clone 到一个固定目录我习惯放在~/.superpowers这样多项目共用一套技能库不至于每个仓库都复制一份git clone 仓库地址 ~/.superpowers cd ~/.superpowers less README.md注意仓库地址以你在 GitHub 上搜到的项目 README 为准不同时间段主分支可能不同直接看官方说明最靠谱。README 里一般会给出 setup 脚本有的版本需要在 clone 后执行一次初始化命令用于生成默认配置和安装依赖这一步别跳它会把技能目录、日志目录、默认 workflow 的路径都准备好。2.2 配置技能目录与基础设置初始化完成之后核心配置在config.json里。常见结构是这个样子{ skills_dir: skills, workflows_dir: workflows, log_dir: logs, default_workflow: workflows/code_change_loop.md, model: codex-1 }这里有几个点值得注意。skills_dir指向技能包目录如果你团队里把技能库单独放在一个 Git 仓库统一管理就把这个路径改成对应的绝对路径或环境变量。default_workflow决定了 Agent 在不特别指定 workflow 时默认走哪条流程刚上手建议先用内置的简单流程别一上来就改默认。model建议先用你 Codex CLI 环境里本来就配置好的模型避免版本兼容问题。配置好后可以用一个最简单的命令测试加载是否成功codex exec list available skills如果输出里能看到技能名列表说明 superpowers 已经接入到 Codex CLI 了。如果提示找不到技能先回到config.json确认路径写没写对再看一下技能目录是否存在这两步占了大多数“装不上”的问题。2.3 安装后的三步体检装完不等于能用了我建议做一次三步体检花不了两分钟但能帮你避开后面大量的“无头案件”。第一步跑技能列表确认加载了哪些技能。这一步的意义是排除配置层的问题列表里能看到名字至少说明目录和解析是通的。第二步执行一个最小技能。比如很多版本自带一个summarize_changes类型的技能作用是把当前 git diff 简单总结一下。你可以跑codex exec --skill summarize_changes 分析当前工作区的改动如果它能输出有结构的总结说明技能文件被正确读取了。第三步看日志。很多问题是“技能跑了但结果不对”这时候日志是你的第一现场tail -f ~/.superpowers/logs/agent.log日志里通常能看到技能加载顺序、每一步的输入输出摘要。我个人的习惯是安装完先备份config.json确认跑通后再把改动同步到团队仓库因为后边每次调技能改坏了能随时回滚。3. Java 项目实战用 workflow 把重构拆成可控步骤3.1 场景设定迁移到 java.time 的 Maven 多模块改造说了那么多安装咱们来一个真实的 Java 场景。假设你手头是一个 Maven 多模块项目里面有大量老代码还在用java.util.Date和SimpleDateFormat现在要做一次“技术债清理”把所有Date相关的调用统一迁移到java.time。这种任务听起来不难但真正做起来很烦涉及文件多、模块之间依赖复杂、Date和LocalDateTime的 API 语义还不完全一样改错一个地方测试就给你颜色看。以前我直接把这个任务扔给 Codex CLI结果它一口气改了十几个文件看着很爽一跑测试就炸了。后来我用 superpowers 把任务拆成了三条 skill再串成一个 workflow情况就完全不一样了。先定义一个 workflow 配置文件我习惯放在workflows/migrate_java_time.yamlname: migrate_to_java_time description: 在 Maven 多模块项目中完成 Date 到 java.time 的迁移 model: codex-1 steps: - skill: analyze_codebase args: target: src/main/java pattern: java.util.Date|SimpleDateFormat output: output/impact_analysis.md - skill: java_time_migration depends_on: analyze_codebase input: output/impact_analysis.md - skill: verify_build command: mvn -q test第一条 skill 先做影响面分析扫描哪些文件、哪些方法调用需要改生成一份impact_analysis.md。第二条 skill 拿到这份清单逐个文件做迁移它只负责“按清单改”不负责“决定改哪里”。第三条 skill 跑构建和测试把结果反馈回来。三段式的好处是每一步都是可验证的不会出现“跑了两小时发现第一步就错了”的情况。3.2 技能步骤里的关键参数怎么定很多人在这一步会纠结workflow 里要不要加model上下文窗口怎么分配一次跑多少个模块合适我的经验是把它们当成“资源预算”来算而不是拍脑袋。先看model。如果你的环境支持多模型切换分析类步骤可以用能力稍弱但更快的模型因为它在做的是扫描和归纳生成代码的步骤再用更强模型因为这里最需要判断力测试步骤其实不用模型直接跑命令就行。这种“分级配置”比全程用一个最强模型更划算速度也更快。再看上下文。假设模型上下文是 128k tokens我会按四个方向做预算技能说明本身控制在 6k 左右项目背景和目录结构给 10k真正要处理的目标文件内容给 40k 到 50k剩下必须留给 Agent 推理和输出的空间。一旦超出预算比如一次要处理 200 个文件就先把范围缩小到单个模块或者让脚本先做一轮筛选别指望模型一口气全看完。最后是模块并发量。Java 多模块项目里模块之间是有依赖关系的我建议一个 workflow 里默认只对单个模块生效跑通了再扩大到全量。别迷信“并行更快”迁移类任务最怕的就是多个模块同时改改完互相踩脚。3.3 worbuddy 这类编排工具怎么接入 superpowers热词里常被问到“worbuddy 怎么用 superpowers”我猜你用的是一款把 Agent 能力做成可视化工作流的编排工具。这类工具的接入方式核心就一句话让工具能调用到 superpowers 提供的技能接口。假设 worbuddy 支持自定义工具节点最简单的做法是在节点里声明一个superpowers_skill类型把技能目录和入口文件指给它{ tool: { type: superpowers_skill, skillDir: ~/.superpowers/skills, entry: skills/code_review/SKILL.md } }如果它不支持自定义工具类型但支持“命令执行”节点也有变通办法直接在节点里启动一个 codex 子进程跑技能对应的命令codex exec --skill code_review 对当前 PR 做代码审查只要编排工具能收命令输出能传参数就能把 superpowers 当成一个可复用的“技能节点”挂进去。我不确定你用的 worbuddy 版本支不支持直接加载技能目录但按这类工具的通用设计两条路总有一条能走通。关键的判断标准只有一个工具能拿到技能结果并把结果传给下一个节点吗能就说明整条链路已经通了。4. 常见问题与排查别再被“技能没生效”卡住4.1 典型故障速查表我把这段时间在实际使用中遇到的高频问题整理成了表格你可以直接对照着查现象可能原因处理建议技能列表里看不到某个技能技能目录没被正确扫描检查 config.json 的 skills_dir 路径重启 Codex CLIAgent 加载了技能但完全不按步骤走SKILL.md 的描述太模糊模型不知道怎么匹配精简描述明确输入输出给出一个具体样例任务跑到一半上下文爆掉workflow 太长或者中间产物太大让每个步骤把结果写入文件而不是全部留在对话里Java 项目里 mvn test 总是失败工作目录不在模块目录找不到 pom.xml在技能脚本里先检测并切换到模块目录中文注释或日志出现乱码编译/执行环境没指定 UTF-8在 Maven 配置里显式设置 file.encodingUTF-8Codex CLI 升级后技能突然失效技能格式或默认模型变了看升级日志重跑初始化脚本必要时重置 config.json改了技能文件但效果没变化技能列表有缓存删掉缓存目录或用命令重启技能加载器这张表看着简单但每一条都是我真实踩过的。比如“技能列表缓存”那条最坑因为它不会直接报错只会让你怀疑“我改的代码怎么没生效”。4.2 我踩过的三个坑第一个坑是 workflow 设计得太长。我有一次写了一条 8 个步骤的 workflow前两层步骤还要跨模块分析结果跑到第 6 步的时候Agent 已经忘了第 2 步得出的结论开始自己瞎猜。后来我把每个步骤的中间结论都写成文件让下一步从文件里读而不是靠对话上下文记忆问题就解决了。写 workflow 的时候记住一点能落盘的信息就不要留在对话里模型记忆不可靠文件才可靠。第二个坑是技能脚本里的绝对路径。一开始我在自定义技能里图省事写了类似/Users/me/project/src/main/java/...这样的绝对路径在本机跑没问题换到同事电脑上直接废了。后来统一改成环境变量或者$PROJECT_ROOT相对路径才真正做到了技能包跨机器复用。特别提醒如果配的是 Windows 环境路径分隔符最好在脚本里统一转换否则又是新一轮踩坑。第三个坑是 Java 命令的工作目录。Codex CLI 默认工作目录是仓库根目录但很多 Maven 技能需要在具体模块目录里执行mvn test直接跑会报找不到pom.xml。我现在的习惯是在脚本开头加一段目录探测逻辑先确认pom.xml在哪一层如果找不到就逐级向上找再决定从哪执行构建。4.3 排查的核心思路先日志、再配置、后缓存如果你遇到问题不知道怎么下手我有一个三层排查法先看日志再看配置最后才清缓存。很多人一上来就怀疑自己的技能写错了开始反复改 SKILL.md其实多半是配置路径或缓存的问题。第一次看日志重点看技能加载顺序和每一步的输入输出摘要能定位到是“没加载”还是“加载了但结果不对”。如果日志显示技能加载正常只是结果不符合预期再去看配置和技能描述。如果改了配置还是原样那基本就是缓存。清缓存不需要手忙脚乱把技能列表的缓存目录删掉重启一次会话通常就能恢复。整个过程不超过五分钟比你在 SKILL.md 里瞎试半小时高效得多。5. 从使用者变成维护者自定义技能与团队推广5.1 手写一个最小可用的技能包等到你熟悉了内置技能大概率会想写自己的技能。我先给一个最小模板以“Java 代码变更风险审查”为例文件结构是这样的skills/my_reviewer/ ├── SKILL.md ├── scripts/review.py └── examples/sample.javaSKILL.md 的内容不用太长但要把“边界”写清楚--- name: my_reviewer description: 针对 Java 变更的逐行风险审查 input: git diff 文本或变更文件列表 output: 风险清单标记严重级别 --- ## 执行步骤 1. 读取输入中的 diff 2. 对每个变更文件检查是否有空指针、资源未关闭、硬编码敏感信息 3. 按 BLOCKER/MAJOR/MINOR 输出风险清单 4. 不修改代码只输出审查结论写技能描述的时候我吃过不少亏。最大的教训是别写“高质量地审查代码”这种模糊话模型根本不知道高质量是什么意思。你要给它明确的检查项、明确的输出格式、明确的禁止操作。就像给实习生布置任务你说“认真点”是没用的你得说“文件用完必须关掉、连接用完必须释放、错误信息不许打日志就吞掉”。5.2 团队共享时的规范建议如果要在团队里推广我强烈建议把技能目录放进 Git 仓库像管理代码一样管理技能。技能变更走 PR至少要有一个人 review这能避免“某天有人偷偷改了一个技能描述第二天所有人的 Agent 行为都变了”这种事故。命名规范也建议提前定好。我团队里的约定是“领域_动作”比如java_refactor、sql_analyze、ci_optimize。这样技能多起来之后不容易撞名而且一眼就能看出它是干什么的。workflow 的命名则用“目标场景”比如migrate_java_time、new_feature_loop让人一听就知道这条流程是解决什么问题的。版本号我建议跟着 Git tag 走技能文件头部也可以写一个简单的变更记录方便追溯。5.3 安全红线技能里的命令必须可控最后说一条我认为最重要的经验superpowers 类工具的本质是让 Agent 执行命令所以安全边界一定要提前设计。不要在 SKILL.md 里写任何密钥、令牌、数据库密码配置文件也不要放进 Git 仓库。技能里涉及高风险的命令比如删除文件、覆盖分支、推送远端最好加一个人工确认步骤不要让 Agent 直接执行。日志里如果涉及代码片段确认脱敏后再保留。我见过太多人为了省事把连接字符串直接写进了技能脚本结果技能包一共享等于给全公司发了一份凭证字典。这种事一次都不能发生。技术框架用得再熟练安全意识跟不上早晚要出问题。也算不上什么宏大理论就是些最基本的规矩命令可控、凭证隔离、变更留痕。把这三点守住你就可以放心地把越来越多重复工作交给 Agent 了。再多说一句我自己的感受。superpowers 这套东西我前后用了大半年最开始觉得它无非就是把 prompt 拆成文件没什么稀奇。真正用起来才发现它逼我养成了一个特别好的习惯每次让 Agent 干活之前我得先想清楚这件事到底分几步、每一步怎么验证、什么情况要停下来。这个思考过程本身比任何技能包都值钱。如果你也想上手我的建议是别贪多先挑一个你每周都会重复、又最容易出错的环节写成第一个技能跑通它再决定要不要串成 workflow。我踩过的那些坑写在这里了希望你不用再踩一遍。