写代码这件事，过去几年最大的变量就是AI助手。从最早的代码补全，到能听懂人话的对话式编程，再到今天能自主跑测试、修bug的智能体，工具链更新换代的频率快得让人措手不及。如果你已经用上了Codex CLI这类命令行编程助手，大概率会碰到一个瓶颈：助手确实聪明，但它不了解你和你的项目的“规矩”。比如它不知道你的代码风格偏好，不记得上一轮改到哪儿了，每次都要你重新解释一遍上下文。这种挫败感，用过的人都懂。
我在折腾了两个月之后，终于把一套叫“superpowers”的玩法跑通了。它不是某个单独的工具，而是一套给Codex CLI这类编程助手“加buff”的组合方案：用自定义指令、技能库、记忆文件和MCP服务，把AI从“能用”拉到“好用”。这篇文章不跟你聊虚的，直接把我的完整配置、踩坑记录和几个真实场景复现步骤放出来，想省时间的直接抄作业。
1. 项目核心思路：为什么要叫“superpowers”
1.1 痛点诊断：AI编程助手差在哪
我最早用Codex CLI写项目时，感觉就像雇了一个特别聪明但从没在你公司上过班的临时工。代码能力没得说，但每次交接都要花十分钟讲背景：项目的架构是啥、代码风格什么要求、数据库设计遵循什么规范、测试要跑到什么覆盖率。讲完这些，它才能进入状态干活。而真正写起来又是一堆小摩擦：生成的文件路径不对，它不主动改；跑完测试报错了，它不会自动追踪上一轮改了啥；你上午让它重构了A模块，下午再说B模块的改动，它已经忘了A模块是怎么改的。
这些问题的根源，是大多数AI助手默认“无状态”——你给它一个上下文窗口，它在这个窗口内很聪明，但窗口一关就全忘了。superpowers这套方案解决的就是这个根本矛盾：把“临时协作”变成“长期共事”。核心思路是三层：
- 技能库（Skills）：把你在某个场景下的工作流固化成指令文件，比如“写Java接口时要先定义DTO再写Controller最后补测试”的流程，让AI按套路出牌。
- 记忆机制（Memory）：用专门的记忆文件记录项目的技术决策、架构演变、待办事项，让AI每次开工前先“翻档案”。
- 上下文管理器（Sessions）：把一次会话当成一个“项目现场”，AI在会话过程中随时把状态、进展、下一步计划落盘，下次接着干。
这三层玩明白了，你的AI助手就从一个“偶尔灵光一现的新人”变成了“熟悉你所有习惯的老师傅”。
1.2 适合谁看、能解决什么问题
如果你符合下面任意一条，这篇文章的内容能直接救你出火坑：
- 已经在用Codex CLI，但总觉得“差点意思”，主要时间花在反复解释项目背景。
- 想尝试AI智能体编程，但对着一堆配置文件和概念无从下手。
- 在用Cursor、Claude Code或者其他AI编程工具，但苦于没有一套自己的“行为公约”。
- 团队里想做AI辅助开发的标准化，需要一个现成的模板打底。
我这里强调的是Codex CLI生态，但你放心，思路是通用的。不管底层是Claude、GPT还是开源模型，superpowers这套“技能+记忆+会话”的组合框架都能迁移。模型是大脑，这套配置就是大脑的“职业训练”。
2. 核心细节拆解：superpowers的三大核心模块
2.1 技能指令库（Skills）：给AI一份SOP
技能指令库看上去就是一堆Markdown文件，但它是整套方案里最考功力的部分。每个技能文件定义一个完整的工作流程，AI在遇到对应任务时会自动读取并严格按流程执行。我的目录结构长这样：
superpowers/ └── skills/ ├── skill-definitions/ │ ├── java-microservice.md │ ├── frontend-debugging.md │ ├── database-migration.md │ └── code-review.md └── workflows/ ├── job-queue-pattern.md ├── api-exploration.md └── test-driven-development.md每个技能文件都有固定的frontmatter格式，AI能快速识别这个技能是干什么的、什么时候触发。举个例子，我的“Java微服务开发”技能文件开头是这么写的：
--- name: java-microservice description: 适用于Spring Boot微服务的新功能开发与接口实现，包括分层架构、DTO设计、异常处理与测试规范。 triggers: - "新增接口" - "实现业务逻辑" - "创建RestController" ---trigger定义很关键。有了它，AI在任务规划阶段就能自己判断“这个需求落到了哪个技能范围内”，不需要你每次手动点技能。我在实际使用中发现，trigger描述得越具体，AI的命中率越高。刚开始我只写了“java开发”这种宽泛词，结果AI经常识别不到；改成“新增接口”、“写Mapper”这种动作词之后，准确率直接从40%飙到90%。
技能文件的主体部分，就是一步步的工作流程。这里有一个核心原则：能写多细就写多细，任何你觉得“AI应该自己懂吧”的步骤，都可能被它跳过。比如我写“新增接口”时，流程是这样的：
- 分析需求，识别涉及的业务领域和实体模型。
- 定义请求DTO和响应DTO，注意字段命名与校验注解。
- 编写Controller层，只负责参数校验和响应封装，不写业务逻辑。
- 在Service层实现业务逻辑，使用事务注解。
- 编写Mapper或Repository层，SQL必须带索引字段。
- 生成单元测试，覆盖Controller层、Service层核心逻辑。
- 执行mvn test，确认所有测试通过后再要求人工review。
每一步之间的逻辑关系要讲清楚，为什么先定义DTO、为什么Controller不允许写业务逻辑，这些都要明明白白写在技能里。AI不是不懂，而是它默认会选择最“省路径”的方式——如果你不写清楚，它能给你把一堆逻辑塞进Controller里。
另一个容易被忽视的技巧：技能文件里要写“禁止事项”。比如我的前端调试技能里有一条“禁止直接修改node_modules目录内的文件”，数据库技能里有一条“禁止在生产环境执行DDL操作”。这些底线写清楚，AI就不会在需要人的判断环节自作主张。
2.2 记忆与状态持久化：AI不患失忆症
如果说技能库是“肌肉记忆”，那么记忆文件就是AI的“长期记忆皮层”。我项目中维护的核心记忆文件有三个，各司其职：
第一个是AGENTS.md，放在项目根目录，记录的是项目级绝对规则。哪里放什么代码、包名怎么起、日志规范是什么、数据库连接串在哪配，这些“项目宪法”全写在这里，AI每次启动时会自动读取。我见过很多人忽视这个文件，结果AI生成的代码全是通用风格，和现有工程风格格格不入。
第二个是SESSIONS.md，这是superpowers方案里我最看重的一个文件。每次会话开始，AI会读取这个文件了解当前进行到哪一步；会话过程中，它会持续追加内容；会话结束时，它会更新状态。这就相当于“项目黄历”——清清楚楚记录了几月几号干了什么事、下一步该干什么、哪些坑已经踩过了。我的会话文件里有一个“当前任务”区块，写的是：
## 当前任务状态 - 上次更新：2025-01-12 14:30 - 进行中：订单模块的Kafka消费端改造 - 已完成：生产端发送逻辑、消息体schema定义 - 受阻：消费端事务边界不清晰，等待确认是否需要引入分布式事务 - 下一步：（待处理）消费者的幂等性考虑使用Redis SETNX方案，改进前需和组内确认第三个是区域性的记忆文件，放在各个子模块下。比如backend/memory/目录里记录数据库设计变更，frontend/memory/记录组件库使用约定和样式体系。这种本地化记忆比全项目一个文件更精准，AI在处理某个子模块时不用加载一堆无关信息。
记忆机制的核心挑战是“读什么、不读什么”。信息全塞进去，上下文窗口很快就撑爆了。我的实践经验是：项目根目录的AGENTS.md控制在50行以内只写“不遵守就会出事”的规则，SESSIONS.md记录最近7天的工作状态（太旧的滚动归档），模块级记忆文件控制在100行以内。这样AI每次启动要读的核心信息不超过几千个token，既省上下文又够用。
2.3 MCP服务集成：让AI有了“手”
技能和记忆解决的是“会干活”和“记得事”，MCP（Model Context Protocol）解决的是“碰得到东西”。没有MCP的AI助手，就像一个只能看到思维但摸不到世界的大脑——它看不到你本地的文件结构，跑不了命令，查不了数据库。
我给Codex CLI配了三个最常用的MCP服务：
- filesystem：读写本地目录文件，这让AI不用依赖shell命令就能查看和编辑项目文件，路径感知更准。
- fetch：抓取和分析远程URL内容，比如看个文档网页、拉个接口返回示例、查个依赖包说明。
- chrome-devtools：让AI可以控制一个浏览器，打开网页、看console报错、分析网络请求。前端调试的神器。
MCP的配置在Codex CLI的设置文件里，类似这样：
{ "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "./"] }, "fetch": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-fetch"] }, "chrome-devtools": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-chrome-devtools"] } } }配置MCP服务这件事，日常最常踩的坑有两个：一是NODE_PATH没配好，导致npx找不到全局包；二是权限边界没想清楚，MCP给了AI太强的文件操作能力，它可能在你没注意的时候改了不该改的文件。我的建议是，filesystem服务初始范围只指向工作目录，不要直接指向整个用户根目录。chrome-devtools服务只在需要调试前端页面时才临时启用，平时不挂载，省资源也降低风险。
3. 实操过程：完整配置一套superpowers环境
3.1 从零开始的配置步骤
我以macOS + Codex CLI为例，完整跑一遍配置流程。Windows和Linux的区别主要在第1步的安装方式上，其他基本一致。
第1步：安装Codex CLI
如果你还没用上Codex CLI，先装这个。它是OpenAI推出的开源命令行AI编程助手，可以直接跑在终端里，支持读取本地项目、执行命令、多文件编辑。
npm install -g @openai/codex安装完先跑一下codex --version确认装好了。首次运行会让你登录账号，这一步按提示走完，之后codex就能正常对话。
第2步：创建superpowers目录结构
我还是建议把superpowers配置独立成一个目录，不直接污染你的项目仓。这样多个项目都能复用同一套技能库，改动一处全局生效。
mkdir -p ~/.superpowers/skills/skill-definitions mkdir -p ~/.superpowers/skills/workflows mkdir -p ~/.superpowers/sessions mkdir -p ~/.superpowers/memory把技能文件丢到sills/skill-definitions下面。同时，在你的项目根目录放一个AGENTS.md（项目规则）和一个SESSIONS.md（会话状态），这两个是本项目的实时状态文件。
第3步：配置Codex的启动行为
Codex CLI支持通过配置文件加载“预先指令”，这样每次启动时它可以先读取AGENTS.md和SESSIONS.md。在~/.codex/config.toml里加一段：
[start] instructions = [ "先读取根目录下的AGENTS.md，熟悉项目规则后再开始工作。", "读取SESSIONS.md，了解当前任务状态，如存在'下一步'计划，按计划继续推进。", "涉及标准开发流程时，从~/.superpowers/skills/中读取对应技能文件并严格遵循。" ]很多朋友在这一步会犯的错：以为只在system prompt里写清楚就够了。实际上，skill文件和AGENTS.md这类外部记忆，必须通过指令显式唤醒才会被读取。启动指令写得越具体，AI自主触发的概率越大。
第4步：创建你的第一个技能文件
我建议从你最常做的任务类型开始写，而不是一上来想着覆盖所有场景。比如你是Java后端为主，就先写java-microservice这个技能文件。写的时候不要追求一步到位，先按你手头项目的实际操作流程写一版，用两周之后回头修订，把AI执行时暴露出来的模糊步骤改具体。
第5步：初始化SESSIONS.md
在项目根目录新建SESSIONS.md，首次内容不用复杂：
# 会话记录 ## 当前任务状态 - 上次更新：启动日期 - 进行中：（无） - 已完成：（无） - 受阻：（无） - 下一步：初始化项目结构，开始第一个功能开发。这个文件是“活的”，你要习惯在每次合作结束后让AI花30秒更新它。养成这个习惯后，你会发现跨会话协作的顺畅度是质变。
3.2 Java实战：用superpowers写一个完整接口
理论说再多不如直接跑一遍。下面我用一个具体的Java接口开发，演示superpowers在真实工作流里是怎么运作的。
需求背景：假设你的项目是Spring Boot单体应用，要新增一个“查询用户订单列表”的接口。你打开终端，输入：
codex按我的配置，Codex启动时会自动加载AGENTS.md和SESSIONS.md，它就知道这个项目的包结构是com.example.order、使用MyBatis-Plus、DTO命名规范、返回统一封装Result<T>。然后你对它说：
新增一个查询用户订单列表的接口，用户ID从请求头获取。要求分页返回，并附上订单创建时间倒序排序。参考java-microservice技能。
注意这句描述里的“参考java-microservice技能”。虽然设置了trigger机制，但明确点名技能依然是最稳妥的做法。AI会去读取~/.superpowers/skills/skill-definitions/java-microservice.md，按照文件里定义的流程一步步执行：
- 它先解析出需求涉及的两个实体：用户（User）和订单（Order）。
- 定义请求参数类：
OrderQueryDTO，包含pageNum和pageSize字段，做了@Min校验。 - 定义响应VO：
OrderVO，把订单核心字段透出，没有暴露数据库字段。 - Controller层写了一个
@RestController，从HttpServletRequest里取userId，封装好参数后调Service。 - Service层实现查询逻辑，用了MyBatis-Plus的
LambdaQueryWrapper做分页和排序。 - 补了一个单元测试，用MockMvc模拟请求并验证返回结构。
整个过程大约3分钟，期间代码就出现在了项目里。你只需要在它完成后做一次review，看看业务判断有没有偏差——真正“写”的活基本被包了。
这个流程里最能体现superpowers价值的地方在于：AI的做法完全符合你们项目的习惯。它没有擅自把DTO和Entity搞混，没有把业务逻辑堆在Controller里，没有为了“省事”不写测试。这些全是技能文件和AGENTS.md的功劳。
3.3 前端场景：用chrome-devtools调试一个样式问题
另一个高频场景是前端样式bug。传统做法是自己打开浏览器、找元素、看样式、改代码，循环无数遍。配置了chrome-devtools MCP之后，这个流程可以变得极快。
我让你的需求是：“首页导航栏在移动端宽度下出现横向滚动条，需要修复。”启动codex后，直接说：
打开本地开发环境的首页，用移动端视口模式检查导航栏横向滚动条的问题。定位原因并修复。
AI会通过chrome-devtools MCP启动一个浏览器（开发者模式），自动切换到375px宽度的视口，打开http://localhost:3000，截取首屏快照。它会在Console里检查报错，在Elements里检查导航栏容器的宽度和overflow属性，在Network里看资源是否异常加载。定位到是某个容器设置了min-width: 1200px导致视口内溢出后，它会直接在代码里修正——把min-width改成min-width: auto或者加overflow-x: hidden，然后重新刷新浏览器验证。
这个场景里，最爽的不是它替你改样式，而是连“打开浏览器看效果”这个动作它都替你做了。我实际测试下来，一个中小型样式bug，从提出需求到修复验证，平均5分钟内能完成。传统手工排查起码要15分钟起。
注意chrome-devtools MCP有个限制：它跑的是Chromium的开发者模式实例，有些需要登录的页面会卡在登录态。我一般遇到需要登录的场景，先在正常浏览器完成登录，然后导出Cookies给AI用，或者绕过登录态只测可匿名访问的页面。
4. 常见问题与排查技巧实录
4.1 高频问题速查表
| 现象 | 可能原因 | 解决方案 |
|---|---|---|
| AI启动后完全不读技能文件 | 启动指令没写，或者技能文件路径不对 | 确认config.toml的start指令里有“读取skill文件”的内容，检查路径是否指向实际存在的文件 |
| 技能文件明明存在但AI就是不触发 | trigger关键词描述太宽泛或太具体 | 把trigger改成“动作+对象”结构，比如“新增接口”、“修改Mapper”，不要用单个名词 |
| 会话跨天之后AI忘了之前做到哪 | SESSIONS.md未在会话结束时更新 | 每轮任务完成后固定让AI补写SESSIONS.md，把“已完成任务”和“下一步计划”写清楚 |
| MCP服务报“unable to start” | npx找不到包或node版本过低 | 确认node版本在18以上，尝试用npx -y @modelcontextprotocol/server-xxx手动跑一次看报错信息 |
| AI改代码时动了不该动的文件 | MCP文件访问权限太宽 | 给filesystem的根路径限定到项目工作目录，不要指向用户根目录。关键目录用.gitignore排除 |
| 生成代码风格与项目不一致 | AGENTS.md里没有明确的代码规范 | 把编码规范、包名风格、命名约定、注释要求、禁止事项全量写入AGENTS.md |
| 上下文窗口很快被占满 | 技能文件或者记忆文件太长，或SESSIONS.md从未清理 | 按“最近7天”窗口清理SESSIONS.md，技能文件控制在100行以内，前言信息尽量精简 |
| AI频繁修改已经稳定的代码 | 缺少对“已稳定模块”的只读标记 | 在AGENTS.md里写明哪些目录是“只读参考”，哪些是“可修改范围” |
| 使用superpowers后仍觉得AI“傻” | 期望太高，或缺少对AI输出的有效反馈循环 | 每次review发现问题时，不仅改代码，还要把问题原因回写到技能文件，形成闭环优化 |
4.2 我踩过的三个大坑
第一个坑是技能文件写得太“教科书”。我最初写java-microservice技能时，把流程写成“1. 分析需求 2. 设计数据库 3. 编写接口...”——每个步骤只有一句概括，结果AI执行时依然“自由发挥”。后来我把每个步骤后面的“预期产出”和“验收标准”都写出来，比如“分析需求后，输出一份包含接口字段清单的简短文档，再开始写代码”。这个“先产出、再动手”的节奏，让AI的每一步都有中间校验点，质量明显提升。
第二个坑是上下文窗口无节制增长。有一段时间我让AI在每轮任务后把全部中间结果都写进SESSIONS.md，结果文件膨胀到几千行，后面直接“爆”了。现在的方案是只让它写“当前状态、遇到的阻塞、下一步”，最多20行。中间的分析过程如果不重要，直接丢弃。这样SESSIONS.md始终是稳定的“状态指针”，而不是“过程流水账”。
第三个坑是我一开始把AGENTS.md写得太长，50条规范全堆上去。结果AI反而无所适从，分不清哪些是“必守底线”哪些是“建议风格”。后来我砍到12条以内，只保留“不遵守会导致事故”的硬规则，比如“禁止修改生产数据库”、“禁止删除未备份文件”、“所有返回必须统一Result封装”、“接口文档注释必须同步更新”等。建议项全部移除，效果反而更好。
4.3 团队协作时的配置同步问题
如果你是单人用，配置到这里已经很舒服了。但如果你们团队想统一收编这套玩法，有两个协作层面的问题要提前解决：
第一是技能库的版本管理。我的做法是单独建一个Git仓库存放~/.superpowers下的技能文件和workflow模板。团队成员clone下来后，用符号链接或者一键脚本挂到自己的用户目录。任何人对技能的改进，走MR流程合并，其他人pull之后立刻生效。这比口头传文件强一百倍。
第二是AGENTS.md的冲突管理。开发业务代码的人是高频使用方，AGENTS.md是他们“喂”出来的。但技术负责人也要把控规范演进。我们团队的做法是：AGENTS.md由技术负责人审核后写入主干，业务开发者遇到的规则问题先提issue，不要自己擅自改主干文件。这避免了规范混乱和“同一件事两种说法”的难题。
还有一个团队级别的技巧：给不同项目配不同“profile”。比如需要严格测试覆盖的金融项目，技能文件里就加上“每个功能必须带完整单元测试，覆盖率不低于80%”；快速原型项目，技能文件里就写“优先快速跑通主流程，测试只做冒烟级别”。不要试图用一套技能库硬套所有项目——规则越贴合业务特征，AI的表现越让你惊喜。
5. 进阶玩法：把superpowers变成你的“第二大脑”
5.1 打造个人知识沉淀系统
你可能会问：我搭建这个环境只是为了提升写代码效率，但superpowers的价值远不止“写代码快”。
因为你让AI写技能文件、记忆文件的过程，本质上是在把“你团队里那个资深开发的经验”外化、结构化、固化下来。当我把“如何设计一个易扩展的订单状态机”、“如何排查线上偶发超时”这类经验写成技能文件后，我发现新人培训变的极其丝滑——新同事问问题时，直接让他看对应技能文件，比人肉讲一遍高效得多。AI再配合这些技能去辅导新人，更是如虎添翼。
所以我的建议是，不要局限于“代码开发”这个范畴。你可以给superpowers技能库加各种主题：代码审查、SQL调优、架构评审、API设计评审、技术方案撰写、甚至Readme文档写作。每个主题一套SOP，AI都能直接执行。你积累的不只是配置文件，而是团队的“操作手册全集”。
5.2 持续迭代：技能文件的“进化”逻辑
最后说一个我认为最重要的心法：superpowers不是一个一次性搭好的静态环境，而是一个要持续演进的“活系统”。它的价值完全取决于你对它的反馈循环有多勤快。
我现在的工作习惯是：每当AI做完一件事，我会在review时问自己三个问题：
- 哪些步骤它是做得对的？对的流程是否值得固化到技能文件里？
- 哪些步骤它做偏了？是不是技能文件里没写清楚这个偏好？
- 这个项目有哪些新的“潜规则”是在沟通中才暴露出来的，要不要沉淀到AGENTS.md或模块记忆文件？
带着这三个问题，每天花10分钟更新配置，两周后你的superpowers就完全“私有化”了——它不再是一个通用AI，而是“知道你的审美、懂你的代码洁癖、记住你们项目每个历史坑”的专属搭档。
我自己的体验是，从裸用Codex到搭建完整superpowers体系，前期大概有3天左右的“配置阵痛期”，因为你得逼自己把平时凭感觉做的事写成规则。但这三天投入换来的是之后的“无痛驾驶”——每次开新的会话，它都像是从未离职过的老员工，接上上下文就能继续干活。
如果你也想让自己的AI助手从“能用”变成“好用”，从今天开始，先写一个你最常做任务的技能文件，配上项目AGENTS.md，跑通一个任务。剩下的，交给时间和持续迭代。动手吧，这才是superpowers真正的用法。
