这个superpowers我刚接触的时候以为又是某个蹭AI热度的玩具项目结果用下来发现完全不是那么回事。如果你正在用 Codex 这类 AI 编码工具应该能感受到一个矛盾它们单看每一次对话都很聪明但放到真实项目里经常跑偏改着改着就失控了。superpowers 的核心思路就是给这些 AI 编码工具套上一整套标准化的工作流程和外挂技能让它们从偶尔惊艳的聊天对象变成稳定交付的结对程序员。这篇文章我会从设计思路、安装配置、核心模块到日常排障完整拆一遍我自己的实战过程。1. 项目定位它到底解决的是什么痛点如果你上手过 Codex CLI 或者其他终端里的 AI 编码助手多半遇到过这几类场面让它改个 bug它顺手把无关模块的样式也改了让它加个功能代码写到一半突然停住说我觉得这样设计更好更常见的是同一个项目里每次对话风格都不一样上午刚建的抽象接口下午就给你推倒重来。大模型本身没有项目记忆也没有工程纪律它只知道单次对话里的上下文。superpowers 本质上是给 AI 编码工具建立了一套工程化的工作协议什么时候做需求分析、什么时候写实施计划、代码改到哪一步必须停下来验证、界面改动用什么标准自查。它不是模型不是插件也不依赖某个特定平台而是以 Markdown 指令加脚本的形式组织的一套技能包。这类工具最适合的受众我觉得是这几类人已经把 Codex 类工具用于日常开发、但对结果稳定性不太满意的开发者需要在不同项目间复用同一套 AI 协作流程的团队对终端工作流有好奇心、愿意折腾的新手。如果你是刚接触 AI 编程直接拿它当教程可能有点重但你完全可以从它的 prompt 设计里学到该怎么给 AI 提需求才不会被带偏。1.1 为什么叫 superpowers作者把每一个能力模块称为一项superpower比如启动新功能开发调查并修复 bug代码审查全项目重构。每个 superpower 对应一套完整的、结构化的提示词工作流或者说是一个可复用的战术模板。使用的时候你先把当前项目的情况和需求写进去AI 会按照预定义的步骤推进而不是天马行空。这种方式说白了就是把 AI 当成一个真实团队里的新成员你给它的不是一句帮我写个登录页而是一份包含需求背景、验收标准、涉及文件清单和实施步骤的工单。它的名字虽然中二但理念非常务实。1.2 和普通提示词工程的差异网上到处是所谓的提示词技巧但大多停留在你要把需求写清楚这种层面。superpowers 做了三件更重的事一是把工作流拆成了阶段每个阶段有独立的 Prompt 和目标AI 不会跨阶段乱来二是引入了项目级的知识来源让 AI 可以从项目结构、技术栈说明、需求文档里自动提取背景信息三是设计了人机协作的检查点AI 不能一口气闷头干到底它会停下来问你问题、展示方案、确认后再动手。这三件事合起来才是超能力的真正来源——它约束了 AI 的不确定性把它的强项留在可控的轨道里。2. 核心机制与工作流拆解要理解 superpowers先得理解它跑起来的时候内部到底发生了什么。它不是一个后台常驻服务而是在你需要的时候被调用的命令集合。比如你输入begin a new feature或者调用对应的 skill它会动态拼装出一整套上下文当前项目的 README、项目结构树、你最近改动的文件、相关模块的源码然后再根据当前任务加载对应的流程模板。整套响应虽然由大模型驱动但步骤是几乎可预期的。2.1 基于 PLAN / TASK 文件的任务流转superpowers 里有两个很核心的状态文件PLAN.md 和 TASK.md。启动一个功能开发后AI 会先进入分析模式检查代码库、核对需求、列出技术选项然后在 PLAN.md 里写下完整实施方案包括要修改的文件、要创建的模块、测试策略、回滚方案。只有当你审查并确认方案后它才会进入执行模式把方案拆成一条条 TASK逐条完成。每完成一条任务它会更新 TASK.md 状态把完成情况标记清楚。这个机制看起来很简单但实际用下来体验提升非常明显AI 不再边想边写写着写着自己改主意因为 PLAN 一旦确认后续执行都忠于方案。2.2 检查点与人机协作另一个让我印象深刻的机制是它默认开启了每次执行前先确认的交互节奏。在很多任务里它不是上来就调工具改文件而是先把当前目标、影响范围、风险点列出来问你一句确认这样做吗或者有两个方案你选哪个。如果你不问它就按预设的优先级来但依然会在关键节点停下来汇报。这种节奏对开发效率短看似乎是拖慢了长看其实是大幅减少了AI 写完你review然后打回重做的反复拉扯。它把高频的双向沟通集中到了任务开始阶段执行阶段反而干净利落。2.3 从代码库自动提炼上下文superpowers 的 prompt 系统里专门设计了上下文收集器逻辑。它会读取你的项目文件树识别项目类型和主要语言抓取关键配置文件和文档片段然后把这些信息注入给模型。以 Java 项目为例它会自动去读 pom.xml 或者 build.gradle识别你用的 Spring Boot 版本、Java 版本、依赖管理方式如果是 Python 项目会读 pyproject.toml 或 requirements.txt判断是用 FastAPI 还是 Django。这个能力背后的设计理念是第一性原理AI 编码工具表现差很多时候不是模型不够强而是它对你项目的背景信息知道得太少。你肉眼可见的优化就是把项目背景这份材料喂足。3. 安装与上手实操全记录下面进入实际安装和配置部分。我以当前主流的 Codex CLI 环境为例把整个流程走一遍包含我踩过的坑和最后稳定运行的配置。所有命令都是基于常见实践整理的不同版本细节可能有出入但思路通用。3.1 前置依赖准备安装之前确认三件事Node.js 环境版本建议 18 以上git 已经配置好且能正常访问你的代码仓库Codex CLI 已经安装并能成功调用模型接口。可以先用这些命令自查node -v git --version codex --version如果 codex 命令还没有需要先完成 Codex CLI 的基础安装和登录。这一步过关后我们来拉取 superpowers 项目本体。它的安装方式很简单本质上就是把整个技能仓库克隆到本地然后通过配置让 Codex 知道去哪里加载这些技能文件。git clone superpowers仓库地址 ~/.superpowers这里的仓库地址以你实际获取到的为准。克隆完成后进入项目目录看一下结构你会看到明显的技能模块目录比如 skills、prompts、lib 之类。后续的配置都是围绕这些目录展开。3.2 配置 AGENTS.md 接入点安装的核心在于让 Codex 每一次启动都能自动加载 superpowers 的上下文。目前主流做法是在项目的 AGENTS.md或者旧版本的 CLAUDE.md不同工具有差异里写入引用指令把 superpowers 的主入口文件挂载进来。操作步骤cd ~/.superpowers npm install如果项目提供了全局安装脚本可以按它的说明执行。手动配置的话你需要回到自己的项目根目录创建一个 AGENTS.md 文件如果还没有然后在文件开头写入类似这样的内容你的工作流遵循 ~/.superpowers 下定义的规范。开始处理任务前先阅读对应技能目录下的 SKILL.md 文件按其定义的阶段执行。所有重要方案必须先写入 PLAN.md经用户确认后再开工。这里的具体措辞以你克隆下来的仓库里的说明为准每个版本的挂载词可能略有差异。配好之后可以跑一个简单命令验证是否生效随便输入一句请问你当前知道哪些技能如果 AI 能列出 superpowers 的模块清单说明挂载成功。3.3 第一次启动新功能开发配好之后最好的上手方式是拿一个真实的小功能来试。比如我在一个内部管理项目里新增一个导出 CSV功能我输入的命令是这样codex 使用 begin new feature 技能为订单列表页新增导出 CSV 的功能包含列映射规则注意这里的关键是明确调用了begin new feature技能而不是让 AI 自由发挥。实际运行中它会先花一点时间分析项目然后可能反问你几个问题比如导出范围是当前筛选结果还是全部订单列映射以列表页展示字段为准吗导出文件对时间字段的格式有要求吗这个过程可能会让急性子朋友觉得烦但建议认真回答因为后面少踩的坑都是这会儿省下来的。回答完之后它生成了 PLAN.md里面有完整的技术方案我确认没问题后按了个确认它才开始动手改代码。3.4 日常命令的高频用法用了一段时间之后我自己形成了一套固定的使用习惯。启动新功能用 begin new feature遇到 bug 的时候用 investigate and fix bug这个技能有个很好的习惯它会先让你贴错误信息或者描述复现路径然后去做代码定位定位到具体文件行号之后才提修改方案需要做代码审查的时候用 code review它会按预定义的检查清单逐条核对而不是泛泛地说看起来不错。这些技能的入口名称在仓库的 skills 目录下都能找到也可以通过对话让 AI 帮你列出来。4. 不同技术栈下的适配要点不同技术栈的项目superpowers 的工作流在使用体验上有差别。这里我重点聊两个我实际使用最多的场景Java 后端项目和其他常见 Web 项目。4.1 Java 项目中的实测体验Java 项目是我使用 superpowers 最频繁的场景。以 Spring Boot 项目为例它的上下文收集器读取了 pom.xml 之后很多行为会立刻变得更专业它会明确使用项目里现有的分层结构新建 controller、service、mapper 时自动遵循原有命名习惯遇到依赖问题会先检查本地仓库的 .m2 配置在生成数据库相关代码时更倾向于配合迁移工具而不是直接改表结构。有个细节让我很满意一次它需要读取一个复杂的 MyBatis 映射文件来分析 SQL 性能问题它主动选择了先阅读文件、再对照 VO 类字段最后才给出索引优化建议这个步骤已经是相当合格的 Java 工程师习惯。4.2 前端或全栈项目的处理细节在 TypeScript 前端项目里它表现也不赖。它懂得读 package.json 的 scripts用项目已有的 lint 和 format 命令改组件的时候会检查相关的样式文件涉及 API 调用的时候会主动去找项目的请求封装层统一走项目的 request 实例。这里要提醒一下如果是特别冷门的技术栈或者高度定制化的项目结构初始的上下文收集可能不够精准你需要手动在 AGENTS.md 里补充一些项目约定比如所有接口返回类型定义在 src/types/api.ts状态管理使用 zustand 且禁止直接修改 store 内部状态之类。它给了你一个规则注入的入口剩下的还是需要你去调教。4.3 多模块项目下配置 AGENTS.md 的经验遇到大型的多模块仓库比如一个包含 admin 端、用户端、公共模块的 monorepo我强烈建议不要只在一个根级 AGENTS.md 里写全局规则。更好的做法是在根目录写总体架构说明在每个子模块目录里再写各自的 AGENTS.md比如只描述该模块的技术约定和业务术语。这样 AI 在读取上下文时会按照目录层级就近获取信息不会把 admin 端的惯例套到用户端上。这个做法在实践里极大减少了张冠李戴式的问题。5. 高频问题排查与避坑实录这套体系用久了多多少少会遇到一些问题和你以为它坏了其实是配置问题的时刻。我把最常遇到的几类整理成速查表方便你直接对照排查。现象常见原因处理方法运行时提示找不到技能模块仓库路径未正确挂载或 AGENTS.md 引用路径写死确认配置里的路径与实际安装目录一致建议用绝对路径或 $HOME 变量AI 完全不按流程走上来就改代码项目没有 AGENTS.md或内容被其他配置覆盖检查根目录及父级目录是否存在多个 AGENTS.md确保 superpowers 的引用在文件内靠前位置PLAN.md 生成了但一直不进入执行交互模式停在等待确认状态检查终端是否有未处理的确认提示或者明确输入确认/继续Java 项目读不到依赖配置上下文收集器没有读取构建文件权限确认当前终端对项目的 pom.xml 有读权限且工作目录确实在项目根下技能列表加载不全安装版本较旧或仓库有更新定期 git pull 更新技能仓库然后重新载入对话上下文5.1 我踩过比较深的坑第一个坑是过度设计。刚开始用的时候我让 AI 每次任务都务必写完 PLAN 再动工结果连修复一个变量名错误这种小事它也给你写五百字方案那个体验确实很拖节奏。后来我调整了用法只有新增功能、跨模块改动、涉及数据库或接口协议变更的任务才走完整 PLAN简单 bug 修复直接用 investigate and fix 技能它内部也会有个轻量级的计划阶段但明显快很多。这个工具它给了你选择权但前提是你得知道什么任务该用什么技能这个判断力只能靠多练。第二个坑是不对齐版本。有一次我更新完 superpowers 仓库之后发现它生成的 Plan 格式和我项目里另一套自动化脚本解析的格式冲突了。后来我固定了仓库版本号不随意更新只在确实需要新功能时才升级。这种提示词类的工具更新频率不低但每次更新都可能微调行为模式生产环境里最好锁版本。第三个坑更隐蔽多项目环境下的上下文串味。因为我同一个终端可能在不同项目目录间切换有几次发现它读上下文的时候把我上一个项目的 README 也带进去了。原因是终端的历史对话上下文没有清理。后来我养成习惯每个新项目会话都开全新的 --session不在旧会话里直接切目录干活。5.2 排查问题时的基本方法论如果你遇到了文档里没写的问题我建议按这个顺序排查第一步确认技能仓库路径和环境变量是否正常最简单直接重新 source 配置或重启终端第二步检查 AGENTS.md 的实际渲染内容如果你不确定 AI 到底读到了什么就让它原样输出你的系统提示词和当前加载的技能列表这招很管用第三步缩小变量范围开一个全新项目目录只配置最简 AGENTS.md 然后跑同一个任务如果正常说明是你原项目的配置太复杂如果还不正常再考虑模型本身或 API 服务的问题换一个模型跑同样的任务做对比。6. 从使用到深度定制让工作流更贴合自己当你能熟练用默认技能跑完几条完整任务之后下一步自然是按自己的习惯去改造它。这个工具的可定制性很强整个技能定义其实就是 Markdown 加一些变量占位符。你看一看技能目录里的 SKILL.md 文件结构基本就能理解它的编写范式。6.1 自己写一个简单技能拿我自己的一次实践举例。我们项目里频繁需要写接口变更说明文档每次让 AI 写出来的格式都不太统一。我就新建了一个技能文件叫 write-api-changelog在 SKILL.md 里定义了输入参数变更模块、接口列表、是否涉及破坏性变更和输出模板变更日期、模块路径、接口名称、请求方式、变更描述、兼容性说明然后在 AGENTS.md 里把新技能路径加了进去。之后再用的时候它生成的文档格式完全统一直接就能贴到内部协作平台上。整个过程没有写一行代码只是组织好了 prompt 结构但收益非常直接。如果你也想写自己的技能可以先从最简单的固定输出模板开始不需要一上来就设计多阶段工作流。用熟了之后再加需要向用户确认哪些前置问题需要收集哪些项目上下文这类进阶设计。这个项目最大的价值其实是它教会了你一种给 AI 定流程的思维方式一旦你掌握了很难退回去用裸奔的聊天窗口写代码。6.2 关于模型选择的个人感受superpowers 这种深度 prompt 体系对模型能力和上下文长度的要求都不低。在长上下文模型上表现明显更好因为它需要同时容纳技能模板和项目代码片段在代码理解和指令遵循能力强的模型上工作流的还原度更高。如果你发现某个技能跑起来经常漏步骤先别急着怀疑工具换一个综合能力更强的模型往往立刻有改善。不过也要看成本这类工具每一次任务调用消耗的 token 比日常聊天多不少长任务尤其明显预算敏感的话可以只在复杂任务上走完整流程简单任务直接用轻量模式。6.3 版本更新和社区生态superpowers 这类项目通常迭代很快安装目录下的 git 历史能看出来。我的建议是关注它的 CHANGELOG 或者 release notes了解每个版本更新了什么技能、修复了什么 prompt 逻辑再有选择地升级。社区里也有很多人在不同技术栈下分享自己的技能配置比如有人专门做了 Kubernetes 运维场景的增强技能有人针对数据分析场景做了可视化报告模板。找到适合自己的那套再融合进自己的日常工作流这个工具才能真正发挥出超能力这三个字的价值。最后说一点我自己的体会。工具的本质是约束superpowers 给 AI 编码这件事带来了非常需要的流程约束感。我用它最大的收获不是 AI 写的代码质量一夜暴涨而是整个开发过程变得更可预期、更少返工、更接近和一位有经验的同事协作的体验。如果你手上正好有 Codex 等终端 AI 编码工具又对现在失控式的协作方式不满意强烈建议花半天时间把这套流程跑起来按它的引导做完一整个功能你会感受到那种结构性带来的踏实感。