每日一仓

ONE OPEN-SOURCE REPO A DAY

每天 08:00 更新 数据来源 · Atlas 精选榜 2026 年 11 月 18 日

第 13 期 · 2026-11-13

obra/superpowers — 给编码 Agent 的一套开发方法论

第 13 期介绍的是最近一年里 Star 涨得最快的 Agent 方法论仓库:obra/superpowers。它回答的不是“怎么让 AI 写代码”,而是“怎么让 AI 像一个有纪律的工程师那样工作”——先问清需求、写计划、再动手,每一步都有对应的技能兜底。

一句话定位

一套给编码 Agent 用的开发方法论:15 个可组合的 Markdown 技能 + 一个会话启动钩子,把头脑风暴、写计划、子代理驱动开发、TDD、代码评审串成强制流程,覆盖 16 种 Agent 工具。

源码结构

这个仓库拉下来第一眼会让人意外:它几乎没有“应用代码”。浅克隆 2.9M、236 个文件(不含 .git),其中 Markdown 112 个、Shell 脚本 53 个、JSON 17 个。GitHub 把它的主要语言识别为 Shell,原因正是那 53 个脚本与钩子——仓库的本体是方法论文本,代码只是让这套方法论在各家 Agent 里跑起来的胶水。

  • skills/:15 个技能目录,每个技能一个 SKILL.md(带 name/description 的 frontmatter,供 Agent 按描述触发)加可选的 references/ 参考文档和 scripts/ 辅助脚本。15 个技能的 Markdown 正文合计约 8,900 行,其中 writing-skills 一个技能就占了 2,627 行(含 8 篇参考文档),subagent-driven-development 1,018 行、diagnosing-superpowers 876 行、systematic-debugging 689 行、brainstorming 638 行、test-driven-development 528 行。最小的 verification-before-completion 只有 120 行——一句话技能也有。
  • hooks/:会话启动钩子。session-start 是 90 行 Bash,hooks.json 把它注册为 Claude Code 的 SessionStart 钩子(startup、clear、compact 三种触发),run-hook.cmd 是 Windows 入口。钩子的活很单纯:读出 skills/using-superpowers/SKILL.md 全文,转义后以 JSON 形式注入会话上下文,相当于每次开会话先给 Agent 塞一张“你有超能力,先查技能再动手”的说明书。
  • 各家 Agent 的插件清单:.claude-plugin/、.codex-plugin/、.cursor-plugin/、.devin-plugin/、.hermes-plugin/、.kimi-plugin/、.muse-plugin/、.antigravity-plugin/ 各有 plugin.json(另有两份 marketplace.json),.opencode/plugins/superpowers.js(405 行)与 .pi/extensions/superpowers.ts(116 行)是 OpenCode 与 Pi 的原生扩展,另有 .agents/plugins。README 里 16 种工具各有一节安装说明:Claude Code、Antigravity、Codex App/CLI、Cursor、Devin CLI、Factory Droid、Gemini CLI、GitHub Copilot CLI、Grok Build CLI、Kimi Code、OpenCode、Pi、Qwen Code、Hermes Agent、Muse。
  • scripts/:bump-version.sh(版本号同步)、lint-shell.sh、sync-to-codex-plugin.sh 与 package-codex-plugin.sh(Codex 插件打包同步)、render-antigravity-logo.sh。
  • tests/:79 个文件、19 个子目录,62 个是可执行测试脚本。按平台分了 claude-code、codex、devin、hermes、kimi、opencode、pi、antigravity 等目录,另有 hooks、skill-layout、skill-size、version-bump、shell-lint 等专项。行为级测试用的是外部的 drill 评估框架(superpowers-evals 仓库,克隆进 evals/ 跑),仓库内只保留插件基础设施测试。
  • docs/:22 篇设计文档在 docs/superpowers/specs/(2026 年 1 月到 10 月,每篇对应一次功能设计,如 2026-10-05 的 brainstorming 重构、2026-08-27 的 diagnosing-superpowers 设计),docs/plans/ 另有 4 篇,外加 docs/testing.md、docs/porting-to-a-new-harness.md(新平台移植指南)、docs/windows/polyglot-hooks.md。RELEASE-NOTES.md 1,611 行约 120KB,README 400 行约 14KB。
  • 治理文件:AGENTS.md(121 行,给 AI 助手的投稿守则)、CODE_OF_CONDUCT.md、.github/ 下的 issue 模板与 PR 模板、.pre-commit-config.yaml、.version-bump.json。

