如果你是Codex CLI的重度用户，大概率碰到过这种尴尬：模型代码写得挺快，但经常不按你项目的既定套路来——测试命令猜错、包结构乱来、构建规则全靠蒙。直到我把superpowers装进工作流，这个问题才算真正治本。它不是一个写代码的模型，也不会替你做架构决策，它干的事情非常聚焦：自动分析你的项目，生成一份Codex能读懂的“项目说明书”，并且在日常使用中帮你把反复出现的命令和规范固化下来。今天这篇，我不打算念官方README，而是把superpowers安装、初始化、多语言适配（尤其是Java项目）和日常排查经验从头到尾讲清楚。适合的人群很简单：已经在用Codex CLI，但又觉得它“不够懂你项目”的人；以及准备入坑Codex但不想每次开工都手写一堆规则的人。

1. 项目拆解：superpowers到底解决什么问题

1.1 痛点：Codex CLI“不认项目”

Codex CLI很聪明，但有一个结构性短板：每次对话它都要从零理解你的仓库。它不知道你的项目是Maven还是Gradle，不知道单测命令是mvn test还是./gradlew test，也不知道你们团队约定俗成的包命名规则。你可以在每次对话开头手动告诉它，但人一旦偷懒，对话质量立刻下滑。我试过把规则写进系统提示词，效果不稳定，因为Codex CLI的会话长度、上下文窗口、以及你对提示词的表达能力，都会影响最终结果。

superpowers走的是另一条路：把规则从“对话时口述”变成“项目内存在”。它在项目根目录生成AGENTS.md，让Codex启动时自动读到本地工程上下文。这相当于你给AI队友发了一本《新员工手册》，而不是每次开会都口播一遍公司制度。它能自动检测语言和构建工具，再按模板生成对应内容，整个过程不需要你跟它解释什么是Gradle。

这也是我认为这个工具最有价值的地方：它解决的不是“模型能力”问题，而是“工程接入”问题。模型能力再强，对项目上下文一无所知，产出的代码也只能靠运气。

1.2 核心方案：AGENTS.md自动化

可能还有人不太熟悉AGENTS.md，这里多讲两句。它的概念很朴素：在仓库根目录放一个Markdown文件，里面写清楚构建、测试、代码风格、目录说明、注意事项等结构化信息。Codex CLI在启动时会读取这个文件，把它当作项目级的工作约定，后续的代码建议、命令执行都会优先遵循里面的规则。

手写AGENTS.md当然是可行的，我自己也写过，但维护成本很高。项目一多，每个仓库的构建命令、规范、坑点都不一样，手工维护要么流于形式，要么很快过期。superpowers的自动化生成逻辑，是它先扫描项目里明显的工程文件，比如pom.xml、build.gradle、go.mod、package.json，从而判断语言和构建体系；再结合当前目录结构生成一个相对准确的初始版本。它不追求一步到位，但能给你一个很扎实的起点，接下来再把团队特有的规范追加进去就行。

这个设计的巧妙之处在于“用工程事实代替人工总结”。与其让开发者回忆项目里有哪些命令，不如直接让工具去读构建文件。这也是我后来在多个仓库里反复验证过的：自动生成的AGENTS.md，准确率通常比临时口述高得多。

1.3 它没有解决的边界

说句公道话，superpowers不是万能钥匙。它不做代码评审，不负责模型选择，也不能替你约束Codex的权限范围。它的输出是一份“静态配置”，如果你的项目在不停演进，这份配置也会失真，需要定期重新生成。

另外，它生成的内容偏向“通用工程规范”，不会知道你产品里某个模块的特殊约定。比如某个服务必须走特定的接口前缀、某个目录不能被改动，这些还得靠你手动补充。理解这个边界很重要，否则你会把它当成一个“装完就能甩手”的工具，然后失望。

2. 安装与初始化全流程

2.1 安装前提：Node环境与Codex CLI

先讲环境要求。superpowers本质是一个Node.js写的CLI工具，所以机器上要有可用的Node.js运行时，我建议Node 18以上，版本太低有些语法糖和API会出问题。另外一个隐含前提是你已经装好了Codex CLI，并且能正常发起对话——因为superpowers是给Codex配套用的，它本身不包含模型推理能力。

安装命令我直接给出来：

npm install -g superpowers-cli

如果npm在你机器上权限受限，可以加sudo，但我更推荐把npm的全局安装路径配置到用户目录下，避免各种权限问题。装完之后，在终端里敲一下：

superpowers --help

能正常输出版本和子命令说明，就说明CLI本身没问题了。有些发行版里，工具的入口命令可能是superpowers，也可能是简写形式（如果官方配置了别名），以你实际安装版本为准。我个人习惯全局安装，因为后续要从任意目录直接调用。

2.2 初始化项目：superpowers init

安装完成后，进入你的项目根目录，执行：

superpowers init

它做的事情大致分三步：扫描项目结构、识别语言和构建工具、生成AGENTS.md。如果目录里没有.git仓库，它通常会提示你先初始化Git，因为它要检查未提交变更，避免覆盖工作区里的已有内容。

