最近这几个月我几乎每天都在和 Codex CLI 打交道但真正让我从会用 AI 写代码变成敢把 AI 写代码当日常工作流的反倒是这个叫 superpowers 的项目。如果你也用过 Claude Code、Codex CLI 这类工具你大概率也遇到过同样的问题它很聪明但像一个记性差、还总爱自作主张的实习生——你交代需求它一口气给你吐几百行代码看着挺像回事一跑就发现要么漏了边界条件要么根本没按项目里的既有约定来。superpowers 解决的就是这个事。它不是一个新模型也不是一个 IDE 插件而是一套给 AI 编程代理加的技能增强层通过技能skills、工作流workflow、子代理subagent和记忆memory四个核心机制把资深工程师的工作习惯结构化地灌进 AI 的上下文里。支持接入 Codex CLI、Claude Code 等主流命令行编程工具。无论你是 Java、Python、前端还是全栈只要你愿意让 AI 在动手前先思考、先规划、再按纪律执行这篇文章值得你花十分钟读完。1. superpowers到底解决了什么问题1.1 从代码生成器到会工程的协作者先聊聊我自己的痛点。在接触 superpowers 之前我对 Codex CLI 的使用方式非常简单粗暴给它一个需求它直接生成实现。小型任务还行比如写个工具函数解析这段 JSON但一旦遇到跨文件、多模块的中型任务问题马上暴露。印象最深的一次我让它重构一个支付回调的处理方法它直接把整个类重写了参数列表、异常处理、日志风格全都改了。功能确实跑通了但 code review 的时候同事直接炸毛这代码风格跟整个项目根本不是一个路子。更麻烦的是它没有留下任何重构说明我根本不知道它动了哪些调用方。这类问题的本质是什么是 AI 编程工具天然缺乏工程约束。它知道大量代码但它不知道你这个项目的约定、不知道哪些模块是敏感地带、不知道先写测试再写实现这种基本流程。你指望靠提示词把这一切说清楚每次会话都要重新说一遍而且说多了上下文就爆了。superpowers 的核心思路相当直白把这些工程纪律从你每次临时输入的提示词变成AI 每次自动加载的文件和流程。它不追求让 AI 更聪明而是让 AI 按一个有经验的人的方式工作。1.2 四个核心机制技能、工作流、子代理、记忆拆开看superpowers 的架构由四个概念组成技能Skill本质是一份结构化的 Markdown 文档通常叫 SKILL.md。里面写清楚这个技能解决什么问题、在什么场景触发、执行时遵循哪些步骤、有哪些红线不能碰。AI 在会话中会根据描述自动判断何时调用它。工作流Workflow多个技能的有序串联。比如先规划、再写测试、再实现、最后审查就是一个工作流。它们被拆成模板AI 执行时不会跳过中间环节。子代理Subagent独立的、上下文隔离的小对话。比如你让主 AI 开发功能同时派一个代码审查子代理去看改动它的上下文只关注审查不会被主任务冲淡。这在大型任务里尤其好用。记忆Memory跨会话的项目状态存储。AI 会把重要决策、已知问题、未完成任务写到 memory 文件里下次开新会话自动读取。相当于给 AI 配了一个长期记忆库不用每次从零开始。这四个机制组合起来就等于你给每个 AI 会话配备了一份岗位手册 项目历史档案 工作流程模板。1.3 和多写几句提示词的差别在哪有人可能觉得这不就是把提示词换成文件吗差别很大。提示词是一次性的、碎片化的。你这次写请先写测试再写实现AI 照做了下次你不写它就忘了。而且提示词很难承载复杂流程你很难用一段话让 AI 同时记住先分析影响面、再定接口、写测试、重构、跑 mvn test、审查 diff这一整套动作。技能文件则是持久的、经过验证的。它不只是描述性文字还包含边界条件和执行纪律。比如一个代码审查技能里会明确写审查时不得修改代码、必须按严重程度输出问题清单、必须指出测试覆盖盲区。这是普通提示词很难做到的约束力。我给个更直白的类比提示词像是你临时口述的要求技能像是公司里沉淀下来的 SOP 文档。口述的东西全靠对方记性和自觉SOP 文档才是真正能稳定复现工作质量的东西。2. 环境准备与安装三大主流代理配置一次说清2.1 前置依赖到底需要什么superpowers 本身是一个开源项目理论上你只需要三个东西Node.js建议 18 以上安装脚本和部分 CLI 工具依赖它Git用于从仓库拉取代码和后续更新你常用的 AI 编程 CLI 工具之一比如 Codex CLI、Claude Code我测试时用的是 Node 20、Codex CLI 的最新稳定版和 Claude Code 1.x跑下来没遇到兼容性问题。如果你本机还没装 Node先去官网下载 LTS 版本装上这一步不用赘述。多说一句不要用 sudo 把 superpowers 装到全局目录。它本质是往你的用户目录写配置和技能文件装到全局反而容易出现权限混乱更新时还要反复输密码。老老实实装在用户目录即可。2.2 拉取仓库并执行安装我当时用的安装方式大致是这样git clone https://github.com/obra/superpowers.git cd superpowers npm install node bin/install.js安装脚本跑完之后它会在你的用户目录下创建几个关键路径~/.superpowers/主目录技能库和配置都在这~/.superpowers/skills/所有技能的存放位置每个技能一个子目录~/.superpowers/config.json全局配置决定哪些代理启用了哪些技能不同版本路径可能略有差异但大差不差。如果你在安装时想自定义技能存放目录可以在执行脚本前设置环境变量指向自己的目录我建议保持默认少折腾。2.3 接入 Codex CLIAGENTS.md 是那把钥匙Codex CLI 本身有一套项目指令机制它会读取当前工作目录下的AGENTS.md文件把它作为项目级的系统提示。superpowers 接入 Codex 的关键就是把技能索引写进这个文件。我当时的做法是在项目根目录的AGENTS.md里加上这样一段## Available Skills You have access to the following skills. Read the corresponding skill file before using them: - Planning: ~/.superpowers/skills/planning/SKILL.md - TDD: ~/.superpowers/skills/tdd/SKILL.md - Code Review: ~/.superpowers/skills/code-review/SKILL.md - Debugging: ~/.superpowers/skills/debugging/SKILL.md注意这里写的是绝对路径。如果你希望多个项目共用同一套技能可以把这个文件放在你的全局配置里如果你只想让个别项目使用放在项目根目录的 AGENTS.md 里最合适。2.4 接入 Claude Code插件配置方式如果你用的是 Claude Code接入方式类似但入口不同。Claude Code 支持在~/.claude/目录下配置插件和技能引用。你可以在设置里声明技能目录或者在会话中通过/plugin命令导入。我目前同时接入了 Codex 和 Claude平时主力是 Codex遇到需要更长上下文、更复杂对话的任务会切到 Claude Code。两边读的技能文件是同一套维护成本没有增加。安装完后怎么验证最简单的办法开一个新会话直接问 AI你现在加载了哪些技能分别的作用是什么如果它能准确列出 planning、tdd、code-review 这些技能并且说清楚触发条件说明接好了。如果它答不上来或者只说我没看到任何技能文件那十有八九是路径或文件名对不上回到上一步检查。3. 别急着写代码superpowers 的核心使用姿势3.1 用一句话触发完整工作流工具装好只是开始真正改变我使用习惯的是它先规划后动手的工作方式。以前我遇到需求第一反应是直接甩给 AI实现一个 XX 功能。现在我会说用 planning 工作流处理这个需求先分析影响面输出 PLAN.md等我确认后再进入实现。这句话一出来AI 的行为模式立刻不一样。它不会急着生成代码而是先读取相关模块、梳理依赖关系、列出任务清单、标注风险点。我花两分钟看计划确认方向没问题再让它进入下一步。这种模式本质上是在 AI 和你之间加了一道设计评审的关口。好处非常明显大部分方向性错误在动手前就被拦截了而不是等代码写完了再推翻重来。3.2 常用技能清单什么时候该用哪个用了一段时间之后我结合自己的项目类型沉淀下来一张技能选择表技能名称典型触发场景预期输出planning需求较大、涉及多模块改动PLAN.md含任务拆解、风险点、实施顺序tdd新功能开发或 bug 修复先产出测试用例再写实现code-review代码提交前的自审按严重程度排列的问题清单debugging线上问题或疑难缺陷排查根因分析报告而非修改建议memory多会话长期项目更新的 MEMORY.md记录决策与状态选择技能的时候我有个原则同一时间只挂载必要的技能不要全量加载。关于这点后面踩雷录里会专门展开。3.3 记忆机制让 AI 记住项目的前因后果记忆机制是我认为 superpowers 最被低估的功能。长期用 Codex 的人都有这种体验新开一个会话AI 完全不记得昨天讨论过的方案和踩过的坑所有上下文都要重新交代一遍。superpowers 的记忆机制改变了这一点。它会在每次会话结束时把关键信息写入记忆文件本次做了什么决策为什么做这个决策哪些任务还没完成下一步要做什么遇到了什么坑后续需要规避什么下次新会话开始时AI 自动读取这些记忆直接进入状态。我经常早上开工第一句就是加载昨天的记忆我们继续那个支付模块的重构。它真的能接上这种连续性是原生工具给不了的。3.4 手把手创建你自己的技能工具自带的技能是通用的真正好用的是你自己沉淀的。我自己写了个数据库迁移检查的技能每次让 AI 改动数据库相关代码时自动触发检查有没有给大表加索引、有没有破坏已有外键关系、有没有考虑数据回滚。创建步骤很简单在~/.superpowers/skills/下新建目录比如db-migration-check/目录里新建SKILL.md文件文件用 frontmatter 格式声明技能信息正文写执行步骤和检查清单一个最小示例--- name: db-migration-check description: 审查所有涉及数据库结构变更的改动在提交前调用。重点关注索引、外键、回滚。 when_to_use: 当 diff 中包含 migration 文件、DDL 语句或 ORM 实体变更时 --- ## 执行步骤 1. 提取本次改动涉及的表和字段 2. 检查变更是否需要新增索引评估现有数据量 3. 检查外键关联是否被破坏 4. 确认回滚脚本存在且可执行 5. 输出审查结论包括风险和修改建议 ## 红线 - 禁止直接在生产环境执行任何 DDL - 禁止在未评估数据量的情况下建议加锁写完这个文件后AI 会在遇到数据库变更时自动读取并执行检查。关键在description字段写得越具体AI 越容易判断什么时候该用这个技能。4. 当技能遇上 Java一次真实的重构复盘4.1 为什么 Java 项目特别吃这套Java 项目大概是所有语言里潜规则最多的那一类Maven 还是 Gradle、Lombok 用不用、Controller 层应该多薄、异常是抛还是吞、Checkstyle 规则怎么配。这些约定很少写进文档全靠团队口头传承。原生 AI 写 Java 代码功能对但风格经常和团队不一致review 成本极高。superpowers 的切入点正好卡在这。你可以把团队所有的编码规范写成一个Java 编码约束技能AI 每次生成代码前自动加载。它的代码风格会稳定很多因为约束不再靠运气而是每次都在上下文中。4.2 一次 Spring Boot 支付模块的重构全过程我拿最近一次实践做例子。项目是一个 Spring Boot 的支付服务核心的OrderService类膨胀到了 1200 多行里面塞了支付宝、微信、银行卡三种支付渠道的 switch-case 逻辑。三个渠道逻辑互相纠缠只要改一处另外两处就可能坏。没人敢动。我当时的操作分四步第一步让 AI 用 code-review 技能分析现状。它输出的问题清单有 6 类包括switch-case 分支过多、渠道参数校验缺失、重复的订单状态流转代码、异常处理不统一、测试覆盖严重不足、类职责混乱。这个清单基本和团队一致。第二步执行 planning 技能拆出重构阶段设计渠道策略接口、编写现有行为的特征测试、分渠道实现策略类、最后回归。计划产出后我确认了优先级。第三步按 tdd 技能进入实现。先为三个渠道分别写测试用例边界情况包括退款、部分退款、金额不一致。这些测试把现有功能不能改坏这个底线锁死。第四步改造完成后跑 code-review 复查 diff。结果OrderService从 1200 行降到 400 行左右三个支付渠道变成独立的策略类旧测试全部通过新增了 20 多个特征测试。整个过程大约用了一个工作日换作以前纯人工来动这块代码没两三天我不敢让人上。4.3 Java 团队可以复用的技能组合基于这次经验我给 Java 团队一个可以直接抄的技能组合建议触发顺序很重要planning先拆任务定义接口和改动边界Java 约束检查加载团队规范确保生成代码风格统一tdd先写测试锁定行为实现与重构只允许改动与本次任务相关的代码code-review以审查子代理身份自查 diff这个顺序的核心逻辑是先定边界再动手比让 AI 一口气写完重要得多。顺序反了AI 很容易陷入边写边改边推翻的无序状态。4.4 省时间的真相性价比体现在返工减少说到收益量化我做一个不算严谨但很直观的对比任务类型纯人工原生 AI 直写AI superpowers简单功能 100 行半天1-2 小时1-2 小时中型重构500-1000 行2-3 天1 天但 review 要额外半天半天review 通过率高跨模块改造4-5 天2 天方向容易跑偏1 天我最真实的感受AI superpowers 在简单任务上并不比原生 AI 快多少但中型以上任务省下的不是写代码时间而是返工和 review 时间。方向对了代码风格对了测试兜住了后面所有环节都顺了。5. 踩雷录新手最容易翻车的五个地方5.1 装了跟没装一样技能加载不上这是反馈最多的问题我自己也踩过。症状是明明在技能目录里看到了文件AI 会话里却完全无感该直接写代码还是直接写。排查链路按这个顺序来检查 AGENTS.md 里的路径是否真实存在~是否被正确展开检查文件名是否和引用一致——注意大小写SKILL.md和skill.md在某些文件系统下是不同的确认文件编码是 UTF-8不要有 BOM 头新开会话再试因为技能是在会话启动时加载的中途改文件不会热更新95% 的情况是路径写错或者文件名不匹配剩下的就是忘了开新会话。5.2 技能挂载太多AI 反而变笨了这是另一个极端。有人觉得技能越多越好把十几份 SKILL.md 全写进配置。结果 AI 的上下文被技能说明占掉一大块真正留给业务代码的空间就变小了而且技能之间还会互相打架。一个典型表现AI 同时看到代码审查技能和重构技能搞不清楚当前该走哪个流程输出变得犹豫不决。我的建议是常驻 3-5 个核心技能其余技能通过按需触发来调用也就是在对话中需要时再让 AI 读取对应文件而不是一开始全塞进去。5.3 记忆文件越写越长AI 在故纸堆里打转记忆机制用久了会面临一个新问题文件里堆了几百条历史记录AI 每次加载时都要读一遍反而降低了响应质量和速度。我的解决办法是给记忆文件做结构化分层MEMORY.md索引层只保留当前最重要的决策和状态一两屏能读完memory/archive/归档层按周或按月归档的历史记录不被 AI 主动加载需要时再查每周末花十分钟整理一次记忆文件把不再相关的记录归档。这样 AI 的记忆永远是清爽的不会变成一团乱麻。5.4 过度造技能维护成本反超收益我见过最离谱的是有人给写一个简单的 REST 接口都专门造了个技能。技能确实能造但每造一个都要维护内容过时了还可能误导 AI。我给自己立了个标准同一个问题被连续卡住三次以上才值得为此写一个技能。一次两次偶发的问题直接在对话里说清楚就好。技能是要跟随你很久的资产宁缺毋滥。5.5 权限和子代理边界别让 AI 自己审自己最后一个坑是关于子代理的权限问题。我早期配置子代理时给它终端执行权限然后让它同时负责写代码和审查。结果等于让运动员当裁判审查流于形式什么问题都没发现。正确做法是把角色和权限分开写代码的主代理拥有文件写入和执行权限审查子代理只读代码、跑测试、输出报告不允许修改文件。这个边界一旦模糊审查环节就形同虚设。6. 最后分享几个我自己的小习惯文章到这里核心内容基本都讲完了。最后说几个我实际操作中沉淀下来的小习惯不一定适合所有人但可以参考每天早上开工我第一句永远是让 AI 加载项目记忆然后走一遍 planning 流程把当天要做的改动整理成计划再动手。新项目初始化时我会先让 AI 用 planning 技能生成一份 PLAN.md结合项目结构和团队规范确认后再开始写代码。每个季度我会 review 一遍技能列表删掉超过一个月没用过的技能保持技能库的新陈代谢。还有一个收益最大的习惯把整个 superpowers 配置和技能文件提交到团队 Git 仓库里。新人入职 clone 项目后内置的 AGENTS.md 和技能文件会自动生效团队所有成员等于共用一份持续更新的AI 工作手册。说到底superpowers 没有让 AI 变得更聪明它只是让 AI 用上了更有纪律的工作方式。我自己的体会是换模型带来的提升是线性的而改变工作流带来的提升是复利式的。只要你肯花一点时间建立自己的技能库这笔投入会一直滚下去。