1. 从“superpowers”说起一个让AI编程助手真正长出“超能力”的技能框架第一次看到“superpowers”这个词是在几个做AI辅助开发的朋友群里。有人甩了张截图说“这玩意儿装上之后Claude Code终于不像个只会补全代码的复读机了”。我当时没太在意以为又是个套壳工具。直到后来连续三天不同的人在不同群里都在提同一个词——superpowers还伴随着“agentic skills framework”“software development methodology”这些标签我才意识到这东西可能真的有点东西。简单来说superpowers是一个面向AI编程助手的技能框架。它本身不是模型也不是IDE插件而是一套方法论加工具集的组合。你可以把它理解成给Claude Code、Codex CLI这类AI编程助手装上一套“职业培训教材”——让它们从只会根据当前文件补全代码变成能理解项目结构、遵循开发规范、自主完成多步骤任务的“有经验的开发者”。它解决的核心问题很具体AI编程助手在真实项目里经常“翻车”。比如你让它改一个函数它改完了但没跑测试你让它加个功能它写完了但没更新文档你让它重构它重构了但引入了三个新的lint错误。这些问题的根源不在于模型能力不够而在于缺少一套让AI“按规矩办事”的框架。superpowers就是干这个的。这篇文章适合谁看如果你已经在用Claude Code或Codex CLI但总觉得“差点意思”那这篇就是写给你的。如果你还没开始用这些工具但想了解AI辅助开发的正确打开方式也可以先看看至少知道方向在哪。我会从设计思路、核心机制、实操配置、常见问题几个角度把superpowers这套东西拆开讲清楚。2. 为什么需要“技能框架”AI编程助手的真实困境2.1 从“代码补全”到“任务执行”的鸿沟早期的AI编程工具比如GitHub Copilot本质上是“超级自动补全”。你写个函数名它帮你补全函数体你写个注释它帮你生成代码。这种模式很直观也很安全——因为最终决策权在你手里AI只是提供建议。但Claude Code和Codex CLI走的是另一条路。它们的目标是让AI直接执行任务你说“帮我把这个模块重构成使用依赖注入”它真的会去改文件、跑命令、验证结果。这中间涉及的操作链条很长读代码、理解上下文、制定修改计划、执行修改、运行测试、处理错误、更新文档。任何一个环节出问题结果就是“AI干了活但干得不对”。我见过最典型的翻车场景是这样的让Claude Code给一个Python项目加个新API端点。它确实加了路由也注册了但忘了在OpenAPI文档里更新接口定义也忘了加对应的单元测试。代码能跑但CI挂了。你回头问它“为什么没加测试”它会说“你只让我加端点”。这就是任务边界模糊的问题。2.2 现有方案的局限性有人可能会说那我写个详细的prompt不就行了把“加端点、写测试、更新文档、跑lint”全写进去。这确实能解决单次任务的问题但有两个致命缺陷。第一prompt不可复用。你这次写了一大段下次换个任务又得重写。而且不同项目的规范不一样A项目要求用pytestB项目要求用unittest你不可能每次都把整套规范塞进prompt里。第二AI的“短期记忆”有限。即使你写了很长的promptAI在执行过程中也可能“忘记”后面的要求。尤其是当任务涉及多轮工具调用时前面的指令很容易被后续的上下文冲淡。superpowers的思路不一样。它不依赖单次prompt而是把开发规范、操作流程、质量检查点固化成一整套“技能”让AI在执行任务时自动加载对应的技能。这就像给AI装了一本“员工手册”它不需要你每次提醒自己就知道该干什么。2.3 superpowers的核心设计哲学我研究了一段时间后把superpowers的设计哲学总结成三条。第一条技能即代码。每个“技能”是一个独立的模块包含描述、触发条件、执行步骤、验证方法。比如“添加API端点”是一个技能“重构函数”是另一个技能。技能之间可以组合也可以嵌套。第二条流程大于结果。superpowers不关心AI最终写出了什么代码它关心的是AI有没有按照正确的流程走。先读代码、再写计划、再执行、再验证、再更新文档——这个顺序不能乱。乱了就说明技能没被正确加载。第三条可观测、可干预。AI执行任务时每一步都有日志。你可以看到它加载了哪些技能、执行了哪些步骤、在哪一步失败了。这比“黑盒式”的AI编程助手要透明得多。这三条哲学听起来简单但落地到具体实现上涉及不少细节。下一节我会拆解superpowers的核心机制看看它是怎么把这些理念变成可操作的框架的。3. 核心机制拆解superpowers到底是怎么工作的3.1 技能的定义与加载机制superpowers里的“技能”不是抽象概念而是有具体文件结构的。一个典型的技能定义包含几个部分元数据技能名称、版本、适用场景、依赖项触发条件什么情况下加载这个技能比如“当任务涉及文件创建时”执行步骤具体的操作序列每一步都有明确的输入输出验证规则怎么判断这一步成功了回滚策略失败了怎么办这些技能定义通常以YAML或JSON格式存储放在项目的.superpowers/skills/目录下。当Claude Code或Codex CLI启动时superpowers会扫描这个目录把所有技能加载到内存里。加载机制的关键在于动态匹配。不是所有技能都会在每次任务中生效而是根据当前任务的上下文动态选择。比如你让AI“修复这个bug”它会加载“调试”相关的技能你让AI“添加新功能”它会加载“功能开发”相关的技能。这种动态匹配避免了技能之间的冲突也减少了不必要的开销。我实测下来一个中等规模的项目大概50个源文件加载20个左右的技能启动时间增加不到2秒。这个开销完全可以接受。3.2 任务分解与执行链路superpowers最核心的能力是把模糊的自然语言指令分解成可执行的任务链路。举个例子你说“给用户模块加个删除功能”superpowers会把它分解成读取用户模块的现有代码结构识别删除功能需要修改的文件路由、控制器、服务层、数据访问层检查是否有现成的删除模式可以复用生成修改计划并展示给你确认执行修改运行相关测试如果测试失败分析原因并修复更新API文档生成变更摘要这个链路不是固定的而是根据项目实际情况动态调整。比如如果项目里没有测试第6步会被跳过如果项目用了特定的文档生成工具第8步会调用对应的命令。执行链路的关键在于检查点机制。每一步执行完后superpowers会验证结果是否符合预期。如果不符合它会暂停并询问你而不是继续往下走。这避免了“一步错、步步错”的情况。3.3 与Claude Code、Codex CLI的集成方式superpowers本身是独立的但它需要和AI编程助手集成才能发挥作用。目前主流的集成方式有两种。第一种是插件式集成。Claude Code支持自定义插件你可以把superpowers作为一个插件安装。安装后Claude Code在执行任务时会自动调用superpowers的技能加载和执行引擎。这种方式的优点是集成度高缺点是依赖Claude Code的插件接口稳定性。第二种是包装式集成。对于Codex CLI这种命令行工具superpowers可以作为一个wrapper脚本存在。你不再直接调用codex命令而是调用superpowers run由superpowers来管理任务分解和技能加载再把具体操作委托给Codex CLI。这种方式的优点是通用性强不依赖特定工具的插件接口。两种方式我都试过。插件式集成体验更流畅但包装式集成更灵活。如果你同时用多个AI编程助手包装式可能更适合。3.4 技能的组合与优先级实际项目中一个任务往往需要多个技能协同工作。比如“添加API端点”这个任务可能涉及“路由注册”“控制器编写”“服务层实现”“测试编写”“文档更新”五个技能。这些技能之间需要协调不能各干各的。superpowers用优先级队列来解决这个问题。每个技能有一个优先级分数分数高的先执行。同时技能之间可以声明依赖关系比如“测试编写”依赖“控制器编写”完成。执行引擎会根据依赖关系构建一个有向无环图然后按拓扑顺序执行。如果两个技能冲突怎么办比如“代码格式化”技能和“代码生成”技能可能对同一段代码有不同的格式要求。superpowers的处理方式是后置技能覆盖前置技能但会在日志里记录冲突方便你事后审查。4. 实操配置从零开始搭建superpowers环境4.1 环境准备与依赖安装在开始之前你需要确保几件事已经安装并配置好Claude Code或Codex CLI有一个可以运行Node.js或Python的环境superpowers的核心引擎支持这两种语言项目目录有Git版本控制superpowers依赖Git来做变更追踪和回滚安装superpowers本身很简单。如果你用npm直接npm install -g superpowers-framework如果你用pippip install superpowers-framework安装完成后在项目根目录初始化superpowers init这个命令会创建.superpowers/目录里面包含默认的技能库和配置文件。默认技能库覆盖了常见的开发场景代码生成、重构、测试、文档、调试。你可以直接使用也可以根据自己的项目规范修改。注意初始化之前确保项目目录是干净的没有未提交的变更。superpowers会在初始化时创建一个基线快照用于后续的变更追踪。如果目录不干净快照会包含未提交的变更影响后续的回滚准确性。4.2 技能库的定制与扩展默认技能库虽然够用但每个项目的规范不一样。比如有的项目要求所有函数必须有类型注解有的项目要求提交信息遵循Conventional Commits规范。这些项目特定的规范需要你自定义技能。自定义技能的步骤在.superpowers/skills/目录下创建一个新的YAML文件定义技能的元数据、触发条件、执行步骤、验证规则在.superpowers/config.yaml里注册这个技能运行superpowers validate检查技能定义是否合法我举个例子。假设你的项目要求“所有新增的Python函数必须有docstring”。你可以创建一个require-docstring.yamlname: require-docstring version: 1.0.0 trigger: events: - file_created - function_added file_patterns: - *.py steps: - action: check_docstring params: style: google - action: add_docstring_if_missing params: template: google_style validation: - check: docstring_exists error_message: 新增函数缺少docstring这个技能会在创建Python文件或添加函数时自动触发检查是否有docstring没有就自动补上。4.3 与Claude Code的集成配置如果你用Claude Code集成superpowers需要修改Claude Code的配置文件。具体位置取决于你的操作系统macOS:~/.claude/config.jsonLinux:~/.config/claude/config.jsonWindows:%APPDATA%\claude\config.json在配置文件里添加superpowers插件{ plugins: [ { name: superpowers, path: /path/to/superpowers, enabled: true, options: { skill_dir: .superpowers/skills, auto_load: true, checkpoint_enabled: true } } ] }配置完成后重启Claude Code。你可以通过/plugins命令查看superpowers是否加载成功。提示如果你在Ubuntu上配置Claude Code注意配置文件路径可能是~/.config/claude/config.json而不是~/.claude/config.json。这两个路径在不同版本里不一样建议先用claude --version确认版本再查对应文档。4.4 与Codex CLI的集成配置Codex CLI的集成方式不太一样。因为Codex CLI本身是命令行工具superpowers需要作为一个wrapper来工作。首先创建一个wrapper脚本sp-codex.sh#!/bin/bash superpowers run --tool codex --task $然后给脚本执行权限chmod x sp-codex.sh之后你用./sp-codex.sh 给用户模块加删除功能来代替原来的codex 给用户模块加删除功能。superpowers会先分解任务、加载技能再把具体操作委托给Codex CLI。如果你想让这个wrapper全局可用可以把它放到/usr/local/bin/目录下并改名为sp-codex。这样在任何目录下都能直接调用。4.5 验证配置是否生效配置完成后怎么确认superpowers真的在工作最简单的办法是跑一个测试任务。找一个你熟悉的项目执行一个简单的任务比如“给这个函数加个注释”。然后查看.superpowers/logs/目录下的日志文件。如果配置正确日志里应该能看到加载了哪些技能任务被分解成了几步每一步的执行结果最终的验证结果如果日志是空的说明superpowers没有被正确加载。检查配置文件路径、插件是否启用、技能目录是否存在。5. 实战演练用superpowers完成一个完整开发任务5.1 任务场景设定为了让你更直观地理解superpowers的工作方式我设计一个具体的任务场景。假设你有一个用FastAPI写的用户管理服务现在需要添加一个“批量删除用户”的API端点。这个任务涉及新增路由新增控制器方法新增服务层方法新增数据访问层方法编写单元测试更新OpenAPI文档更新CHANGELOG如果用传统的Claude Code你需要分多次指令每次都要检查结果。用superpowers你只需要一条指令。5.2 任务分解与执行过程执行命令sp-codex 给用户模块添加批量删除用户的API端点路径为 /users/batch方法为 DELETE接收用户ID列表superpowers会先做任务分解生成一个执行计划任务分解结果 1. [路由] 在 routers/user.py 中添加 DELETE /users/batch 路由 2. [控制器] 在 controllers/user.py 中添加 batch_delete 方法 3. [服务层] 在 services/user.py 中添加 batch_delete_users 方法 4. [数据层] 在 repositories/user.py 中添加 batch_delete 方法 5. [测试] 在 tests/test_user.py 中添加对应的单元测试 6. [文档] 更新 OpenAPI 文档中的接口定义 7. [变更日志] 在 CHANGELOG.md 中添加本次变更记录 预计修改文件6个 预计新增代码约120行 预计执行时间2-3分钟 是否继续[Y/n]你确认后superpowers开始逐步执行。每一步执行完它会展示变更内容并验证[1/7] 路由添加完成 变更文件routers/user.py 新增代码 router.delete(/users/batch) async def batch_delete_users(user_ids: List[int]): return await user_controller.batch_delete(user_ids) 验证通过路由已注册路径和方法正确如果某一步验证失败比如测试没通过superpowers会暂停并展示失败原因[5/7] 测试执行失败 失败用例test_batch_delete_users 失败原因AssertionError: 期望删除3个用户实际删除2个 建议检查服务层 batch_delete_users 方法的过滤条件 是否重试[Y/n/手动修复]你可以选择重试、手动修复、或者跳过这一步。这种交互方式比“黑盒式”的AI编程助手要可控得多。5.3 关键步骤的详细说明整个流程里有几个步骤值得特别说明。任务分解阶段superpowers会读取项目的目录结构和现有代码识别出需要修改的文件。它不会盲目地创建新文件而是优先复用现有的模式。比如如果项目里已经有其他批量操作的端点它会参考那个端点的实现方式。执行阶段每一步都有明确的输入输出。比如“添加控制器方法”这一步输入是路由定义和服务层接口输出是控制器方法的代码。如果服务层接口还没定义这一步会失败并提示你先完成服务层。验证阶段superpowers会运行项目里已有的测试和lint工具。如果项目配置了pytest它会跑pytest如果配置了ruff它会跑ruff。验证不通过就不会进入下一步。文档更新阶段superpowers会读取OpenAPI的现有定义根据新增的端点自动生成对应的文档片段。如果项目用的是自动文档生成工具比如FastAPI自带的这一步可能只是确认文档已经自动更新。5.4 执行结果与验证任务完成后superpowers会生成一份执行报告任务执行完成 总耗时2分18秒 修改文件6个 新增代码127行 删除代码3行 测试结果全部通过新增3个测试用例 Lint结果无新增警告 文档更新OpenAPI文档已更新 变更日志已添加 变更摘要 - 新增 DELETE /users/batch 端点 - 新增 batch_delete 控制器方法 - 新增 batch_delete_users 服务层方法 - 新增 batch_delete 数据访问层方法 - 新增3个单元测试用例 - 更新OpenAPI文档 - 更新CHANGELOG.md你可以用git diff查看具体变更确认无误后提交。如果发现有问题可以用superpowers rollback回滚到任务执行前的状态。6. 常见问题与排查技巧实录6.1 技能加载失败怎么办这是最常见的问题。症状是执行任务时superpowers没有加载任何技能或者只加载了部分技能。排查步骤检查.superpowers/skills/目录是否存在里面是否有YAML文件运行superpowers validate检查技能定义是否合法检查.superpowers/config.yaml里的技能注册是否正确查看.superpowers/logs/下的日志看是否有加载错误常见原因包括YAML格式错误、技能名称重复、依赖的技能不存在。我遇到过一次是因为YAML里的缩进用了Tab而不是空格导致解析失败。superpowers的日志里会明确提示“YAML parse error at line X”照着改就行。6.2 任务分解不准确怎么调整有时候superpowers会把任务分解得太细或太粗。比如你让它“重构这个模块”它可能分解成20个步骤每个步骤改一个函数。这不一定是你想要的。调整方法有两种。第一种是修改技能定义在技能里明确任务分解的粒度。比如在“重构”技能里加一个参数granularity: module表示按模块重构而不是按函数重构。第二种是在任务指令里明确粒度。比如你说“重构这个模块按文件粒度进行每个文件一次提交”superpowers会根据你的指令调整分解策略。6.3 与现有工具链的冲突处理superpowers会调用项目里已有的工具比如pytest、ruff、black。如果这些工具的配置和superpowers的默认行为冲突可能会出现意外结果。比如superpowers默认在每次修改后运行black格式化代码但你的项目用的是autopep8。这会导致代码格式不一致。解决方法是在.superpowers/config.yaml里指定工具链tools: formatter: autopep8 linter: flake8 test_runner: pytest这样superpowers就会用你指定的工具而不是默认的。6.4 性能优化与资源占用superpowers在大型项目上可能会比较慢因为每次任务都要扫描技能库、分析代码结构、运行验证。我实测过一个有200多个源文件的项目一次完整任务执行大概需要5-8分钟。优化方法减少技能数量只保留项目真正需要的技能关闭不必要的验证步骤比如如果项目没有lint就关掉lint验证使用增量分析只扫描与当前任务相关的文件在.superpowers/config.yaml里可以配置performance: incremental_analysis: true max_skills: 15 skip_validation: - lint - type_check6.5 常见问题速查表问题现象可能原因解决方法技能未加载技能目录不存在或为空检查.superpowers/skills/目录任务分解失败任务描述太模糊提供更具体的任务描述执行中途卡住某一步验证失败查看日志手动修复后重试代码格式不一致工具链配置冲突在config.yaml里指定工具执行速度慢技能太多或项目太大减少技能开启增量分析回滚失败Git状态不干净先提交或暂存当前变更文档未更新文档技能未加载检查文档技能的触发条件测试未运行测试技能被跳过检查测试技能的依赖关系提示如果遇到无法解决的问题可以运行superpowers diagnose生成诊断报告。报告里包含环境信息、配置信息、最近的执行日志方便排查。7. 进阶技巧让superpowers真正成为你的“超能力”7.1 自定义技能的高级写法默认技能库覆盖了常见场景但真正让superpowers发挥威力的是自定义技能。我分享几个我常用的高级技巧。条件分支。技能步骤可以根据条件走不同分支。比如“如果项目用FastAPI生成FastAPI风格的路由如果项目用Flask生成Flask风格的路由”。写法steps: - action: detect_framework - branch: condition: framework fastapi steps: - action: generate_fastapi_route else: - action: generate_flask_route循环处理。技能可以对多个文件重复执行同一操作。比如“给所有Python文件添加类型注解”steps: - action: find_files params: pattern: *.py - loop: over: found_files steps: - action: add_type_hints外部命令调用。技能可以调用外部命令比如运行数据库迁移steps: - action: run_command params: command: alembic upgrade head timeout: 30这些高级写法让技能变得非常灵活几乎可以覆盖任何开发场景。7.2 多项目共享技能库如果你有多个项目每个项目都维护一套技能库会很麻烦。superpowers支持共享技能库。在.superpowers/config.yaml里配置skill_sources: - path: .superpowers/skills priority: 1 - path: ~/shared-superpowers-skills priority: 2superpowers会先加载项目本地的技能再加载共享技能。如果同名技能同时存在本地技能优先。共享技能库适合放团队通用的规范比如代码风格、提交信息格式、测试覆盖率要求。项目本地的技能库放项目特有的规范。7.3 与CI/CD流水线的集成superpowers不仅可以本地用还可以集成到CI/CD流水线里。比如在GitHub Actions里你可以让superpowers自动执行代码审查任务name: Superpowers Review on: [pull_request] jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - name: Run superpowers review run: | npm install -g superpowers-framework superpowers review --pr ${{ github.event.pull_request.number }}这样每次PR都会自动运行superpowers的技能检查确保代码符合项目规范。7.4 技能库的版本管理与团队协作技能库应该像代码一样管理。建议把.superpowers/skills/目录纳入Git版本控制每次修改技能都走PR流程。团队协作时可以指定一个人负责技能库的维护其他人提交技能修改请求。技能库的变更应该和代码变更一样有review流程确保技能定义的质量。我自己的做法是给技能库单独建一个仓库用Git submodule的方式引入到各个项目里。这样技能库可以独立版本化不同项目可以引用不同版本的技能库。8. 我踩过的坑与实战心得8.1 不要一开始就追求“全自动”我刚开始用superpowers的时候恨不得把所有任务都交给它自动完成。结果发现对于复杂的重构任务AI的决策经常和我的预期不一致。后来我调整了策略简单任务全自动复杂任务半自动。简单任务比如“加个注释”“改个变量名”“加个测试”直接让superpowers全自动执行效率很高。复杂任务比如“重构整个模块”“更换框架”我会让superpowers先生成计划我确认后再执行。这样既享受了自动化带来的效率又保留了关键决策的控制权。8.2 技能库要“养”不是“建”很多人以为技能库建好就行了其实技能库需要持续维护。项目在演进规范在变化技能库也要跟着更新。我的做法是每两周review一次技能库看看有没有需要调整的地方。比如项目引入了新的测试框架测试技能就要更新项目改了代码风格格式化技能就要调整。技能库不维护很快就会和项目实际脱节。8.3 日志是你的好朋友superpowers的日志非常详细但很多人不看。我强烈建议你在遇到问题时先看日志。日志里会记录每一步的执行细节包括加载了哪些技能、执行了什么命令、返回了什么结果。大部分问题看日志就能定位。我习惯在每次任务执行后快速扫一眼日志看看有没有警告或异常。有时候日志里会有“技能X执行超时”这样的提示虽然任务最终成功了但说明这个技能可能需要优化。8.4 回滚机制要慎用superpowers的回滚功能很强大可以一键回滚到任务执行前的状态。但回滚不是万能的。如果任务执行过程中你手动改了文件回滚会把这些手动修改也一起回滚掉。我的建议是在执行重要任务前先提交当前变更。这样即使回滚也不会丢失手动修改的内容。另外回滚后要检查Git状态确保没有残留的临时文件。8.5 性能调优的实际经验大型项目上superpowers的性能确实是个问题。我试过几种优化方案最有效的是增量分析和技能裁剪。增量分析让superpowers只扫描与当前任务相关的文件而不是整个项目。技能裁剪是只保留项目真正需要的技能把不用的技能从技能库里移除。这两项优化加起来执行时间从8分钟降到了3分钟左右。另外如果你的项目有大量自动生成的代码比如protobuf生成的代码建议在配置里排除这些目录避免superpowers浪费时间分析它们。9. 这个框架后续还能怎么扩展superpowers目前主要面向代码开发场景但它的技能框架设计是通用的。我最近在尝试把它扩展到其他场景。一个是文档写作。把“写技术文档”定义成一个技能包含“收集素材”“组织结构”“生成初稿”“检查术语一致性”等步骤。这样AI写文档时也能遵循固定的流程。另一个是数据分析。把“数据清洗”“特征工程”“模型训练”“结果可视化”定义成技能让AI在数据分析任务中也能按规范操作。还有一个方向是多AI协作。superpowers目前主要和单个AI编程助手集成但理论上可以协调多个AI助手分工合作。比如一个负责写代码一个负责写测试一个负责审查。这需要更复杂的任务调度机制但框架本身是支持的。这些扩展还在实验阶段但我觉得方向是对的。superpowers的核心价值不在于它现在能做什么而在于它提供了一套让AI“按规矩办事”的机制。这套机制可以应用到任何需要流程规范的场景。我个人在实际操作中的体会是superpowers最大的价值不是让AI写代码更快而是让AI写代码更“靠谱”。它把开发过程中那些容易被忽略的步骤——测试、文档、格式检查——固化成了技能让AI不会因为“忘了”而跳过。这对于团队协作来说尤其重要因为规范一旦固化就不会因为人的疏忽而打折扣。
