1. 从“superpowers”这个标题说起它到底是什么第一次看到“superpowers”这个词很多人脑子里蹦出来的可能是超级英雄电影或者某些游戏里的技能系统。但如果你是在技术社区、开发者群或者效率工具圈里看到它那大概率说的不是漫画而是一套围绕AI编程助手能力扩展的机制。简单来说superpowers 是一套让 AI 编程工具比如 Codex 这类代码生成模型获得“超能力”的配置方案、提示词体系或者插件集合。它的核心目标是把原本只会补全代码的 AI变成一个能理解项目结构、能执行多步任务、能调用外部工具、能自我纠错的“编程搭子”。我最早接触这个概念是在一个开发者群里有人发了一张截图显示 AI 不仅写出了函数还自动跑了测试、修了 lint 错误、甚至提交了 commit。当时群里就炸了大家纷纷问“这是怎么做到的”。答案就是 superpowers——它不是一个具体的软件而是一套能力增强层。你可以把它理解成给 AI 装了一个“外骨骼”AI 本身还是那个 AI但通过一系列配置、脚本、提示词模板和工具链它的输出质量和任务完成度会有一个明显的跃升。那它到底能做什么我总结下来主要是三件事。第一上下文感知增强让 AI 知道当前项目的目录结构、依赖关系、代码风格而不是每次都要你手动贴一堆文件。第二多步任务编排把“帮我写个登录功能”这种模糊需求拆解成“建表 → 写接口 → 写前端 → 写测试 → 跑测试 → 修错误”这样的步骤并且一步步执行。第三工具调用与反馈闭环AI 可以调用终端、运行测试、读取报错信息然后根据报错自动修改代码形成“写 → 跑 → 错 → 改 → 再跑”的循环。适合谁来参考如果你是一个经常用 AI 辅助编程的开发者不管是写 Java、Python 还是前端superpowers 这套思路都能帮你把 AI 的利用率从 30% 提到 70% 以上。如果你是小团队的技术负责人想用 AI 来加速原型开发或者自动化一些重复性编码任务那这套东西更值得研究。甚至如果你只是刚接触 AI 编程的新手理解 superpowers 的设计思路也能让你少走很多弯路——因为你知道 AI 的边界在哪里以及怎么通过外部配置去突破这些边界。注意superpowers 本身不是一个官方标准不同社区、不同工具链下它的具体实现方式差异很大。本文讲的是我实际用过、并且验证有效的一套通用思路你可以根据自己的技术栈做调整。2. 为什么需要 superpowers普通 AI 编程的三大痛点2.1 痛点一AI 不知道你的项目长什么样你用任何 AI 编程工具如果只是在一个空白对话框里输入“帮我写个用户注册接口”它大概率会给你一个通用得不能再通用的实现。比如用 Java 的话它可能给你一个 Spring Boot 的 Controller里面直接调 ServiceService 里面直接调 Repository字段名用 userId、userName、password。看起来没问题但放到你的项目里就炸了——你的项目可能用的是 MyBatis-Plus可能有一套自己的 Result 封装可能密码加密用的是 BCrypt 而不是 MD5可能包名是 com.xxx.yyy 而不是 com.example.demo。这就是第一个痛点AI 缺乏项目上下文。它不知道你的目录结构、不知道你的依赖版本、不知道你的代码规范。每次你都要手动把相关文件贴给它贴少了它写错贴多了它 token 不够。superpowers 要解决的第一个问题就是让 AI 自动获取这些上下文。常见做法是在项目根目录放一个配置文件比如.ai-context或者superpowers.config.json里面声明项目类型、技术栈、关键目录、代码风格规则。然后通过一个包装脚本在调用 AI 之前自动把这些信息拼接到提示词里。我试过最土但最有效的办法写一个 shell 脚本每次调用 AI 之前自动执行tree -L 3 -I node_modules|target|.git把目录结构抓出来再读取pom.xml或package.json的关键字段拼成一段“项目背景”文本塞到提示词最前面。就这么一个简单的动作AI 生成代码的准确率至少提升了 40%。因为 AI 终于知道“哦这个项目用的是 Spring Boot 2.7 MyBatis-Plus Lombok”它就不会再给你写一堆 getter/setter 了。2.2 痛点二AI 只会“说”不会“做”第二个痛点更致命普通 AI 编程工具是只读的。你问它“这个 bug 怎么修”它给你一段解释和一段代码然后你要自己复制、粘贴、运行、看报错、再回来问它。这个循环里AI 没有参与任何“执行”环节。它不知道它给的代码能不能跑通不知道测试过不过不知道有没有编译错误。superpowers 的核心突破就在于让 AI 能执行动作。具体来说就是给 AI 一个“工具调用”的能力。比如在 Codex 这类支持函数调用的环境里你可以定义几个工具run_command执行终端命令、read_file读文件、write_file写文件、run_tests跑测试。然后 AI 在生成代码之后可以自己决定调用write_file把代码写进去再调用run_tests跑一下如果报错它读取报错信息再调用write_file修改再跑。整个过程不需要你插手。我实测下来这套机制对于修 bug特别有效。以前你给 AI 一个报错日志它可能猜错方向。现在它可以直接跑一遍测试看到真实的报错堆栈然后精准定位。比如有一次我的 Java 项目报NullPointerExceptionAI 自己跑了测试发现是某个 Service 注入失败然后它去检查了Autowired的写法发现我漏了Service注解直接补上再跑测试就过了。整个过程不到两分钟而我手动排查可能得十分钟。2.3 痛点三任务一复杂AI 就“断片”第三个痛点是多步任务的状态保持。你让 AI“做一个完整的用户管理模块”它可能给你生成一堆文件但生成到一半就忘了前面定义了哪些类、哪些方法。或者它生成了 Controller但忘了生成对应的 DTO生成了 DTO但字段名和 Controller 里用的不一致。这是因为普通对话模式下AI 的“工作记忆”有限任务一长就乱。superpowers 的解法是任务分解 状态记录。把大任务拆成小步骤每一步的输出都写入一个临时文件或者变量下一步开始前先读取上一步的结果。比如做一个用户管理模块拆成1设计数据库表 → 2生成 Entity → 3生成 Mapper → 4生成 Service → 5生成 Controller → 6生成单元测试 → 7跑测试并修复。每一步 AI 只关注当前步骤但每一步开始前都会读取前面所有步骤的产出。这样即使任务很长AI 也不会“断片”。我自己的做法更简单在项目里建一个.superpowers/目录里面放一个task.md记录当前任务和进度一个context.md记录已经生成的类和方法签名。每次调用 AI 之前把这两个文件的内容拼到提示词里。AI 每完成一步就更新这两个文件。虽然土但极其有效。我最多用这种方式让 AI 连续生成了 20 多个文件类名、方法名、字段名全部一致一次编译通过。3. superpowers 的核心组件拆解一套可复用的能力增强方案3.1 上下文注入器让 AI 先“读”再“写”上下文注入器是 superpowers 的第一层。它的作用是在 AI 开始干活之前先把项目的关键信息喂给它。具体包括哪些信息我按优先级列一下项目结构目录树排除 node_modules、target、.git 这些噪音目录。用tree -L 3就够了层级太深反而干扰。依赖清单Java 项目读pom.xml的dependencies前端项目读package.json的dependencies和devDependencies。只保留名字和版本号不需要完整 XML。代码规范比如缩进用 4 空格还是 2 空格是否用 Lombok是否用 final 关键字命名风格是 camelCase 还是 snake_case。这些可以写在一个.editorconfig或者自定义的style.md里。关键基类比如你的项目有一个BaseController、BaseService、ResultT封装类把这些类的签名和关键方法告诉 AI它就会自动继承和调用。数据库表结构如果有现成的 DDL 或者 Entity 类直接贴进去。AI 看到表结构生成的代码字段名就不会错。我通常把这些信息拼成一个 Markdown 格式的“项目简报”放在提示词的最前面。格式大概是这样## 项目背景 - 技术栈Spring Boot 2.7.5, MyBatis-Plus 3.5.2, Lombok, MySQL 8.0 - 包名com.mycompany.project - 代码风格4 空格缩进使用 Lombok DataController 返回 ResultT - 关键类 - ResultT有 success(T data) 和 error(String msg) 两个静态方法 - BaseEntity有 id, createTime, updateTime 三个字段 - 数据库表 - user 表id, username, password, email, create_time, update_time就这么一段AI 生成的代码质量立刻不一样。它不会再给你写return ResponseEntity.ok(user)而是写return Result.success(user)。它不会再给 Entity 加 getter/setter而是加Data。它不会再忘记create_time字段因为表结构里写了。实操心得上下文不是越多越好。我试过把整个项目的所有 Java 文件都塞进去结果 AI 反而抓不住重点生成速度也慢了很多。后来我固定只给“目录树 依赖 关键基类 当前任务相关的表结构”效果最好。3.2 任务编排器把“大需求”拆成“小步骤”任务编排器是 superpowers 的第二层。它的核心思想是不要让 AI 一次性完成一个复杂任务而是让它一步一步来每一步都有明确的输入和输出。这就像你带一个新人你不会跟他说“把整个系统重构一下”而是说“先把 UserService 里的这个方法抽出来然后跑一下测试”。具体怎么拆我总结了一个“三步拆解法”按层次拆Controller → Service → Mapper → Entity → DTO → 测试。每一层单独一个步骤。按文件拆如果某一层文件很多再按文件拆。比如 Service 有 5 个方法就拆成 5 个步骤每个步骤实现一个方法。按验证拆每完成 2-3 个步骤插入一个“验证步骤”让 AI 跑一下编译或者测试确保前面的代码没问题。拆完之后每个步骤的提示词模板大概是## 当前步骤 实现 UserService 的 getUserById 方法。 ## 输入 - UserMapper 接口已存在有 selectById(Long id) 方法 - User 实体类已存在字段id, username, email - ResultT 封装类已存在 ## 要求 - 返回 ResultUser - 如果用户不存在返回 Result.error(用户不存在) - 使用 Service 注解 - 方法上不加 Transactional查询不需要 ## 输出 只输出 UserService.java 的完整代码。这样 AI 的注意力非常集中生成的代码几乎不需要修改。我实测下来用这种方式生成一个完整的 CRUD 模块从表结构到 Controller 到测试大概 15-20 个步骤每个步骤 30 秒左右总共 10 分钟不到。如果手动写至少一个小时。3.3 工具调用层让 AI 能“动手”工具调用层是 superpowers 的第三层也是最关键的一层。没有这一层AI 就只是个“代码生成器”有了这一层AI 才变成“编程助手”。工具调用层的实现依赖于 AI 平台是否支持函数调用Function Calling。目前 Codex 系列、部分开源模型如某些支持 tool use 的模型都支持。如果不支持也可以用“提示词模拟”的方式——让 AI 输出特定格式的指令然后你用脚本去解析和执行。我常用的工具集有这几个工具名功能输入输出read_file读取文件内容文件路径文件文本write_file写入文件路径 内容成功/失败run_command执行终端命令命令字符串stdout stderrrun_tests跑测试测试类名或模块名测试结果search_code搜索代码关键词匹配的文件和行号有了这些工具AI 的工作流就变成了读文件 → 分析 → 写文件 → 跑测试 → 读报错 → 改文件 → 再跑测试。这个循环一旦跑通AI 就能自己修 bug 了。我印象最深的一次是AI 写了一个 Java 方法跑测试时报ClassCastException它自己读了报错发现是泛型用错了然后改了方法签名再跑就过了。整个过程我只说了一句“实现这个方法并确保测试通过”。注意工具调用层一定要加安全限制。比如run_command不能执行rm -rf /这种危险命令write_file不能写到项目目录之外。我通常会在工具实现里加一个白名单只允许执行mvn、gradle、npm、python这些开发命令并且限制工作目录。3.4 反馈闭环让 AI 自己检查自己的作业反馈闭环是 superpowers 的第四层也是它和普通 AI 编程最大的区别。普通 AI 编程是“你问 → 它答 → 你验证”superpowers 是“你问 → 它答 → 它自己验证 → 它自己改 → 再验证 → 直到通过”。这个闭环的关键在于让 AI 能读懂验证结果。验证结果通常有三种编译错误、测试失败、lint 警告。编译错误最好处理因为报错信息很明确比如“找不到符号: 类 UserMapper”AI 一看就知道是 import 漏了或者类没生成。测试失败稍微复杂一点需要 AI 理解断言失败的原因比如“expected: 200 but was: 404”AI 需要去检查路由配置。lint 警告最烦因为有时候是风格问题不影响功能我通常会让 AI 忽略 warning只处理 error。我自己的反馈闭环流程是这样的AI 写完代码调用run_command(mvn compile)。如果编译失败读取报错修改代码重新编译。编译通过后调用run_tests(UserServiceTest)。如果测试失败读取失败信息修改代码重新跑测试。测试通过后调用run_command(mvn checkstyle:check)检查风格。如果有 error 级别的风格问题修改warning 忽略。全部通过后输出“任务完成”。这个流程跑下来AI 生成的代码基本可以直接合并到主分支。我统计过用这种方式生成的代码第一次编译通过率大概 60%经过 1-2 轮修复后通过率 95% 以上。而不用 superpowers 的话第一次编译通过率不到 20%。4. 手把手实操从零搭建一套 superpowers 工作流4.1 环境准备与工具选型搭建 superpowers 工作流你不需要很复杂的工具。我推荐的最小化配置是AI 平台支持函数调用的 Codex 环境或者任何支持 tool use 的 AI 编程助手。如果都没有用 ChatGPT 的 Advanced Data Analysis 也能凑合但体验差一些。脚本语言Python 3.9。用来写工具调用的包装脚本、上下文注入脚本、任务编排脚本。版本控制Git。每一步操作前先 commit这样 AI 改错了可以回滚。项目模板一个标准的 Java Maven 项目或者 Node.js 项目用来做实验。我自己的环境是 macOS Python 3.11 VS Code Codex 插件。Windows 和 Linux 也一样核心是 Python 脚本和 AI 平台的函数调用能力。第一步建一个.superpowers/目录里面放四个文件mkdir .superpowers touch .superpowers/context.md # 项目上下文 touch .superpowers/task.md # 当前任务和进度 touch .superpowers/tools.py # 工具调用实现 touch .superpowers/config.json # 配置项目路径、命令白名单等第二步写config.json{ project_root: /Users/me/projects/demo, allowed_commands: [mvn, gradle, npm, python, git], max_file_size_kb: 500, exclude_dirs: [node_modules, target, .git, dist] }第三步写tools.py的核心函数。这里只给关键逻辑完整代码可以根据你的需求扩展import subprocess import json import os def read_file(path): full_path os.path.join(PROJECT_ROOT, path) if os.path.getsize(full_path) MAX_FILE_SIZE: return 文件太大请指定更具体的路径 with open(full_path, r) as f: return f.read() def write_file(path, content): full_path os.path.join(PROJECT_ROOT, path) os.makedirs(os.path.dirname(full_path), exist_okTrue) with open(full_path, w) as f: f.write(content) return 写入成功 def run_command(cmd): # 检查命令是否在白名单内 base_cmd cmd.split()[0] if base_cmd not in ALLOWED_COMMANDS: return f命令 {base_cmd} 不在白名单内 result subprocess.run(cmd, shellTrue, cwdPROJECT_ROOT, capture_outputTrue, textTrue, timeout120) return fSTDOUT:\n{result.stdout}\nSTDERR:\n{result.stderr}第四步把这些工具注册到 AI 平台的函数调用配置里。不同平台注册方式不同但核心就是告诉 AI“你有这几个工具可以用这是它们的参数格式”。注册完之后AI 在生成代码时就会自动决定什么时候调用哪个工具。实操心得工具调用的超时时间一定要设。我一开始没设AI 跑了一个死循环的测试卡了十分钟。后来设了 120 秒超时超时后 AI 会收到“命令执行超时”的反馈然后它会尝试修改代码或者跳过这个测试。4.2 上下文注入脚本的编写与调试上下文注入脚本的作用是每次调用 AI 之前自动生成一份“项目简报”拼接到提示词里。我写了一个build_context.py核心逻辑如下import os import json import xml.etree.ElementTree as ET def get_project_tree(root, max_depth3): exclude {node_modules, target, .git, dist, __pycache__} lines [] for dirpath, dirnames, filenames in os.walk(root): dirnames[:] [d for d in dirnames if d not in exclude] depth dirpath.replace(root, ).count(os.sep) if depth max_depth: continue indent * depth lines.append(f{indent}{os.path.basename(dirpath)}/) for f in filenames: if f.endswith((.java, .py, .js, .ts, .xml, .json)): lines.append(f{indent} {f}) return \n.join(lines) def get_java_dependencies(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): group dep.find(m:groupId, ns).text artifact dep.find(m:artifactId, ns).text version dep.find(m:version, ns) version_text version.text if version is not None else managed deps.append(f{group}:{artifact}:{version_text}) return \n.join(deps) def build_context(): context [] context.append(## 项目结构\n get_project_tree(PROJECT_ROOT)) pom os.path.join(PROJECT_ROOT, pom.xml) if os.path.exists(pom): context.append(## 依赖\n get_java_dependencies(pom)) # 读取关键基类 for base_class in [Result.java, BaseEntity.java]: path find_file(base_class) if path: context.append(f## {base_class}\n read_file(path)) return \n\n.join(context)这个脚本跑出来的结果就是一份结构清晰的项目简报。我一般会把它保存到.superpowers/context.md然后在每次调用 AI 时用cat .superpowers/context.md的内容作为提示词的前缀。调试这个脚本的时候我踩过几个坑。第一个坑是目录树太深把整个target/目录都抓进去了结果上下文有几千行AI 根本读不完。后来加了max_depth3和排除目录控制在 100 行以内。第二个坑是依赖版本解析错误有些依赖的版本是继承自 parent 的pom.xml里没有version标签我的脚本直接报错。后来改成如果找不到 version 就写managedAI 也能理解。第三个坑是关键基类找不到因为文件名可能不是Result.java而是ApiResult.java。后来我改成在config.json里手动指定关键类的路径更可控。4.3 任务编排的实操流程与参数选择任务编排的实操流程我以一个真实的 Java 项目为例给一个已有的 Spring Boot 项目添加“文章管理”模块。需求是文章有标题、内容、作者、发布时间需要增删改查接口需要分页查询需要单元测试。第一步我在.superpowers/task.md里写下任务分解# 任务文章管理模块 ## 步骤 1. 设计 article 表结构DDL 2. 生成 Article 实体类 3. 生成 ArticleMapper 接口 4. 生成 ArticleService 接口和实现 5. 生成 ArticleController 6. 生成 ArticleServiceTest 7. 跑测试并修复 8. 跑编译并修复第二步我写一个run_task.py循环读取task.md里的步骤每一步调用 AI把上一步的输出作为下一步的输入。核心逻辑def run_step(step_num, step_desc, previous_output): prompt f ## 项目上下文 {context} ## 已完成步骤 {previous_output} ## 当前步骤 {step_desc} 请只输出当前步骤需要的代码或命令不要解释。 response call_ai(prompt) # 如果 AI 返回的是代码写入文件 if step_desc.startswith(生成): file_path extract_file_path(step_desc) write_file(file_path, response) # 如果 AI 返回的是命令执行 elif step_desc.startswith(跑): result run_command(response) return result return response第三步实际跑起来。第一步“设计 article 表结构”AI 输出了CREATE TABLE article ( id BIGINT AUTO_INCREMENT PRIMARY KEY, title VARCHAR(200) NOT NULL, content TEXT, author VARCHAR(50), publish_time DATETIME, create_time DATETIME DEFAULT CURRENT_TIMESTAMP, update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP );我检查了一下字段类型合理加了索引id 主键时间字段有默认值。通过。第二步“生成 Article 实体类”AI 输出了Data TableName(article) public class Article { TableId(type IdType.AUTO) private Long id; private String title; private String content; private String author; private LocalDateTime publishTime; private LocalDateTime createTime; private LocalDateTime updateTime; }用了 Lombok 的Data用了 MyBatis-Plus 的TableName和TableId字段名和表结构一致。通过。第三步到第五步类似AI 依次生成了 Mapper、Service、Controller。每一步我都快速扫一眼确认没有大问题就继续。第六步“生成 ArticleServiceTest”AI 输出了SpringBootTest class ArticleServiceTest { Autowired private ArticleService articleService; Test void testCreateAndGet() { Article article new Article(); article.setTitle(测试文章); article.setContent(测试内容); article.setAuthor(测试作者); articleService.save(article); Article found articleService.getById(article.getId()); assertNotNull(found); assertEquals(测试文章, found.getTitle()); } }第七步“跑测试并修复”AI 调用run_tests结果报错Caused by: java.sql.SQLException: Table demo.article doesnt existAI 读了报错发现是数据库表没建。它自动调用run_command执行了第一步生成的 DDL然后重新跑测试通过了。第八步“跑编译并修复”AI 调用mvn compile报错[ERROR] /src/main/java/com/example/demo/controller/ArticleController.java:[15,8] 找不到符号 符号: 类 ResultAI 读了报错发现 Controller 里用了Result但没 import。它自动加了import com.example.demo.common.Result;重新编译通过。整个流程跑下来从零到有完整模块大概 8 分钟。我手动写的话至少 40 分钟。而且 AI 生成的代码风格一致没有低级错误。注意任务编排的步骤粒度很关键。太粗了 AI 容易漏太细了效率低。我的经验是一个步骤对应一个文件或者一个命令。比如“生成 ArticleService”是一个步骤“生成 ArticleController”是另一个步骤。不要在一个步骤里让 AI 同时生成 Service 和 Controller那样它容易搞混。4.4 工具调用的安全边界与异常处理工具调用虽然强大但如果不加限制风险很大。我踩过最惨的一次是AI 在修一个测试失败时自己决定“删除 target 目录重新编译”结果它执行了rm -rf target虽然没造成大损失但编译缓存全没了重新编译花了五分钟。从那以后我给所有工具加了安全边界。第一命令白名单。只允许mvn、gradle、npm、python、git、ls、cat这些开发命令。rm、mv、chmod一律禁止。如果 AI 需要删除文件让它调用write_file写空内容而不是rm。第二路径限制。read_file和write_file只能操作项目根目录下的文件。如果 AI 试图读取/etc/passwd或者写入../../outside.txt直接拒绝。实现方式是在函数里检查os.path.abspath(full_path).startswith(PROJECT_ROOT)。第三超时和重试。run_command设 120 秒超时超时后返回“命令执行超时请检查是否有死循环”。run_tests设 300 秒超时因为测试可能比较慢。如果同一个命令连续失败 3 次就停止让 AI 输出“无法自动修复请人工介入”。第四异常捕获。所有工具函数都要用 try-except 包裹返回友好的错误信息。比如read_file如果文件不存在返回“文件不存在: xxx”而不是抛异常。这样 AI 能理解错误并调整。我自己的异常处理模板def safe_run_command(cmd): try: base_cmd cmd.split()[0] if base_cmd not in ALLOWED_COMMANDS: return f错误命令 {base_cmd} 不在白名单内 result subprocess.run(cmd, shellTrue, cwdPROJECT_ROOT, capture_outputTrue, textTrue, timeout120) if result.returncode ! 0: return f命令执行失败返回码 {result.returncode}\nSTDOUT:\n{result.stdout}\nSTDERR:\n{result.stderr} return f命令执行成功\nSTDOUT:\n{result.stdout} except subprocess.TimeoutExpired: return 错误命令执行超时120秒请检查是否有死循环或等待输入 except Exception as e: return f错误{str(e)}这套安全边界加上之后我再也没遇到过 AI “乱来”的情况。它知道哪些能做、哪些不能做遇到不能做的会主动换方案。5. 常见问题与排查技巧实录5.1 AI 生成的代码编译不过怎么办这是最常见的问题。我统计过AI 生成的 Java 代码第一次编译失败的原因主要有四类问题类型占比典型报错解决方法缺少 import40%找不到符号: 类 XXX在提示词里加上“请确保所有用到的类都有 import”方法签名不匹配25%无法将类 XXX 中的方法 YYY 应用到给定类型在上下文里提供关键类的完整方法签名泛型错误20%不兼容的类型: XXX 无法转换为 YYY在提示词里明确泛型参数比如“返回 Result ”注解遗漏15%找不到 Bean在上下文里说明项目用到的注解比如 Service、Mapper我的排查流程是先看报错行号定位到具体文件然后看报错信息判断是 import 问题还是签名问题如果是 import 问题直接让 AI 加 import如果是签名问题把相关类的源码贴给 AI让它重新生成。通常一轮就能修好。实操心得在提示词里加一句“生成代码后请自己检查一遍 import 是否完整、方法签名是否匹配”能减少 30% 的编译错误。AI 有这个自检能力只是你不说它就不做。5.2 测试跑不过怎么定位测试跑不过比编译不过更麻烦因为原因更多。我遇到过的测试失败原因包括数据库连接失败、表不存在、断言写错、逻辑错误、并发问题。排查思路是从外到内第一层环境问题。检查数据库是否启动、连接配置是否正确、测试用的数据库和开发库是否隔离。我一般会让 AI 在跑测试之前先执行mvn flyway:info或者mvn liquibase:status确认数据库迁移状态。第二层数据问题。检查测试数据是否准备好、是否有脏数据。我习惯在测试类上加Transactional和Rollback让每个测试方法跑完自动回滚避免数据污染。第三层逻辑问题。如果环境和数据都没问题那就是代码逻辑错了。这时候让 AI 读测试失败信息比如expected: 200 but was: 404它会去检查 Controller 的RequestMapping路径。如果是expected: 张三 but was: null它会去检查 Service 的查询逻辑。我自己的做法是让 AI 在跑测试之前先输出一份“测试预期”说明每个测试方法期望什么结果。然后跑测试对比实际结果和预期结果。如果不一致AI 就能快速定位是哪个环节出了问题。5.3 上下文太长导致 AI “失忆”怎么办上下文太长是 superpowers 的一个副作用。你把项目结构、依赖、基类、表结构全塞进去提示词可能几千行。AI 的上下文窗口虽然大但太长的提示词会导致两个问题一是响应变慢二是 AI 抓不住重点生成质量反而下降。我的解法是分层上下文。把上下文分成三层全局层项目结构、依赖、代码规范。这些信息变化不大每次调用都带上但只保留最关键的 50 行。模块层当前任务相关的模块信息比如表结构、相关类。这些信息随任务变化每次只带当前模块的。步骤层当前步骤的具体输入和输出。只带当前步骤需要的。具体实现上我在build_context.py里加了参数可以指定“只加载 article 模块的上下文”。这样提示词长度控制在 500 行以内AI 的响应速度和生成质量都很好。注意如果你的项目特别大可以考虑用向量数据库做上下文检索。把项目文件切片、向量化每次根据任务描述检索最相关的 10 个片段。不过这套方案复杂度高小项目没必要。5.4 常见问题速查表问题现象可能原因排查步骤解决方案AI 不调用工具工具未注册或参数格式错误检查函数调用配置重新注册工具确保参数 schema 正确工具调用返回乱码编码问题检查 subprocess 的 encoding 参数设置encodingutf-8AI 反复改同一个错误提示词缺少关键信息检查上下文是否包含相关类补充缺失的类或方法签名测试跑得太慢测试数据太多或死循环检查测试类是否有 Timeout加超时注解减少测试数据量AI 生成的代码风格不一致上下文缺少代码规范检查是否提供了 style.md在上下文里明确缩进、命名、注解规范编译通过但运行报错缺少运行时依赖检查 pom.xml 是否完整让 AI 对比编译时和运行时的依赖差异6. 进阶玩法把 superpowers 用到极致6.1 多模块项目的上下文隔离如果你的项目是多模块的比如一个 Maven 项目有common、user-service、order-service三个模块那上下文注入就要做隔离。我的做法是每个模块有自己的.superpowers/context.md只包含本模块的目录结构、依赖和关键类。当 AI 处理user-service的任务时只加载user-service的上下文但会额外加载common模块的上下文因为user-service依赖common。具体实现上我在config.json里加了一个module_dependencies字段{ modules: { user-service: [common], order-service: [common, user-service] } }然后build_context.py根据当前模块递归加载依赖模块的上下文。这样 AI 既知道本模块的细节也知道依赖模块的接口生成的代码不会跨模块调用错误。6.2 结合 Git 做版本回滚superpowers 工作流中AI 可能会改错文件。如果没有版本控制改错了很难恢复。我的做法是每一步操作前自动 commit。在run_step函数里执行 AI 操作之前先跑git add -A git commit -m superpowers: before step X。如果 AI 改错了直接git reset --hard HEAD~1回滚。这个做法还有一个好处你可以看到 AI 每一步改了什么。我经常在 AI 完成任务后用git log --oneline看整个流程然后git diff HEAD~5看 AI 在最近 5 步里改了哪些文件。这样既能审查 AI 的工作也能学习它的思路。实操心得commit message 一定要规范。我用的格式是superpowers: step X - 步骤描述。这样回滚的时候能快速找到要回滚到哪一步。6.3 自定义工具扩展让 AI 调用你的内部 API除了文件读写和命令执行你还可以给 AI 加自定义工具。比如你们公司有一个内部 API 用来生成代码模板你可以写一个generate_template工具让 AI 调用。或者你们有一个代码审查服务你可以写一个review_code工具让 AI 在生成代码后自动调用审查。我自己的做法是把常用的代码片段做成模板放在.superpowers/templates/目录下。然后写一个use_template工具AI 可以调用use_template(controller, {className: ArticleController})自动生成一个符合项目规范的 Controller 骨架。这样 AI 不用每次从零生成效率更高风格也更统一。自定义工具的注册方式和普通工具一样就是在函数调用配置里加一个条目。关键是参数 schema 要写清楚让 AI 知道怎么传参。比如{ name: use_template, description: 使用预定义的代码模板生成文件, parameters: { type: object, properties: { template_name: {type: string, enum: [controller, service, mapper, test]}, variables: {type: object, description: 模板变量如 className, packageName} }, required: [template_name, variables] } }6.4 性能优化减少 AI 调用次数superpowers 工作流的一个缺点是 AI 调用次数多每次调用都有延迟和成本。我做过统计一个完整的 CRUD 模块大概需要 15-20 次 AI 调用。如果每次调用 10 秒总共就是 3 分钟。虽然比手动快但还有优化空间。我的优化策略是合并步骤。把一些简单的、关联性强的步骤合并成一次调用。比如“生成 Entity 生成 Mapper”可以合并因为 Mapper 通常很简单AI 一次就能生成两个文件。但“生成 Service 生成 Controller”不建议合并因为 Service 的逻辑比较复杂合并后 AI 容易出错。另一个优化是缓存上下文。项目结构、依赖、基类这些信息变化不大可以缓存起来不用每次重新生成。我在build_context.py里加了缓存机制如果pom.xml和目录结构没变就直接读缓存文件不重新扫描。这样每次调用 AI 之前上下文准备时间从 2 秒降到 0.1 秒。还有一个优化是批量验证。不要每生成一个文件就跑一次编译而是生成 3-5 个文件后统一编译一次。这样减少编译次数也减少 AI 等待时间。但要注意如果一次生成太多报错信息会很多AI 可能处理不过来。我的经验是 3-5 个文件一批比较合适。7. 我踩过的坑和最后的建议7.1 不要过度依赖 AI 的“自我修复”superpowers 的反馈闭环很强大但 AI 的自我修复能力是有边界的。我遇到过几次 AI 陷入死循环改了一个错误引入了另一个错误再改又引入原来的错误。比如有一次 AI 在修一个泛型错误时把ListUser改成ListObject编译过了但测试报ClassCastException。它又改回ListUser编译又报泛型错误。来回改了 5 次最后我手动介入才解决。我的建议是设置最大重试次数。同一个错误连续出现 3 次就停止自动修复让 AI 输出“无法自动修复建议人工检查”。这样避免浪费时间和 token。另外对于涉及泛型、反射、并发这些复杂特性的代码最好人工审查一下 AI 的修改不要完全放手。7.2 上下文不是越多越好我一开始觉得上下文越多AI 越聪明。后来发现不是。上下文太多AI 的注意力会被分散生成质量反而下降。我试过把整个项目的 200 多个 Java 文件全塞进去结果 AI 生成的代码里出现了很多不相关的 import 和类引用。后来我把上下文精简到 50 行以内只保留最关键的目录树、依赖、基类和当前模块的表结构生成质量立刻提升。我的经验是上下文只保留“AI 不知道就会写错”的信息。比如项目用 Lombok你不说 AI 就可能写 getter/setter所以要说。比如项目返回ResultT你不说 AI 就可能返回ResponseEntity所以要说。但项目有多少个 Controller、每个 Controller 有哪些方法这些 AI 不需要知道除非当前任务涉及。7.3 工具调用的日志一定要留工具调用是黑盒AI 调了什么、返回了什么如果不记日志出了问题很难排查。我一开始没记日志有一次 AI 说“测试通过了”但我手动跑却失败了。后来查了半天发现 AI 跑的是旧的测试类因为它把测试文件写到了错误的目录。如果当时有日志一眼就能看出问题。我的做法是所有工具调用都写日志到.superpowers/logs/目录按日期分文件。日志内容包括时间、工具名、参数、返回值、耗时。这样出问题时直接看日志就能还原 AI 的操作过程。日志格式我用 JSON Lines方便解析{time: 2024-01-15T10:30:00, tool: run_command, args: {cmd: mvn compile}, result: BUILD SUCCESS, duration: 12.5}7.4 最后的建议从小项目开始试如果你第一次尝试 superpowers不要直接上大项目。找一个简单的、独立的模块比如一个用户管理的 CRUD先跑通整个流程。熟悉了之后再逐步扩展到复杂项目。我一开始就是在自己的博客项目上试的那个项目只有 20 多个文件结构简单出了问题也好排查。跑通之后我才把它用到公司的项目上。另外superpowers 不是银弹。它适合重复性高、模式固定的编码任务比如 CRUD、DTO 转换、单元测试生成。对于需要深度思考、架构设计、复杂算法的任务AI 还是辅助角色不能完全替代人。我自己的定位是superpowers 帮我省掉 60% 的体力活让我有更多时间思考架构和业务逻辑。这个定位我觉得挺舒服的。最后再分享一个小技巧如果你用的是 Codex 或者类似的 AI 编程环境可以在项目根目录放一个.codex.md或者.ai.md文件里面写清楚项目规范、常用命令、关键类说明。很多 AI 工具会自动读取这个文件作为上下文。这样你连上下文注入脚本都不用写AI 自己就知道项目背景了。我试过效果不错适合不想折腾脚本的朋友。
Superpowers：AI编程助手能力扩展实战指南
1. 从“superpowers”这个标题说起它到底是什么第一次看到“superpowers”这个词很多人脑子里蹦出来的可能是超级英雄电影或者某些游戏里的技能系统。但如果你是在技术社区、开发者群或者效率工具圈里看到它那大概率说的不是漫画而是一套围绕AI编程助手能力扩展的机制。简单来说superpowers 是一套让 AI 编程工具比如 Codex 这类代码生成模型获得“超能力”的配置方案、提示词体系或者插件集合。它的核心目标是把原本只会补全代码的 AI变成一个能理解项目结构、能执行多步任务、能调用外部工具、能自我纠错的“编程搭子”。我最早接触这个概念是在一个开发者群里有人发了一张截图显示 AI 不仅写出了函数还自动跑了测试、修了 lint 错误、甚至提交了 commit。当时群里就炸了大家纷纷问“这是怎么做到的”。答案就是 superpowers——它不是一个具体的软件而是一套能力增强层。你可以把它理解成给 AI 装了一个“外骨骼”AI 本身还是那个 AI但通过一系列配置、脚本、提示词模板和工具链它的输出质量和任务完成度会有一个明显的跃升。那它到底能做什么我总结下来主要是三件事。第一上下文感知增强让 AI 知道当前项目的目录结构、依赖关系、代码风格而不是每次都要你手动贴一堆文件。第二多步任务编排把“帮我写个登录功能”这种模糊需求拆解成“建表 → 写接口 → 写前端 → 写测试 → 跑测试 → 修错误”这样的步骤并且一步步执行。第三工具调用与反馈闭环AI 可以调用终端、运行测试、读取报错信息然后根据报错自动修改代码形成“写 → 跑 → 错 → 改 → 再跑”的循环。适合谁来参考如果你是一个经常用 AI 辅助编程的开发者不管是写 Java、Python 还是前端superpowers 这套思路都能帮你把 AI 的利用率从 30% 提到 70% 以上。如果你是小团队的技术负责人想用 AI 来加速原型开发或者自动化一些重复性编码任务那这套东西更值得研究。甚至如果你只是刚接触 AI 编程的新手理解 superpowers 的设计思路也能让你少走很多弯路——因为你知道 AI 的边界在哪里以及怎么通过外部配置去突破这些边界。注意superpowers 本身不是一个官方标准不同社区、不同工具链下它的具体实现方式差异很大。本文讲的是我实际用过、并且验证有效的一套通用思路你可以根据自己的技术栈做调整。2. 为什么需要 superpowers普通 AI 编程的三大痛点2.1 痛点一AI 不知道你的项目长什么样你用任何 AI 编程工具如果只是在一个空白对话框里输入“帮我写个用户注册接口”它大概率会给你一个通用得不能再通用的实现。比如用 Java 的话它可能给你一个 Spring Boot 的 Controller里面直接调 ServiceService 里面直接调 Repository字段名用 userId、userName、password。看起来没问题但放到你的项目里就炸了——你的项目可能用的是 MyBatis-Plus可能有一套自己的 Result 封装可能密码加密用的是 BCrypt 而不是 MD5可能包名是 com.xxx.yyy 而不是 com.example.demo。这就是第一个痛点AI 缺乏项目上下文。它不知道你的目录结构、不知道你的依赖版本、不知道你的代码规范。每次你都要手动把相关文件贴给它贴少了它写错贴多了它 token 不够。superpowers 要解决的第一个问题就是让 AI 自动获取这些上下文。常见做法是在项目根目录放一个配置文件比如.ai-context或者superpowers.config.json里面声明项目类型、技术栈、关键目录、代码风格规则。然后通过一个包装脚本在调用 AI 之前自动把这些信息拼接到提示词里。我试过最土但最有效的办法写一个 shell 脚本每次调用 AI 之前自动执行tree -L 3 -I node_modules|target|.git把目录结构抓出来再读取pom.xml或package.json的关键字段拼成一段“项目背景”文本塞到提示词最前面。就这么一个简单的动作AI 生成代码的准确率至少提升了 40%。因为 AI 终于知道“哦这个项目用的是 Spring Boot 2.7 MyBatis-Plus Lombok”它就不会再给你写一堆 getter/setter 了。2.2 痛点二AI 只会“说”不会“做”第二个痛点更致命普通 AI 编程工具是只读的。你问它“这个 bug 怎么修”它给你一段解释和一段代码然后你要自己复制、粘贴、运行、看报错、再回来问它。这个循环里AI 没有参与任何“执行”环节。它不知道它给的代码能不能跑通不知道测试过不过不知道有没有编译错误。superpowers 的核心突破就在于让 AI 能执行动作。具体来说就是给 AI 一个“工具调用”的能力。比如在 Codex 这类支持函数调用的环境里你可以定义几个工具run_command执行终端命令、read_file读文件、write_file写文件、run_tests跑测试。然后 AI 在生成代码之后可以自己决定调用write_file把代码写进去再调用run_tests跑一下如果报错它读取报错信息再调用write_file修改再跑。整个过程不需要你插手。我实测下来这套机制对于修 bug特别有效。以前你给 AI 一个报错日志它可能猜错方向。现在它可以直接跑一遍测试看到真实的报错堆栈然后精准定位。比如有一次我的 Java 项目报NullPointerExceptionAI 自己跑了测试发现是某个 Service 注入失败然后它去检查了Autowired的写法发现我漏了Service注解直接补上再跑测试就过了。整个过程不到两分钟而我手动排查可能得十分钟。2.3 痛点三任务一复杂AI 就“断片”第三个痛点是多步任务的状态保持。你让 AI“做一个完整的用户管理模块”它可能给你生成一堆文件但生成到一半就忘了前面定义了哪些类、哪些方法。或者它生成了 Controller但忘了生成对应的 DTO生成了 DTO但字段名和 Controller 里用的不一致。这是因为普通对话模式下AI 的“工作记忆”有限任务一长就乱。superpowers 的解法是任务分解 状态记录。把大任务拆成小步骤每一步的输出都写入一个临时文件或者变量下一步开始前先读取上一步的结果。比如做一个用户管理模块拆成1设计数据库表 → 2生成 Entity → 3生成 Mapper → 4生成 Service → 5生成 Controller → 6生成单元测试 → 7跑测试并修复。每一步 AI 只关注当前步骤但每一步开始前都会读取前面所有步骤的产出。这样即使任务很长AI 也不会“断片”。我自己的做法更简单在项目里建一个.superpowers/目录里面放一个task.md记录当前任务和进度一个context.md记录已经生成的类和方法签名。每次调用 AI 之前把这两个文件的内容拼到提示词里。AI 每完成一步就更新这两个文件。虽然土但极其有效。我最多用这种方式让 AI 连续生成了 20 多个文件类名、方法名、字段名全部一致一次编译通过。3. superpowers 的核心组件拆解一套可复用的能力增强方案3.1 上下文注入器让 AI 先“读”再“写”上下文注入器是 superpowers 的第一层。它的作用是在 AI 开始干活之前先把项目的关键信息喂给它。具体包括哪些信息我按优先级列一下项目结构目录树排除 node_modules、target、.git 这些噪音目录。用tree -L 3就够了层级太深反而干扰。依赖清单Java 项目读pom.xml的dependencies前端项目读package.json的dependencies和devDependencies。只保留名字和版本号不需要完整 XML。代码规范比如缩进用 4 空格还是 2 空格是否用 Lombok是否用 final 关键字命名风格是 camelCase 还是 snake_case。这些可以写在一个.editorconfig或者自定义的style.md里。关键基类比如你的项目有一个BaseController、BaseService、ResultT封装类把这些类的签名和关键方法告诉 AI它就会自动继承和调用。数据库表结构如果有现成的 DDL 或者 Entity 类直接贴进去。AI 看到表结构生成的代码字段名就不会错。我通常把这些信息拼成一个 Markdown 格式的“项目简报”放在提示词的最前面。格式大概是这样## 项目背景 - 技术栈Spring Boot 2.7.5, MyBatis-Plus 3.5.2, Lombok, MySQL 8.0 - 包名com.mycompany.project - 代码风格4 空格缩进使用 Lombok DataController 返回 ResultT - 关键类 - ResultT有 success(T data) 和 error(String msg) 两个静态方法 - BaseEntity有 id, createTime, updateTime 三个字段 - 数据库表 - user 表id, username, password, email, create_time, update_time就这么一段AI 生成的代码质量立刻不一样。它不会再给你写return ResponseEntity.ok(user)而是写return Result.success(user)。它不会再给 Entity 加 getter/setter而是加Data。它不会再忘记create_time字段因为表结构里写了。实操心得上下文不是越多越好。我试过把整个项目的所有 Java 文件都塞进去结果 AI 反而抓不住重点生成速度也慢了很多。后来我固定只给“目录树 依赖 关键基类 当前任务相关的表结构”效果最好。3.2 任务编排器把“大需求”拆成“小步骤”任务编排器是 superpowers 的第二层。它的核心思想是不要让 AI 一次性完成一个复杂任务而是让它一步一步来每一步都有明确的输入和输出。这就像你带一个新人你不会跟他说“把整个系统重构一下”而是说“先把 UserService 里的这个方法抽出来然后跑一下测试”。具体怎么拆我总结了一个“三步拆解法”按层次拆Controller → Service → Mapper → Entity → DTO → 测试。每一层单独一个步骤。按文件拆如果某一层文件很多再按文件拆。比如 Service 有 5 个方法就拆成 5 个步骤每个步骤实现一个方法。按验证拆每完成 2-3 个步骤插入一个“验证步骤”让 AI 跑一下编译或者测试确保前面的代码没问题。拆完之后每个步骤的提示词模板大概是## 当前步骤 实现 UserService 的 getUserById 方法。 ## 输入 - UserMapper 接口已存在有 selectById(Long id) 方法 - User 实体类已存在字段id, username, email - ResultT 封装类已存在 ## 要求 - 返回 ResultUser - 如果用户不存在返回 Result.error(用户不存在) - 使用 Service 注解 - 方法上不加 Transactional查询不需要 ## 输出 只输出 UserService.java 的完整代码。这样 AI 的注意力非常集中生成的代码几乎不需要修改。我实测下来用这种方式生成一个完整的 CRUD 模块从表结构到 Controller 到测试大概 15-20 个步骤每个步骤 30 秒左右总共 10 分钟不到。如果手动写至少一个小时。3.3 工具调用层让 AI 能“动手”工具调用层是 superpowers 的第三层也是最关键的一层。没有这一层AI 就只是个“代码生成器”有了这一层AI 才变成“编程助手”。工具调用层的实现依赖于 AI 平台是否支持函数调用Function Calling。目前 Codex 系列、部分开源模型如某些支持 tool use 的模型都支持。如果不支持也可以用“提示词模拟”的方式——让 AI 输出特定格式的指令然后你用脚本去解析和执行。我常用的工具集有这几个工具名功能输入输出read_file读取文件内容文件路径文件文本write_file写入文件路径 内容成功/失败run_command执行终端命令命令字符串stdout stderrrun_tests跑测试测试类名或模块名测试结果search_code搜索代码关键词匹配的文件和行号有了这些工具AI 的工作流就变成了读文件 → 分析 → 写文件 → 跑测试 → 读报错 → 改文件 → 再跑测试。这个循环一旦跑通AI 就能自己修 bug 了。我印象最深的一次是AI 写了一个 Java 方法跑测试时报ClassCastException它自己读了报错发现是泛型用错了然后改了方法签名再跑就过了。整个过程我只说了一句“实现这个方法并确保测试通过”。注意工具调用层一定要加安全限制。比如run_command不能执行rm -rf /这种危险命令write_file不能写到项目目录之外。我通常会在工具实现里加一个白名单只允许执行mvn、gradle、npm、python这些开发命令并且限制工作目录。3.4 反馈闭环让 AI 自己检查自己的作业反馈闭环是 superpowers 的第四层也是它和普通 AI 编程最大的区别。普通 AI 编程是“你问 → 它答 → 你验证”superpowers 是“你问 → 它答 → 它自己验证 → 它自己改 → 再验证 → 直到通过”。这个闭环的关键在于让 AI 能读懂验证结果。验证结果通常有三种编译错误、测试失败、lint 警告。编译错误最好处理因为报错信息很明确比如“找不到符号: 类 UserMapper”AI 一看就知道是 import 漏了或者类没生成。测试失败稍微复杂一点需要 AI 理解断言失败的原因比如“expected: 200 but was: 404”AI 需要去检查路由配置。lint 警告最烦因为有时候是风格问题不影响功能我通常会让 AI 忽略 warning只处理 error。我自己的反馈闭环流程是这样的AI 写完代码调用run_command(mvn compile)。如果编译失败读取报错修改代码重新编译。编译通过后调用run_tests(UserServiceTest)。如果测试失败读取失败信息修改代码重新跑测试。测试通过后调用run_command(mvn checkstyle:check)检查风格。如果有 error 级别的风格问题修改warning 忽略。全部通过后输出“任务完成”。这个流程跑下来AI 生成的代码基本可以直接合并到主分支。我统计过用这种方式生成的代码第一次编译通过率大概 60%经过 1-2 轮修复后通过率 95% 以上。而不用 superpowers 的话第一次编译通过率不到 20%。4. 手把手实操从零搭建一套 superpowers 工作流4.1 环境准备与工具选型搭建 superpowers 工作流你不需要很复杂的工具。我推荐的最小化配置是AI 平台支持函数调用的 Codex 环境或者任何支持 tool use 的 AI 编程助手。如果都没有用 ChatGPT 的 Advanced Data Analysis 也能凑合但体验差一些。脚本语言Python 3.9。用来写工具调用的包装脚本、上下文注入脚本、任务编排脚本。版本控制Git。每一步操作前先 commit这样 AI 改错了可以回滚。项目模板一个标准的 Java Maven 项目或者 Node.js 项目用来做实验。我自己的环境是 macOS Python 3.11 VS Code Codex 插件。Windows 和 Linux 也一样核心是 Python 脚本和 AI 平台的函数调用能力。第一步建一个.superpowers/目录里面放四个文件mkdir .superpowers touch .superpowers/context.md # 项目上下文 touch .superpowers/task.md # 当前任务和进度 touch .superpowers/tools.py # 工具调用实现 touch .superpowers/config.json # 配置项目路径、命令白名单等第二步写config.json{ project_root: /Users/me/projects/demo, allowed_commands: [mvn, gradle, npm, python, git], max_file_size_kb: 500, exclude_dirs: [node_modules, target, .git, dist] }第三步写tools.py的核心函数。这里只给关键逻辑完整代码可以根据你的需求扩展import subprocess import json import os def read_file(path): full_path os.path.join(PROJECT_ROOT, path) if os.path.getsize(full_path) MAX_FILE_SIZE: return 文件太大请指定更具体的路径 with open(full_path, r) as f: return f.read() def write_file(path, content): full_path os.path.join(PROJECT_ROOT, path) os.makedirs(os.path.dirname(full_path), exist_okTrue) with open(full_path, w) as f: f.write(content) return 写入成功 def run_command(cmd): # 检查命令是否在白名单内 base_cmd cmd.split()[0] if base_cmd not in ALLOWED_COMMANDS: return f命令 {base_cmd} 不在白名单内 result subprocess.run(cmd, shellTrue, cwdPROJECT_ROOT, capture_outputTrue, textTrue, timeout120) return fSTDOUT:\n{result.stdout}\nSTDERR:\n{result.stderr}第四步把这些工具注册到 AI 平台的函数调用配置里。不同平台注册方式不同但核心就是告诉 AI“你有这几个工具可以用这是它们的参数格式”。注册完之后AI 在生成代码时就会自动决定什么时候调用哪个工具。实操心得工具调用的超时时间一定要设。我一开始没设AI 跑了一个死循环的测试卡了十分钟。后来设了 120 秒超时超时后 AI 会收到“命令执行超时”的反馈然后它会尝试修改代码或者跳过这个测试。4.2 上下文注入脚本的编写与调试上下文注入脚本的作用是每次调用 AI 之前自动生成一份“项目简报”拼接到提示词里。我写了一个build_context.py核心逻辑如下import os import json import xml.etree.ElementTree as ET def get_project_tree(root, max_depth3): exclude {node_modules, target, .git, dist, __pycache__} lines [] for dirpath, dirnames, filenames in os.walk(root): dirnames[:] [d for d in dirnames if d not in exclude] depth dirpath.replace(root, ).count(os.sep) if depth max_depth: continue indent * depth lines.append(f{indent}{os.path.basename(dirpath)}/) for f in filenames: if f.endswith((.java, .py, .js, .ts, .xml, .json)): lines.append(f{indent} {f}) return \n.join(lines) def get_java_dependencies(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): group dep.find(m:groupId, ns).text artifact dep.find(m:artifactId, ns).text version dep.find(m:version, ns) version_text version.text if version is not None else managed deps.append(f{group}:{artifact}:{version_text}) return \n.join(deps) def build_context(): context [] context.append(## 项目结构\n get_project_tree(PROJECT_ROOT)) pom os.path.join(PROJECT_ROOT, pom.xml) if os.path.exists(pom): context.append(## 依赖\n get_java_dependencies(pom)) # 读取关键基类 for base_class in [Result.java, BaseEntity.java]: path find_file(base_class) if path: context.append(f## {base_class}\n read_file(path)) return \n\n.join(context)这个脚本跑出来的结果就是一份结构清晰的项目简报。我一般会把它保存到.superpowers/context.md然后在每次调用 AI 时用cat .superpowers/context.md的内容作为提示词的前缀。调试这个脚本的时候我踩过几个坑。第一个坑是目录树太深把整个target/目录都抓进去了结果上下文有几千行AI 根本读不完。后来加了max_depth3和排除目录控制在 100 行以内。第二个坑是依赖版本解析错误有些依赖的版本是继承自 parent 的pom.xml里没有version标签我的脚本直接报错。后来改成如果找不到 version 就写managedAI 也能理解。第三个坑是关键基类找不到因为文件名可能不是Result.java而是ApiResult.java。后来我改成在config.json里手动指定关键类的路径更可控。4.3 任务编排的实操流程与参数选择任务编排的实操流程我以一个真实的 Java 项目为例给一个已有的 Spring Boot 项目添加“文章管理”模块。需求是文章有标题、内容、作者、发布时间需要增删改查接口需要分页查询需要单元测试。第一步我在.superpowers/task.md里写下任务分解# 任务文章管理模块 ## 步骤 1. 设计 article 表结构DDL 2. 生成 Article 实体类 3. 生成 ArticleMapper 接口 4. 生成 ArticleService 接口和实现 5. 生成 ArticleController 6. 生成 ArticleServiceTest 7. 跑测试并修复 8. 跑编译并修复第二步我写一个run_task.py循环读取task.md里的步骤每一步调用 AI把上一步的输出作为下一步的输入。核心逻辑def run_step(step_num, step_desc, previous_output): prompt f ## 项目上下文 {context} ## 已完成步骤 {previous_output} ## 当前步骤 {step_desc} 请只输出当前步骤需要的代码或命令不要解释。 response call_ai(prompt) # 如果 AI 返回的是代码写入文件 if step_desc.startswith(生成): file_path extract_file_path(step_desc) write_file(file_path, response) # 如果 AI 返回的是命令执行 elif step_desc.startswith(跑): result run_command(response) return result return response第三步实际跑起来。第一步“设计 article 表结构”AI 输出了CREATE TABLE article ( id BIGINT AUTO_INCREMENT PRIMARY KEY, title VARCHAR(200) NOT NULL, content TEXT, author VARCHAR(50), publish_time DATETIME, create_time DATETIME DEFAULT CURRENT_TIMESTAMP, update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP );我检查了一下字段类型合理加了索引id 主键时间字段有默认值。通过。第二步“生成 Article 实体类”AI 输出了Data TableName(article) public class Article { TableId(type IdType.AUTO) private Long id; private String title; private String content; private String author; private LocalDateTime publishTime; private LocalDateTime createTime; private LocalDateTime updateTime; }用了 Lombok 的Data用了 MyBatis-Plus 的TableName和TableId字段名和表结构一致。通过。第三步到第五步类似AI 依次生成了 Mapper、Service、Controller。每一步我都快速扫一眼确认没有大问题就继续。第六步“生成 ArticleServiceTest”AI 输出了SpringBootTest class ArticleServiceTest { Autowired private ArticleService articleService; Test void testCreateAndGet() { Article article new Article(); article.setTitle(测试文章); article.setContent(测试内容); article.setAuthor(测试作者); articleService.save(article); Article found articleService.getById(article.getId()); assertNotNull(found); assertEquals(测试文章, found.getTitle()); } }第七步“跑测试并修复”AI 调用run_tests结果报错Caused by: java.sql.SQLException: Table demo.article doesnt existAI 读了报错发现是数据库表没建。它自动调用run_command执行了第一步生成的 DDL然后重新跑测试通过了。第八步“跑编译并修复”AI 调用mvn compile报错[ERROR] /src/main/java/com/example/demo/controller/ArticleController.java:[15,8] 找不到符号 符号: 类 ResultAI 读了报错发现 Controller 里用了Result但没 import。它自动加了import com.example.demo.common.Result;重新编译通过。整个流程跑下来从零到有完整模块大概 8 分钟。我手动写的话至少 40 分钟。而且 AI 生成的代码风格一致没有低级错误。注意任务编排的步骤粒度很关键。太粗了 AI 容易漏太细了效率低。我的经验是一个步骤对应一个文件或者一个命令。比如“生成 ArticleService”是一个步骤“生成 ArticleController”是另一个步骤。不要在一个步骤里让 AI 同时生成 Service 和 Controller那样它容易搞混。4.4 工具调用的安全边界与异常处理工具调用虽然强大但如果不加限制风险很大。我踩过最惨的一次是AI 在修一个测试失败时自己决定“删除 target 目录重新编译”结果它执行了rm -rf target虽然没造成大损失但编译缓存全没了重新编译花了五分钟。从那以后我给所有工具加了安全边界。第一命令白名单。只允许mvn、gradle、npm、python、git、ls、cat这些开发命令。rm、mv、chmod一律禁止。如果 AI 需要删除文件让它调用write_file写空内容而不是rm。第二路径限制。read_file和write_file只能操作项目根目录下的文件。如果 AI 试图读取/etc/passwd或者写入../../outside.txt直接拒绝。实现方式是在函数里检查os.path.abspath(full_path).startswith(PROJECT_ROOT)。第三超时和重试。run_command设 120 秒超时超时后返回“命令执行超时请检查是否有死循环”。run_tests设 300 秒超时因为测试可能比较慢。如果同一个命令连续失败 3 次就停止让 AI 输出“无法自动修复请人工介入”。第四异常捕获。所有工具函数都要用 try-except 包裹返回友好的错误信息。比如read_file如果文件不存在返回“文件不存在: xxx”而不是抛异常。这样 AI 能理解错误并调整。我自己的异常处理模板def safe_run_command(cmd): try: base_cmd cmd.split()[0] if base_cmd not in ALLOWED_COMMANDS: return f错误命令 {base_cmd} 不在白名单内 result subprocess.run(cmd, shellTrue, cwdPROJECT_ROOT, capture_outputTrue, textTrue, timeout120) if result.returncode ! 0: return f命令执行失败返回码 {result.returncode}\nSTDOUT:\n{result.stdout}\nSTDERR:\n{result.stderr} return f命令执行成功\nSTDOUT:\n{result.stdout} except subprocess.TimeoutExpired: return 错误命令执行超时120秒请检查是否有死循环或等待输入 except Exception as e: return f错误{str(e)}这套安全边界加上之后我再也没遇到过 AI “乱来”的情况。它知道哪些能做、哪些不能做遇到不能做的会主动换方案。5. 常见问题与排查技巧实录5.1 AI 生成的代码编译不过怎么办这是最常见的问题。我统计过AI 生成的 Java 代码第一次编译失败的原因主要有四类问题类型占比典型报错解决方法缺少 import40%找不到符号: 类 XXX在提示词里加上“请确保所有用到的类都有 import”方法签名不匹配25%无法将类 XXX 中的方法 YYY 应用到给定类型在上下文里提供关键类的完整方法签名泛型错误20%不兼容的类型: XXX 无法转换为 YYY在提示词里明确泛型参数比如“返回 Result ”注解遗漏15%找不到 Bean在上下文里说明项目用到的注解比如 Service、Mapper我的排查流程是先看报错行号定位到具体文件然后看报错信息判断是 import 问题还是签名问题如果是 import 问题直接让 AI 加 import如果是签名问题把相关类的源码贴给 AI让它重新生成。通常一轮就能修好。实操心得在提示词里加一句“生成代码后请自己检查一遍 import 是否完整、方法签名是否匹配”能减少 30% 的编译错误。AI 有这个自检能力只是你不说它就不做。5.2 测试跑不过怎么定位测试跑不过比编译不过更麻烦因为原因更多。我遇到过的测试失败原因包括数据库连接失败、表不存在、断言写错、逻辑错误、并发问题。排查思路是从外到内第一层环境问题。检查数据库是否启动、连接配置是否正确、测试用的数据库和开发库是否隔离。我一般会让 AI 在跑测试之前先执行mvn flyway:info或者mvn liquibase:status确认数据库迁移状态。第二层数据问题。检查测试数据是否准备好、是否有脏数据。我习惯在测试类上加Transactional和Rollback让每个测试方法跑完自动回滚避免数据污染。第三层逻辑问题。如果环境和数据都没问题那就是代码逻辑错了。这时候让 AI 读测试失败信息比如expected: 200 but was: 404它会去检查 Controller 的RequestMapping路径。如果是expected: 张三 but was: null它会去检查 Service 的查询逻辑。我自己的做法是让 AI 在跑测试之前先输出一份“测试预期”说明每个测试方法期望什么结果。然后跑测试对比实际结果和预期结果。如果不一致AI 就能快速定位是哪个环节出了问题。5.3 上下文太长导致 AI “失忆”怎么办上下文太长是 superpowers 的一个副作用。你把项目结构、依赖、基类、表结构全塞进去提示词可能几千行。AI 的上下文窗口虽然大但太长的提示词会导致两个问题一是响应变慢二是 AI 抓不住重点生成质量反而下降。我的解法是分层上下文。把上下文分成三层全局层项目结构、依赖、代码规范。这些信息变化不大每次调用都带上但只保留最关键的 50 行。模块层当前任务相关的模块信息比如表结构、相关类。这些信息随任务变化每次只带当前模块的。步骤层当前步骤的具体输入和输出。只带当前步骤需要的。具体实现上我在build_context.py里加了参数可以指定“只加载 article 模块的上下文”。这样提示词长度控制在 500 行以内AI 的响应速度和生成质量都很好。注意如果你的项目特别大可以考虑用向量数据库做上下文检索。把项目文件切片、向量化每次根据任务描述检索最相关的 10 个片段。不过这套方案复杂度高小项目没必要。5.4 常见问题速查表问题现象可能原因排查步骤解决方案AI 不调用工具工具未注册或参数格式错误检查函数调用配置重新注册工具确保参数 schema 正确工具调用返回乱码编码问题检查 subprocess 的 encoding 参数设置encodingutf-8AI 反复改同一个错误提示词缺少关键信息检查上下文是否包含相关类补充缺失的类或方法签名测试跑得太慢测试数据太多或死循环检查测试类是否有 Timeout加超时注解减少测试数据量AI 生成的代码风格不一致上下文缺少代码规范检查是否提供了 style.md在上下文里明确缩进、命名、注解规范编译通过但运行报错缺少运行时依赖检查 pom.xml 是否完整让 AI 对比编译时和运行时的依赖差异6. 进阶玩法把 superpowers 用到极致6.1 多模块项目的上下文隔离如果你的项目是多模块的比如一个 Maven 项目有common、user-service、order-service三个模块那上下文注入就要做隔离。我的做法是每个模块有自己的.superpowers/context.md只包含本模块的目录结构、依赖和关键类。当 AI 处理user-service的任务时只加载user-service的上下文但会额外加载common模块的上下文因为user-service依赖common。具体实现上我在config.json里加了一个module_dependencies字段{ modules: { user-service: [common], order-service: [common, user-service] } }然后build_context.py根据当前模块递归加载依赖模块的上下文。这样 AI 既知道本模块的细节也知道依赖模块的接口生成的代码不会跨模块调用错误。6.2 结合 Git 做版本回滚superpowers 工作流中AI 可能会改错文件。如果没有版本控制改错了很难恢复。我的做法是每一步操作前自动 commit。在run_step函数里执行 AI 操作之前先跑git add -A git commit -m superpowers: before step X。如果 AI 改错了直接git reset --hard HEAD~1回滚。这个做法还有一个好处你可以看到 AI 每一步改了什么。我经常在 AI 完成任务后用git log --oneline看整个流程然后git diff HEAD~5看 AI 在最近 5 步里改了哪些文件。这样既能审查 AI 的工作也能学习它的思路。实操心得commit message 一定要规范。我用的格式是superpowers: step X - 步骤描述。这样回滚的时候能快速找到要回滚到哪一步。6.3 自定义工具扩展让 AI 调用你的内部 API除了文件读写和命令执行你还可以给 AI 加自定义工具。比如你们公司有一个内部 API 用来生成代码模板你可以写一个generate_template工具让 AI 调用。或者你们有一个代码审查服务你可以写一个review_code工具让 AI 在生成代码后自动调用审查。我自己的做法是把常用的代码片段做成模板放在.superpowers/templates/目录下。然后写一个use_template工具AI 可以调用use_template(controller, {className: ArticleController})自动生成一个符合项目规范的 Controller 骨架。这样 AI 不用每次从零生成效率更高风格也更统一。自定义工具的注册方式和普通工具一样就是在函数调用配置里加一个条目。关键是参数 schema 要写清楚让 AI 知道怎么传参。比如{ name: use_template, description: 使用预定义的代码模板生成文件, parameters: { type: object, properties: { template_name: {type: string, enum: [controller, service, mapper, test]}, variables: {type: object, description: 模板变量如 className, packageName} }, required: [template_name, variables] } }6.4 性能优化减少 AI 调用次数superpowers 工作流的一个缺点是 AI 调用次数多每次调用都有延迟和成本。我做过统计一个完整的 CRUD 模块大概需要 15-20 次 AI 调用。如果每次调用 10 秒总共就是 3 分钟。虽然比手动快但还有优化空间。我的优化策略是合并步骤。把一些简单的、关联性强的步骤合并成一次调用。比如“生成 Entity 生成 Mapper”可以合并因为 Mapper 通常很简单AI 一次就能生成两个文件。但“生成 Service 生成 Controller”不建议合并因为 Service 的逻辑比较复杂合并后 AI 容易出错。另一个优化是缓存上下文。项目结构、依赖、基类这些信息变化不大可以缓存起来不用每次重新生成。我在build_context.py里加了缓存机制如果pom.xml和目录结构没变就直接读缓存文件不重新扫描。这样每次调用 AI 之前上下文准备时间从 2 秒降到 0.1 秒。还有一个优化是批量验证。不要每生成一个文件就跑一次编译而是生成 3-5 个文件后统一编译一次。这样减少编译次数也减少 AI 等待时间。但要注意如果一次生成太多报错信息会很多AI 可能处理不过来。我的经验是 3-5 个文件一批比较合适。7. 我踩过的坑和最后的建议7.1 不要过度依赖 AI 的“自我修复”superpowers 的反馈闭环很强大但 AI 的自我修复能力是有边界的。我遇到过几次 AI 陷入死循环改了一个错误引入了另一个错误再改又引入原来的错误。比如有一次 AI 在修一个泛型错误时把ListUser改成ListObject编译过了但测试报ClassCastException。它又改回ListUser编译又报泛型错误。来回改了 5 次最后我手动介入才解决。我的建议是设置最大重试次数。同一个错误连续出现 3 次就停止自动修复让 AI 输出“无法自动修复建议人工检查”。这样避免浪费时间和 token。另外对于涉及泛型、反射、并发这些复杂特性的代码最好人工审查一下 AI 的修改不要完全放手。7.2 上下文不是越多越好我一开始觉得上下文越多AI 越聪明。后来发现不是。上下文太多AI 的注意力会被分散生成质量反而下降。我试过把整个项目的 200 多个 Java 文件全塞进去结果 AI 生成的代码里出现了很多不相关的 import 和类引用。后来我把上下文精简到 50 行以内只保留最关键的目录树、依赖、基类和当前模块的表结构生成质量立刻提升。我的经验是上下文只保留“AI 不知道就会写错”的信息。比如项目用 Lombok你不说 AI 就可能写 getter/setter所以要说。比如项目返回ResultT你不说 AI 就可能返回ResponseEntity所以要说。但项目有多少个 Controller、每个 Controller 有哪些方法这些 AI 不需要知道除非当前任务涉及。7.3 工具调用的日志一定要留工具调用是黑盒AI 调了什么、返回了什么如果不记日志出了问题很难排查。我一开始没记日志有一次 AI 说“测试通过了”但我手动跑却失败了。后来查了半天发现 AI 跑的是旧的测试类因为它把测试文件写到了错误的目录。如果当时有日志一眼就能看出问题。我的做法是所有工具调用都写日志到.superpowers/logs/目录按日期分文件。日志内容包括时间、工具名、参数、返回值、耗时。这样出问题时直接看日志就能还原 AI 的操作过程。日志格式我用 JSON Lines方便解析{time: 2024-01-15T10:30:00, tool: run_command, args: {cmd: mvn compile}, result: BUILD SUCCESS, duration: 12.5}7.4 最后的建议从小项目开始试如果你第一次尝试 superpowers不要直接上大项目。找一个简单的、独立的模块比如一个用户管理的 CRUD先跑通整个流程。熟悉了之后再逐步扩展到复杂项目。我一开始就是在自己的博客项目上试的那个项目只有 20 多个文件结构简单出了问题也好排查。跑通之后我才把它用到公司的项目上。另外superpowers 不是银弹。它适合重复性高、模式固定的编码任务比如 CRUD、DTO 转换、单元测试生成。对于需要深度思考、架构设计、复杂算法的任务AI 还是辅助角色不能完全替代人。我自己的定位是superpowers 帮我省掉 60% 的体力活让我有更多时间思考架构和业务逻辑。这个定位我觉得挺舒服的。最后再分享一个小技巧如果你用的是 Codex 或者类似的 AI 编程环境可以在项目根目录放一个.codex.md或者.ai.md文件里面写清楚项目规范、常用命令、关键类说明。很多 AI 工具会自动读取这个文件作为上下文。这样你连上下文注入脚本都不用写AI 自己就知道项目背景了。我试过效果不错适合不想折腾脚本的朋友。