“superpowers”这名字一听就带着野心但真正用过之后你会发现它其实是一套非常务实的工作流增强方案。简单说它就是围绕 AI 编程助手尤其是 Codex 这类命令行工具打造的一套“规则层 工具层 上下文管理”的组合拳。核心价值就一句话把你反复手写提示词、手动整理上下文、靠记忆维护项目规范的零散动作变成一套可版本化、可复用的工程化配置。我实际用了大概三周最大的感受是——它不是让 AI 更聪明而是让 AI 在正确的地方发力少犯蠢、少跑偏。1. 内容整体设计与思路拆解1.1 为什么需要一套“规则层”先说个扎心的事实AI 编程助手输出的质量很大程度上不取决于模型能力而取决于你喂给它的上下文和约束。同样是 Codex你给它一段含糊的“帮我修修这个 bug”它能给你返回一堆似是而非的猜测但如果你把项目的技术栈、目录约定、测试要求、禁止事项写清楚它的产出质量会有肉眼可见的提升。superpowers 这个名字其实是个误导它听起来像是什么黑科技插件安装完 AI 就真的拥有了超能力。实际用过你会发现它做的是很朴素的事把你在日常开发中反复交代的“废话”沉淀成一套结构化规则。比如“不要修改我注释掉的老代码”、“DTO 和 VO 要分开”、“配置文件必须加校验”这些规矩每次都手打一遍又累又容易漏。superpowers 把它们变成规则文件让 AI 每次开工前自动读取。这套思路跟“设计模式解决重复问题”是一个逻辑只不过这里重复的问题是“给 AI 写提示词”。1.2 核心模块有哪些从我拆解它的配置结构来看superpowers 主要包含三层第一层是“全局规则层”。它约束的是 AI 在所有项目中都要遵守的基础行为比如“代码修改要最小化”、“不主动删除用户代码”、“解释问题先给结论再展开”。这一层的价值是兜底防止 AI 在你没交代细节的时候放飞自我。第二层是“项目规则层”。这一层会绑定到具体仓库内容包括项目技术栈说明、目录职责划分、编码规范、关键业务的约束条件等。为什么要单独拆出来因为不同项目的脾气完全不同。做 Java 后端的时候你希望 AI 严格遵守包命名规范写前端小脚本的时候你更希望它直接出能跑的代码别整一堆抽象类。第三层是“上下文与记忆层”。这是我用下来觉得最值钱的部分。它会把开发过程中产生的关键决策、踩坑记录、临时结论以结构化笔记的形式保存下来下次会话再开始时AI 能“想起”之前聊了什么问题、定了什么方向。这就解决了 AI 会话之间没有记忆的老大难问题。三层结构合在一起如果你的规则写得足够好AI 的行为会非常稳定。我把它理解成“给 AI 画了一个护栏但它仍然能在护栏里自由发挥”。1.3 为什么不用一套新的 DSL我研究过几个类似项目有些选择发明一套新的 DSL 来描述规则和任务。superpowers 没有这么做它几乎全部依赖 Markdown、YAML 和简单的脚本。这个决策我觉得是很聪明的。理由也简单DSL 有学习成本新成员上手要翻文档而且 DSL 本身也是要维护的负担。而 Markdown 是程序员的世界里最通用的交换格式谁都能看懂谁都能改拿 grep 也能搜Git 也能做差异对比。规则写得不好直接用编辑器改规则起了效果回来 diff 对比一下一目了然。这种“把规则当作代码来治理”的理念恰恰是它能落地的关键。如果你一上来要团队学一套新语言那推广阻力就大多了。2. 安装与基础配置实操2.1 准备阶段需要什么环境先交代一下我跑的这套环境仅供参考我用的主力机器是 macOS终端是 iTerm2日常主力开发语言是 Java 和 TypeScript。superpowers 对系统没什么硬件要求它本质上是配置加脚本只要你机器上能跑 Node.js 和 Python 3基本就没问题。如果你主要开发 Java那自然还需要 JDK 环境——但那是你项目的需求不是 superpowers 的依赖。如果你用的是 Windows也没有大问题。核心脚本都是跨平台的但少部分 shell 脚本在 PowerShell 里跑不了我的建议是 Windows 用户开个 WSL 环境能绕开 90% 的坑。实际我帮一个朋友配 Windows 环境时唯一一次卡住就是路径分隔符的问题换到 WSL 后十分钟搞定。2.2 克隆与初始化步骤安装过程不算复杂核心是拿到项目文件后执行一次初始化命令。我重装过一次所以把每一步都记下来了git clone https://github.com/你的仓库/superpowers.git ~/.superpowers cd ~/.superpowers ./bin/setup.sh这步 setup 脚本主要做三件事一是生成一套默认的规则模板放在你当前用户目录下二是检测你机器上有没有 Node.js 和 Python 3缺了会提醒三是把 superpowers 的全局规则目录加入环境变量方便后续在任意项目里调用。如果你装的时候终端代理没开git clone 可能会卡住这时候直接开代理或者换 HTTPS 方式就行。装完之后你可以验证一下是否成功superpowers --version正常应该能看到一个版本号输出。如果你看到的是“command not found”说明 bin 目录没有加入 PATH去~/.zshrc或~/.bashrc里手动加一下 export 就行。2.3 目录结构长什么样装完后你会看到类似这样的结构~/.superpowers/ ├── bin/ # 核心命令入口 ├── rules/ │ ├── global.md # 全局规则 │ ├── java.md # Java 项目规则模板 │ ├── typescript.md # TypeScript 项目规则模板 │ └── template/ │ ├── task-card.md # 任务卡片模板 │ ├── decision-log.md # 决策日志模板 │ └── bug-report.md # Bug 报告模板 ├── scripts/ │ ├── generate-task.sh # 生成任务卡片 │ ├── save-context.py # 格式化保存上下文 │ └── check-project.sh # 检查项目规则是否过期 └── memory/ └── index.md # 跨项目的长期记忆索引说实话第一次看到这个目录我是有点失落的觉得这也太简单了就是些 Markdown 加几个脚本但我越用越觉得这种朴素恰恰是优点。你不需要学什么复杂的抽象所有的东西都是一个“文件”而每个文件里的内容你都能直接控制。规则就是写给人看的脚本就是放在那给 AI 调用的没有黑盒。3. 核心功能解析与使用要点3.1 把规则注入 Codex 的工作流前面说了superpowers 和 Codex 是配合关系。Codex 是一个跑在终端里的 AI 编程助手它能直接执行命令、读写文件所以让它读规则文件没有任何技术障碍。我实际使用中的做法是每次开始一个重要任务前先在项目根目录建一张任务卡片然后让 Codex 先读规则文件再动手。举个例子我在一个 Java Spring Boot 项目里是这样操作的superpowers init-project --language java这个命令会在当前目录下生成一份针对 Java 项目的规则文件里面预填了包命名规范、分层结构Controller、Service、Repository、异常处理约定等。然后我再创建一个任务卡片superpowers new-task 实现用户登录接口支持手机号密码登录需要校验验证码生成的 task-card 文件里会自动带上日期、项目背景、约束条件等字段。接下来我在 Codex 里开始会话时第一句就是“参考项目规则和任务卡片理解完需求再开始”。有了这种前置约束Codex 的输出就明显有了章法它知道用户实体要落在哪个包知道验证码校验不该写在 Controller 里知道返回结构要统一用 Result 包装。3.2 写规则文件时要注意什么写规则文件是有门道的。我最初犯过一个错误我把规则写得过于详细像本技术规范书一样结果 AI 每次读取都要花大量时间理解规则反而挤占了实际执行代码的时间。后来我把规则精简到一页纸以内效果立刻好了。核心原则是能进规则的一定是高频场景和底线性约束低频场景不要写进去靠任务卡片临时交代即可。以 Java 项目的规则文件为例我精简后的核心条目大概是这样# Java 项目规则 - 包名统一使用 com.company.product.feature 结构 - Controller 只做参数接收和校验业务逻辑全部放 Service - Service 之间禁止直接 new 依赖统一通过 Spring 注入 - 数据库操作禁止使用 JDBC 裸写必须走 Mapper 层 - 新增接口必须补充单元测试测试类命名以 Test 结尾 - 所有接口返回统一为 ResultT 结构错误信息不得直接暴露内部异常每条规则都是“可验证的”AI 如果违反了你能够通过 code review 或测试直接发现。这就避免了一些很虚的规则比如“代码要优雅”、“质量要高”那种话 AI 读了等于没读。3.3 用决策日志解决“会话失忆”问题AI 编程助手一个最烦人的缺陷就是会话一关它就什么都不记得了。superpowers 处理这个问题的方式是“在会话结束时强制沉淀决策日志”。我实际操作中会在任务完成之后跑一下superpowers log-decisions --file task-card.md这个命令会引导我把本次会话的关键决策写进一个 structured 的 Markdown 文件里内容包括这次做了什么、遇到了什么问题、最终用了什么方案、为什么不用另一个方案。等下一次打开新会话我先让 AI 读这个决策日志它就能快速恢复上下文不需要我再絮叨一遍背景。这相当于给 AI 建立了一套“外接记忆”。这里我有一个经验决策日志最关键的不是记录结果而是记录“放弃过的方案”。因为 AI 特别容易在下次会话里重新提出之前已经否掉的建议。你只要在决策日志里写清楚“已评估 A 方案因 XXX 放弃”就能省掉很多来回拉扯。4. 常见问题与排查技巧实录4.1 规则不生效AI 还是我行我素这是我被问得最多的问题。遇到这种情况不要急着怀疑工具九成是你没有让 AI 读取规则文件。很多人的习惯是打开 Codex 就直接说需求指望它能自己找到规则文件。但 AI 的工具调用里默认并不会去翻你的目录找规则。你需要在会话开始时主动让它读请先读取 ~/.superpowers/rules/global.md 和项目根目录的 rules/java.md然后总结你理解的约束再开始任务。如果 AI 读了仍然不遵守那就得检查规则本身是否足够明确。规则最大的问题是含糊你说“优化性能”它不知道你指的是响应时间还是内存占用你说“要考虑扩展性”它不知道怎么算合适。我的排查清单如下现象可能原因处理方式规则没被读取会话未指定规则文件开头显式要求读取规则规则读了对行为没影响规则太宽泛或冲突精简规则每条都要可验证新旧规则互相矛盾全局规则和项目规则冲突项目规则声明优先级高于全局规则生效但代码风格还是不对缺少示例代码作为锚点在规则中加入一段“正例”代码4.2 任务卡片和实际需求对不上用了几次之后我发现一个规律任务卡片最好在写代码之前自己先手动清理一遍。因为自动生成的卡片里背景信息经常是缺的只有几个空字段。如果你直接丢给 AI它就会自己脑补需求然后做出跟你预期完全不同的东西。这里我踩过一次重坑——有一次我让它实现一个 Excel 导入功能自动生成的任务卡片里没写字段映射规则AI 自作主张假设了表头名称结果导进来的数据全是乱的。从那以后我每次把任务卡片丢给 AI 之前都会自己花两分钟把“已知信息”和“未知信息”分开列清楚。4.3 脚本报错的常见处理superpowers 里的脚本大多是用的 Python 3 和 shell报错最多的就两类。一类是缺依赖比如你没装 PyYAML脚本在解析 YAML 配置时就抛错另一类是路径问题特别在 macOS 上如果你用的是 zsh环境变量没配好会找不到命令。给你一个通用的排查顺序先看报错信息开头如果是ModuleNotFoundError直接pip3 install pyyaml之类补依赖。如果是command not found检查 PATH 配置。如果是权限错误看下 bin 目录下的脚本有没有执行权限没有的话chmod x一下。其实这些问题的根源都差不多就是你的机器环境比预想的更“原始”需要把基础环境补齐。5. 从“能用”到“好用”的进阶扩展5.1 把规则纳入版本治理用了一段时间之后你会开始改规则、增规则然后你就会面临一个很现实的问题怎么管理规则本身的变更我的建议是把整个 rules 目录纳入 Git 仓库单独建一个私有仓库来管理。这样每一次改规则你都能看到 diff。我后来甚至会给规则变更写 commit message比如“新增禁止在 Controller 里做数据权限校验”这样团队伙伴 review 起来也轻松。而且版本化还有一个好处如果某一次改动让 AI 的整体表现变差了你可以直接回滚到上一版规则。这种事我真的干过有一次我为了让 AI 生成更详细的注释加了一条规则“所有方法必须写详细行内注释”结果它开始给每一行代码都写注释代码噪音大得没法看。我立刻回滚再把规则改成“公共 API 必须注释用途与边界条件私有方法不用注释”效果才恢复。5.2 用预提交检查拦截低级错误superpowers 可以在项目里接入一个轻量级检查脚本把它放到 git 的 pre-commit hook 里。这个脚本不做什么高深的事就是在你提交前快速扫一遍代码里有没有 TODO、FIXME、console.log检查关键目录结构是否符合规则。如果你团队有统一的代码规范这个拦截器还能帮你提前发现问题。预提交检查的价值在于它是“AI 之外的双保险”。AI 不是每次都稳定有时候它会在测试里写死断言有时候它会用奇怪的缩进风格。你靠人肉 review 能发现但加上这个拦截器低级错误在源头就被拦截了效率提升不是一点半点。5.3 针对 Java 项目定制一套规则模板因为我在 Java 项目里用得最多这里专门说说怎么针对 Java 场景定制规则。Java 项目跟脚本项目最大的区别在于它有很强制的分层结构、依赖注入模式和测试惯例。如果你的规则里没有体现这些AI 很容易生成出“看起来能跑但结构很烂”的代码。我自己的 Java 规则模板里有这么几条是我觉得特别关键的禁止在 Controller 层写任何业务逻辑只允许参数校验和调用 Service。实体类禁止直接暴露可变字段所有修改统一走行为方法。Mapper 层禁止手写复杂 SQL复杂查询必须走 XML 文件并加注释。单元测试必须使用 Mockito不要直接 new 依赖对象。新增接口必须同步更新接口文档文档采用 OpenAPI 3.0 规范。这些规则每条都是可检查的。你会发现当规则足够明确时AI 生成的代码从风格到结构都像同一个人写的这在团队协作里价值极大。因为你不再需要为“每个人写出来的风格都不一样”这件事头疼AI 给了你们一个一致的基线。根据我个人经验superpowers 这类东西真正改变的不是 AI 的能力而是你对 AI 的使用方式。以前我是把 AI 当成一个随时可以问的搜索引擎现在更像是带一个“懂规矩的初级开发”先给他讲清楚项目规矩他就能批量产出符合规范的代码。这套工作流跑通之后我已经回不到原来那种“临时写提示词、随手丢需求”的打法了。如果你也在用 Codex 这类终端 AI建议你也试试这套方案先从小项目跑起来把规则慢慢磨出来你的收获会比我更大。