1. 从“superpowers”这个热词说起它到底是什么第一次看到“superpowers”这个词挂在技术社区热搜上的时候我下意识以为是某个新出的超级英雄题材游戏点进去才发现这其实是一个在开发者圈子里悄悄火起来的效率工具组合概念。简单来说superpowers 是一套围绕 AI 编程助手尤其是 Codex 这类工具构建的增强能力集合它把原本零散、需要手动拼接的提示词、工作流、上下文管理技巧打包成一套可复用的“超能力”让 AI 在写代码、改 bug、读项目、生成文档这些场景里表现得更像一个真正懂你项目的搭档而不是一个只会背八股文的实习生。你可能会问市面上 AI 编程工具已经够多了为什么还要搞一个 superpowers我自己的体会是原生 AI 助手最大的问题不是不够聪明而是“记性差”和“不懂规矩”。你让它改一个函数它可能顺手把你整个文件重写了你让它读项目它只看了你贴的那几行完全不知道你用的是哪个框架、哪个版本、团队有什么代码规范。superpowers 要解决的就是这个断层——它通过一套结构化的配置和调用方式把项目上下文、编码规范、任务拆解逻辑提前喂给 AI让每次对话都站在“已经了解项目”的基础上进行。这套东西适合谁如果你满足下面任意一条就值得花时间研究一下每天要跟 AI 编程助手来回拉扯十几次以上团队里多人共用一套 AI 辅助流程但效果参差不齐经常需要让 AI 理解一个陌生代码库然后做修改或者你单纯觉得现在用 AI 写代码“差点意思”想把它调教得更顺手。它不要求你是 AI 专家但需要你对项目结构和基本开发流程有概念否则配置出来的东西也是空中楼阁。我最初接触 superpowers 是因为一个实际痛点手头有个 Java 老项目代码分层混乱注释稀少每次让 AI 帮忙加功能它都要我把相关类从头贴一遍贴完它还经常改错 import。后来在社区看到有人分享用 superpowers 的思路做“项目记忆层”我照着搭了一套虽然踩了不少坑但效果确实肉眼可见——现在 AI 改代码前会先确认包路径和依赖版本改完还会自己跑一遍我预设的检查清单。下面我就把这套东西的来龙去脉、配置细节和实操经验完整拆一遍。2. superpowers 的核心设计思路与方案选型2.1 为什么不是简单的“提示词模板”很多人第一次听说 superpowers会以为它就是一堆写好的提示词复制粘贴就能用。我一开始也这么想结果发现完全不是那么回事。单纯的提示词模板是静态的、无状态的你这次让它“用 Java 8 的语法写”下次开新对话它又忘了。而 superpowers 的核心在于状态管理和上下文注入——它维护了一份关于你项目的“档案”每次调用 AI 时自动把相关部分塞进对话里让 AI 始终在一个受控的认知框架内工作。这个设计思路借鉴了软件工程里的“依赖注入”思想AI 的能力是运行时项目上下文是依赖项superpowers 就是那个容器。它不改变 AI 模型本身而是改变 AI 接收到的信息结构和顺序。这样做的好处是可移植性强——你今天用 Codex明天换另一个支持自定义上下文的助手只要把档案格式适配一下核心逻辑不用重写。2.2 三层架构档案层、调度层、执行层我拆解了社区里几个高赞的 superpowers 实现发现它们基本都遵循一个三层结构我自己也按这个思路搭了一套确实比一锅粥好维护。档案层负责存储项目元信息。包括但不限于项目类型Maven/Gradle/纯 Java、JDK 版本、核心依赖及版本号、包结构约定、命名规范、日志框架、测试框架、甚至团队内部的“禁止使用的 API 列表”。这些信息以结构化格式我用的 YAML也有人用 JSON 或 TOML存放在项目根目录的.superpowers/文件夹下。为什么强调结构化因为 AI 对结构化数据的解析准确率远高于自然语言描述你写“我们用 Java 8”和写jdk_version: 1.8后者被正确执行的几率高得多。调度层是核心逻辑决定“什么时候把什么信息喂给 AI”。比如你发出“帮我加一个用户查询接口”的指令调度层会判断这是新增功能需要注入包结构约定、命名规范、Controller 层模板、Service 层模板、以及最近修改过的相关文件列表。如果你发出的是“这个空指针怎么修”调度层则优先注入异常堆栈、相关类源码、以及该类的最近变更记录。调度策略的精细程度直接决定 superpowers 好不好用我见过有人把所有信息一股脑全塞进去结果 AI 被无关信息干扰反而更容易出错。执行层就是实际调用 AI 接口的部分负责把调度层组装好的上下文和用户指令拼接成最终 prompt发送给 Codex 或其他助手再把返回结果做后处理比如提取代码块、校验 import、跑格式化。这一层通常需要写一点胶水代码我用 Python 写的大概两百行左右核心就是 HTTP 请求加字符串处理没什么高深技术。2.3 为什么选择 Codex 作为主要载体热词里出现了codex superpowers说明很多人是把 superpowers 和 Codex 搭配使用的。我试过几个不同的 AI 编程助手最后也固定在 Codex 上原因有三个。第一Codex 对长上下文的支持比较稳superpowers 注入的档案信息动辄几千 token上下文窗口小的助手直接截断效果大打折扣。第二Codex 的代码补全和对话模式切换自然我可以在写代码时让它自动补全遇到复杂逻辑再切到对话模式详细讨论superpowers 的调度层可以针对两种模式做不同注入。第三社区生态用的人多意味着踩坑有人分享我遇到的好几个问题都是在社区讨论里找到答案的。当然这不是说其他助手不能用superpowers 的设计本身是平台无关的只是 Codex 目前适配得最顺。如果你用的是别的工具只要它支持自定义系统提示或上下文注入理论上都能改造。3. 核心细节解析档案怎么写、调度怎么配3.1 项目档案的字段设计与填写要点档案层是整个 superpowers 的地基写得好不好直接决定后续效果。我一开始图省事只写了项目名和 JDK 版本结果 AI 还是经常用错日志框架。后来我把档案扩充到下面这些字段效果才稳定下来。# .superpowers/profile.yaml project: name: user-center type: maven jdk_version: 1.8 spring_boot_version: 2.3.12.RELEASE build_tool: maven encoding: UTF-8 structure: base_package: com.example.usercenter layers: - controller - service - service.impl - mapper - entity - dto - config resource_dirs: - src/main/resources - src/test/resources conventions: naming: class: UpperCamelCase method: lowerCamelCase constant: UPPER_SNAKE_CASE db_column: lower_snake_case logging: framework: slf4j annotation: Slf4j forbidden: System.out.println exception: base_class: com.example.usercenter.exception.BizException handler: com.example.usercenter.config.GlobalExceptionHandler api_response: wrapper: com.example.usercenter.common.Result success_code: 200 error_code_prefix: 4 dependencies: - groupId: org.springframework.boot artifactId: spring-boot-starter-web version: 2.3.12.RELEASE - groupId: com.baomidou artifactId: mybatis-plus-boot-starter version: 3.4.3.2 - groupId: org.projectlombok artifactId: lombok version: 1.18.20 forbidden: - 使用 java.util.Date统一用 java.time.LocalDateTime - 在 Controller 里写业务逻辑 - 直接返回 Entity必须转 DTO - 使用 SELECT *这份档案有几个关键点值得展开说。forbidden字段是我踩坑最多的地方一开始没写AI 生成的代码里System.out.println和SELECT *满天飞后来我把团队代码规范里最常被违反的几条列进去AI 就老实了。注意措辞要具体写“不要用 Date”不如写“使用 java.util.Date统一用 java.time.LocalDateTime”后者给了明确替代方案AI 执行起来不犹豫。conventions.naming里的db_column字段容易被忽略但如果你用 MyBatis-Plus 这类 ORM实体类字段和数据库列的映射规则必须提前说清楚否则 AI 生成的TableField注解可能对不上。我见过有人因为没写这条AI 把userName映射到user_name又映射到username调试了半天。依赖版本号要写全包括RELEASE后缀。AI 对版本号很敏感你写2.3.12和2.3.12.RELEASE它生成的pom.xml片段可能不一样。这个细节看似吹毛求疵但实际项目中版本号不完整会导致构建失败返工成本很高。3.2 调度层的触发规则与优先级调度层要解决的核心问题是用户说了一句话我该往 AI 的上下文里塞哪些档案片段我的做法是维护一个“触发词-档案片段”映射表再加一层优先级排序。# scheduler.py 核心逻辑示意 TRIGGER_RULES [ { keywords: [新增, 添加, 创建, 写一个], inject: [structure, conventions.naming, conventions.api_response, forbidden], priority: 10 }, { keywords: [修改, 改成, 调整, 重构], inject: [structure, conventions.naming, forbidden, recent_changes], priority: 9 }, { keywords: [报错, 异常, 空指针, 失败], inject: [dependencies, conventions.exception, recent_changes], priority: 8 }, { keywords: [测试, 单元测试, test], inject: [structure, conventions.naming, dependencies], priority: 7 } ]这个映射表不是拍脑袋写的是我根据实际使用频率和出错率慢慢调出来的。新增功能时最容易犯的错是命名不规范和返回格式不对所以把conventions.naming和conventions.api_response的优先级调高。修改代码时最容易破坏原有结构所以注入structure和recent_changes让 AI 知道最近谁动过哪些文件避免冲突。recent_changes这个字段需要动态生成我的做法是用 Git 命令抓最近三次提交涉及的文件列表和变更摘要存成一个临时文件调度时读取。这样 AI 在改代码前会“看到”最近有人改过同一个类它会主动提醒你可能存在冲突。这个功能帮我避免了好几次覆盖别人代码的事故。优先级排序的逻辑是当多个规则同时命中时按 priority 从高到低取前三个规则的注入内容去重后拼接。为什么不全部注入因为上下文窗口有限塞太多反而稀释了关键信息。我实测下来每次注入的档案内容控制在 2000 token 以内效果最好超过 4000 token 后 AI 的注意力明显分散开始忽略一些约束条件。3.3 执行层的后处理与校验清单执行层不只是发请求收响应后处理才是保证输出质量的关键环节。我给自己定了一套校验清单每次 AI 返回代码后自动跑一遍不通过就打回重问。校验项检查方式不通过时的处理import 完整性正则提取 import 语句对比项目已有类自动补全缺失的 import禁止 API扫描是否出现 forbidden 列表中的模式打回并附上禁止原因命名规范正则匹配类名、方法名、常量名打回并指出具体违规处返回类型检查 Controller 方法返回是否为 Result 包装打回并要求重新生成日志使用检查是否用了 Slf4j 而非 System.out打回并替换空指针防护检查对象调用前是否有判空打回并提示补充判空这套校验清单是我用血泪换来的。最开始我没做后处理AI 生成的代码看着像模像样一编译就报错不是缺 import 就是返回类型对不上。后来我把这些检查写成脚本每次自动跑返工率从最初的 40% 降到了 10% 左右。剩下的 10% 主要是业务逻辑层面的问题那个确实需要人工判断自动化脚本搞不定。提示校验脚本不要写得太严格否则 AI 会被频繁打回对话轮次暴增反而降低效率。我的经验是只校验“硬性规范”比如 import、禁止 API、返回类型这些命名规范可以适当放宽因为 AI 有时候会用同义词不影响功能。4. 完整实操流程从零搭一套可用的 superpowers4.1 环境准备与目录结构动手之前先把环境理清楚。我假设你用的是 Java 项目加 Codex 助手其他语言和助手可以类比调整。需要准备的东西不多一个能跑 Python 脚本的环境我用 3.8Git 命令行工具以及 Codex 的 API 访问权限如果你用的是网页版需要确认它支持自定义上下文注入不支持的话得换支持 API 的方式。目录结构我建议这样组织放在项目根目录下your-project/ ├── .superpowers/ │ ├── profile.yaml # 项目档案 │ ├── scheduler.py # 调度逻辑 │ ├── validator.py # 后处理校验 │ ├── recent_changes.txt # 动态生成的最近变更 │ └── templates/ # 常用代码模板 │ ├── controller.tpl │ ├── service.tpl │ └── test.tpl ├── src/ └── pom.xml.superpowers/文件夹建议加入.gitignore的例外也就是说档案文件要提交到仓库但recent_changes.txt这种动态生成的文件不提交。这样团队每个人拉下来就有统一的档案减少“我这里跑得好好的”这类扯皮。4.2 档案初始化用脚本自动提取项目信息手写profile.yaml太累且容易漏我写了个初始化脚本自动扫描项目提取关键信息。核心逻辑是解析pom.xml或build.gradle拿依赖列表扫描源码目录推断包结构读取现有代码统计命名风格。# init_profile.py 核心片段 import xml.etree.ElementTree as ET import os import re def parse_pom(pom_path): tree ET.parse(pom_path) root tree.getroot() ns {m: http://maven.apache.org/POM/4.0.0} deps [] for dep in root.findall(.//m:dependency, ns): groupId dep.find(m:groupId, ns).text artifactId dep.find(m:artifactId, ns).text version_el dep.find(m:version, ns) version version_el.text if version_el is not None else managed deps.append({ groupId: groupId, artifactId: artifactId, version: version }) return deps def infer_package_structure(src_dir): packages set() for root, dirs, files in os.walk(src_dir): for f in files: if f.endswith(.java): with open(os.path.join(root, f), r, encodingutf-8) as fh: content fh.read() match re.search(rpackage\s([\w.]);, content) if match: packages.add(match.group(1)) return sorted(packages)这个脚本跑一遍能自动填好dependencies和structure.base_package以及layers的大部分内容。剩下的conventions和forbidden需要手动补因为那些是团队约定脚本猜不出来。我一般会花十分钟跟团队确认这几条一次确认长期受益。4.3 调度脚本的调用方式与参数说明调度脚本我设计成命令行工具方便在终端里直接调用也方便集成到编辑器的快捷键里。# 基本用法传入用户指令输出组装好的 prompt python .superpowers/scheduler.py --input 帮我加一个根据用户ID查询订单列表的接口 # 指定输出格式直接写入文件供 Codex 读取 python .superpowers/scheduler.py --input 修复订单查询的空指针 --output prompt.txt # 查看当前会注入哪些档案片段调试用 python .superpowers/scheduler.py --input 新增接口 --dry-run--dry-run这个参数我强烈建议加上调试调度规则时特别有用。你可以看到针对不同指令实际会注入哪些档案片段如果发现某个该注入的没注入或者注入了无关内容就回去调TRIGGER_RULES。我调了大概二十几次才把规则调顺现在基本能做到“该有的都有不该有的不塞”。调度脚本的输出格式也有讲究。我最终采用的格式是[项目档案] {注入的档案片段YAML 格式} [最近变更] {recent_changes.txt 内容} [用户指令] {原始输入} [输出要求] 1. 只输出代码不要解释 2. 代码块用 java 包裹 3. 如果需要新增文件先输出文件路径 4. 修改现有文件时只输出变更部分用注释标注上下文最后那段“输出要求”是固定模板它比档案本身还重要。没有这段约束AI 会给你写一大段解释文字代码混在里面提取起来很麻烦。加上这段之后输出干净多了我写了个简单的解析器就能自动提取代码块和文件路径。4.4 与 Codex 的对接实操对接方式取决于你用的是什么形态的 Codex。如果是 API 方式直接发 HTTP 请求就行import requests def call_codex(prompt, api_key): headers { Authorization: fBearer {api_key}, Content-Type: application/json } payload { model: codex, messages: [ {role: system, content: 你是一个严格遵守项目规范的 Java 开发助手。}, {role: user, content: prompt} ], temperature: 0.2, max_tokens: 2000 } resp requests.post(https://api.example.com/v1/chat/completions, headersheaders, jsonpayload) return resp.json()[choices][0][message][content]temperature设成 0.2 是我反复试出来的。设 0 太死板AI 有时候会卡在一个错误方案上反复输出设 0.5 以上又太发散生成的代码风格飘忽不定。0.2 在稳定性和灵活性之间平衡得比较好。如果你用的是网页版 Codex没有 API 权限那就手动把调度脚本生成的 prompt 复制粘贴进去。虽然多了一步操作但效果是一样的。我早期就是这么干的后来调用频繁了才换成 API。4.5 后处理校验脚本的集成校验脚本我集成在调用 Codex 之后自动执行流程是调度生成 prompt → 调用 Codex → 提取代码 → 跑校验 → 通过则写入文件不通过则把校验失败原因拼回 prompt 重新调用。def validate_and_fix(code, profile): errors [] # 检查禁止 API for forbidden in profile[forbidden]: pattern forbidden.split()[0].replace(使用 , ) if pattern in code: errors.append(f使用了禁止的 API: {pattern}) # 检查 import 完整性 imports re.findall(rimport\s([\w.]);, code) # ... 对比项目已有类补全缺失 import # 检查返回类型 if Controller in code and Result not in code: errors.append(Controller 方法未使用 Result 包装返回) return errors校验失败时我会把errors列表拼成一段话追加到原 prompt 后面再调一次 Codex。通常第二次就能过因为 AI 看到具体错误原因后会针对性修正。如果第二次还不过我就人工介入不再自动重试避免陷入死循环浪费 token。5. 常见问题与排查技巧实录5.1 档案写了但 AI 不遵守怎么办这是最常见的问题我一开始也遇到。档案里明明写了“禁止使用 System.out.println”AI 还是照写不误。排查下来原因有三个。第一是档案位置不对AI 根本没读到。检查方法是用--dry-run看注入内容里有没有你写的约束。第二是约束太靠后被前面的内容稀释了。解决办法是把最重要的约束放在档案最前面或者单独拎出来放在 prompt 的开头部分。第三是措辞太模糊AI 理解不了。比如写“注意代码规范”等于没写要写“类名用 UpperCamelCase方法名用 lowerCamelCase”这种可执行的规则。我现在的做法是把最关键的 3-5 条约束单独拎出来放在 prompt 的最开头用醒目的标记包起来比如[硬性约束 - 必须遵守] 1. 禁止使用 System.out.println统一用 Slf4j 2. Controller 必须返回 Result 包装 3. 禁止使用 java.util.Date这样 AI 几乎不会违反。剩下的约束放在档案里作为补充违反率也低了很多。5.2 上下文太长导致 AI “失忆”superpowers 注入的档案加上项目源码很容易超过 AI 的上下文窗口。我遇到过注入内容太长AI 把前面的约束忘了只记得最后几行的情况。解决办法是分层注入核心约束永远放在最前面且保持简短详细档案放在中间最近变更放在后面。如果还是超长就只注入与当前任务最相关的档案片段而不是全量注入。我做了个简单的 token 估算函数用字符数除以 4 粗略估算 token 数超过 3000 就触发裁剪逻辑按优先级从低到高丢弃档案片段。这个粗暴的方法实测够用比精确计算 token 省事多了。5.3 生成的代码风格与项目不一致AI 生成的代码能跑但风格跟项目里其他代码格格不入比如别人用Autowired构造器注入它用字段注入别人用Optional判空它用if (obj ! null)。这个问题根源在于档案里没有提供足够的风格样本。我的解决办法是在templates/文件夹里放几个“标杆文件”也就是项目里写得最规范的几个类调度时把标杆文件的关键片段也注入进去。AI 看到实际样本后模仿能力比看文字描述强得多。5.4 常见问题速查表问题现象可能原因排查方法解决措施AI 不遵守约束档案未注入/措辞模糊/位置靠后用 --dry-run 检查注入内容核心约束前置措辞具体化上下文超长失忆注入内容过多估算 token 数分层注入按优先级裁剪代码风格不一致缺少风格样本对比标杆文件注入标杆文件片段import 缺失后处理未校验跑校验脚本自动补全或打回重问返回类型错误档案未强调检查 api_response 字段加入硬性约束列表命名不规范命名规则未注入检查 conventions 字段补充命名规则并前置重复生成相同错误重试时未附错误原因检查重试逻辑把校验错误拼回 prompt调度规则不生效关键词未命中用 --dry-run 测试调整 TRIGGER_RULES 关键词这张表是我踩坑踩出来的基本上覆盖了 90% 的常见问题。建议把这张表打印出来贴在显示器旁边遇到问题先查表能省不少排查时间。5.5 几个容易被忽略的实操心得第一档案要版本化。我把.superpowers/profile.yaml提交到 Git每次修改都写 commit message比如“增加禁止使用 Date 的约束”。这样当 AI 行为发生变化时可以回溯是哪次档案修改导致的。我遇到过改了档案后 AI 突然开始用错日志框架回滚档案就恢复了。第二定期清理 recent_changes。这个文件如果一直追加不清理会越来越长最终拖垮上下文。我的做法是只保留最近 7 天的变更记录更早的自动归档到另一个文件不参与注入。第三不同任务用不同档案。我维护了两份档案一份是“开发模式”约束严格适合写新功能一份是“探索模式”约束宽松适合让 AI 快速读代码、做分析。切换档案比改档案方便也避免了探索时被一堆约束束手束脚。第四别指望一次配置到位。superpowers 是个需要持续调优的东西我用了三个月还在微调调度规则。把它当成一个需要迭代的项目而不是一次性配置心态会好很多。每次 AI 出错不要只骂它笨想想是不是档案或调度哪里可以改进改完下次就好了。6. 进阶玩法把 superpowers 用到 Java 之外虽然热词里superpowers java出现频率最高但这套思路并不局限于 Java。我后来把它迁移到了前端项目和一个 Python 数据处理脚本上核心逻辑完全一样只是档案字段和校验规则换了。前端项目里我把conventions换成 ESLint 规则摘要forbidden换成“禁止使用 var”“禁止直接操作 DOM”这类约束templates里放 React 函数组件的标杆写法。效果同样明显AI 生成的组件风格统一多了不会再一会儿用 class 组件一会儿用函数组件。Python 项目里我把structure.layers换成模块划分conventions.naming换成 PEP 8 摘要forbidden加上“禁止使用 mutable 默认参数”这类 Python 特有的坑。校验脚本里加了flake8的调用AI 生成的代码直接过一遍 lint不通过就打回。迁移的关键是抽象出“档案-调度-校验”这个骨架然后针对不同语言填充具体内容。骨架代码几乎不用改改的是 YAML 档案和校验规则。我大概花了半天时间就把前端版本搭起来了因为核心逻辑已经跑通了。如果你团队里有人用不同的技术栈可以各自维护自己的.superpowers/档案但共享调度和校验脚本。这样既保证了各栈的个性化又避免了重复造轮子。我们团队现在就是这么干的Java 组和前端组各有一份档案调度脚本是同一份维护成本很低。最后分享一个我最近在试的玩法把 superpowers 的档案生成也交给 AI。我写了个脚本让 AI 读一遍项目源码自动生成profile.yaml的初稿我再人工审核修改。这样初始化新项目时能省不少事虽然生成的档案不够精确但作为起点足够了改起来比从零写快得多。这个思路还在打磨中等稳定了再单独写一篇分享。
