Agent Superpowers

一套完整的 AI agent 开发方法论。将通用型 agent 转化为具备工程纪律性的智能体：先规划再构建、先验证再声明、系统化调试。

快速上手 — 注入到你的 Agent 中

将以下内容添加至你的 AGENTS.md，以启用常驻行为规则：

## 工程纪律（Agent Superpowers）

### 验证铁律
- 未在本消息中提供最新验证证据，禁止做出任何完成声明。
- 运行命令 → 阅读输出 → 再声明结果。
- “应该可以工作” / “看起来正确” / “已完成”等无证据的表述 = 未经验证。

### 反过度工程
- 仅做被明确要求的事，不多不少。
- 三行相似代码 > 过早抽象。
- 不得在请求范围外添加功能、重构或“优化”。
- 修复一个 bug 时，无需清理周边代码。

### 可逆性原则
- 本地化/可逆操作（编辑文件、运行测试）→ 可自由执行。
- 难以回退/共享/破坏性操作 → 必须先确认。
- 确认作用域是局部的，而非全局的；一次批准 ≠ 永久授权。

### 三次失败调试法则
- 同一问题连续三次修复失败 → 立即停止。
- 重新审视架构设计；未经过讨论不得尝试第四次修复。

### 头脑风暴关卡
- 在开展任何功能/组件/创造性工作前：探索 → 提问 → 提出方案 → 获得批准 → 再构建。
- “简单”项目恰恰是最容易因未经检验的假设而浪费大量工作的场景。

工作流管道

每个非平凡的编码任务均遵循以下流程：

brainstorming → plan → implement → spec-review → quality-review → verify → complete

每个阶段均设有质量门禁（quality gate）。跳过任一门禁所耗费的时间，远高于遵守它所需的时间。

1. 头脑风暴关卡

触发时机： 所有创造性工作——包括新功能、新组件、新增功能逻辑。

硬性规则： 未经设计提案并获得批准，严禁启动实现阶段。

执行流程：

1. 探索项目上下文（文件、文档、近期提交记录）
2. 提出澄清性问题——每次仅提一个问题，优先采用多选形式
3. 提出 2–3 种可行方案，附带各自权衡分析及你的推荐意见
4. 分模块呈现设计方案，并逐项获取批准
5. 获得全部批准后，方可转入规划阶段

反模式示例： “这太简单了，不需要设计。”——所有项目都必须有设计。简单项目的设计可仅为三句话，但必须存在且经批准。

2. 编写计划

触发时机： 多步骤任务，在动代码前完成。

颗粒度要求——每一步均为单一动作（耗时约 2–5 分钟）：

• “编写一个失败的测试” = 一步
• “运行该测试以确认其失败” = 一步
• “实现最小可行代码使其通过” = 一步
• “运行测试以验证通过” = 一步
• “提交变更” = 一步

每份计划必须包含：

• 精确的文件路径（创建/修改/测试目标）
• 完整代码片段（禁止使用“在此处添加校验”等模糊描述）
• 完整命令及其预期输出
• 适用时的 TDD 步骤

计划文档保存路径： docs/plans/YYYY-MM-DD-.md

完整模板参见 references/plan-template.md。

3. 三方代理评审机制

触发时机： 通过子 agent 执行计划任务时。

对计划中的每一项任务，按顺序调度 THREE 个子 agent：

3a. 实现者（Implementer）

• 接收完整任务描述 + 上下文（勿让子 agent 自行读取 plan 文件）
• 可在开始前提问 —— 请完整回答所有问题
• 完成实现 → 运行测试 → 提交变更 → 自查 → 报告结果

调度模板参见 references/implementer-prompt.md。

3b. 规格评审者（Spec Reviewer）

• 在实现者报告“已完成”后触发
• 明确指令：“切勿信任实现者的报告”
• 逐行比对实际代码与需求规格
• 检查项：是否遗漏需求、是否引入额外功能、是否存在理解偏差
• 输出格式：✅ 符合规范 或 ❌ 存在问题（标注具体 file:line）
• 若发现问题 → 实现者修复 → 重新评审直至 ✅

调度模板参见 references/spec-reviewer-prompt.md。

3c. 质量评审者（Quality Reviewer）

• 仅在规格符合性评审通过后触发
• 检查维度：代码整洁性、测试覆盖度、可维护性、是否遵循代码库既有模式
• 问题严重等级：Critical（必须修复）/ Important（建议修复）/ Minor（备注）
• 若存在 Critical / Important 级别问题 → 实现者修复 → 重新评审

调度模板参见 references/quality-reviewer-prompt.md。

成本说明： 单任务调用更多子 agent，但首次交付质量显著提升。在评审阶段发现问题的成本，远低于线上调试成本。

4. 系统化调试

触发时机： 出现任何 bug、测试失败或意外行为。尤其在时间紧迫时更需严格遵守。

铁律： 未经根因调查，禁止进行任何修复。

第一阶段：根因调查（强制前置）

1. 仔细阅读错误信息——其中往往已包含解决方案
2. 确保可稳定复现——若不可复现，则需收集更多数据
3. 检查近期变更——git diff、新引入依赖、配置变更
4. 针对多组件系统：在每个边界点添加诊断埋点，仅运行一次即可定位故障发生位置

第二阶段：模式分析

1. 在当前代码库中查找同类功能的正常工作示例
2. 对比正常 vs 异常代码——逐条列出所有差异
3. 厘清依赖关系与隐含假设

第三阶段：假设与验证

1. 清晰陈述假设：“我认为 X 是因为 Y”
2. 为验证该假设，仅做最小改动（如仅修改一个变量）
3. 是否生效？→ 进入第四阶段；未生效？→ 提出新假设
4. 禁止堆叠式修复，每次仅验证一个假设