一个值得留意的细节:.version-bump.json 列出了 12 个文件,bump-version.sh 发版时把这 12 处的版本号一起改掉——Claude、Cursor、Codex、Devin、Kimi、Antigravity、Muse 各自的 plugin.json,两份 marketplace.json,Hermes 的 plugin.yaml,Gemini 的扩展清单,以及 package.json。当前版本 7.0.2,最新提交就是 v7.0.2 的发版提交。

架构图

flowchart TD
    A[16 种 Agent 工具] --> B[插件清单与扩展]
    B --> C[SessionStart 钩子]
    C --> D[using-superpowers 引导注入]
    D --> E[15 个技能]
    E --> F[头脑风暴与写计划]
    F --> G[子代理驱动开发或行内执行]
    G --> H[TDD 与代码评审]
    H --> I[收尾合并]
    J[tests 79 个文件] --> E
    K[scripts 版本与打包] --> B
    L[docs 22 篇设计文档] --> E

分层设计说明

这套方法论分四层,每层解决一个不同的问题。

引导层:让技能一定会被用上。 大模型用技能的最大问题是“想不起来用”。Superpowers 的解法是不依赖模型自觉:SessionStart 钩子在会话开始、清空、压缩后都把 using-superpowers 全文塞进上下文,技能里用 <EXTREMELY-IMPORTANT> 写死一条规则——“哪怕只有 1% 的可能相关,也必须先调用技能”,并附了一张 12 行的“合理化借口”对照表(“这只是个简单问题”“我先快速看一下文件”之类),每句借口旁边都写着它为什么是错的。规则文本本身就是产品。

技能层:15 个技能按开发流程排布。 流程技能在前、实现技能在后:brainstorming(动工前先问清意图,小改动在聊天里定稿,大项目写成设计文档)→ using-git-worktrees(隔离工作区、跑通测试基线)→ writing-plans(把活拆成 2–5 分钟一个的任务,每个任务写明确切文件路径、完整代码与验证步骤)→ subagent-driven-development 或 executing-plans(前者每个任务派一个全新子代理、做完即审,最彻底;后者在当前会话里行内执行、最后统一审一次,最便宜)→ test-driven-development → requesting-code-review(按严重程度报问题,关键问题阻塞进度)→ finishing-a-development-branch(验证测试、给合并/PR/保留/丢弃四种选择、清理 worktree)。另有三类横切技能:systematic-debugging(四阶段根因定位)、verification-before-completion(宣称完成前必须跑验证命令)、diagnosing-superpowers(会话跑偏时读 transcript、逐行举证哪里出了问题,还能打包一份脱敏报告给维护者)。writing-skills 是元技能——教人怎么写技能。

适配层:一份技能,多家工具。 15 个技能的正文是平台中立的,各家差异收进 references/ 下的工具对照文件(如 claude-code-tools.md、codex-tools.md、pi-tools.md),以及各自的插件清单与一小段原生扩展。加一个新平台的成本就是一份清单加一份对照文档,docs/porting-to-a-new-harness.md 就是这份移植指南。README 明确写了:技能更新必须在所有支持的 Agent 上都能工作。

保障层:测试与版本。 技能正文有硬性体积上限——tests/skill-size/test-skill-size.sh 规定每个 SKILL.md 不得超过 20,000 字节,因为 Claude Code 压缩会话后重挂技能时会截断到 20,000 字符,超出的部分当场丢失;只在某些步骤才需要的内容必须挪进 references/,由 Agent 在需要时现读。tests/skill-layout/ 则禁止把开发文件塞进技能目录。版本号由 .version-bump.json 一处清单管 12 个文件,避免某个平台的清单漏改。

技术亮点