第一次跑初始化的时候，我建议你在一个干净的Git仓库里试。为什么？因为初始化过程可能会重写或新建AGENTS.md，如果你之前手写过一份并已经加入版本管理，它可能会跟你确认是否覆盖。这时候如果你本地有未提交的改动，一不小心就会丢内容。后面我会专门讲这个坑。

初始化完成后，项目根目录会多出一个AGENTS.md。我建议立刻打开看一眼，别急着提交。重点检查三块：构建命令是不是你平时用的那套、测试命令有没有写对、目录结构的描述是否大致符合实际。自动识别不会100%精确，比如一个同时存在Maven和Gradle文件的项目，它可能选了其中一个作为默认，这就需要你手动修正。

2.3 生成后的AGENTS.md长什么样

以我最近处理的一个Spring Boot项目为例，生成后的文件大概包含这么几个区域：项目简介、常用命令（build/test/run）、代码风格约定、目录结构说明。Markdown的层级清晰，后面Codex读取时也容易解析。

我摘一段当时生成的骨架，给你们做个参考：

# AGENTS.md ## 项目简介 这是一个基于 Spring Boot 的订单服务，使用 Java 17 编写。 ## 常用命令 - 构建：mvn clean package - 测试：mvn test - 运行：mvn spring-boot:run ## 代码风格 - 遵循阿里巴巴规约，禁止魔法值，常量必须定义 - 包结构按模块划分：controller/service/repository ## 目录说明 - src/main/java：业务代码 - src/test/java：单元测试

注意，这些内容是自动生成的初步版本，不是最终答案。我会把“阿里巴巴规约”这种团队规范手动追加进去，因为工具不可能知道你们内部用的规范是什么。工具的价值在于提高起点，而不是替代人的判断。

3. 日常使用指南：把superpowers融入Codex工作流

3.1 什么时候该重新初始化

AGENTS.md不是写一次就一劳永逸的。项目结构变化、构建工具升级、目录大调整，都会让旧配置失真。我自己定的节奏是：每个迭代结束做一次检查，如果发现Codex最近频繁给出不符合项目现状的命令，就重新跑一次superpowers init，看它生成的差异。

但重新初始化前，务必确认现有AGENTS.md有没有你手动补充的重要规则。如果有，先commit或者复制一份备份，否则工具很可能直接覆盖掉。我吃过这个亏：手动加了半天的团队规范，一次重新init全没了。现在我的习惯是，手动补充的部分集中放在AGENTS.md末尾，并且用注释块隔开，这样即使重新生成，我也能快速恢复。

3.2 用自定义命令扩展提示词

superpowers另一个很实用的能力是自定义命令。你可以把项目里高频使用的Codex提示词固化成一个短命令，比如用superpowers add定义一个名为review的命令，内容是一段完整的Codex提示词，要求它按AGENTS.md里的规范做代码审查。之后需要做审查时，直接唤起这个命令，Codex就会带着完整的上下文执行。

这个方法特别适合团队规范化。比如你们约定提交前必须让Codex检查一遍测试覆盖率和命名规范，把这些要求写成命令模板，新人上手也能保证输出质量。从工程效率角度看，相当于把团队经验沉淀到了工具配置里，而不仅仅是靠人传人。

3.3 对未提交变更的态度：自动清理与保护

我见过不少CLI工具在初始化时会把无关文件删得干干净净，superpowers在这点上相对克制，但也不是没有风险。因为Codex本身有执行终端命令的能力，如果你在bash里强烈要求它自己“清理环境”或“重置目录”，它可能会按照AGENTS.md里的命令去执行，而不区分哪些是自动生成的。

所以我的建议是：在AGENTS.md里明确写上“不要删除任何未提交的文件”“不要执行git clean”这类禁止性规则。工具生成的初始模板不一定包含这些约束，你需要自己补上。说到底，AGENTS.md既是给Codex的指引，也是给它划的安全边界。

4. 以Java项目为例的实战拆解

4.1 Maven与Gradle的识别逻辑

搜索词里“superpowers java”热度很高，我猜不少人是想在Java项目里用这个工具。Java项目跟前端项目最大的不同是构建体系相对复杂：Maven、Gradle都能构建同一个项目，但命令差异很大。superpowers这类工具通常通过根目录的pom.xml或build.gradle文件来判断，检测到哪个就生成对应的命令模板。

但有个尴尬情况：一个仓库里同时存在多个模块，有的模块是Maven，有的是Gradle。这种情况我建议你手动改AGENTS.md，明确告诉Codex“外层用Maven，service模块用Gradle”，否则它很容易在错误的目录里执行错误的构建命令。我的经验是，对多模块Java项目，初始化后一定要自己跑一遍mvn test和./gradlew test，确认生成的命令正确，再让Codex接管。

4.2 Java项目的AGENTS.md应包含哪些关键信息

结合我用下来的体会，一个能真正指导Codex的Java项目AGENTS.md，至少要覆盖这些：

