1. 从“superpowers”说起这套方法论到底想解决什么问题第一次看到“superpowers”这个词是在一个开发者社群里有人贴了一张截图里面是一套围绕 Claude Code 和 Codex CLI 构建的 agentic skills framework。当时我的第一反应是又是一个包装概念的东西。但仔细看完它的结构之后我改变了看法——它其实在试图回答一个很实际的问题当 AI 编程助手从“补全代码”进化到“自主执行任务”之后我们该怎么组织这些能力才能让它们真正稳定地干活这个问题的背景是这样的Claude Code 和 Codex CLI 这类工具已经不只是聊天窗口了它们能读写文件、执行终端命令、调用外部 API、甚至自己规划多步操作。但大多数人用它们的方式还停留在“问一句答一句”的阶段没有形成一套可复用的工作流。superpowers 这套框架的核心主张就是把 AI 编程助手当成一个需要被“编排”的团队成员而不是一个更聪明的搜索引擎。它适合谁来参考我梳理了一下大概三类人最需要第一类是已经在用 Claude Code 或 Codex CLI但感觉效率没有质变的开发者第二类是团队里负责制定 AI 辅助开发规范的技术负责人第三类是对 agentic skills 这个概念感兴趣、想自己搭一套类似体系的人。不管你用的是哪个工具这套思路都有可迁移的地方。接下来我会从设计思路、核心细节、实操过程、常见问题几个维度把这套框架拆开讲清楚。不是照搬文档而是结合我自己在 Ubuntu 和 macOS 上配置 Claude Code、在 VS Code 里调试 Codex CLI 的实际经验把那些文档里不会写的坑和技巧一并交代。2. 整体设计思路为什么是“技能框架”而不是“提示词集合”2.1 从提示词工程到技能编排的范式转变大多数人接触 AI 编程助手的第一步是学怎么写提示词。但提示词工程有一个根本性的局限它是无状态的。你每次对话都要重新交代背景、重新设定角色、重新说明约束条件。对于一次性的小任务这没问题但对于一个需要持续几小时甚至几天的开发任务这种模式就崩溃了。superpowers 的设计出发点就是解决这个“状态丢失”的问题。它的做法是把常用的开发能力抽象成一个个“技能”skill每个技能包含触发条件、执行步骤、所需工具、输出格式、异常处理。这听起来很像传统软件工程里的“函数”或者“微服务”只不过执行者从代码变成了 AI agent。我举个例子你就明白了。假设你要让 AI 帮你重构一个模块。在纯提示词模式下你得写“你是一个资深 Python 开发者请帮我重构以下代码要求保持接口不变提升可读性添加类型注解……”然后 AI 给你一版你发现它改了接口你得重新强调。但在技能框架下“重构”这个技能本身就内置了“接口不变”的约束AI 在执行时会自动检查这个条件不需要你每次重复。注意技能框架不是要取代提示词而是把提示词里那些反复出现的约束和步骤固化下来。你仍然需要为每个技能写清晰的描述只是这个描述只需要写一次。2.2 为什么选择 Claude Code 和 Codex CLI 作为主要载体市面上能执行终端命令的 AI 工具不少但 superpowers 这类框架通常优先适配 Claude Code 和 Codex CLI原因有几个。第一是这两个工具都提供了相对完整的“工具调用”接口AI 不仅能生成文本还能实际执行 shell 命令、读写文件、调用外部程序。第二是它们都有“项目级上下文”的概念能读取项目里的配置文件这为技能的定义和加载提供了天然容器。第三点可能更重要这两个工具的设计哲学都偏向“可组合”。Claude Code 支持通过配置文件定义自定义命令Codex CLI 支持通过命令行参数切换模型和行为模式。这种可组合性让技能框架能够以插件的形式接入而不需要修改工具本身的源码。我在 Ubuntu 上配置 Claude Code 的时候特意观察了它的配置文件加载顺序。它会先读全局配置再读项目级配置最后读当前目录的配置。这个层级结构正好可以用来组织技能全局放通用技能项目级放项目特定技能当前目录放临时技能。这种设计不是巧合而是工具作者有意为之的扩展点。2.3 技能框架的四个核心抽象拆开来看superpowers 这类框架通常包含四个核心抽象理解这四个东西你就理解了整套体系。第一个是Skill技能。这是最基本的单元定义了一个具体的开发动作比如“写单元测试”“生成 API 文档”“执行数据库迁移”。每个技能有明确的输入和输出以及执行过程中需要遵循的约束。第二个是Workflow工作流。工作流把多个技能串联起来形成一个完整的开发流程。比如“新功能开发”工作流可能包含需求分析 → 接口设计 → 代码实现 → 测试编写 → 文档更新。工作流定义了技能之间的依赖关系和执行顺序。第三个是Context上下文。这是技能执行时的环境信息包括当前项目结构、代码风格、依赖版本、环境变量等。上下文的质量直接决定了技能执行的效果。第四个是Guardrail护栏。这是安全机制确保 AI 在执行技能时不会做出危险操作比如删除生产数据库、提交敏感信息、修改不该修改的文件。护栏通常以规则的形式定义在技能执行前和执行中进行检查。这四个抽象组合起来就形成了一套可复用、可组合、可审计的 AI 辅助开发体系。我个人的体会是刚开始只需要定义三五个核心技能就能感受到效率的明显提升。随着技能库的积累整个开发流程会越来越顺畅。3. 核心细节解析技能定义、加载与执行的完整链路3.1 技能定义文件的格式与关键字段技能定义通常是一个 Markdown 文件放在项目根目录的.skills/文件夹下或者放在全局配置目录里。文件名就是技能名比如write-unit-test.md。文件内容分为两部分YAML frontmatter 和正文。YAML frontmatter 定义技能的元信息关键字段包括name技能的唯一标识建议用 kebab-case比如write-unit-test。description一句话描述这个技能做什么会显示在技能列表里。triggers触发条件可以是关键词列表也可以是自然语言描述。当用户的请求匹配到这些条件时AI 会自动加载这个技能。tools这个技能需要使用的工具列表比如read_file、write_file、run_command。guardrails这个技能特有的护栏规则比如“不允许修改package.json”。正文部分则是技能的具体执行步骤用自然语言描述但结构要清晰。我通常会用有序列表来写步骤每一步都说明“做什么”和“为什么”。比如--- name: write-unit-test description: 为指定函数生成单元测试 triggers: - 写测试 - 生成单元测试 - unit test tools: - read_file - write_file - run_command guardrails: - 不允许修改被测函数的实现 - 测试文件必须放在 tests/ 目录下 --- 1. 读取目标函数的源码理解其输入、输出和边界条件。 2. 检查项目中是否已有测试框架优先使用已有的框架。 3. 根据函数的参数类型和返回值设计至少三个测试用例正常情况、边界情况、异常情况。 4. 生成测试代码确保测试文件命名符合项目规范。 5. 运行测试确认全部通过。如果失败分析原因并修正测试代码。这个格式的好处是AI 在加载技能后能清楚地知道自己的任务边界和约束条件不需要你每次重复交代。3.2 技能加载机制什么时候加载、加载哪些技能加载有两种模式自动加载和手动加载。自动加载依赖triggers字段当你的请求里包含触发词时AI 会自动把对应的技能加载到当前上下文。手动加载则是通过命令显式调用比如在 Claude Code 里输入/skill write-unit-test。自动加载的优点是省事缺点是可能加载了不需要的技能占用上下文窗口。我的经验是把最常用的三五个技能设为自动加载其他的用手动。另外triggers的关键词要选得精准一些不要用太泛的词。比如“测试”这个词太泛可能在你只是想讨论测试策略时也被触发。用“写测试”“生成测试”这种更具体的短语会好很多。还有一个细节技能加载是有优先级的。项目级技能会覆盖全局技能当前目录技能会覆盖项目级技能。这个机制可以用来做项目特定的定制。比如全局的write-unit-test技能用的是 pytest但某个项目用的是 unittest你可以在项目级目录里放一个同名技能覆盖全局的。提示如果你发现某个技能总是被意外触发检查一下它的triggers是不是太宽泛了。我踩过这个坑后来把触发词从“文档”改成“生成 API 文档”就解决了。3.3 上下文注入让 AI 知道“现在是什么情况”技能执行的效果很大程度上取决于上下文的质量。superpowers 框架通常会在技能执行前自动注入以下几类上下文项目结构当前目录的文件树让 AI 知道项目里有哪些文件、怎么组织的。代码风格从已有的代码文件里提取的命名规范、缩进风格、注释习惯等。依赖信息从package.json、requirements.txt、go.mod等文件里读取的依赖列表和版本。环境变量当前 shell 的环境变量但会过滤掉敏感信息。Git 状态当前分支、最近提交、未提交的修改。这些上下文不是一股脑全塞进去的而是根据技能的需要选择性注入。比如“写单元测试”技能需要项目结构和依赖信息但不需要 Git 状态。这种选择性注入既节省了上下文窗口也减少了干扰。我实测下来上下文注入的质量对技能执行效果影响极大。有一次我在一个没有requirements.txt的项目里执行“写单元测试”技能AI 因为不知道用了什么测试框架生成了一堆 pytest 代码但项目实际用的是 unittest。后来我在技能定义里加了一条“如果找不到依赖文件先询问用户使用什么测试框架”问题就解决了。3.4 护栏机制怎么防止 AI “好心办坏事”护栏是技能框架里最容易被忽视、但最重要的部分。AI 在执行任务时有时候会“过度热情”比如你让它修一个 bug它顺手把整个文件重写了你让它加一个日志它把日志级别改成了 DEBUG 并且提交了。护栏机制通过规则来约束 AI 的行为。规则可以分几个层级全局护栏适用于所有技能比如“不允许执行rm -rf”“不允许修改.env文件”“不允许直接 push 到 main 分支”。技能级护栏特定技能的约束比如“写单元测试”技能不允许修改被测函数的实现。运行时护栏在技能执行过程中动态检查比如“如果修改的文件超过 5 个暂停并请求确认”。护栏的实现方式通常是在技能执行前和执行中插入检查点。执行前检查是静态的看 AI 的计划里有没有违规操作。执行中检查是动态的每执行一步就检查一次。如果发现违规AI 会暂停并请求用户确认。我自己的做法是全局护栏尽量严格技能级护栏根据实际情况调整。比如在个人项目里我可以允许 AI 直接修改文件但在团队项目里我会要求所有修改都先展示 diff确认后再写入。4. 实操过程从零搭建一套可用的技能框架4.1 环境准备Claude Code 与 Codex CLI 的安装与配置在开始搭建技能框架之前你需要先确保 Claude Code 或 Codex CLI 能正常工作。我分别在 Ubuntu 和 macOS 上装过这两个工具流程大同小异但有几个坑值得提前说。Claude Code 的安装官方推荐的方式是通过 npm 全局安装。在 Ubuntu 上你需要先确保 Node.js 版本不低于 18。我建议用 nvm 来管理 Node 版本这样切换起来方便。安装命令是npm install -g anthropic-ai/claude-code安装完成后第一次运行claude会引导你完成登录和初始化配置。如果你在 VS Code 里使用还需要安装 Claude Code 的 VS Code 插件然后在设置里配置好路径。Codex CLI 的安装同样是通过 npmnpm install -g openai/codex这里有一个常见的坑在国内网络环境下npm 安装可能会很慢甚至超时。我的解决办法是配置 npm 的镜像源或者用pnpm代替npm速度会快很多。另外Codex CLI 对 Node 版本也有要求建议用 LTS 版本。安装完成后你可以通过codex --version和claude --version来验证是否安装成功。如果遇到权限问题在 Linux 上可能需要用sudo但我不建议全局用sudo装 npm 包更好的做法是配置 npm 的全局目录到用户目录下。注意如果你在 VS Code 里同时使用 Claude Code 和 Codex CLI建议给它们配置不同的快捷键避免冲突。我一开始没注意结果按快捷键总是唤起错误的工具。4.2 技能目录结构设计与初始化环境准备好之后下一步是设计技能目录的结构。我推荐的结构是这样的project-root/ ├── .skills/ │ ├── global/ │ │ ├── write-unit-test.md │ │ ├── generate-api-doc.md │ │ └── refactor-code.md │ ├── project/ │ │ ├── deploy-staging.md │ │ └── run-migration.md │ └── local/ │ └── debug-current-issue.md ├── .claude/ │ └── config.json └── .codex/ └── config.jsonglobal/放通用技能project/放项目特定技能local/放临时技能这个目录应该加到.gitignore里。.claude/和.codex/分别是两个工具的配置文件目录。初始化的时候我建议先从三个技能开始一个代码生成类比如“写单元测试”一个代码分析类比如“解释这段代码”一个流程类比如“提交前检查”。这三个技能覆盖了日常开发中最常见的场景能让你快速感受到技能框架的价值。4.3 编写第一个技能以“写单元测试”为例我们来完整走一遍编写技能的过程。假设你要为一个 Python 项目写一个“写单元测试”技能。第一步确定技能的边界。这个技能只负责生成测试代码不负责修改被测代码不负责运行测试运行测试是另一个技能。边界清晰了护栏就好写了。第二步写 YAML frontmatter。triggers我设了三个“写测试”“生成单元测试”“unit test”。tools需要read_file、write_file、run_command。guardrails设了两条不允许修改被测函数测试文件必须放在tests/目录下。第三步写执行步骤。我把它分成五步读源码、检查测试框架、设计用例、生成代码、运行验证。每一步都写清楚“做什么”和“为什么”。第四步测试技能。我找了一个简单的函数输入“写测试”看 AI 是否自动加载了这个技能执行结果是否符合预期。第一次测试时AI 把测试文件放在了项目根目录而不是tests/目录下。我检查了技能定义发现护栏里写了“测试文件必须放在 tests/ 目录下”但 AI 没有遵守。后来我在执行步骤里也加了一条“测试文件路径为 tests/test_函数名.py”问题就解决了。这个经历告诉我护栏和执行步骤要互相配合。护栏是“不允许做什么”执行步骤是“应该怎么做”。两者都写清楚AI 的执行才会稳定。4.4 技能组合与工作流编排单个技能用起来之后下一步是把它们组合成工作流。工作流的定义方式和技能类似也是 Markdown 文件但内容是指定技能的执行顺序和条件。比如一个“新功能开发”工作流--- name: new-feature description: 从需求到测试的完整开发流程 skills: - analyze-requirement - design-interface - implement-code - write-unit-test - update-doc --- 1. 执行 analyze-requirement 技能理解需求并输出需求摘要。 2. 执行 design-interface 技能设计接口并输出接口定义。 3. 执行 implement-code 技能根据接口定义实现代码。 4. 执行 write-unit-test 技能为新增代码生成测试。 5. 执行 update-doc 技能更新相关文档。 6. 所有步骤完成后输出变更摘要等待用户确认。工作流的价值在于它把多个技能的执行顺序和依赖关系固化下来你只需要说“开始新功能开发”AI 就会按顺序执行所有技能。这比手动一个个调用技能效率高得多。我实测下来工作流最适合那些步骤固定、重复性高的开发任务。比如“修 bug”工作流、“发布新版本”工作流、“代码审查”工作流。对于探索性的任务比如“调研某个技术方案”工作流反而会限制 AI 的灵活性这时候用单个技能或者纯对话更合适。5. 常见问题与排查技巧实录5.1 技能不触发或触发错误怎么办这是最常见的问题。症状是你输入了触发词但 AI 没有加载对应的技能或者加载了错误的技能。排查思路分三步。第一步检查triggers字段是否包含了你输入的关键词。注意大小写和单复数有些框架对大小写敏感。第二步检查技能文件的路径是否正确。技能必须放在框架能扫描到的目录下通常是.skills/及其子目录。第三步检查是否有同名技能覆盖。项目级技能会覆盖全局技能如果你在项目级目录里放了一个同名但内容不同的技能全局技能就不会生效。我遇到过一次比较隐蔽的情况技能文件里 YAML frontmatter 的格式有误导致整个文件被跳过。YAML 对缩进和冒号后面的空格很敏感建议用编辑器插件做语法检查。5.2 技能执行结果不符合预期的调试方法技能触发了但执行结果不对。比如“写单元测试”技能生成的测试代码跑不起来或者“重构代码”技能把接口改了。调试方法是从后往前查。先看输出结果哪里不对然后看执行步骤里哪一步可能导致这个结果最后看上下文注入是否充分。大多数情况下问题出在上下文不足或者执行步骤描述不够具体。我自己的经验是在技能定义里加一个“自检”步骤。比如“写单元测试”技能的最后一步是“运行测试确认全部通过”。如果测试失败AI 会分析原因并修正。这个自检步骤能拦截大部分低级错误。另外技能的描述要尽量具体避免模糊词汇。比如“生成高质量的代码”这种描述AI 不知道什么叫“高质量”。改成“生成符合 PEP 8 规范、包含类型注解、函数长度不超过 50 行的代码”AI 就知道该怎么做了。5.3 上下文窗口不足的优化策略技能框架用久了技能库会越来越大上下文窗口不够用是迟早的事。症状是 AI 开始“忘记”之前的指令或者执行到一半突然中断。优化策略有几个。第一把不常用的技能从自动加载改为手动加载。第二精简技能定义去掉冗余的描述和示例。第三把大段的上下文信息比如完整的项目结构改成摘要形式。第四使用框架提供的“上下文压缩”功能如果支持的话。我自己的做法是每个技能的定义控制在 500 字以内执行步骤不超过 7 步。超过这个规模就考虑拆分成多个技能。另外定期清理不再使用的技能保持技能库的精简。5.4 常见问题速查表问题现象可能原因排查方法解决方案技能不触发触发词不匹配检查triggers字段添加或修改触发词技能触发错误触发词太宽泛查看加载了哪个技能改用更具体的触发词执行结果不对上下文不足检查注入的上下文补充项目结构或依赖信息执行中断上下文窗口不足查看技能库大小精简技能或改为手动加载护栏未生效护栏规则不具体检查guardrails字段改用明确的禁止性描述技能覆盖异常同名技能冲突检查各层级目录重命名或删除冲突技能提示这张表建议放在项目 README 里团队新成员遇到问题时可以先自查减少沟通成本。5.5 几个我踩过的坑和对应的技巧第一个坑技能定义里的tools字段写得太少。我以为 AI 会自动使用所有可用工具但实际上框架只会加载tools里列出的工具。有一次“写单元测试”技能需要运行测试但我忘了在tools里加run_command结果 AI 生成完测试代码就停了没有运行验证。第二个坑护栏规则写得太模糊。我写过一条“不允许修改重要文件”结果 AI 不知道哪些文件算“重要”还是修改了config.py。后来改成“不允许修改config.py、settings.py、.env”问题就解决了。第三个坑技能之间的依赖关系没有显式声明。工作流里如果技能 B 依赖技能 A 的输出但你没有在技能 B 的定义里说明这一点AI 可能会在技能 A 还没完成时就执行技能 B。解决办法是在工作流定义里明确指定执行顺序并且在技能 B 的上下文注入里包含技能 A 的输出。第四个坑没有版本控制。技能定义也是代码应该纳入 Git 管理。我一开始把技能文件放在.gitignore里结果换电脑后所有技能都没了。后来把.skills/global/和.skills/project/纳入版本控制.skills/local/保持忽略这样就既能共享又能保留个人定制。6. 技能框架的扩展方向与个人实践体会6.1 从个人使用到团队协作的演进路径一个人用技能框架和团队用完全是两回事。个人使用时你可以随意修改技能定义不需要考虑兼容性。但团队使用时技能定义就变成了“接口”需要版本管理和变更评审。我的建议是分三步走。第一步个人先跑通一套技能积累经验。第二步把验证有效的技能提取出来放到团队共享仓库里加上版本号和变更日志。第三步建立技能评审机制任何技能定义的修改都需要至少一个人 review。团队协作还有一个特殊问题不同成员的开发环境可能不同。比如有人用 macOS有人用 Ubuntu有人用 Windows。技能定义里如果包含平台特定的命令就会出问题。解决办法是在技能定义里用条件判断或者把平台特定的部分抽成单独的技能。6.2 技能库的维护与迭代节奏技能库不是建好就完了需要持续维护。我的做法是每个月做一次技能库回顾检查哪些技能经常用、哪些从来没用过、哪些需要更新。经常用的技能考虑优化执行步骤从来没用过的技能考虑删除需要更新的技能根据最近的踩坑经验补充护栏或调整步骤。迭代节奏上我建议小步快跑。不要一次性写一个完美的技能而是先写一个能用的版本然后在实际使用中不断调整。我自己的“写单元测试”技能改了七八版才达到比较稳定的状态。每一版都是因为遇到了新的问题比如测试框架识别错误、测试文件命名不规范、边界用例覆盖不全等。6.3 我个人在实际操作中的几点体会用了几个月下来我最大的体会是技能框架的价值不在于“让 AI 更聪明”而在于“让 AI 更稳定”。AI 本身的能力已经很强了但它有时候会“发挥不稳定”。技能框架通过固化流程和约束把 AI 的输出稳定在一个可预期的范围内。这对于需要重复执行的任务来说价值巨大。第二个体会是不要追求大而全的技能库。我一开始兴致勃勃地写了二十多个技能结果常用的就五六个。技能太多反而会增加上下文负担降低执行效率。现在我保持技能库在十个以内每个都经过实际验证。第三个体会是护栏比技能本身更重要。一个没有护栏的技能就像一辆没有刹车的车跑得越快越危险。我现在的做法是每写一个新技能先想清楚“这个技能绝对不能做什么”把护栏写好再写执行步骤。最后分享一个小技巧如果你用的是 Claude Code可以在项目根目录放一个CLAUDE.md文件里面写项目的整体约定和常用命令。这个文件会在每次对话开始时自动加载相当于一个“全局上下文”。把技能框架的说明也放进去AI 就能更好地理解你的工作方式。Codex CLI 也有类似的机制通常是AGENTS.md或.codex/instructions.md。这个文件不用写太长几百字就够了关键是信息密度要高。