AI 编程助手用久了你会发现一个规律写个几十行的脚本、改个函数、生成单元测试它比谁都快可一旦丢给它一个跨模块的功能改造、一场需要前后端联动的完整需求它就频繁断片——要么一股脑把代码全堆在一个文件里要么做了一半忘记最初的约束要么对着一个报错反复打转。这半年我一直在折腾各种方式去调教 Agent最后稳定下来用的是superpowers这套方案。它不是某个 IDE 插件也不是单条提示词咒语而是一套把编程助手从聊天机器人变成工程协作者的技能包工作流。配合Codex这类命令行编程工具能明显减少返工和上下文漂移。这篇文章就把我的使用思路、配置过程、踩过的坑一次说清楚希望能让你少走点弯路。1. 先搞懂 superpowers 到底解决了什么问题1.1 它是什么不是 IDE 插件而是一套技能包工作流第一次接触 superpowers 的时候我下意识以为它是个 VSCode 插件或者重量级框架装上之后发现完全不是这么回事。它本质上是一套结构化的技能包集合以SKILL.md、AGENTS.md这类 Markdown 文件为载体给编程助手提供一套可执行的工作方法。你可以把它理解成给 Agent装脑子默认的 Codex 或 Claude 遇到复杂任务靠的是模型自身的推理能力上下文一长就容易迷失而 superpowers 把这些能力沉淀成一个个标准动作——遇到需求先写思考笔记动手前先拆任务计划出 bug 先采集现场信息再分析根因。整个工作流是显式的、可被 Agent 按步骤执行的而不是靠大模型临场发挥。我实际用下来最大的感受是它改变的不是单次回答的质量而是整个协作过程的稳定性。以前问 Agent帮我加个功能它可能直接开写现在它会先产出计划、列出影响面、标明它准备改哪些文件我再决定是否放行。这套流程本身就是工程协作里应有的节奏。1.2 为什么普通提示词不够用Agent 上下文的短视问题你可能试过在提示词里写请一步一步思考、请先分析再写代码但效果时好时坏。原因在于这些提示词是一次性的只对当前这次对话起作用一旦任务拆成多轮执行Agent 很容易忘记最初的约束或者在新信息出现后推翻之前的决策。superpowers 解决这个问题的方式是把方法论文件化、持久化。当 Agent 每轮接收消息时它会重新读到AGENTS.md里的工作约定再加载对应的 skill 文件相当于每轮对话都复习了一遍我们约定好的工作方法。这就像团队里的新人与其指望他记住你口头交代的所有要求不如把这套协作规范写成文档放在项目根目录他每次进来都会先看一遍。另一个关键痛点是上下文碎片化。在纯聊天的交互方式里Agent 的执行过程是黑盒——它改了什么、为什么这么改、测试结论如何全混在对话里。superpowers 通过让 Agent 在关键节点把状态写入独立的 Markdown 文件比如计划文件、进度文件、调试日志把思考过程从对话流里剥离出来既减轻了上下文负担也让整个执行过程可回溯。1.3 适用人群与不适用场景什么人最适合这套方案我的判断是重度使用 AI 编程工具的开发者如果你每天花大量时间跟 Codex、Claude Code 协作且经常被改了 A 坏了 B的问题困扰。需要把 Agent 工作流标准化的人比如团队想统一 Agent 的编码风格、提交流程、测试规范。愿意折腾配置的技术爱好者虽然安装不算复杂但前期调 skill 还是需要点耐心。不太适用的情况也存在如果你是偶尔用 AI 查个语法、写个一次性脚本那直接对话就够了没必要引入这套流程如果项目本身是一个简单到一眼能看穿的小工具让 Agent 走完整套思考-计划-执行-复盘反而显得重。工具是为人服务的别为了流程而流程。2. superpowers 的核心思路拆解从聊天到工程化协作2.1 把 Agent 当实习生给它完整的工作方法我一直觉得和 AI 编程助手协作的最好心态不是把它当成神器而是当成一个能力很强但经验不足的实习生。你交给实习生一个任务不会只说一句去做吧而是会告诉他先理清需求、再列个计划、遇到问题怎么处理、完成后怎么验证。superpowers 做的就是这件事。它的AGENTS.md相当于我们给实习生看的部门工作手册里面定义了工作原则永远先读任务说明、不要修改未出现在计划里的文件、每个功能都要跑测试等等。而skills/目录下的一个个 skill 文件则是把如何做需求分析、如何拆任务、如何调试这些方法写成标准操作流程。这套思路最妙的地方在于显式化。模型不擅长的事我们用流程去兜底模型擅长的事我们给它足够的自由度。比如让 Agent 做技术方案设计它天马行空很正常但流程要求它先列出候选方案、做出取舍、再把选型记录到计划文件里这样它的创意就有了约束边界不至于跑偏。2.2 核心模块思考、计划、执行、复盘在用过的各种技能包里我认为最核心的能力可以归为四类深度思考thinking在接到任务后Agent 先写一段任务分析——理解需求本质、识别约束条件、列出潜在风险。这一步能显著减少理解偏差。很多返工都是因为 Agent 根本没读懂需求就动手了思考环节相当于强制它先想清楚再干。任务规划planning把一个大需求拆成若干个小步骤每个步骤有明确的产出物和验收标准。实际使用中planning 最强的价值是让 Agent 在一个文件里维护任务进度清单——哪些完成了、哪些阻塞中、哪些还没开始。我随时打开这个文件就能知道它的进度而不是疯狂翻聊天记录。执行纪律execution这是容易被忽略的模块。它规定 Agent 只能按照计划文件的清单逐项执行不允许跳步也不允许顺手修改计划之外的文件。听起来死板但正是这种约束让它在复杂改动中不会失控。同时执行模块还会要求 Agent 每完成一个步骤就同步更新进度文件保持事实一致。调试复盘debugging / retrospection当测试失败或出现新 bugAgent 不能靠猜。它会先采集现场信息——报错堆栈、相关代码片段、最近的改动记录——再形成假设、设计最小验证实验、记录结论。我见过太多猜一个方案跑一下错了再猜的 Agent 死循环debug 模块基本从机制上堵住了这个毛病。2.3 可复用、可版本控制、跨工具迁移还有一个很实际的优点superpowers 只是一堆文本文件。它可以被提交进 Git 仓库跟代码一起做版本管理你可以给不同的项目配置不同的技能包组合你甚至可以 fork 一份自己改。相比那些藏在工具内部、不可见的魔法设置这种一切都可读、可改、可 diff 的特性非常符合工程师的习惯。再加上AGENTS.md和SKILL.md这套约定已经被多家工具支持迁移成本也很低。今天在 Codex 里用这套技能包明天拿到 Claude Code 里把目录结构一放、引用路径一配就能跑。它不是被某个工具绑架的私有配置更像一个开放标准。这也是我愿意投入时间研究它的核心原因——学一次到处用。3. 安装与配置从零到能跑只需十分钟3.1 前提条件本机环境准备开始之前先确认一下基础环境。你至少需要一台能正常访问终端环境的开发机macOS / Linux / Windows 的 WSL 均可而且最好能顺畅访问大模型 API 服务。这部分属于基础网络环境请确保你的网络环境本身符合相关要求。一个可用的 AI 编程工具命令行入口。我用得最多的是Codex CLI同时也用 Claude Code 做过对比测试。两者对AGENTS.md和 skill 目录的解析方式略有差异但核心机制一致。Git 肯定要有因为安装方式就是从仓库拉取技能包。另外建议装好jq这类命令行 JSON 处理工具后面调试 skill 输出格式时用得上。这些条件都不算苛刻属于开发者的常规环境配置。如果你平时已经在用 Codex 写代码那环境基本是现成的。3.2 安装步骤拉取技能包并建立目录结构安装本质就是把技能包仓库克隆到本地然后在项目里引用它。以我常用的目录结构为例# 在你的工作目录或全局工具目录下拉取技能包 git clone https://github.com/your-fork/superpowers.git ~/tools/superpowers cd ~/tools/superpowers # 目录结构大概是这样的 # superpowers/ # ├── skills/ # │ ├── thinking/SKILL.md # │ ├── planning/SKILL.md # │ ├── debugging/SKILL.md # │ ├── executing/SKILL.md # │ ├── documenting/SKILL.md # │ └── ... # ├── templates/ # └── AGENTS.md然后在你要使用 AI 助手的项目根目录里创建或合并AGENTS.md文件内容大致是# 项目协作规范 本项目的所有 AI 编码任务遵循 superpowers 工作流。 ## 基本规则 1. 收到任务后先加载 thinking skill 进行任务分析。 2. 使用 planning skill 拆解任务计划并将计划写入 .agent/plan.md。 3. 执行过程中严格按计划逐项完成每完成一项更新进度状态。 4. 任何测试失败都使用 debugging skill 处理禁止盲目猜测。 5. 所有功能完成后使用 documenting skill 更新相关文档。 ## 技能包路径 - 技能包根目录~/tools/superpowers - 技能加载方式根据任务类型选用 skills/ 下对应子目录中的 SKILL.md这样配置以后每次 Agent 启动都会读到这份规范相当于把工作手册摆在了它面前。3.3 配置 Agent 工具与 skill 加载方式光有文件还不行还要让 Codex 真正去读这些 skill。Codex CLI 的项目配置里可以通过自定义指令的方式把技能包路径告诉它。我常用的做法是在 Codex 的AGENTS.md里增加这么一段说明## 技能包使用说明 当用户要求完成一个复杂任务时请依次执行以下步骤 1. 首先阅读 ~/tools/superpowers/skills/thinking/SKILL.md按其中的方法完成需求分析输出分析结论。 2. 然后阅读 ~/tools/superpowers/skills/planning/SKILL.md创建任务计划文件。 3. 日常编码过程中阅读并遵循 ~/tools/superpowers/skills/executing/SKILL.md 中的执行纪律。这里的关键是把何时加载哪个 skill的规则写清楚。否则 Agent 虽然知道有这些文件但它不知道什么时候该用等于白搭。你可以在 AGENTS.md 里用 if-then 式的规则来定义触发条件比如当测试失败时先读取 debugging skill。如果你用的是 Claude Code机制类似只是配置文件叫CLAUDE.md而且它原生支持.claude/skills目录把SKILL.md放进去即可被自动加载。Codex 这边目前更依赖 AGENTS.md 里的显式引路。两者各有特点统一思路都是用文本约定驱动 Agent 行为。4. 完整实操让 Codex 具备规划执行调试超能力4.1 实战场景从零实现一个 REST API 项目理论说再多不如跑一遍真实流程。我挑一个典型的任务用 Python FastAPI 从零实现一个带 SQLite 存储的 REST API支持用户注册和登录凭证管理。这个需求涉及项目初始化、数据库设计、接口实现、单元测试几个环节足够展示 superpowers 的工作流。我先在终端里启动 Codex给它的初始任务指令是codex 在当前目录下从零创建一个 FastAPI 项目实现用户注册和登录凭证管理功能使用 SQLite 存储数据并提供完整的单元测试。请遵循 AGENTS.md 中的工作流。注意指令结尾我特意加了遵循 AGENTS.md 中的工作流这是在告诉 Agent不要跳过规划环节。实测下来加不加这句话效果差异很大加了之后它会更自觉地先加载 thinking 和 planning 流程。4.2 实操一先写思考笔记把需求理解钉在纸面上任务发起后Codex 会按 AGENTS.md 的约定先读取 thinking skill。这个 skill 会引导它输出以下内容需求本质用户要的是一个带持久化存储的用户认证系统核心是注册接口与登录凭证校验。约束条件技术栈锁定 Python FastAPI SQLite必须有单元测试项目结构要清晰。潜在风险密码不能明文存储需要考虑哈希方案登录接口要考虑失败场景测试需要临时数据库方案。这段话看着简单但它有非常实际的价值把 Agent 对需求的理解显式化。如果它理解有偏我在这个环节就能纠正而不是等它写完几百行代码才发现方向错了。有一回它把登录凭证管理理解成了实现 JWT 签发如果没在 thinking 阶段暴露出来后面整个设计都会跑偏。我通常要求 Agent 把思考结论写到.agent/analysis.md文件里而不是只输出在对话里。这样后面的执行阶段它能随时回去翻不需要让我重复上下文。4.3 实操二用 planning skill 拆任务并维护可勾选的进度清单思考确认没问题进入 planning 环节。Codex 读取 planning skill 后会生成一个.agent/plan.md内容类似# 用户凭证管理 API 实施计划 ## 步骤 1初始化项目结构 - 创建项目目录、虚拟环境 - 安装 fastapi、uvicorn、sqlite3 驱动、pytest - 状态进行中 ## 步骤 2实现数据库模块 - 设计 users 表结构 - 实现数据库连接与初始化逻辑 - 状态待开始 ## 步骤 3实现注册与登录接口 - 注册接口参数校验、密码哈希、落库 - 登录接口校验凭证、返回结果 - 状态待开始 ## 步骤 4编写单元测试 - 覆盖注册成功、重复注册、登录成功、密码错误等场景 - 状态待开始 ## 步骤 5运行测试并修复问题 - 状态待开始这个计划文件最大的好处是可追踪。Agent 每完成一步就把待开始改成已完成同时补上关键决策记录。我随时cat .agent/plan.md就能看到实时进度。有一次任务执行到一半需要中断第二天我重新拉起 Codex让它先读 plan.md它立刻知道进行到哪一步无缝续上这个体验比纯对话式协作强太多。4.4 实操三报错时的 debug 模式不靠猜靠定位前端几步都比较顺但实际运行测试时Agent 遇到了一个报错注册接口测试失败提示 SQLite 数据库表不存在。如果按默认模式它可能会直接改代码、乱加建表逻辑。但因为有 debugging skill 约束它会先进入现场信息采集复现命令与完整报错堆栈。检查数据库初始化代码是否在应用启动时被正确调用。查看测试代码是否用了独立测试数据库还是复用了开发数据库。采集完之后它形成的假设是测试启动时没有触发建表语句验证方式是在测试启动代码里显式调用初始化函数并重跑。整个过程记录在.agent/debug_log.md里。修完后还能定位到一个更深的问题之前的初始化逻辑放在了__main__块里用uvicorn启动时并不会执行。这个根因如果没有 debug 流程很可能要来回试好几轮才找到。我印象很深的一点是debugging skill 让 Agent 从盲猜变成了有方法论地排查。它输出的每一步都有依据我作为人类审查者能很快速地判断它思路是否正确而不是面对一堆试错记录无从下手。5. 常用技能包解析像搭积木一样组合 Agent 能力5.1 核心技能包清单与分工superpowers 之所以叫超能力能被称为一个体系是因为它把 Agent 需要的能力模块化了。以下是我用下来最频繁的几个技能包核心职责典型触发时机thinking需求分析、风险识别、约束梳理接到复杂任务时planning任务拆解、计划文件维护、依赖识别确认需求理解后executing执行纪律、文件改动范围控制、进度更新编码实施阶段debugging现场采集、假设验证、根因分析测试失败或出现异常时documenting更新 README、接口文档、变更记录功能完成、准备交付时reviewing代码自查、潜在问题清单、重构建议任务收尾、提交前每个技能包内部都是背景说明 操作流程 输出模板的结构Agent 读取之后会按照模板要求输出结构化内容。这种模板化设计是有意的结构化输出比自由输出更容易被审查也更容易被后续步骤复用。比如 planning 输出的计划文件是固定的 Markdown 清单格式debugging 日志有固定的填写字段这让多个 skill 之间可以顺畅衔接。5.2 不同场景下的技能组合推荐技能包不是越多越好按照任务类型做减法反而更有效。分享几个我常用的组合方案小型任务比如给某个函数补充参数校验thinking executing 就够不需要 planning 和 documenting。任务复杂度低走全流程反而拖慢速度。中等任务比如新增一个内部工具脚本并接入主流程thinking planning executing debugging。需要拆步骤但不需要大动干戈写完整文档。大型任务比如重构用户模块并保持兼容性全流程都要上reviewing 和 documenting 绝对不能省。重构场景里最容易出现回归reviewing 能逼 Agent 自查documenting 能把改动沉淀下来。运维排查类比如线上接口偶发超时thinking debugging 优先而且要加上限制条件——先采集证据再改任何配置。这四种组合我都在实际项目中验证过核心原则是让流程匹配任务复杂度。很多人用不好 superpowers不是因为少装了某个技能包而是因为所有任务都套同一个重型流程最终自己都嫌烦。5.3 自定义一个自己的 skillsuperpowers 最吸引我的一点其实是它允许你轻松追加自己的方法论。任何你觉得 Agent 反复做不好的事都可以固化成一个 skill。比如我团队里经常有变更数据库表结构的需求每次 Agent 都会忘记生成对应的回滚语句。我干脆写了个db_migration/SKILL.md--- name: db_migration description: 数据库结构变更的标准流程所有涉及建表、改表、索引变更的任务必须使用。 --- ## 流程 1. 先输出当前表结构快照。 2. 编写正向迁移 SQL写到 migrations/ 目录。 3. 编写回滚 SQL写到同一目录文件名带 _rollback 后缀。 4. 执行正向迁移并验证结构。 5. 更新迁移记录文件。写法很简单name和description作为元信息正文部分是具体操作流程。写好放到技能包目录后再在 AGENTS.md 里加一条触发规则即可。从此以后Agent 做数据库变更时默认就会先写回滚 SQL这个从习惯性遗忘到流程保障的变化就是技能包复利的体现。6. 常见问题与排查技巧实录6.1 高频问题速查表用这套工作流几个月我积累了一些高频问题的应对经验整理成下表问题现象可能原因解决方法Agent 不加载技能包AGENTS.md 触发规则不明确在配置文件里写明遇到什么情况加载哪个 skill的 if-then 规则计划文件不更新Agent 跳过了执行纪律要求执行步骤里强制声明每完成一项必须更新 plan.md否则视为未完成思考笔记过于空泛thinking skill 缺少结构化模板修改 skill 文件强制要求输出需求本质/约束/风险/验证标准四个小节调试过程反复猜debug 日志没有现场采集环节强化先采集信息再形成假设的步骤禁止直接改代码技能包路径找不到路径用了相对路径且 Agent 工作目录不一致统一使用绝对路径或在 AGENTS.md 里设置路径变量多技能包冲突多个 skill 对同一动作给出不同指示在 AGENTS.md 里明确优先级顺序比如debugging 优先级高于 executing其中路径问题是我踩过最多的坑。一开始我用的是相对路径../superpowers/skills/...但当 Agent 在子目录执行命令时相对路径就失效了。后来统一改成绝对路径或者环境变量才彻底解决。6.2 踩坑实录三个让我印象深刻的教训第一个教训是关于流程约束过细则导致效率下降。我最初把技能包设计得事无巨细连变量命名必须使用 snake_case都写成了强制步骤。结果 Agent 把大量精力花在格式检查上真正的业务逻辑反而写得糙。后来我把约束分级硬性底线才写进强制流程。流程是兜底的不是束缚手脚的。第二个教训是检查点要留得够多但也要够准。执行阶段如果要求 Agent每写 50 行代码就暂停汇报它会被频繁打断效率很低如果完全不设检查点它容易一口气写错一大片。我的折中方案是只在完成一个独立功能模块后设检查点这个节奏既能及时纠偏又不至于把执行切得太碎。第三个教训更偏心理层面别把 AI 的能力神话。superpowers 能显著减少出错次数但不可能做到零错误尤其在选型决策这类开放问题上Agent 给出的方案未必是最优的。它的价值是让过程可靠让错误可发现、可定位但最终的设计裁决权还是要掌握在人手里。我现在的习惯是核心架构决定自己拿主意重复性执行全部放手给 Agent。这个分工模式让我的效率提升了一个量级。另外关于多工具协同我建议你把AGENTS.md和技能包目录纳入 Git 仓库统一管理。每次调整工作流后Commit 信息里写明增强了 xxx 技能包的 yyy 环节这样过段时间回头看能很清楚知道自己的协作方法是怎么演进的。这套工作流本身也一样需要复盘才能越用越顺手。最后分享一个小技巧当 Agent 完成一个大任务后我会让它把整个过程中的思考摘要和遇到的坑追加到项目里的AGENTS.md底部。这等于让项目自身的协作手册不断进化下次再有类似任务Agent 就能直接参考之前的经验。我用了几周之后最明显的变化是重复错误明显变少因为那些坑已经被沉淀成了流程的一部分。这大概就是 superpowers 真正的超能力所在——不是替你做决定而是让你把一次次的实践智慧变成可复用的工作方法。 superpowers：把AI编程助手从聊天机器人变成工程协作者
AI 编程助手用久了你会发现一个规律写个几十行的脚本、改个函数、生成单元测试它比谁都快可一旦丢给它一个跨模块的功能改造、一场需要前后端联动的完整需求它就频繁断片——要么一股脑把代码全堆在一个文件里要么做了一半忘记最初的约束要么对着一个报错反复打转。这半年我一直在折腾各种方式去调教 Agent最后稳定下来用的是superpowers这套方案。它不是某个 IDE 插件也不是单条提示词咒语而是一套把编程助手从聊天机器人变成工程协作者的技能包工作流。配合Codex这类命令行编程工具能明显减少返工和上下文漂移。这篇文章就把我的使用思路、配置过程、踩过的坑一次说清楚希望能让你少走点弯路。1. 先搞懂 superpowers 到底解决了什么问题1.1 它是什么不是 IDE 插件而是一套技能包工作流第一次接触 superpowers 的时候我下意识以为它是个 VSCode 插件或者重量级框架装上之后发现完全不是这么回事。它本质上是一套结构化的技能包集合以SKILL.md、AGENTS.md这类 Markdown 文件为载体给编程助手提供一套可执行的工作方法。你可以把它理解成给 Agent装脑子默认的 Codex 或 Claude 遇到复杂任务靠的是模型自身的推理能力上下文一长就容易迷失而 superpowers 把这些能力沉淀成一个个标准动作——遇到需求先写思考笔记动手前先拆任务计划出 bug 先采集现场信息再分析根因。整个工作流是显式的、可被 Agent 按步骤执行的而不是靠大模型临场发挥。我实际用下来最大的感受是它改变的不是单次回答的质量而是整个协作过程的稳定性。以前问 Agent帮我加个功能它可能直接开写现在它会先产出计划、列出影响面、标明它准备改哪些文件我再决定是否放行。这套流程本身就是工程协作里应有的节奏。1.2 为什么普通提示词不够用Agent 上下文的短视问题你可能试过在提示词里写请一步一步思考、请先分析再写代码但效果时好时坏。原因在于这些提示词是一次性的只对当前这次对话起作用一旦任务拆成多轮执行Agent 很容易忘记最初的约束或者在新信息出现后推翻之前的决策。superpowers 解决这个问题的方式是把方法论文件化、持久化。当 Agent 每轮接收消息时它会重新读到AGENTS.md里的工作约定再加载对应的 skill 文件相当于每轮对话都复习了一遍我们约定好的工作方法。这就像团队里的新人与其指望他记住你口头交代的所有要求不如把这套协作规范写成文档放在项目根目录他每次进来都会先看一遍。另一个关键痛点是上下文碎片化。在纯聊天的交互方式里Agent 的执行过程是黑盒——它改了什么、为什么这么改、测试结论如何全混在对话里。superpowers 通过让 Agent 在关键节点把状态写入独立的 Markdown 文件比如计划文件、进度文件、调试日志把思考过程从对话流里剥离出来既减轻了上下文负担也让整个执行过程可回溯。1.3 适用人群与不适用场景什么人最适合这套方案我的判断是重度使用 AI 编程工具的开发者如果你每天花大量时间跟 Codex、Claude Code 协作且经常被改了 A 坏了 B的问题困扰。需要把 Agent 工作流标准化的人比如团队想统一 Agent 的编码风格、提交流程、测试规范。愿意折腾配置的技术爱好者虽然安装不算复杂但前期调 skill 还是需要点耐心。不太适用的情况也存在如果你是偶尔用 AI 查个语法、写个一次性脚本那直接对话就够了没必要引入这套流程如果项目本身是一个简单到一眼能看穿的小工具让 Agent 走完整套思考-计划-执行-复盘反而显得重。工具是为人服务的别为了流程而流程。2. superpowers 的核心思路拆解从聊天到工程化协作2.1 把 Agent 当实习生给它完整的工作方法我一直觉得和 AI 编程助手协作的最好心态不是把它当成神器而是当成一个能力很强但经验不足的实习生。你交给实习生一个任务不会只说一句去做吧而是会告诉他先理清需求、再列个计划、遇到问题怎么处理、完成后怎么验证。superpowers 做的就是这件事。它的AGENTS.md相当于我们给实习生看的部门工作手册里面定义了工作原则永远先读任务说明、不要修改未出现在计划里的文件、每个功能都要跑测试等等。而skills/目录下的一个个 skill 文件则是把如何做需求分析、如何拆任务、如何调试这些方法写成标准操作流程。这套思路最妙的地方在于显式化。模型不擅长的事我们用流程去兜底模型擅长的事我们给它足够的自由度。比如让 Agent 做技术方案设计它天马行空很正常但流程要求它先列出候选方案、做出取舍、再把选型记录到计划文件里这样它的创意就有了约束边界不至于跑偏。2.2 核心模块思考、计划、执行、复盘在用过的各种技能包里我认为最核心的能力可以归为四类深度思考thinking在接到任务后Agent 先写一段任务分析——理解需求本质、识别约束条件、列出潜在风险。这一步能显著减少理解偏差。很多返工都是因为 Agent 根本没读懂需求就动手了思考环节相当于强制它先想清楚再干。任务规划planning把一个大需求拆成若干个小步骤每个步骤有明确的产出物和验收标准。实际使用中planning 最强的价值是让 Agent 在一个文件里维护任务进度清单——哪些完成了、哪些阻塞中、哪些还没开始。我随时打开这个文件就能知道它的进度而不是疯狂翻聊天记录。执行纪律execution这是容易被忽略的模块。它规定 Agent 只能按照计划文件的清单逐项执行不允许跳步也不允许顺手修改计划之外的文件。听起来死板但正是这种约束让它在复杂改动中不会失控。同时执行模块还会要求 Agent 每完成一个步骤就同步更新进度文件保持事实一致。调试复盘debugging / retrospection当测试失败或出现新 bugAgent 不能靠猜。它会先采集现场信息——报错堆栈、相关代码片段、最近的改动记录——再形成假设、设计最小验证实验、记录结论。我见过太多猜一个方案跑一下错了再猜的 Agent 死循环debug 模块基本从机制上堵住了这个毛病。2.3 可复用、可版本控制、跨工具迁移还有一个很实际的优点superpowers 只是一堆文本文件。它可以被提交进 Git 仓库跟代码一起做版本管理你可以给不同的项目配置不同的技能包组合你甚至可以 fork 一份自己改。相比那些藏在工具内部、不可见的魔法设置这种一切都可读、可改、可 diff 的特性非常符合工程师的习惯。再加上AGENTS.md和SKILL.md这套约定已经被多家工具支持迁移成本也很低。今天在 Codex 里用这套技能包明天拿到 Claude Code 里把目录结构一放、引用路径一配就能跑。它不是被某个工具绑架的私有配置更像一个开放标准。这也是我愿意投入时间研究它的核心原因——学一次到处用。3. 安装与配置从零到能跑只需十分钟3.1 前提条件本机环境准备开始之前先确认一下基础环境。你至少需要一台能正常访问终端环境的开发机macOS / Linux / Windows 的 WSL 均可而且最好能顺畅访问大模型 API 服务。这部分属于基础网络环境请确保你的网络环境本身符合相关要求。一个可用的 AI 编程工具命令行入口。我用得最多的是Codex CLI同时也用 Claude Code 做过对比测试。两者对AGENTS.md和 skill 目录的解析方式略有差异但核心机制一致。Git 肯定要有因为安装方式就是从仓库拉取技能包。另外建议装好jq这类命令行 JSON 处理工具后面调试 skill 输出格式时用得上。这些条件都不算苛刻属于开发者的常规环境配置。如果你平时已经在用 Codex 写代码那环境基本是现成的。3.2 安装步骤拉取技能包并建立目录结构安装本质就是把技能包仓库克隆到本地然后在项目里引用它。以我常用的目录结构为例# 在你的工作目录或全局工具目录下拉取技能包 git clone https://github.com/your-fork/superpowers.git ~/tools/superpowers cd ~/tools/superpowers # 目录结构大概是这样的 # superpowers/ # ├── skills/ # │ ├── thinking/SKILL.md # │ ├── planning/SKILL.md # │ ├── debugging/SKILL.md # │ ├── executing/SKILL.md # │ ├── documenting/SKILL.md # │ └── ... # ├── templates/ # └── AGENTS.md然后在你要使用 AI 助手的项目根目录里创建或合并AGENTS.md文件内容大致是# 项目协作规范 本项目的所有 AI 编码任务遵循 superpowers 工作流。 ## 基本规则 1. 收到任务后先加载 thinking skill 进行任务分析。 2. 使用 planning skill 拆解任务计划并将计划写入 .agent/plan.md。 3. 执行过程中严格按计划逐项完成每完成一项更新进度状态。 4. 任何测试失败都使用 debugging skill 处理禁止盲目猜测。 5. 所有功能完成后使用 documenting skill 更新相关文档。 ## 技能包路径 - 技能包根目录~/tools/superpowers - 技能加载方式根据任务类型选用 skills/ 下对应子目录中的 SKILL.md这样配置以后每次 Agent 启动都会读到这份规范相当于把工作手册摆在了它面前。3.3 配置 Agent 工具与 skill 加载方式光有文件还不行还要让 Codex 真正去读这些 skill。Codex CLI 的项目配置里可以通过自定义指令的方式把技能包路径告诉它。我常用的做法是在 Codex 的AGENTS.md里增加这么一段说明## 技能包使用说明 当用户要求完成一个复杂任务时请依次执行以下步骤 1. 首先阅读 ~/tools/superpowers/skills/thinking/SKILL.md按其中的方法完成需求分析输出分析结论。 2. 然后阅读 ~/tools/superpowers/skills/planning/SKILL.md创建任务计划文件。 3. 日常编码过程中阅读并遵循 ~/tools/superpowers/skills/executing/SKILL.md 中的执行纪律。这里的关键是把何时加载哪个 skill的规则写清楚。否则 Agent 虽然知道有这些文件但它不知道什么时候该用等于白搭。你可以在 AGENTS.md 里用 if-then 式的规则来定义触发条件比如当测试失败时先读取 debugging skill。如果你用的是 Claude Code机制类似只是配置文件叫CLAUDE.md而且它原生支持.claude/skills目录把SKILL.md放进去即可被自动加载。Codex 这边目前更依赖 AGENTS.md 里的显式引路。两者各有特点统一思路都是用文本约定驱动 Agent 行为。4. 完整实操让 Codex 具备规划执行调试超能力4.1 实战场景从零实现一个 REST API 项目理论说再多不如跑一遍真实流程。我挑一个典型的任务用 Python FastAPI 从零实现一个带 SQLite 存储的 REST API支持用户注册和登录凭证管理。这个需求涉及项目初始化、数据库设计、接口实现、单元测试几个环节足够展示 superpowers 的工作流。我先在终端里启动 Codex给它的初始任务指令是codex 在当前目录下从零创建一个 FastAPI 项目实现用户注册和登录凭证管理功能使用 SQLite 存储数据并提供完整的单元测试。请遵循 AGENTS.md 中的工作流。注意指令结尾我特意加了遵循 AGENTS.md 中的工作流这是在告诉 Agent不要跳过规划环节。实测下来加不加这句话效果差异很大加了之后它会更自觉地先加载 thinking 和 planning 流程。4.2 实操一先写思考笔记把需求理解钉在纸面上任务发起后Codex 会按 AGENTS.md 的约定先读取 thinking skill。这个 skill 会引导它输出以下内容需求本质用户要的是一个带持久化存储的用户认证系统核心是注册接口与登录凭证校验。约束条件技术栈锁定 Python FastAPI SQLite必须有单元测试项目结构要清晰。潜在风险密码不能明文存储需要考虑哈希方案登录接口要考虑失败场景测试需要临时数据库方案。这段话看着简单但它有非常实际的价值把 Agent 对需求的理解显式化。如果它理解有偏我在这个环节就能纠正而不是等它写完几百行代码才发现方向错了。有一回它把登录凭证管理理解成了实现 JWT 签发如果没在 thinking 阶段暴露出来后面整个设计都会跑偏。我通常要求 Agent 把思考结论写到.agent/analysis.md文件里而不是只输出在对话里。这样后面的执行阶段它能随时回去翻不需要让我重复上下文。4.3 实操二用 planning skill 拆任务并维护可勾选的进度清单思考确认没问题进入 planning 环节。Codex 读取 planning skill 后会生成一个.agent/plan.md内容类似# 用户凭证管理 API 实施计划 ## 步骤 1初始化项目结构 - 创建项目目录、虚拟环境 - 安装 fastapi、uvicorn、sqlite3 驱动、pytest - 状态进行中 ## 步骤 2实现数据库模块 - 设计 users 表结构 - 实现数据库连接与初始化逻辑 - 状态待开始 ## 步骤 3实现注册与登录接口 - 注册接口参数校验、密码哈希、落库 - 登录接口校验凭证、返回结果 - 状态待开始 ## 步骤 4编写单元测试 - 覆盖注册成功、重复注册、登录成功、密码错误等场景 - 状态待开始 ## 步骤 5运行测试并修复问题 - 状态待开始这个计划文件最大的好处是可追踪。Agent 每完成一步就把待开始改成已完成同时补上关键决策记录。我随时cat .agent/plan.md就能看到实时进度。有一次任务执行到一半需要中断第二天我重新拉起 Codex让它先读 plan.md它立刻知道进行到哪一步无缝续上这个体验比纯对话式协作强太多。4.4 实操三报错时的 debug 模式不靠猜靠定位前端几步都比较顺但实际运行测试时Agent 遇到了一个报错注册接口测试失败提示 SQLite 数据库表不存在。如果按默认模式它可能会直接改代码、乱加建表逻辑。但因为有 debugging skill 约束它会先进入现场信息采集复现命令与完整报错堆栈。检查数据库初始化代码是否在应用启动时被正确调用。查看测试代码是否用了独立测试数据库还是复用了开发数据库。采集完之后它形成的假设是测试启动时没有触发建表语句验证方式是在测试启动代码里显式调用初始化函数并重跑。整个过程记录在.agent/debug_log.md里。修完后还能定位到一个更深的问题之前的初始化逻辑放在了__main__块里用uvicorn启动时并不会执行。这个根因如果没有 debug 流程很可能要来回试好几轮才找到。我印象很深的一点是debugging skill 让 Agent 从盲猜变成了有方法论地排查。它输出的每一步都有依据我作为人类审查者能很快速地判断它思路是否正确而不是面对一堆试错记录无从下手。5. 常用技能包解析像搭积木一样组合 Agent 能力5.1 核心技能包清单与分工superpowers 之所以叫超能力能被称为一个体系是因为它把 Agent 需要的能力模块化了。以下是我用下来最频繁的几个技能包核心职责典型触发时机thinking需求分析、风险识别、约束梳理接到复杂任务时planning任务拆解、计划文件维护、依赖识别确认需求理解后executing执行纪律、文件改动范围控制、进度更新编码实施阶段debugging现场采集、假设验证、根因分析测试失败或出现异常时documenting更新 README、接口文档、变更记录功能完成、准备交付时reviewing代码自查、潜在问题清单、重构建议任务收尾、提交前每个技能包内部都是背景说明 操作流程 输出模板的结构Agent 读取之后会按照模板要求输出结构化内容。这种模板化设计是有意的结构化输出比自由输出更容易被审查也更容易被后续步骤复用。比如 planning 输出的计划文件是固定的 Markdown 清单格式debugging 日志有固定的填写字段这让多个 skill 之间可以顺畅衔接。5.2 不同场景下的技能组合推荐技能包不是越多越好按照任务类型做减法反而更有效。分享几个我常用的组合方案小型任务比如给某个函数补充参数校验thinking executing 就够不需要 planning 和 documenting。任务复杂度低走全流程反而拖慢速度。中等任务比如新增一个内部工具脚本并接入主流程thinking planning executing debugging。需要拆步骤但不需要大动干戈写完整文档。大型任务比如重构用户模块并保持兼容性全流程都要上reviewing 和 documenting 绝对不能省。重构场景里最容易出现回归reviewing 能逼 Agent 自查documenting 能把改动沉淀下来。运维排查类比如线上接口偶发超时thinking debugging 优先而且要加上限制条件——先采集证据再改任何配置。这四种组合我都在实际项目中验证过核心原则是让流程匹配任务复杂度。很多人用不好 superpowers不是因为少装了某个技能包而是因为所有任务都套同一个重型流程最终自己都嫌烦。5.3 自定义一个自己的 skillsuperpowers 最吸引我的一点其实是它允许你轻松追加自己的方法论。任何你觉得 Agent 反复做不好的事都可以固化成一个 skill。比如我团队里经常有变更数据库表结构的需求每次 Agent 都会忘记生成对应的回滚语句。我干脆写了个db_migration/SKILL.md--- name: db_migration description: 数据库结构变更的标准流程所有涉及建表、改表、索引变更的任务必须使用。 --- ## 流程 1. 先输出当前表结构快照。 2. 编写正向迁移 SQL写到 migrations/ 目录。 3. 编写回滚 SQL写到同一目录文件名带 _rollback 后缀。 4. 执行正向迁移并验证结构。 5. 更新迁移记录文件。写法很简单name和description作为元信息正文部分是具体操作流程。写好放到技能包目录后再在 AGENTS.md 里加一条触发规则即可。从此以后Agent 做数据库变更时默认就会先写回滚 SQL这个从习惯性遗忘到流程保障的变化就是技能包复利的体现。6. 常见问题与排查技巧实录6.1 高频问题速查表用这套工作流几个月我积累了一些高频问题的应对经验整理成下表问题现象可能原因解决方法Agent 不加载技能包AGENTS.md 触发规则不明确在配置文件里写明遇到什么情况加载哪个 skill的 if-then 规则计划文件不更新Agent 跳过了执行纪律要求执行步骤里强制声明每完成一项必须更新 plan.md否则视为未完成思考笔记过于空泛thinking skill 缺少结构化模板修改 skill 文件强制要求输出需求本质/约束/风险/验证标准四个小节调试过程反复猜debug 日志没有现场采集环节强化先采集信息再形成假设的步骤禁止直接改代码技能包路径找不到路径用了相对路径且 Agent 工作目录不一致统一使用绝对路径或在 AGENTS.md 里设置路径变量多技能包冲突多个 skill 对同一动作给出不同指示在 AGENTS.md 里明确优先级顺序比如debugging 优先级高于 executing其中路径问题是我踩过最多的坑。一开始我用的是相对路径../superpowers/skills/...但当 Agent 在子目录执行命令时相对路径就失效了。后来统一改成绝对路径或者环境变量才彻底解决。6.2 踩坑实录三个让我印象深刻的教训第一个教训是关于流程约束过细则导致效率下降。我最初把技能包设计得事无巨细连变量命名必须使用 snake_case都写成了强制步骤。结果 Agent 把大量精力花在格式检查上真正的业务逻辑反而写得糙。后来我把约束分级硬性底线才写进强制流程。流程是兜底的不是束缚手脚的。第二个教训是检查点要留得够多但也要够准。执行阶段如果要求 Agent每写 50 行代码就暂停汇报它会被频繁打断效率很低如果完全不设检查点它容易一口气写错一大片。我的折中方案是只在完成一个独立功能模块后设检查点这个节奏既能及时纠偏又不至于把执行切得太碎。第三个教训更偏心理层面别把 AI 的能力神话。superpowers 能显著减少出错次数但不可能做到零错误尤其在选型决策这类开放问题上Agent 给出的方案未必是最优的。它的价值是让过程可靠让错误可发现、可定位但最终的设计裁决权还是要掌握在人手里。我现在的习惯是核心架构决定自己拿主意重复性执行全部放手给 Agent。这个分工模式让我的效率提升了一个量级。另外关于多工具协同我建议你把AGENTS.md和技能包目录纳入 Git 仓库统一管理。每次调整工作流后Commit 信息里写明增强了 xxx 技能包的 yyy 环节这样过段时间回头看能很清楚知道自己的协作方法是怎么演进的。这套工作流本身也一样需要复盘才能越用越顺手。最后分享一个小技巧当 Agent 完成一个大任务后我会让它把整个过程中的思考摘要和遇到的坑追加到项目里的AGENTS.md底部。这等于让项目自身的协作手册不断进化下次再有类似任务Agent 就能直接参考之前的经验。我用了几周之后最明显的变化是重复错误明显变少因为那些坑已经被沉淀成了流程的一部分。这大概就是 superpowers 真正的超能力所在——不是替你做决定而是让你把一次次的实践智慧变成可复用的工作方法。