1. 从superpowers这个词说起它到底指什么第一次看到superpowers这个标题加上agentic skills frameworksoftware development methodology这几个关键词我脑子里第一反应是这不是某个具体工具的名字而是一套给AI编程助手加装能力的方法论框架。换句话说它讨论的不是用哪个模型而是怎么把模型组织成一支能干活的小队。我接触这套思路的起点很朴素。早些年用命令行AI助手写代码最大的痛点不是模型不够聪明而是它记不住上下文、不会主动拆任务、干到一半就忘了自己要干嘛。你让它改一个函数它改完就停了不会顺手把调用它的地方一起更新你让它加个功能它写完主体逻辑测试和边界条件全靠你自己补。这种一问一答的模式本质上还是把AI当成一个高级补全工具而不是一个能独立推进任务的代理agent。superpowers这类框架想解决的正是这个断层。它的核心主张是把软件开发拆成一组可复用的技能skills每个技能封装一类具体能力——比如读代码库并画出依赖关系按TDD流程写一个模块排查一个失败的测试生成一份变更说明。然后让一个调度层通常就是Claude Code、Codex CLI这类命令行代理根据当前任务自动挑选并串联这些技能形成一条完整的执行链。这套东西适合谁我的判断是三类人最受益一是独立开发者一个人要顶一个团队最缺的就是有人帮你把流程串起来二是小团队的技术负责人需要把团队的编码规范、评审习惯固化进AI的工作流里三是刚上手命令行AI工具的新手与其自己摸索怎么提问不如直接套用一套已经被验证过的技能组合。需要提前说清楚的是superpowers本身不是一个能下载安装的软件包它更像一套约定和目录结构。你会在社区里看到大量围绕它的讨论比如想要安装superpowerssuperpowers怎么用但真正落地的动作其实是在你的项目里建一套skills目录写清楚每个技能干什么、什么时候触发、输出什么格式。理解了这一点后面所有的操作才不会跑偏。2. 技能框架的底层逻辑为什么技能比提示词更靠谱2.1 提示词的天花板在哪里大部分人用AI写代码习惯是现编提示词。今天要写个登录接口就临时敲一段帮我写一个基于JWT的登录接口用Express要校验参数。明天要改个bug又临时敲一段这个函数报错了帮我看看。这种方式在单次、孤立的任务上没问题但一旦任务变复杂问题就暴露了不可复用同样的写接口需求你每次都要重新描述一遍技术栈、规范、错误处理要求费时且容易漏。不可组合一个完整功能往往包含设计数据结构→写实现→写测试→跑测试→修bug多个环节临时提示词很难让AI自动走完这一整条链。不可审计你没法回看上次这个任务AI是怎么一步步做的出了问题只能重来。我踩过最典型的一个坑让AI改一个涉及五六个文件的配置项它只改了主文件漏掉了两个引用它的地方结果编译直接挂掉。当时我就想如果有一个改配置的技能明确规定必须先用搜索找出所有引用点再逐个修改最后跑一次构建验证这种低级错误根本不会发生。2.2 技能框架把经验变成了资产superpowers这类框架的关键设计是把上面那些我踩过坑才知道要做的事固化成一个个带触发条件和执行步骤的技能文件。一个技能通常包含几块内容组成要素作用举例技能名称与描述让调度层知道这个技能是干嘛的refactor-safe安全重构触发条件什么情况下该用这个技能当任务涉及修改被多处引用的代码时执行步骤具体怎么做分几步1.搜索引用 2.评估影响 3.逐个修改 4.构建验证输出约定完成后交付什么变更清单验证结果注意事项容易出错的地方注意动态引用静态搜索可能漏这么一封装好处立刻显现。第一经验可沉淀团队里谁踩过的坑写成技能后所有人都受益。第二行为可预测AI不再是随机发挥而是按既定流程走输出质量稳定得多。第三可组合一个复杂任务可以拆成技能A→技能B→技能C的流水线调度层负责串联。打个生活化的比方临时提示词像是你每次做饭都凭感觉放调料做得好是运气技能框架像是你把奶奶的菜谱一道道写下来盐几克、火候几分钟都标清楚谁照着做都不会难吃。2.3 调度层与技能层为什么要分开这里有个容易被忽略的设计点技能框架本身不负责执行执行交给命令行代理。Claude Code、Codex CLI这些工具扮演的是调度层角色它们负责理解你的意图、读取技能目录、决定调用哪个技能、把技能的输出接续到下一步。为什么要这么分因为技能是领域知识调度是通用能力。领域知识应该稳定、可版本管理、可跨工具复用而调度能力会随着工具迭代不断变强。分开之后你写的技能不会因为换了工具就作废工具升级了你的技能照样能用。这也是为什么社区里既有claude code使用的讨论也有codex cli命令的讨论——大家在用不同调度层跑同一套技能思路。3. 把框架跑起来环境准备与技能目录搭建3.1 调度层的选择与安装要点要跑superpowers这套思路第一步是选一个命令行代理作为调度层。目前社区里讨论最多的是Claude Code和Codex CLI两个方向。我不在这里比较谁更好只讲安装时最容易卡住的几个点这些是我和身边人反复遇到的。Node环境是前提。这两个工具大多通过npm分发所以你得先有Node。很多人反馈node安装codex cli很慢本质是npm默认源在国外网络抖动导致。我的做法是配置国内镜像源命令很简单npm config set registry https://registry.npmmirror.com配完之后再装速度通常能从卡半天变成几分钟搞定。如果还是慢可以试试用pnpm或yarn替代npm它们对依赖的并发处理更好。版本兼容性要留意。社区里出现过由于与64位版本的windows不兼容这类报错多半是Node版本太老或者装成了32位。建议统一用Node 18以上的LTS版本Windows用户优先用官方安装包而不是某些第三方打包版。安装完成后先验证。别急着写技能先跑一下基础命令确认工具活着claude --version codex --version能打印出版本号说明调度层就绪。如果提示command not found八成是全局安装路径没进PATH检查一下npm的全局bin目录有没有加到环境变量里。3.2 技能目录应该长什么样调度层装好之后核心工作就是建技能目录。虽然不同工具的目录约定略有差异但结构大同小异。我推荐的组织方式是这样skills/ ├── code-reading/ │ └── SKILL.md ├── tdd-workflow/ │ └── SKILL.md ├── safe-refactor/ │ └── SKILL.md ├── test-debugging/ │ └── SKILL.md └── changelog-gen/ └── SKILL.md每个技能一个文件夹里面放一个描述文件通常叫SKILL.md或类似名字。为什么一个技能一个文件夹而不是全塞一个文件因为技能会越来越多分开之后增删改都清晰也方便用git单独追踪每个技能的演进历史。这跟微服务拆分的思路是一样的——边界清晰才好维护。3.3 一个技能文件该怎么写技能文件是整个框架的灵魂写得好不好直接决定AI干活靠不靠谱。我总结了一个四段式写法实测下来最稳第一段一句话说清这个技能干什么。比如当需要理解一个陌生代码库的结构时用这个技能生成模块依赖图和入口说明。这句话是给调度层看的它靠这句话判断该不该调用。第二段写触发条件。明确什么时候用和什么时候不用。比如当任务涉及跨多个文件的修改时使用单文件小改动不需要。边界写清楚能避免AI滥用技能。第三段写执行步骤。这是最核心的部分要具体到可操作。别写分析代码要写1.用grep搜索目标符号的所有出现位置 2.区分定义点和引用点 3.对每个引用点评估修改影响 4.按依赖顺序从底层往上改。第四段写输出格式和注意事项。规定AI交付什么比如输出一份变更清单每项包含文件路径、改动摘要、验证方式。注意事项则把你踩过的坑写进去比如注意同名符号可能来自不同模块搜索时要带上文件路径限定。提示技能文件不要写得太长。一个技能控制在能一屏读完最好太长了AI反而抓不住重点。复杂流程拆成多个技能用调度层串联比写一个巨型技能更有效。4. 几个高频技能的设计思路与实操细节4.1 代码阅读技能让AI先看懂再动手新手最容易犯的错是让AI在没看懂代码库的情况下直接改。结果就是改一处崩三处。代码阅读技能的作用是强制AI在动手前先建立全局认知。我在这个技能里规定的步骤是先找入口文件比如main、index、app这类再顺着import关系往下追画出模块依赖。然后识别出核心模块和边缘模块——核心模块改动风险高边缘模块相对安全。最后输出一份简短的代码地图包括每个模块的职责和它们之间的调用关系。实操中我发现一个细节特别重要让AI明确标注不确定的地方。代码库里总有动态加载、反射调用这类静态分析看不透的东西。与其让AI假装看懂了不如让它标出来这里可能有隐藏依赖需要人工确认。这个习惯帮我避免了好几次以为改干净了其实没有的事故。4.2 TDD工作流技能先写测试再写实现测试驱动开发TDD这套方法人来做都容易偷懒让AI来做反而有优势——因为AI不会嫌先写测试麻烦。TDD技能的核心是把红-绿-重构这个循环固化下来。具体步骤我这样设计第一步根据需求写一个会失败的测试红第二步写最少的代码让测试通过绿第三步在测试保护下重构代码重构。每一步都要求AI先说明我现在处于哪个阶段避免它跳步。这里有个反直觉的经验别让AI一次写太多测试。我试过让它为一个模块一次性写二十个测试结果它写的测试之间互相耦合改一个全挂。后来改成一次一个测试通过后再写下一个稳定性大幅提升。这跟人写测试的节奏其实是一样的——小步快跑。4.3 安全重构技能改代码前先摸清影响面前面提到的改配置漏引用那个坑就是靠这个技能补上的。安全重构技能的第一条铁律改任何被引用的东西之前先搜索所有引用点。我规定的流程是用搜索工具找出目标符号的所有出现位置逐个判断是定义还是引用对每个引用点评估改了之后会不会坏然后按从底层到上层的顺序修改也就是先改被依赖的再改依赖别人的最后跑一次构建或测试验证。注意静态搜索有盲区。字符串拼接出来的函数名、配置文件里的动态引用搜索工具是找不到的。所以技能里我特意加了一条改完后人工review一遍动态引用相关的代码这条看似多余实际救过我好几次。4.4 测试排错技能从报错信息倒推根因测试挂了怎么办新手习惯是把报错信息整个丢给AI说帮我修。但这样AI容易头痛医头改完这个测试别的又挂了。排错技能要教AI的是系统性定位而不是打补丁。我的设计是先让AI完整读一遍报错栈定位到具体文件和行号然后判断这是测试本身写错了还是被测代码有bug如果是代码bug再往上追一层看是不是某个上游改动引起的最后给出修复方案并说明这个修复会不会影响其他测试。这套流程的价值在于它逼着AI去理解因果关系而不是碰运气。我实测下来用这个技能修bug一次修对的概率比直接丢报错高不少返工率明显下降。5. 调度层怎么把技能串起来命令与工作流5.1 常用命令的实际用途调度层提供了一批命令用来控制对话和上下文。社区里常问codex cli命令哪些我挑几个真正高频的说说它们在技能框架里怎么用。/compact这个命令作用是压缩当前对话的上下文。为什么重要因为技能执行链往往很长上下文会越堆越多到后面AI就开始忘事。在跑完一个技能、准备进入下一个技能之前用/compact把前面的过程压缩成摘要能显著降低失忆概率。/model用来切换模型。这个在技能框架里有个巧妙用法不同技能可以用不同模型。比如代码阅读这种需要长上下文的用上下文窗口大的模型写测试这种需要精确性的用推理能力强的模型。切换成本很低但效果差异明显。/resume用来恢复之前的会话。这个在任务做一半被打断时特别有用。我经常上午跑一半的技能链下午用/resume接着跑不用从头再来。5.2 一条完整工作流的串联示例光说单个技能不够直观我拿一个真实场景串一遍给一个已有项目加一个新功能。第一步调用代码阅读技能让AI先摸清项目结构和相关模块。第二步调用TDD工作流技能先写测试再写实现。第三步如果测试挂了调用测试排错技能定位问题。第四步功能跑通后调用安全重构技能清理临时代码。第五步调用变更说明生成技能输出一份给人看的改动清单。整条链跑下来AI不是一问一答而是像一个有经验的工程师一样按流程推进任务。这才是superpowers这类框架真正的价值所在——它把怎么做事这件事从人的脑子里搬到了可复用的技能文件里。5.3 技能之间的衔接要注意什么串联技能时最容易出问题的是上下文传递。技能A的输出要能顺畅地变成技能B的输入。我的经验是每个技能的输出格式要统一最好都用结构化清单的形式包含做了什么、涉及哪些文件、有什么待确认项。另外别把技能链设计得太长。超过五六个技能的链条中间任何一环出错都会导致后面全乱。我一般把复杂任务拆成几个小链条每个链条跑完人工确认一下再跑下一个。这样虽然多几次交互但整体可控性强得多。6. 踩过的坑与排查思路6.1 技能不触发先查描述再查触发条件最常见的坑是我写了技能但AI根本不用。排查顺序是这样先看技能描述是不是太模糊。如果描述写的是帮助处理代码AI根本不知道啥时候该用改成当需要跨文件修改时使用触发率立刻上来。再看触发条件是不是太窄比如限定死了仅当用户明确说重构时那AI自然不会主动用。6.2 技能执行到一半跑偏多半是步骤不够具体另一个高频问题是AI用着用着就不按技能走了。这通常是因为执行步骤写得太抽象。比如写分析影响AI可能分析两下就跳过了改成列出所有引用点逐个标注风险等级它就没法偷懒。步骤越具体AI越难跑偏。6.3 上下文丢失善用压缩和分段长任务跑到后面AI忘事是命令行代理的通病。除了用/compact压缩我的另一个技巧是把关键信息写进文件。比如让AI把当前进度和待办事项写到一个PROGRESS.md里下一轮开始时先读这个文件。这样即使上下文被压缩了关键状态还在。6.4 模型切换后行为不一致技能要写模型无关不同模型对同一段技能描述的理解可能不一样。我踩过的坑是某个技能在A模型上跑得好好的换到B模型就乱套。后来我调整了写法尽量用做什么而不是怎么想来描述步骤减少对特定模型推理风格的依赖。这样换模型时行为一致性好了很多。7. 关于这套框架我个人的几点体会用了一段时间superpowers这套思路我最大的感受是它改变的不是AI的能力上限而是AI的稳定性下限。模型本身聪明不聪明那是模型厂商的事但AI能不能稳定地、可预测地帮你把活干完这是技能框架能决定的。我特别想强调一点别指望一次就把技能写完美。我的技能文件都是改了好几版才稳定的每次踩坑就往里加一条注意事项。这跟写代码是一样的——先跑起来再迭代。那些看起来设计得很优雅的技能往往是踩了无数坑之后才长成那样的。还有个容易被忽略的价值技能文件本身就是最好的团队文档。新人入职与其让他读一堆零散的wiki不如让他读技能目录——每个技能都写清楚了这类任务该怎么做比任何培训材料都直接。最后分享一个小技巧定期回顾你的技能目录把不再用的删掉。技能多了之后调度层选择成本会上升一些过时的技能反而会干扰判断。我一般每个月清理一次保持目录精简。这跟维护代码库是一个道理——删代码和写代码同样重要。