亮点一:用钩子解决“技能想不起来用”的问题,证据在 90 行 Bash 里。 hooks/session-start 的写法本身就是一堂工程课:它刻意不用任何命令替换与管道(Git Bash 下一次 fork 要几十毫秒)、不用 dirname(启动时 PATH 可能是坏的,注释里点名了 anthropics/claude-code#43127 这个上游 issue)、用 Bash 内置的 read 读文件、用参数替换做 JSON 转义。也就是说,注入引导文本这个动作被当成性能敏感路径来写——因为它在每次会话启动时都要跑。代价是可读性让位于速度,注释不得不写得很细;适用边界也很清楚:这套钩子只解决“开局注入”,会话中途的技能触发仍靠模型按描述匹配。

亮点二:TDD 技能把规则写成不可商量的铁律,并配了“反模式”附录。 skills/test-driven-development/SKILL.md 开头就是铁律:“没有先失败的测试,就不写生产代码”(NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST),先写了代码再补测试的要删掉重来;“只跳过这一次”的想法被直接点名为合理化。技能还附了 writing-good-tests.md,并在 README 里注明包含“测试反模式”参考。证据在行数上:528 行的技能正文里,例外情况只有三种——一次性原型、生成代码、配置文件,且要先问过人。这种“规则 + 例外清单 + 反模式”的三件套写法,比只喊口号的 TDD 倡议扎实得多;代价是小修小补也要先写测试,对赶时间的改动确实拖慢节奏,仓库自己的立场是:这正是它要的纪律。

值得参考的设计或实现

  • 技能即 Markdown + frontmatter 触发。 每个技能就是一个 SKILL.md,description 字段写清触发条件,Agent 按描述匹配调用。没有注册表、没有服务端、没有构建步骤——分发就是 git clone 或插件市场安装。想给自己的团队做一套内部规范,可以直接抄这个形状。
  • 20,000 字节上限是给上下文窗口做的预算管理。 技能正文超限就进 references/ 按需读取,主文件只留主干流程。这条规则本身还有自动化测试兜底(test-skill-size.sh),值得任何写 Agent 提示词的团队借鉴:提示词不是越长越好,超出的部分会在压缩后悄悄丢失。
  • 平台差异收进 references 而不是复制技能。 一份正文 + 每家一份工具对照文档,加新平台只需加清单与对照文件,不用把 15 个技能重写一遍。docs/porting-to-a-new-harness.md 把这套做法写成了指南。
  • 贡献治理写在 AGENTS.md 里,而且毫不客气。 文件开头就写:本仓库 PR 拒绝率 94%,几乎全是没读守则的 Agent 提交的;要求 PR 模板每节都填、摘要必须由人类亲手写、提交前必须给人类看过完整 diff、不得隐藏“这是 Agent 生成的”。这是一种治理机制:当贡献者主要是 Agent 时,把“人类在环”写进仓库根目录的守则,比事后关 PR 省事得多。
  • 遥测只做到“数人头”,且默认可关。 README 末尾说明:头脑风暴的可视化配图会从官网加载一张带版本号的 logo,仅用于粗略统计使用量,不含项目与提示词信息;设 SUPERPOWERS_DISABLE_TELEMETRY 即可关闭,也认 Claude Code 的两个同类开关。统计需求与隐私边界都写在明处。

适合谁

  • 每天用 Claude Code、Codex、Cursor、OpenCode 这类编码 Agent 干活、觉得它经常“自作主张直接开写”的开发者——装上后最直观的变化是 Agent 动工前会先追问需求、写计划。
  • 想给团队沉淀一套 Agent 工作规范的人:15 个技能可以直接拿去改,比从零写提示词快得多。
  • 对“提示词工程”本身感兴趣的人:这个仓库是目前 Star 最高的提示词方法论样本之一,技能写法、体积预算、多平台适配都值得拆开看。

怎么上手

按你用的工具在 README 的安装一节里找对应命令,核心都一样:装插件、重启会话、验证。以 Claude Code 为例,在官方插件市场里安装后,新开会话说一句要做的事,Agent 应在写代码前先触发头脑风暴;如果它没有,说明安装没生效。仓库建议的验证句式是“做一个 React 待办清单”,看它是否先问需求而不是直接写代码。更新时各家命令不同(多为重新安装同一命令),Muse 与 Devin 有专门的 update 命令。注意它不改你的模型配置,也不联网调用任何服务——技能是本地文本,钩子是本地脚本;唯一联网的是可视化配图里那张带版本号的 logo 图片,不想要就设环境变量关掉。

数据卡

  • 仓库:obra/superpowers
  • Star:316,761(2026-11-13 实时;Atlas 快照 308,970)
  • Fork:28,185
  • 主要语言:Shell(技能本体为 Markdown,胶水代码为 Shell)
  • 许可证:MIT
  • 创建时间:2025-10-09
  • 最近更新:2026-11-12(最近推送 2026-11-03)
  • 当前版本:7.0.2
  • Atlas 分类:开发工具 · 软件开发
  • 作者:Jesse Vincent(obra)与 Prime Radiant 团队
  • 未解决 Issue:344 个 · 关注者:1,145

← 返回仓库目录