1. 为什么 AI 编码助手需要 Superpowers从“随时失忆”到“持续成长”如果你最近关注 AI 编程大概率会在技术社区里反复看到 superpowers 这个词。它不是什么超级英雄电影周边而是一套给 Claude Code、Codex 这类 AI 编码代理加Buff的开源工具集。这篇文章我会从实际使用的角度把 superpowers 的安装、配置、核心机制、Java 项目实战和踩坑记录一次性讲清楚适合正在折腾 AI 代理、觉得“AI 写代码总差一口气”的开发者。1.1 默认状态下的 AI 代理到底缺什么我最早开始重度使用 Claude Code 时感受是分裂的它写单文件函数、补测试、解释报错都非常利落可一旦任务跨度超过一个会话就立刻暴露短板。最典型的场景是我在下午让它搭了一个 Spring Boot 模块晚上继续对话时它已经不太记得上午定的包结构、命名约定甚至会把刚跑通的接口路径又改回旧版本。更头疼的是每换一个新项目它都要从零开始摸索一遍技术栈完全没有跨项目的经验积累。这不是模型能力的问题而是工作方式的结构性缺陷。默认状态下AI 编码代理是一个“有知识但没方法”的协作者它读过大量代码但不会像人一样在项目里留下笔记、维护一份任务清单、把长期约束沉淀成团队规范。它在每个会话里都像第一天入职、并且没有老员工带教的实习生。1.2 Superpowers 解决的核心痛点superpowers 这个项目最初来自开源社区对 Claude Code 的深度定制后来被整合成一套独立的技能体系。它的核心思路非常朴素把你希望 AI 表现出的“超能力”——规划能力、记忆能力、多步骤任务拆解能力、测试驱动开发纪律——以 Markdown 技能包的形式显式注入到代理的工作流里。这套体系解决了三个我长期抱怨的问题失忆问题通过项目级和全局级的记忆目录让代理在多次会话之间保留关键决定、架构约束和踩坑记录。无方法问题把“先写测试再写实现”“先拆任务再写代码”“完成后做 review”这类优秀工程师的习惯固化成可触发、可执行的技能文件。单点能力问题默认代理在同一时刻只有一个思维链而通过子代理机制你可以把代码审查、方案设计、测试编写拆给不同“角色”并行或串行处理各司其职。说白了superpowers 是把“好工程师的工作方法”翻译成 AI 代理能理解和执行的文档再通过一套轻量的运行框架让它在合适的时机自动调用。这也是为什么它和 Codex 这类同样定位的代理工具会产生大量结合场景——它们缺的不是模型是流程。2. 安装和初始配置把 superpowers 接进你的终端2.1 前置依赖与最小环境要求在开始安装前先把环境清单理清楚。根据我自己的部署经历最省心的组合是依赖项最低要求推荐配置说明Node.js18.x20.x 及以上运行安装器与本地服务npm9.x10.x 及以上包管理与技能更新AI 代理 CLIClaude Code 或 Codex CLI保持最新版真正干活的大脑Git任意现代版本2.30拉取技能仓库操作系统Linux / macOS同左Windows 建议 WSL2路径与权限差异较多我见过很多人卡在第一步本地 Node 版本太老导致安装器运行时报语法错误。如果你的环境是公司统一发的开发机不要急着升级全局 Node我用nvm装一个单独的 LTS 版本就够用避免影响同机上的旧项目。注意superpowers 本身并不包含大模型它只是给 Claude Code 或 Codex 提供更好的“操作流程”。如果你没有可用的模型 API装完之后是跑不起来的。2.2 安装与初始化全过程安装过程其实比很多人想象的轻量。第一步是用 npm 全局安装 CLI 工具npm install -g superpowers装完以后切到你的项目根目录执行初始化superpowers init这个命令会做几件事在当前目录生成.superpowers/配置文件夹、询问你要启用哪些技能包、把默认的记忆文件模板写好。如果你第一次执行时拿不准我建议直接用默认推荐项等跑通第一个任务后再按需增删。如果你只打算给某个单独项目用也可以直接把初始化路径指到项目目录superpowers init --project ./my-java-service这样生成的内容会局限在该项目内不会污染全局配置。2.3 验证安装是否生效安装完最怕的是“感觉装了但代理根本没反应”。我习惯用两种方式快速验证第一种直接看目录结构。正常初始化后应该能同时看到~/.superpowers/全局配置和全局技能.superpowers/项目级配置和项目技能至少一个skills/目录里面是以 Markdown 文件形式存在的技能定义第二种触发一个技能跑一遍。大多数技能都会在文件头部有description和when_to_use之类的元信息。你可以在对话里直接对 Claude Code 说“按照 TDD 技能给这个类写测试”。如果代理开始引用技能文件内容而不是凭感觉写就说明生效了。2.4 升级与版本管理superpowers 迭代速度很快社区每周都会新增或修正技能。升级命令很简单superpowers update但要注意升级后部分技能文件可能会发生前后不兼容的变化。我的做法是在项目根目录把.superpowers/纳入版本控制每次升级前提交一次碰到问题对比 diff 就很直观。特别是团队协作场景这个习惯能帮你精准定位是“谁改了技能导致代理行为突变”。3. 核心机制拆解skills、子代理与记忆如何协同3.1 skill 文件到底长什么样很多人把 superpowers 想得很玄实际上它最核心的部分就是一个又一个 Markdown 文件。每个技能文件通常包含两部分YAML 格式的元信息块以及正文指令。我拿自己写的 Java 测试技能举个例子文件结构大致是这样的--- name: java-test-generator description: 当用户要求为 Java 类生成单元测试时使用 triggers: - 生成测试 - 写单测 --- # 执行步骤 1. 先阅读目标类提取所有 public 方法。 2. 根据方法行为划分测试用例正常路径、边界值、异常路径。 3. 使用 JUnit 5 和 AssertJ 编写断言。 4. 在写测试前先确认是否存在既有测试约定不要重复造轮子。 5. 测试使用 Spring Boot 上下文时需要标记 SpringBootTest纯单元测试一律不加载 context。关键在于description和triggers这两段。代理在每次任务开始时都会快速扫描可用技能通过语义匹配决定是否调用。所以技能描述必须写清楚“什么时候用、不用会怎样”而不是堆砌“高质量”“全面”这种空话。我在多语言项目里的体会是技能文件写得好不好直接决定代理的行为稳定性。同样一句“给这段代码补测试”没有技能时它可能随机选一种风格有了技能约束它每次都会按照你 K 过一遍的流程走。3.2 子代理把任务拆给“专门团队”子代理是 superpowers 里最有价值、也最容易被忽视的设计。它的思路是把复杂任务横向拆开每个子代理只负责一个明确职责。比如做一个中等规模的 Java API 功能我会拆成三层架构师代理负责读需求、定接口路径、规划模块划分输出设计方案。实现代理根据方案写代码不纠结方案合理性。审查代理最后拉一遍 diff检查命名、异常处理、数据库事务边界。这样做的直接好处是代理在单一职责下不容易“精神分裂”。如果让一个代理同时做方案设计、编码、审查它在面对取舍时往往会自我肯定而这种肯定经常是错的。拆开之后审查代理可以独立批评实现代理的代码效果立竿见影。配置子代理也很简单通常是在技能或配置文件中声明子代理的角色、背景、任务边界。我个人建议一开始不要超过三个子代理否则上下文窗口和运行时间都会迅速膨胀。3.3 记忆与学习循环superpowers 的记忆机制解决了前面提到的“失忆”痛点。但我必须强调它记忆的不是对话内容而是“结论”。每次任务收尾时代理会把关键决策写入记忆文件。常见的记录对象包括项目采用的技术栈版本和原因业务上不可违背的约束条件已经排查过的报错和结论用户对代码风格的偏好记忆文件同样是 Markdown支持按主题拆多个文件。例如 Java 项目会有java-conventions.md、database-decisions.md、known-issues.md。使用一段时间后你会明显感觉到代理“变得更懂你的项目了”。最典型的表现是它不再问已经回答过的基础问题也不再反复提出被否过的方案。这种体验很像带了一个真正常驻的资深同事。3.4 和 Codex 等其他代理的配合很多人在搜索 superpowers 时会把 Codex 相关词组放在一起因为两者定位有天然互补性。我的实践经验是如果你主力用的是 Codex同样可以使用 superpowers 的技能仓库作为“方法库”通过自定义指令或技能目录的方式加载。区别在于集成深度Claude Code 对 skills 机制有原生支持加载后可以直接触发并读取技能文件Codex 目前更依赖用户把技能内容通过 prompt 或配置文件传进去联动性稍弱但核心思路一样——先定义好流程再让模型执行。所以我的建议是不要纠结“必须用哪个”而是先把技能的通用部分沉淀好。同一个 Markdown 技能文件稍微调整加载方式Claude Code、Codex、甚至其他编码代理都能用。这也是这套体系最有魅力的地方——它绑定的不是某个模型 API而是你自己的工作方法论。4. 在 Java 项目里用 superpowers 的真实体验从抽象需求到可运行代码4.1 为什么 Java 反而更需要这类框架Java 生态有一个特点项目结构复杂、约定多、技术栈重。Spring Boot 项目动辄几十个类Maven 或 Gradle 构建链路长再加上数据库迁移、缓存、消息队列代理很容易陷入“只见树木不见森林”。如果不加约束让 AI 代理自由发挥最常见的后果就是它能写出一堆语法正确但风格混乱的代码——Controller 里塞业务逻辑、事务注解乱放、异常吞掉不记录、测试只覆盖快乐路径。superpowers 的作用就是把这些约束变成显式规则。你可以在项目技能里直接写明分层约束Controller 只做参数校验和响应封装Service 层承载业务Repository 层禁止出现业务逻辑。事务边界事务注解加在 Service 层公开方法上禁止在私有方法内使用自调用事务。依赖注入统一使用构造器注入禁止字段注入。异常处理业务异常必须带错误码和上下文参数禁止打印堆栈后返回空数据。Java 项目的开发更像“在轨道上行驶”而不是“在旷野上探索”。superpowers 恰好就是给 AI 代理铺轨道的工具这也是我坚定把它用在 Java 主项目上的原因。4.2 单个需求从提出到落地的完整过程说得再具体一点我用上周做一个用户积分查询接口的过程来演示。我在 Claude Code 里给出需求“新增一个按用户 ID 查询积分明细的接口支持分页要求记录操作日志不允许直接查全表。”如果没装 superpowers代理大概率会直接开写Controller、Service、Mapper 一气呵成然后告诉我“完成了”。但装了之后事件流是这样的第一步代理读取了backend-java-development技能先输出执行计划包括新建 DTO、定义 Repository 查询方法、设计 Service 层接口、创建 Controller、写集成测试。第二步代理打开java-conventions.md记忆文件确认当前项目统一用PageImpl作为分页返回类型、日志用Slf4j、错误码前缀是POINT_。第三步代理先写测试再写实现。测试覆盖了正常分页、用户不存在返回空页、积分明细为空时的行为等场景。第四步实现完成后审查代理介入发现一个潜在问题分页查询如果直接传Pageable给 Repository遇到排序字段不在实体中时会抛异常。它自动加了一个白名单校验。整个流程下来我没有手写一行代码但每一步都在我的技术决策框架内。这个体验和默认状态天差地别。4.3 构建脚本与测试策略的注入Java 项目里另一个大坑是构建和测试。代理写代码是一把好手但让它理解“当前项目的测试是怎么跑起来的”就很难。我通常会在 superpowers 技能里明确注入构建相关约定# 项目测试只跑指定模块避免全量构建 cd ecosystem-service mvn test -pl . -am -DtestUserPointsQueryTest # 打包时跳过单元测试但运行前必须执行编译检查 mvn package -DskipTests -Dmaven.compiler.failOnErrortrue把这些命令写进技能文件后代理在调用 Maven 或 Gradle 时就不会“随便拿一个命令凑合”——它会先去技能里查标准命令按项目约定执行。这看似细节实际能省掉大量无效构建时间。我还推荐在技能里定义“测试失败时的处理路径”是直接修复测试代码还是标记为已知问题并继续实现还是需要停下来问用户。没有这个约定代理很容易陷入“疯狂重试同一个失败测试”的循环。4.4 实际效果和常见偏差连续用了一周之后我的真实体感是superpowers 能把 AI 编码代理的“下限”拉高不少。裸用 Claude Code 时它经常写出 70 分的代码有了技能和记忆的约束稳定在 85 分以上而且风格统一。但也别指望它全对。我遇到过的偏差包括技能写得太死导致代理不敢变通比如把所有异常都要求抛业务异常结果遇到第三方 SDK 的网络异常也强行包装掩盖了重试语义。记忆文件更新不及时项目推进中改了数据库表结构但记忆文件没记录代理在后续任务中继续引用旧结构设计代码。多个技能触发条件重叠测试生成技能和代码审查技能同时响应代理在一个步骤里做了两件事输出逻辑混乱。所以我的原则是技能要“约束关键路径保留弹性空间”不要把每一步都规定死。真正优秀的技能文件读起来更像一份 playbook而不是一段算法。5. 踩坑记录我不太建议盲目开启的东西和替代做法5.1 一次性开太多技能反而拖慢任务刚开始用 superpowers 时我也犯了“什么都要装”的毛病TDD、架构设计、代码审查、数据库优化、安全扫描……所有技能一股脑全启用。结果代理每次任务都要先读取和匹配十几个技能文件光是在“思考该用哪个技能”上就花费了大量 token 和时间。更麻烦的是技能多了之后互相之间的指导会产生冲突。比如 TDD 技能要求“先写测试再写实现”架构设计技能又要求“先完成全局设计再动手”表面看没矛盾但在代理的上下文窗口里它会反复在两个技能之间切换导致任务推进非常拖沓。我的调整方案是“按角色启用”日常开发只开语言约定、测试生成、代码审查三件套涉及大功能设计时临时启用架构规划技能上线前再手动开启安全注意项。用完之后再关掉避免长驻占用。5.2 权限放太开代理什么文件都敢改superpowers 给代理赋予了读取和操作项目文件的能力但默认权限范围通常比你想的要大。有一次它为了“优化代码结构”把项目的pom.xml格式重新排了一遍还顺手改了两个微服务的端口配置直接导致本地启动失败。从那以后我定了几条硬规矩代理的写权限只锁定在src/main/java、src/test/java、配置文件的允许清单里。关键文件如.gitlab-ci.yml、Dockerfile、application.yml在技能里明确标记为“只读除非用户明确要求修改”。涉及 Maven 依赖版本升级这类操作先出 diff 方案人工确认后再执行。给 AI 代理授权这件事和给团队成员授权是一样的最小权限原则永远适用。宁可多问几次也不要让它自由发挥。5.3 团队协作时技能文件冲突怎么办如果你们团队多人共用同一个项目技能的维护就成了新的协作问题。我遇到过的情况是两个人各自在本地调整了java-conventions.md内容一个是“所有 Controller 返回统一包装类”另一个是“Controller 直接返回业务对象”push 到仓库后直接冲突。这个问题没有银弹但有非常实用的处理流程技能文件全部走 Git 评审任何修改都过 MR不允许本地静默修改。确定全局技能和项目技能的边界全局技能放“团队通用规范”项目技能放“本业务特有约束”。每隔一两个迭代花十分钟 review 一遍技能文件删除过时内容把新踩的坑沉淀进去。这套流程跑顺之后技能文件会成为团队活的知识库而不是个人玩具。5.4 网络环境与依赖源的坑最后说一个技术问题。在部分内网开发环境里执行superpowers update时容易遇到资源和插件拉取超时或校验失败。这个问题我在本地遇过一次提示某个依赖源证书过期前后折腾了半小时。基本排查思路是先确认当前 npm registry 配置npm config get registry切换成团队内部镜像源。确认 git 协议部分内网只允许 HTTPS 拉取把技能仓库地址改成显式 HTTPS。如果代理在运行中频繁超时优先看本地代理配置的环境变量那常常是命令行的隐藏瓶颈。遇到这种情况不用慌大多数都是网络代理链路或者镜像源配置的问题和 superpowers 本身逻辑无关。排查清楚了之后运行会很稳定。5.5 我最终留下的配置组合折腾了快一个月我最终稳定的配置组合是语言约定类技能常驻测试生成和代码审查技能按需触发架构设计技能只在大型改动时开启记忆文件每周更新一次技能文件全部纳入 Git代理的权限范围严格按照项目目录白名单走。这套组合跑下来单个功能的实现速度虽然不一定比裸用快多少但代码质量和可维护性是肉眼可见地提升了反复返工率降低了很多。如果你也想让 AI 编码代理真正变成团队里一个“懂规矩、记得住事”的成员而不是每次都要重新交代背景的临时工建议从一个小项目开始先装好 superpowers再逐步把自己的工作习惯沉淀成技能文件。磨刀不误砍柴工这个投入后面会持续兑现。
