补充超能力技能套件特性的研究

PR 地址：NousResearch/hermes-agent#46524 · 从 obra/superpowers 补齐三个开发方法论技能

研究摘要

Hermes 已从 obra/superpowers 适配了 5 个技能（writing-plans、subagent-driven-development、test-driven-development、systematic-debugging、requesting-code-review），覆盖了规划、委托、测试、调试、评审五个环节，但开发方法论里三个关键环节仍然缺失：没有设计先行的门禁（agent 直接跳进实现，假设错了白干）、没有完成前的验证护栏（声称"测试通过"却从未实际运行）、没有结构化的分支收尾流程（merge、开 PR 还是清理，全靠临场决定）。本研究向 Hermes 上游补充了这三个技能：brainstorming、verification-before-completion、finishing-a-development-branch，均改编自 obra/superpowers v5.1.0（MIT 许可）。改动规模 +578/-0，3 个文件，纯 SKILL.md，零新增依赖。

三个技能分别对应"开工前、完工前、收尾时"三个时间点的强制纪律，合起来把 agent 的开发流程补齐为完整的闭环。这篇研究拆解三个技能各自的约束设计、适配方式与执行边界。

一、问题背景：开发方法论的三块拼图

1.1 没有设计先行门禁：假设错了就白干

缺少设计环节的 agent 会直接进入实现：需求理解停留在表面，设计假设未经验证，代码写到一半发现方向错误。浪费的不只是时间——重写代码的时间成本是显性的——还有用户对 agent 判断力的信任：一次"方向错了"的交付，用户需要投入精力解释需求、验证假设、重走流程，信任成本远高于一次失败的构建。

已有的 writing-plans 技能在"计划"环节兜底，但计划之前缺少一个更早的门禁：先探索意图、澄清需求、敲定设计，再谈计划与实现。顺序是关键的——基于错误设计的计划，写得越细，浪费越大。

设计门禁与既有技能的关系是衔接而非重复：brainstorming 承担“意图 → 设计”，writing-plans 承担“计划”，两者组合形成“意图探索 → 设计敲定 → 计划细化”的三段链——缺了前段，后段的计划就建立在未经确认的假设上。

1.2 没有验证护栏：声称与事实脱节

“测试通过了"“bug 修好了"这类完成声明若没有新鲜验证证据支撑，就是在透支信任。常见的坏习惯有两种：把"应该能过"当结论——基于推理而非运行；引用上一次运行的结果——证据不是当前的，结论就不可靠。agent 场景里，这类虚假完成声明比人类开发者更隐蔽：agent 表达流畅、语气笃定，用户难以从措辞上分辨"验证过"与"没验证”，失败成本最终由用户承担。

1.3 没有结构化收尾：实现完了，然后呢

实现完成后的分支处置（本地 merge、开 PR、保留分支、丢弃改动）没有标准流程，agent 容易默认选一个最省事的路径，留下半成品分支或错过 PR 评审。收尾环节的混乱会直接污染仓库状态：未清理的分支堆积、未提交的改动丢失、错误的 merge 决策难以回滚。它是开发方法论里最容易被忽视、却最影响协作质量的一环——因为收尾决策影响的不只是当前任务，还有仓库的长期健康。

二、特性设计：三把时间点上的纪律锁

2.1 brainstorming：硬门禁，设计先行

brainstorming 技能设定一条 HARD-GATE（硬门禁）：设计未呈现并获得用户批准之前，禁止写代码。执行路径是固定的探索链路——用户意图 → 需求 → 设计 → 规格 → 计划，逐层收敛，每一层都以前一层的确认结果为前提，而不是一步跨到实现。

技能显式处理一个高频反模式：“这个太简单不需要设计”——即使是工具脚本和配置变更也要走流程，因为"简单"的判断本身就常常是错误假设的来源：越是看起来简单的任务，越容易被跳过澄清直接开写，而需求误解在简单任务上同样致命。定稿的规格写入 docs/superpowers/specs/，让设计决策可追溯，而非只存在于对话里——后续实现偏离设计时，有据可查。

规格文档的落盘位置也经过考虑：docs/superpowers/specs/ 与上游结构对齐，用户若同时使用上游工作流可以无缝衔接；对 Hermes 用户而言，规格的持久化让设计评审与实现对照有了固定载体，设计决策不再只存在于对话里。

2.2 verification-before-completion：铁律，先证据后声明

verification-before-completion 把完成声明绑定到一条铁律：没有新鲜验证证据，不得声称完成。门函数是五步链：识别命令 → 运行 → 读取输出 → 验证 → 声明。每一步都是显式的：识别"该用什么命令验证”，运行"实际执行"，读取"看真实输出"，验证"输出是否符合预期"，最后才允许声明。覆盖的验证类型包括测试通过、lint 干净、构建成功、bug 修复——都是"完成"声明的高发区。

