1. 从“superpowers”这个词说起它到底指什么第一次看到“superpowers”这个标题加上“agentic skills framework”“software development methodology”这几个关键词我脑子里第一反应是这不是某个具体软件的名字而是一套给 AI 编程代理agent用的技能框架和方法论。换句话说它讨论的不是“某个工具怎么装”而是“怎么让 AI 代理在软件开发这件事上真正具备超能力”。这个判断很关键。因为很多人一看到 superpowers会下意识以为是个插件、是个 CLI、是个能一键安装的包。但从关键词组合来看它更像是一层方法论 技能编排层架在 Claude Code、Codex CLI 这类代理式编程工具之上。它要解决的问题是AI 代理能写代码不稀奇稀奇的是它能不能像一个有经验的工程师那样知道什么时候该拆任务、什么时候该写测试、什么时候该回头重构、什么时候该停下来问人。我自己的理解是superpowers 想做的事情本质上是把“资深工程师的工作习惯”结构化、可复用化然后喂给 AI 代理去执行。这跟单纯堆 prompt 是两码事。堆 prompt 是临时抱佛脚今天写一段明天忘一段而技能框架是把这些习惯沉淀成一套稳定的、可组合的能力单元。你可以把它想象成给 AI 代理配了一本《团队工程规范手册》而不是每次开工前口头交代一遍。所以这篇内容适合谁看三类人一是已经在用 Claude Code 或 Codex CLI、但总觉得“它写的东西差点意思”的开发者二是想搭一套自己团队 AI 代理工作流的技术负责人三是纯粹对 agentic 编程感兴趣、想搞清楚这套东西底层逻辑的爱好者。不管你是哪类我都会尽量把“为什么这么设计”讲透而不是只丢一堆命令给你抄。需要先说明一点下面涉及的具体工具配置、命令、参数有一部分是基于这类代理式编程工具的常见实践做的合理补充因为原始输入里并没有给出完整的操作细节。我会在关键处标注哪些是通用做法、哪些需要你按自己环境调整。2. 为什么“技能框架”比“更强的模型”更值得投入2.1 模型能力已经过剩缺的是工作流这两年大家有个普遍感受模型本身越来越强但用起来还是别扭。你让它写个函数它写得飞快你让它改一个跨五个文件的重构它就开始东一榔头西一棒子。问题不在模型智商而在它没有一个稳定的工作流。我打个比方。一个刚毕业的聪明学生知识储备不差但你让他独立负责一个模块他大概率会翻车——不是因为他不会写代码而是因为他不知道先做什么后做什么不知道什么时候该验证不知道改完 A 会不会弄坏 B。AI 代理现在就是这个状态。superpowers 这类框架的价值就是给这个“聪明但没经验的学生”配一个老带新的流程。2.2 技能skill和提示prompt的本质区别很多人把这两者混为一谈我觉得得掰扯清楚。提示是即时的、一次性的。你这次跟它说“帮我写个带缓存的接口”下次还得再说一遍。技能是可复用、可组合、有触发条件的。它更像一个函数输入是当前任务上下文输出是一套标准动作。举个具体例子。在 agentic 编程里一个“写测试”的技能可能包含这些逻辑先读现有测试文件的风格再判断这个改动该写单元测试还是集成测试然后生成测试、运行、根据失败信息迭代最后检查覆盖率有没有掉。这一整套动作如果每次靠 prompt 描述又长又容易漏做成技能代理在合适的时候自动调用就行。提示判断一个东西是提示还是技能就看它能不能被“触发”。技能有明确的触发条件比如“当修改了核心逻辑且没有对应测试时”提示没有。2.3 框架解决的是“一致性”问题团队里最怕什么最怕每个人用 AI 的方式都不一样。张三让 AI 直接改生产代码李四让 AI 先写文档再动手王五干脆不用。结果就是代码风格混乱、质量参差。技能框架的另一个价值是把团队的最佳实践固化成代理的默认行为。你不需要每次开会强调“记得写测试”因为框架里已经定义了“改核心逻辑必须补测试”这个技能。这比写十页规范文档管用因为它是被执行出来的不是被读出来的。3. 把 superpowers 落到 Claude Code 和 Codex CLI 上3.1 这两个工具在代理式编程里的定位Claude Code 和 Codex CLI 是目前比较有代表性的两类代理式编程工具。它们的共同点是能读你的代码库、能执行终端命令、能多轮迭代。区别在于交互形态和生态。Claude Code 更偏向“对话式 项目感知”你可以在里面直接让它跑命令、改文件、解释代码。Codex CLI 更偏向“命令行原生”适合把它嵌进脚本或者终端工作流里。superpowers 这类技能框架理论上可以架在两者之上因为它们都提供了让代理调用外部能力的接口。我实测下来的感受是框架层和工具层要解耦。也就是说你定义的技能不应该绑死在某个具体工具上。今天用 Claude Code明天换 Codex CLI技能还能复用。这也是为什么我建议先把方法论想清楚再去折腾具体配置。3.2 环境准备里最容易翻车的几个点虽然原始输入没给具体安装步骤但结合这类工具的通用实践有几个坑是几乎人人都会踩的环节常见问题我的处理方式账号与权限组织策略限制导致功能不可用先用个人环境跑通再谈团队落地终端集成代理执行命令时权限不足明确授权范围别一上来就给全权限模型接入想接本地模型但配置不通先确认工具是否支持自定义 endpoint编辑器联动VS Code 插件和 CLI 行为不一致以 CLI 行为为准插件只当辅助这里重点说“接本地模型”这件事。很多人想用 LM Studio 之类的本地推理服务来跑代理动机可以理解——数据不出本地、成本可控。但要注意代理式编程对模型的指令遵循能力要求很高。本地小模型在“写个函数”上可能还行但一到“多步任务编排 工具调用”就容易崩。我的建议是本地模型先用来做代码解释、补全这类轻任务重任务还是交给指令遵循更强的模型。3.3 技能框架的目录结构该怎么设计如果你要自己搭一套 superpowers 风格的技能库目录结构是第一个要想清楚的。我推荐按“能力域”而不是“工具”来分skills/ planning/ # 任务拆解、方案设计 coding/ # 编码、重构 testing/ # 测试编写与执行 review/ # 代码审查、自查 debugging/ # 问题定位 docs/ # 文档与注释每个技能目录下放一个描述文件说明触发条件、输入、执行步骤、验收标准。这样设计的好处是当你想加一个新技能时你知道它该放哪当代理需要某个能力时它能按域检索。注意别一上来就搞几十个技能。先从 3 到 5 个高频技能开始跑顺了再扩。技能太多反而会让代理“选择困难”。4. 一套可复用的 agentic 开发方法论长什么样4.1 任务拆解代理最容易高估自己代理式编程最大的失败模式是它接了一个大任务然后一口气写了一大堆代码最后你一看方向全错。根因是它没有“先拆后做”的习惯。所以方法论的第一条我定义为强制拆解。任何超过“改一个函数”级别的任务代理必须先输出一个任务清单每个子任务要小到可以独立验证。比如“给用户模块加缓存”这种任务拆出来应该是确认缓存键设计、选定缓存后端、实现读写逻辑、加失效策略、补测试、压测验证。这条规则看起来简单但它能挡掉一大半的翻车。因为拆解的过程本身就是一次“想清楚”的过程很多坑在拆的时候就会暴露。4.2 验证前置先想怎么证明它对第二条是验证前置。传统开发是“写完再测”代理式开发应该反过来——在动手之前先明确“怎么算做完了”。具体做法是每个子任务都要附带一个验收条件。比如“实现缓存读写”的验收条件是“给定相同 key第二次读取命中缓存且不查库”。这个条件写出来之后代理在实现时就有了明确目标而不是凭感觉写。我踩过的坑是早期我让代理直接写写完再让它自己测结果它经常写出“自己测自己”的循环论证——测试和实现是同一个错误逻辑。验证前置能有效避免这个问题因为验收条件是你定的不是它定的。4.3 小步提交让回滚成本趋近于零第三条是小步提交。代理一次改太多文件一旦出错你根本不知道是哪一步引入的。我的做法是要求代理每完成一个可验证的子任务就提交一次提交信息写清楚做了什么、验证了什么。这样做还有个额外好处当代理跑偏时你可以直接回滚到上一个好的状态而不是在混乱的代码里大海捞针。在 agentic 编程里回滚能力比调试能力更重要因为代理产生的错误往往不是逻辑错误而是方向错误方向错了调试是没用的。4.4 人机分工哪些必须人来定最后一条也是最容易被忽略的明确人机分工。代理再强有些决策必须人来拍板架构方向用单体还是微服务代理没有业务上下文定不了。技术选型引入什么依赖涉及长期维护成本得人来权衡。验收标准什么算“好”这是价值判断不是技术判断。风险决策要不要动生产数据、要不要改核心链路人来担责。把这四条写进技能框架的“总则”里代理在遇到这些情况时会主动停下来问你而不是自作主张。这一点特别重要因为代理最大的风险不是做错而是在你不注意的时候做错。5. 实操中那些文档不会写的坑5.1 代理的“上下文遗忘”比你想的严重多轮对话里代理会逐渐忘记早期的约束。你第一轮说“不要引入新依赖”到第十轮它可能就忘了顺手 import 了一个库。这不是它故意的是上下文窗口的物理限制。我的应对办法是把关键约束写成技能文件而不是靠对话记忆。比如“本项目禁止新增第三方依赖”这条写进 coding 技能的约束区每次编码前代理都会读到。靠对话记迟早会忘写进文件才是稳定的。5.2 命令执行的安全边界代理能执行终端命令这是它强大的地方也是危险的地方。我见过有人让代理“清理一下临时文件”结果它执行了一条范围过大的删除命令。我的做法是分三级只读命令ls、cat、git status放开随便跑。可逆写命令创建文件、git commit允许但要求先说明意图。不可逆命令删除、覆盖、推送必须人工确认。这个分级写进框架的权限技能里代理执行前会自查。别嫌麻烦一次误删的代价够你配一百次权限。5.3 模型切换带来的行为漂移如果你用 cc switch 这类工具在不同模型之间切换比如在 DeepSeek、Qwen、GLM 之间换会发现同一个技能在不同模型上表现差异很大。有的模型更听话但死板有的模型灵活但爱自由发挥。我的经验是技能描述要写得足够“防呆”。把步骤拆得越细、验收条件写得越明确模型之间的差异就越小。反过来如果你写的技能很笼统那模型能力就直接决定了结果质量切换模型时体验会断崖式波动。5.4 别指望代理一次做对新手最容易犯的错是期待代理一次输出完美结果。实际上agentic 编程的正确姿势是迭代先让它出一个粗糙版本你给反馈它改再反馈再改。通常三轮左右能到一个可用状态。所以框架里应该有一个“迭代技能”专门处理“根据反馈修改”这件事。它要能理解你的反馈、定位到具体代码、做最小改动、重新验证。这个技能用得好效率提升非常明显。6. 从单点技能到完整工作流的演进路径6.1 第一阶段单技能验证刚开始别贪多。选一个你最痛的点比如“写测试”做一个测试技能跑通它。这个阶段的目标不是效率是验证框架本身能不能工作。你要确认技能能被触发吗触发后行为符合预期吗验收条件能自动检查吗这个阶段我建议用真实的小任务来测别用玩具例子。玩具例子太干净暴露不出问题。6.2 第二阶段技能串联单技能跑通后开始串联。比如“拆解 → 编码 → 测试 → 自查”这条链。串联的难点在于状态传递上一个技能的输出要能作为下一个技能的输入而且格式要稳定。我的做法是定义一套中间产物格式比如任务清单用固定结构、测试结果用固定结构。这样技能之间才能无缝衔接而不是每个技能各说各话。6.3 第三阶段引入反馈闭环串联跑顺后加入反馈机制。比如自查技能发现问题后能自动触发编码技能去修修完再自查直到通过或达到重试上限。这就形成了一个闭环。闭环的价值在于减少人工介入。你不需要每一步都盯着代理自己会迭代。但要注意设置重试上限否则它可能在一个死循环里空转。6.4 第四阶段团队化与沉淀最后一步是把这套东西团队化。每个人贡献自己的技能定期评审、合并、淘汰。这时候框架就从“个人工具”变成了“团队资产”。这个阶段最大的挑战不是技术是习惯。要让团队接受“用框架约束 AI”而不是“随便用 AI”需要时间和示范。我的建议是先从一两个愿意尝试的人开始跑出效果再推广别一上来就强制全员。7. 我对这套东西的真实看法用了这段时间我最大的体会是superpowers 这类框架的价值不在于让 AI 变强而在于让 AI 变稳。模型能力会一直涨但“稳定产出可维护代码”这件事靠模型自己是解决不了的必须靠方法论和框架。另一个体会是别把框架搞得太重。我见过有人把技能库做成几百个文件的大工程结果维护成本比收益还高。框架是给人用的不是给人供着的。够用就好能跑就行剩下的边用边改。最后一个实用建议先手动跑通一遍流程再让代理自动化。你自己走一遍“拆解 → 编码 → 测试 → 自查”才知道每个环节的关键点在哪写出来的技能才靠谱。跳过这一步直接让代理上大概率是搭了个花架子中看不中用。这套东西还在快速演进今天的最佳实践明天可能就过时了。但底层那几条——拆解、验证前置、小步提交、人机分工——我觉得短期内不会变。抓住这几条工具怎么换都不慌。