这几天在梳理自己的 AI 编码工作流时重新研究了社区里讨论度很高的superpowers项目。如果你一直在用 codex CLI 或 Claude Code 这类终端 AI 助手大概会有这种感觉模型很聪明但它更像一个“指哪打哪”的实习生——你告诉它做什么它做完就停缺乏一个贯穿始终的方法论。superpowers想解决的就是这个问题它通过一套精心设计的 Skill 集合把“如何拆解任务、如何写测试、如何调试、如何重构”这些资深工程师脑子里的隐性知识显式地注入给 AI 代理。这篇文章我会从superpowers的核心设计理念讲起然后完整走一遍在 codex CLI 里的安装、配置和实战流程最后分享几个我在 trae work cn 这类外部环境里折腾superpowers时踩过的坑。内容比较长既有概念解释也有可直接复制的命令适合已经用上 AI 编程助手、但觉得“差点意思”的开发者。1. superpowers 不只是技能包它改变了 AI 编码的思维方式第一次看到superpowers这个项目名我以为又是一套提示词模板合集。实际用下来才发现它真正有价值的部分不是那些具体指令而是藏在指令背后的分层思考模型。1.1 从“一次生成一大段”到“分层思考”大多数 AI 编码助手的工作方式是读入你的需求然后一次性生成一大段代码。这在简单任务上没问题但一旦涉及多文件、多模块、有状态迁移的项目这种方式很容易失控——AI 会凭“直觉”跳过某些边界情况或者为了满足显式需求而破坏隐式的架构约束。superpowers的分层思考模型强制 AI 换一种工作节奏先把任务拆成规划层明确目标、约束、验收标准。再进入设计层确定接口、数据结构、模块边界。最后才进入实现层逐文件、逐函数编写代码。这个思路跟 TDD 的“红-绿-重构”循环是兼容的或者说它把 TDD 从“一种测试方法”升级成了“一种任务推进策略”。AI 不再是拿到需求就写代码而是先回答问题这个功能的验收条件是什么哪些边界情况需要处理如果中途发现问题应该回退到哪一层重新决策1.2 为什么测试驱动开发会成为核心工作流superpowers把 TDD 写进了 Skill 工作流的底层这一点很多人不理解觉得“让 AI 写测试再写代码”是多此一举。但实际跑过一轮复杂功能开发后你会明白它的价值测试是唯一可执行的规格说明书。自然语言需求有歧义注释会过时但一个失败的测试用例会始终如一地向 AI 表明“你还没完成”。快速反馈循环。AI 写一段代码跑一次测试红了调整再绿——这个循环比让 AI 一次性输出 500 行代码再人工 review 要可靠得多。防止回归。项目越到后期越怕“改了一个 bug 引出三个新 bug”。有测试兜底AI 的重构才有安全感。superpowers的 Skill 定义里每一步都会明确提醒模型先写最小失败测试再实现再运行测试确认。如果你用惯了“对话式编程”刚切换到这种模式会觉得繁琐但坚持几个功能后你会看到代码质量的明显差距。1.3 模块里到底装了什么核心 Skill 与目录结构superpowers在 GitHub 上以skills目录组织每个子模块都遵循 Anthropic 提出的 Agent Skills 规范核心是SKILL.md文件——用 Markdown 描述该 Skill 的适用场景、工作流程和约束条件。模块里比较核心的几个Skill 名称作用我的使用频率stratified-thinking分层思考任务规划每次任务都触发tdd测试驱动开发工作流几乎每次编码任务都触发debugging系统化调试方法论遇到 bug 时触发refactoring重构工作流保障行为不变代码需要整理时触发code-review对生成代码做审查合并前触发这套 Skill 之间是有嵌套关系的stratified-thinking是底座tdd是编码阶段的主力debugging和refactoring是后续维护阶段的分支。superpowers没有把每个 Skill 做成孤岛而是通过SKILL.md里的上下文引用让它们协同工作这是它和普通提示词模板最大的区别。2. 动手准备给 codex CLI 安装 superpowers 之前的环境检查superpowers建议的运行环境是 codex CLI 或 Claude Code。我主力用的是 codex CLI所以下面的步骤以它为例。在拉代码之前有几项环境检查值得先做能避免后面莫名其妙的报错。2.1 codex 版本要求与 Node 环境superpowers的官方安装脚本依赖 Node.js 环境如果你机器上还没有 Node或者版本太老安装过程会失败或在后续读取 Skill 时出现解析异常。建议 Node 版本不低于 20我用的版本是v20.19.0一路跑下来没有兼容问题。codex CLI 确保升级到较新版本。我用的是codex --version能看到版本号的版本旧版本可能不支持AGENTS.md全局指令或者skills字段。另外检查一下你的终端是否支持长路径和特殊字符这个在 Windows 上特别容易出问题。2.2 安装方式对比官方脚本与手动同步superpowers的 README 里推荐用一条curl命令完成安装它的本质是克隆项目仓库并执行安装脚本。不过我更推荐先手动把仓库克隆到本地看清楚目录结构再决定怎么安装原因有两个官方脚本默认把文件装进~/.codex/skills之类的全局目录但如果你有多台机器或想用 dotfiles 统一管理配置手动克隆到自己的项目目录会更灵活。了解文件落点后后续排查“Skill 没生效”这类问题会快很多。安装方式没有绝对的对错关键是你要理解superpowers只是一个文件集合真正让它生效的是 codex 配置里指向这些SKILL.md的引用路径。所以无论用哪种方式最终都要确认配置引用正确。2.3 初始化配置AGENTS.md 与工作区的关系codex CLI 的一个特性是支持AGENTS.md文件——你可以把它理解成“给 AI 代理看的 README”。superpowers建议每个项目根目录放一份AGENTS.md里面说明项目的技术栈、目录结构、常用命令和约束条件。为什么要特别强调这个文件因为superpowers的分层思考模型里规划层的第一步就是理解项目上下文。如果 AI 对你的项目一无所知它产出的计划再漂亮也是悬空的。一份合格的AGENTS.md就像给新同事的入职手册能极大提高 AI 后续所有决策的准确率。我通常在AGENTS.md里写四块内容项目一句话简介、技术栈清单、关键脚本命令测试/构建/启动、架构约束比如“所有数据库访问必须走 repository 层”。这些内容不用很长但必须精准。3. 安装实操全记录从代码拉取到 Skill 被识别下面进入正题。我会完整记录我在一台 macOS 机器上从零安装superpowers到 codex CLI 的过程。中间会穿插一些我踩过的坑和验证方法。3.1 标准安装步骤与验证方法如果你只是想快速用起来官方安装命令是最省事的curl -sSL https://raw.githubusercontent.com/obra/superpowers/main/install.sh | bash脚本做的事大致是克隆superpowers仓库到本地缓存目录然后把skills/下的所有 Skill 复制到 codex 的全局 skills 目录一般是~/.codex/skills并在 codex 配置文件里注册。安装完成后我建议做一个快速验证在任意目录打开 codex问它“用分层思考的方式规划一个待办事项 CLI”看它的回复是否包含“分层思考”“测试驱动”这类关键词。如果模型完全没反应说明 Skill 可能没被加载需要检查配置。3.2 codex 配置文件的接入点codex CLI 的配置文件通常位于~/.codex/config.toml。superpowers安装脚本会往里面追加类似下面的内容[superpowers] # 这里是 codex 的自定义配置区域不过在新版本 codex 里我更推荐用一个明确指向 Skill 路径的配置方式。具体来说codex 支持在config.toml里声明额外的 skills 路径这样你可以把superpowers放在任何你喜欢的位置# 示例配置路径按你实际克隆位置调整 [project] skills_dir ~/.codex/skills:/path/to/superpowers/skills每次改完配置文件都需要重启 codex 进程才生效。如果你发现 Skill 一直不生效优先怀疑配置路径写没写对其次是重启了没有。3.3 第一跑让 codex 进入“分层思考”模式配置好之后我第一次真正“跑起来”的测试任务是让 codex 写一个局域网内用的文件同步小工具。我当时是这样问的“用分层思考的模式帮我规划并实现一个简单的目录同步工具支持增量复制和冲突保留。”注意我说了“用分层思考的模式”这个触发词效果立竿见影。codex 没有直接甩代码而是先输出了一段“分析与计划”里面列出了目标、约束、目录结构建议和测试策略。确认这个计划后它才开始按 TDD 流程创建测试文件、实现代码、运行测试。对比之前没用superpowers时的回答最明显的差异是它开始“解释”为什么要这么做而不是直接“展示”它做了什么。这种变化在复杂任务里价值巨大。4. 实战拆解superpowers 驱动下的编码工作流安装只是开始真正有意思的是理解superpowers是如何改变和 AI 协作的节奏的。这一节我会拆解一个我实际完成的模块让读者看到它在真实任务里的工作方式。4.1 起始步骤kick off如何展开superpowers里的kick-off并非一个独立 Skill而是分层思考在任务开始时的启动动作。它会引导 AI 输出一段“任务简报”核心包含目标用户到底要什么用一两句话说清楚。约束有没有技术栈、性能、兼容性方面的限制验收标准完成到什么程度算“真正完成”最好是可执行、可验证的描述。风险点哪些地方容易出错哪些假设可能不成立我强烈建议你在每次任务的初始提示里主动要求 AI 先输出这份简报经你确认后再进入编码阶段。这一步能把“需求理解偏差”造成的返工降到最低。4.2 调试流程系统性排查 bug 而不是碰运气没有superpowers的时候遇到 bug 我通常会直接把报错信息粘贴给 codex让它“看看怎么回事”。它有时能蒙对有时会东改改西改改把问题搞得更糟。superpowers的调试方法论改变了这个局面。它引导 AI 按以下步骤走复现问题写一个最小化的复现脚本确保 bug 不是偶发。二分定位在可能出错的模块间做二分搜索缩小范围。检查假设列出“我以为是对的但可能是错的”假设逐一验证。修复并补测试修复后补一条回归测试防止未来再次出现。一次典型的对话流是这样的我先让 codex“用系统化调试的方法定位这个 bug”它会先问我要复现步骤在得到信息后画出排查思路然后一步步二分定位。整个过程更像一个 debugger 在操作而不是一个凭借记忆猜答案的答题机。4.3 测试驱动开发的真实落地一个最小示例为了让你直观感受 TDD 流程我摘录一个我实际做过的示例。需求是写一个函数parse_duration(s)把30s、1h30m这样的字符串解析成秒数。在superpowers的 TDD Skill 驱动下codex 执行了下面的流程第一步红先创建测试文件覆盖正常输入、空输入、非法输入和边界值。import pytest from duration import parse_duration def test_parse_seconds(): assert parse_duration(30s) 30 def test_parse_minutes_and_seconds(): assert parse_duration(1m30s) 90 def test_parse_hours_minutes_seconds(): assert parse_duration(1h1m1s) 3661 def test_invalid_input_raises(): with pytest.raises(ValueError): parse_duration(abc)第二步运行测试确认全部失败红。pytest test_duration.py # 预期输出4 failed第三步绿实现最小代码让测试通过。import re def parse_duration(s: str) - int: pattern r^(?:(\d)h)?(?:(\d)m)?(?:(\d)s)?$ match re.fullmatch(pattern, s.strip()) if not match or not any(match.groups()): raise ValueError(fInvalid duration: {s!r}) h, m, sec (int(g) if g else 0 for g in match.groups()) return h * 3600 m * 60 sec第四步重构运行全量测试确认通过后再审视代码结构。整个过程非常顺滑而且关键是codex没有自作主张加一些我没要求的边界行为——因为测试用例里没有覆盖的部分它不会硬做。这个例子比较小但流程是一样的。你在复杂模块里同样会经历“先测试、再实现、再重构”的循环区别只是测试数量和拆解的粒度。5. trae work cn 等外部环境安装 superpowers skill 的特别注意事项很多人在 codex CLI 里用顺了之后会想在 trae work cn 里也让 AI 具备superpowers的能力。我自己也折腾过一阵这里分享一下在外部编辑器/工作台环境下使用superpowers的注意事项。5.1 在 trae 工作区中下载 skill 的常见路径问题trae、Trae 这类 AI IDE 的工作区结构和裸终端项目不同它们往往有自己独立的管理目录。superpowers安装脚本默认把文件放到~/.codex/skills但 trae-work-cn 不一定读这个目录。我的做法是手动把superpowers/skills整个目录复制到 trae 项目根目录的.trae/skills/或类似的自定义目录然后在 trae 的规则配置里加一条“永远参考SKILL.md中的方法执行任务”。如果你的 trae 版本找不到自定义技能目录选项可以问一下它的官方文档不同版本差异比较大。5.2 模型能力与工具兼容性的坑superpowers能否发挥效果依赖底层模型的指令遵循能力和长上下文理解能力。在 codex CLI 里它表现好是因为 codex 默认配置的模型本来就是代码能力较强的那一档而 trae work cn 里可能有多套模型可选如果你选了上下文较短或指令遵循较弱的模型superpowers的分层思考很容易执行走形——AI 会在规划阶段就开始写代码或者完全忽略测试步骤。建议在 trae 里使用时要确认模型上下文窗口至少 128Ksuperpowers的完整流程会把计划、测试、实现、日志全部装入上下文。工具调用能力正常能创建文件、运行终端命令。系统提示词没有被自定义设置破坏这是经常被忽略的一个点。5.3 多环境共用一套 skills 的同步策略我在 codex CLI 和 trae 两套环境里都用superpowers如果分别维护两份复制副本很容易因为更新不同步产生行为差异。我的做法是把superpowers仓库作为 git submodule 放在一个统一目录然后让两个环境都通过符号链接指向它。# 在 ~/tools/superpowers 下载仓库后为 trae 创建符号链接 ln -s ~/tools/superpowers/skills /path/to/project/.trae/skills/superpowers这样只要拉取一次上游更新两套环境都同步。缺点是符号链接在某些 Windows 工具上可能不被识别这一点 Windows 用户需要特别留意。6. 常见报错与排查记录这一节记录我在使用superpowers过程中遇到过的几个典型问题按排查链路写出来供你参考。6.1 “找不到 superpowers 相关命令”有段时间我在 codex 里输入superpowers相关指令它完全无动于衷。排查过程先确认文件落点检查skills目录下是否有SKILL.md命令是find ~/.codex/skills -name SKILL.md。确认配置引用打开config.toml看skills_dir路径是否覆盖了superpowers所在目录。确认重启改了配置后是否重启了 codex。最终发现是我没有重启 codex低级的疏忽。6.2 Skill 文件未生效的原因另一个坑是 Skill 文件放对了但 AI 完全不遵守里面的指令。这种情况多半是模型和 Skill 之间的触发关系没建立好。SKILL.md本质上是一种“上下文指令”它有两种被激活的方式显式被模型调用或通过关键词被检索到。如果你在对话开始时不说“按 TDD 流程执行”也不说“使用分层思考”有些模型并不会自动穷举所有可用 Skill而是凭直觉回复。解决方法是在AGENTS.md里写明“默认使用 superpowers 提供的工作流”。或在初始提示里就带一句“请严格遵循 superpowers 的 SKILL.md 工作流程”。6.3 上下文窗口不够时的处理superpowers会把任务拆得很细这带来的副产物是上下文消耗大。一个复杂功能跑到一半经常就接近上下文上限了模型开始“忘事”。我的处理方法是把一个大任务拆成多个子任务每个子任务单独开启一轮对话。在AGENTS.md里维护一份“项目状态备忘录”记录已完成事项、待办事项、关键决策。让 AI 每完成一个阶段就把当前状态追加进备忘录这样即使上下文被截断新会话也能从备忘录恢复上下文。这个技巧本质上是用“外部记忆”弥补上下文窗口的物理限制配合superpowers的分层思考流程效果很好。个人使用体会如果用一句话总结superpowers的价值我觉得是它把“让 AI 干活”变成了“让 AI 像工程师一样干活”。安装它并不复杂难的是理解并接受它那套略显啰嗦的工作流程——先规划、再测试、后实现。但这套流程恰恰是很多资深开发者在真实项目中一直在做、只是没有显式总结出来的方法论。我在配合superpowers使用 codex 的过程中还发现一个小技巧每次会话结束后让 AI 输出一份简短的“会话总结”追加到AGENTS.md把你做过的决策、踩过的坑、遗留的问题都记录下来。下一轮会话开始时AI 能通过这份记录快速恢复上下文效果比手动粘贴历史聊天记录好得多。这套组合拳打下来AI 已经从“聪明的实习生”变成了“靠谱的结对程序员”值得你花一个下午认真试试。