技能同时明确废除了两类无效证据：“应该能过”（未经运行）与"上次跑过"（过期结果）——证据必须来自本次变更后的实际执行。这条铁律的效力在于它把"声称完成"的默认动作从陈述改成了执行：agent 想声明完成，必须先跑一遍验证链。

铁律的效力还在于把验证责任显式放在 agent 侧：用户无需追问“你跑过了吗”，验证是声明的前置条件而非事后补充。这改变了完成声明的默认可信度——凡是按流程发出的声明，默认带有新鲜证据。

2.3 finishing-a-development-branch：结构化收尾

finishing-a-development-branch 定义收尾流程：验证测试 → 探测环境 → 呈现选项 → 执行 → 清理。环境探测覆盖普通仓库、git worktrees 与 detached HEAD 三种形态，避免收尾动作在不同工作区形态下出错——detached HEAD 上直接 merge 与正常分支上的 merge 语义完全不同，结构化的第一步就是先搞清楚"我在哪种环境里"。收尾动作以结构化菜单呈现：本地 merge、创建 PR、保留分支、丢弃改动——把临场决策变成显式选择，每个选项的执行路径清晰、可回滚。

2.4 适配与打包方式

三个技能按 Hermes 规范适配：工具引用从 Claude Code 的 Skill 体系改写为 Hermes 的 skill_view 等既有工具，保证技能在 Hermes 里的操作路径是真实的而非照搬上游；frontmatter 遵循 Hermes 技能格式（version、author、metadata.tags、metadata.related_skills），与既有技能一致，可被技能系统正常索引；声明平台支持 linux、macos、windows；许可与上游一致保持 MIT。

打包方式是纯 SKILL.md 文件，遵循 Hermes 既有的 metadata + description 模式：会话启动时只加载索引（description 级信息），按需时才读取正文，符合渐进披露原则——技能的存在不增加会话启动负担，被调用时才消耗上下文。三个技能合起来 +578 行，全部是文本内容，无 Python 模块、无配置变更，这是刻意的零依赖设计。

3 个文件、578 行全部为文本内容，无 Python 模块、无配置变更——评审面因此集中在内容质量而非实现风险，合入门槛被压到最低；渐进披露模式下，会话启动只加载技能索引，实际上下文开销取决于调用频率，高频任务反复加载技能正文的成本由使用模式决定。

三、实测结果

PR body 记录了技能扫描器的验证结果：

验证覆盖了技能进入 Hermes 技能系统后的完整可见性链路：索引可见、正文可读、元数据合法。这套验证对应技能的实际使用路径——skills_list 决定技能能否被发现，skill_view 决定内容能否被加载，frontmatter 决定元数据是否被正确解析。端到端的开发流程演练（真实执行三个技能约束下的任务）未在 PR body 中记录。

另一个未被验证的层面是触发匹配：技能能否在真实任务中被 agent 正确调用，取决于描述与触发条件的匹配度——扫描器验证的是“能加载”，触发验证的是“会被用”，后者依赖真实任务数据。

四、能力边界

• 三个技能是流程约束而非代码约束：门禁与铁律依赖 agent 在运行中遵循技能指引，无法在编译期或运行时被强制；技能被加载但不被遵守时，约束形同虚设，验证链条的可靠性最终取决于 agent 的执行纪律；
• 适配基线是 obra/superpowers v5.1.0，上游后续版本的新增内容未被跟踪，存在版本漂移风险；
• 技能只定义了流程，未定义失败时的兜底路径——例如设计多次被否、验证反复失败时的处置策略；
• 纯技能形态意味着没有自动化钩子：验证命令的识别与运行完全依赖 agent 的现场判断，命令选择错误时验证结果可能失真；
• 三个技能与既有 5 个 superpowers 技能的组合使用顺序（何时由 brainstorming 转入 writing-plans 等）依赖用户或 agent 自行编排，PR 未定义衔接规则。

五、PR 信息

• PR 地址：https://github.com/NousResearch/hermes-agent/pull/46524
• 改动规模：+578 / -0，3 个文件（brainstorming +242 行、verification-before-completion +139 行、finishing-a-development-branch +197 行）
• 状态：closed
• 提交时间：2026-06-15
• 来源：改编自 obra/superpowers v5.1.0（MIT 许可）

本文记录 x7peeps 向 Hermes Agent 上游贡献的特性研究，所有数据来自 PR 实测记录。