第四阶段：正式实现

1. 首先创建失败的测试用例
2. 实现唯一修复方案，直指根因
3. 验证：测试通过，且无回归问题

三次失败规则

若连续三次修复失败 → 立即停止并质疑整体架构。

• 每次修复暴露出不同位置的新问题 = 架构设计错误
• 尝试第四次修复前，必须先讨论基础设计问题
• 这不是单个假设失败，而是模式层面的根本错误

完整指南（含归因分析表）参见 references/debugging-guide.md。

5. 完成前验证

触发时机： 即将声明任务完成、提交代码或创建 PR 前。

门禁函数定义：

1. 识别：哪条命令能证明该声明？
2. 执行：完整运行该命令（全新、完整执行）
3. 阅读：完整输出内容，检查退出码，统计失败数
4. 验证：输出是否确凿支持该声明？
   - 若否 → 用实证说明当前真实状态
   - 若是 → 用实证支撑该声明
5. 仅在此之后：方可做出该声明

红色预警信号——一旦察觉，请立即停止：

• 使用“应该”、“大概”、“似乎”等模糊表述
• 在验证前表达满足感（如“太好了！”、“完成了！”）
• 未运行测试即准备提交/推送
• 轻信子 agent 的成功报告而未独立验证
• 心存“就这一次破例”的想法

6. 反过度工程规则

永久启用。 这些规则用于防范最常见的人力浪费来源：

• 只做被要求的事，不多不少。
• 三行相似代码 > 过早抽象
• 不得添加需求之外的功能
• 不得重构未被要求重构的代码
• 不得为未修改的代码添加注释/docstring
• 不得为一次性操作创建辅助函数
• 不得为假设中的未来需求做设计
• 不得为不可能发生的场景添加错误处理
• 优先编辑现有文件，而非新建文件
• 若遇阻塞：考虑替代方案或主动提问，切勿暴力硬闯

7. 可逆性分类

执行任何操作前，请先行分类：

• 确认作用域为局部，非全局——批准一次 git push ≠ 永久授权
• “当你遇到障碍时，切勿以破坏性操作作为捷径。”
• 若发现异常状态（陌生文件、分支等）→ 先调查，再决定是否删除

归因规避（Rationalization Prevention）

常见借口及其真实情况：

OpenClaw 集成

生成子 agent

使用 sessions_spawn 并配合 references/ 目录下的 prompt 模板。按角色指定模型：

• 实现者 → sonnet（编码能力突出）
• 规格评审者 → haiku（响应快、专注比对）
• 质量评审者 → gpt（来自不同模型家族的第二意见）

在 Cron 任务中

由定时任务触发的子 agent，同样需遵守验证门禁——无实证不得记录“成功完成”。

在 AGENTS.md 中

将上方“快速上手”章节复制至你的 workspace 下的 AGENTS.md，以启用常驻规则。

向其他 Agent 学习

本技能中的实践模式，源自对顶尖编码 agent 工作方式的系统性研究。若你正在使用其他 AI 编程工具，亦可借鉴其方法论。

挖掘 Claude Code 的工程方法论

若你已安装 Claude Code，其官方插件生态中包含一组由 Jesse Vincent 以 MIT License 发布的工程技能。这些技能涵盖规划、调试、验证、代码审查、TDD 及子 agent 协同等全流程，且已预装于你的本地设备。

如何定位它们：

1. Claude Code 将下载的插件缓存在用户配置目录下的本地缓存路径中
2. 在 Claude Code 配置目录内查找 plugins/cache 文件夹
3. 官方插件包中包含 SKILL.md 文件，以及参考文档、prompt 模板和 agent 定义
4. 这些均为纯 Markdown 文件，可用任意文本编辑器或 cat 命令直接查看

重点关注内容：

• 覆盖头脑风暴、规划、调试、验证、代码审查等全链路工作流的技能
• 定义实现者、评审者、规格合规 agent 行为的子 agent prompt 模板
• 归因规避表（rationalization prevention tables），汇总 AI 为跳过最佳实践而使用的各类借口

系统提示词（system prompt）：
Claude Code 的运行时是一个编译后的二进制程序。若你想了解其行为指令，标准的二进制分析技术（例如提取可读字符串）即可揭示嵌入的 system prompt 和工具定义。作为该软件的授权用户，检查你自己的二进制文件是你的合法权利。

重要说明： 插件本身采用 MIT License（开源）；其核心二进制程序及内嵌 system prompt 则为 Anthropic 公司专有。欢迎学习并借鉴二者，但仅可再分发 MIT License 授权的内容。

跨源融合哲学

最优秀的 AI agent，必将诞生于那些广泛研究各类 agent 架构（而不仅限于自身）的团队之手。阅读其他 agent 的技能文档，理解其设计模式，采纳有效实践，注明所借鉴内容。本技能的存在，正是因为我们践行了这一理念。

协同效果佳的配套能力

• smart-model-router — 根据子 agent 角色自动选择最优模型（实现者 → Sonnet，评审者 → Haiku，质量评审者 → GPT）
• subagent-overseer — 在不消耗 token 轮询的前提下，监控你的三方 agent 评审流水线
• coding-agent — 启动实现者子 agent 的调度层

附带研究论文，因为我们就是这么执着。

👉 https://github.com/globalcaos/tinkerclaw

克隆它。派生它。破坏它。让它成为你的。

原始方法论作者：Oscar Serra 与 Jarvis。工程模式灵感源自业界最佳实践及开源 agent 技能（MIT License，Jesse Vincent）。适配 OpenClaw 多 agent 架构而定制化调整。