写代码这件事过去几年最大的变量就是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有了“手”技能和记忆解决的是“会干活”和“记得事”MCPModel 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命名规范、返回统一封装ResultT。然后你对它说新增一个查询用户订单列表的接口用户ID从请求头获取。要求分页返回并附上订单创建时间倒序排序。参考java-microservice技能。注意这句描述里的“参考java-microservice技能”。虽然设置了trigger机制但明确点名技能依然是最稳妥的做法。AI会去读取~/.superpowers/skills/skill-definitions/java-microservice.md按照文件里定义的流程一步步执行它先解析出需求涉及的两个实体用户User和订单Order。定义请求参数类OrderQueryDTO包含pageNum和pageSize字段做了Min校验。定义响应VOOrderVO把订单核心字段透出没有暴露数据库字段。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文档写作。每个主题一套SOPAI都能直接执行。你积累的不只是配置文件而是团队的“操作手册全集”。5.2 持续迭代技能文件的“进化”逻辑最后说一个我认为最重要的心法superpowers不是一个一次性搭好的静态环境而是一个要持续演进的“活系统”。它的价值完全取决于你对它的反馈循环有多勤快。我现在的工作习惯是每当AI做完一件事我会在review时问自己三个问题哪些步骤它是做得对的对的流程是否值得固化到技能文件里哪些步骤它做偏了是不是技能文件里没写清楚这个偏好这个项目有哪些新的“潜规则”是在沟通中才暴露出来的要不要沉淀到AGENTS.md或模块记忆文件带着这三个问题每天花10分钟更新配置两周后你的superpowers就完全“私有化”了——它不再是一个通用AI而是“知道你的审美、懂你的代码洁癖、记住你们项目每个历史坑”的专属搭档。我自己的体验是从裸用Codex到搭建完整superpowers体系前期大概有3天左右的“配置阵痛期”因为你得逼自己把平时凭感觉做的事写成规则。但这三天投入换来的是之后的“无痛驾驶”——每次开新的会话它都像是从未离职过的老员工接上上下文就能继续干活。如果你也想让自己的AI助手从“能用”变成“好用”从今天开始先写一个你最常做任务的技能文件配上项目AGENTS.md跑通一个任务。剩下的交给时间和持续迭代。动手吧这才是superpowers真正的用法。