• 构建命令：明确是mvn还是./gradlew，是否要跳过测试，是否要指定profile。
• 测试命令：单测、集成测试要分开说，不能混为一谈。Codex如果默认把集成测试也跑一遍，单次会话耗时会被拖垮。
• 包结构约定：比如禁止在controller里写业务逻辑、统一使用Result<T>包裹返回。
• 依赖管理：是否允许直接改pom.xml，还是必须走集中式BOM管理。

工具能自动生成的主要是前两项，后面几项基本靠手动补充。不过这也正常，越是团队特有的约束，越难靠通用工具猜出来。

4.3 一次完整的Java项目工作流演示

我拿一个典型的场景演示一下。假设我接手一个新Java服务，第一步我会运行superpowers init生成AGENTS.md，然后手动补上团队规定和禁止性条款。第二步启动Codex会话，让它先读AGENTS.md，再提出需求，比如“给订单模块增加一个幂等校验”。

因为AGENTS.md里已经写清了项目是Maven、Java 17、包结构如何组织，Codex的第一次响应就不会出现“让我先看看你的项目结构”这种通用回答，而是直接定位到src/main/java下的对应目录，给出符合现有风格的代码。测试命令它也会用mvn test去跑，而不是瞎猜./gradlew test。这个体验上的差别是巨大的。

再补充一个细节：当你让Codex修改代码时，它可能会在你没注意的时候运行格式化命令。如果项目里统一用的是Spotless或Checkstyle，建议把对应命令写进AGENTS.md，否则Codex可能用默认格式器，产生一堆无意义的diff。这个坑我踩过不止一次，现在写进AGENTS.md以后，格式化问题基本绝迹了。

5. 常见问题与排查技巧实录

5.1 安装失败与版本相关

npm安装失败是我被问过最多的问题，这里列一下我碰到过的场景。最常见的是Node版本过低，CLI的某些依赖要求Node 18+，但本机还是16.x。其次是npm全局目录没有写入权限，报错信息通常是EACCES。我的建议是使用nvm管理Node版本，并把npm prefix指向用户目录，一劳永逸。

这类问题未必是工具本身的问题，更多是Node环境没配置干净。所以如果遇到奇怪的报错，我建议先跑一下node -v和npm -v，确认基础环境正常再说。

5.2 Codex不读取AGENTS.md

另一个高频问题是：AGENTS.md明明生成了，但Codex好像无视它。这时先确认文件是否在项目根目录，文件名大小写是否正确；其次看你启动Codex的工作目录跟项目根目录是否一致。Codex是在当前目录启动时读取项目上下文的，如果你在子目录里启动，它很可能没有找到根目录的AGENTS.md。

如果确认路径没问题，但Codex仍然“装失忆”，可以试试在会话开头主动提一句“请先阅读项目根目录的AGENTS.md”，把它变成明确的用户指令。虽然理想情况下，Codex应该自动读取，但实际使用中显式提一句往往更稳定。这是我反复验证过的土办法，好用。

5.3 语言识别不准确

多语言项目里，语言识别不准挺常见。比如一个同时有package.json和pom.xml的仓库，工具可能默认识别成JavaScript项目，生成的AGENTS.md完全没有Java内容。这种情况建议手动指定语言，或在生成后手动修正。

我一般在初始化后都会做一个“人工复核”动作：把AGENTS.md里的命令逐个在终端跑一遍。听起来麻烦，但习惯了之后，每个项目也就多花几分钟，却能避免Codex在实际操作中反复跑错命令。复核之后，再让Codex基于这份文档去干活，明显省心很多。

5.4 多模块与大仓库

最后说一下多模块仓库。很多Java项目都是一个git仓库里放多个服务，根目录没有统一的构建文件。这种情况直接在根目录跑superpowers init，生成的结果往往不太理想。我建议每个模块单独初始化，再在根目录写一个很薄的AGENTS.md，指向各个模块的说明文件。

举个例子，仓库结构是services/order和services/user，那么在services/order下执行初始化，生成这个模块的AGENTS.md；根目录的AGENTS.md只写两行：模块列表，以及“详细信息见services/order/AGENTS.md”。这样Codex每次对话前能快速定位到正确的工程上下文，不会在根目录做无意义的猜测。这也是我接手多模块Java仓库后总结出的最优实践。

我在实际使用中最大的一个感受是，superpowers这类工具的价值不在于它生成了多复杂的配置，而在于它逼着我把“项目规则”这件事从口头约定变成了文件系统里真实存在的东西。只要AGENTS.md在，不管是我自己还是Codex，做任何操作之前都能先对齐规则。如果你也想试试，我的建议是别在生产仓库上直接初始化，先拿一个测试项目跑通全流程，把生成结果、手动补充内容、重新初始化的风险都摸一遍再上正式环境。另外，记得定期把团队规范同步进AGENTS.md，别让这份文件变成新的“僵尸文档”——它和普通README一样，需要被维护，而不是写一次就遗忘。