项目解析— Superpowers：用提示词工程给编码 Agent 强加工程纪律

用途：AI Agent 工程方向项目解析博客
原则：不背技术栈，讲"为什么这样设计"；对缺失能力明确标注，不强行解释
仓库：obra/superpowers（v6.2.0，Prime Radiant / Jesse Vincent）
一句话：它不是一个 Agent 框架，而是一套"提示词即架构"的行为塑造系统

一、先破除一个误解（为什么值得写）

大多数 Agent 项目解析，开头都是"我用了 LangChain / AutoGen / LangGraph 搭了一个 Agent"。Superpowers 这个仓库，一行 Agent runtime 代码都没有——没有 AgentExecutor、没有 Planner、没有 ReAct 循环、没有 LLM 调用层、没有向量库。

它主体是：

• 17 个 Markdown 提示词文件（Skill）
• 一套启动期注入机制（hooks + bootstrap）
• 少量辅助脚本（bash / Node）
• 1 个真正的网络服务：brainstorm 的 WebSocket 伴侣服务（server.cjs）

真正的"Agent"是底层宿主——Claude Code、Codex、Cursor、Gemini CLI。Superpowers 做的事，是用提示词 + 工作流编排，把工程纪律"写进"宿主 Agent 的行为里。作者原话的目标读者是一个会偷懒、会跳过设计/测试/评审的编码 Agent。

这正是它最值钱的地方：Agent 工程不止"写 runtime"，还包括"行为塑造（behavior shaping）"这一支。把它讲清楚，比罗列一个 LangGraph 节点图更能揭示 Agent 工程的本质。

二、项目定位：它解决什么工程问题

2.1 痛点

编码 Agent 接到"写个 React todo"时，会直接跳进写代码，跳过：

• 需求澄清（用户到底要什么）
• 设计（架构、组件边界、数据流、错误处理）
• 测试（TDD）
• 评审（代码质量、规格符合性）

后果是产出"slop"——可维护者公开嘲讽的低质代码。本仓库 CLAUDE.md 明说：PR 拒绝率 94%，绝大多数被拒是因为 Agent 没读/没遵守指南。

2.2 传统方案 vs Agent 方案

关键洞察：LLM 不会自觉遵守流程，它会"自我合理化"绕过流程。所以 Superpowers 的核心工程问题不是"怎么调度工具"，而是"怎么防止一个会偷懒的智能体偷懒"。

项目一句话介绍：
Superpowers 是一套用于给编码 Agent 强加软件工程方法论的 AI Agent 行为塑造系统，通过可自动触发的技能指令 + 启动期注入引导 + 多阶段人工闸门工作流，让任意宿主 Agent 像遵循流程的资深工程师一样工作。

三、架构拆解：职责都"下沉"到了宿主

必须先说清楚：本项目没有传统分层里的 API 层 / Agent 核心 / LLM 调用层。这些职责被下沉到宿主 Agent。Superpowers 只负责"指令"和"少量辅助进程"。

3.1 真实架构图

┌─────────────────────────────────────────────────────────────┐
│ 用户 (Developer / "human partner") │
└───────────────────────────┬─────────────────────────────────┘
│ 自然语言需求
▼
┌─────────────────────────────────────────────────────────────┐
│ 宿主 Agent (Claude Code / Codex / Cursor / Gemini CLI / pi) │
│ — 真正的 Agent 运行时在这里（LLM + 工具调度 + 子代理分发） │
└───────────────────────────┬─────────────────────────────────┘
│
┌───────────────────┴────────────────────┐
▼ ① 启动期注入（SessionStart hook） │
┌───────────────────────────────────────────────┐ │
│ Bootstrap 注入器 │ │
│ hooks/session-start (bash) → 读取 │ │
│ using-superpowers/SKILL.md → 输出 JSON 上下文 │ │
│ （包裹 <EXTREMELY_IMPORTANT>）注入模型上下文 │ │
└───────────────────────────┬───────────────────┘ │
▼
┌───────────────────────────────────────────────┐ │
│ 技能系统 (Skill System) — 全部是 Markdown │ │
│ using-superpowers（路由/强制检查） → 其他技能 │ │
│ brainstorming / writing-plans / executing- │ │
│ plans / subagent-driven-development / TDD / │ │
│ requesting-code-review / verification / │ │
│ systematic-debugging / finishing-a-branch … │ │
└───────────────────────────┬───────────────────┘ │
▼
┌───────────────────┴────────────────────┐
▼ ② 工作流编排（由 Skill 指令"驱动"宿主） │
┌───────────────────────────────────────────────┐ │
│ Workflow（无代码，纯指令编排） │ │
│ design → spec → plan → implement → review │ │
│ → finish，每阶段带人工闸门 │ │
└───────┬────────────────────────────┬────────────┘ │
▼ ▼ │
┌──────────────────┐ ┌──────────────────────────────────┐ │
│ LLM (宿主的模型) │ │ 外部辅助进程（本仓库唯一真·服务） │ │
│ 调用由宿主完成 │ │ skills/brainstorming/scripts/ │ │
│ （Superpowers 不 │ │ server.cjs —— WebSocket 伴侣服务 │ │
│ 直接调 LLM） │ │ 带 token 鉴权 / 防 DNS 重绑定 │ │
└──────────────────┘ └──────────────┬───────────────────┘ │
▼ │
┌──────────────────────────────────┐│
│ 状态与存储（文件系统，非运行时对象）││
│ · 设计文档 docs/superpowers/specs ││
│ · 计划文档 docs/superpowers/plans ││
│ · Ledger .superpowers/sdd/<plan>/ ││
│ · Git Worktree（隔离/检查点） ││
└──────────────────────────────────┘│
┌──────────────────────────────────┐│
│ 评测（EVAL，不在本仓库内） ││
│ superpowers-evals 的 drill 工具 ││
│ 驱动真实 tmux 会话 + LLM 判定 ││
└──────────────────────────────────┘│

3.2 每层职责（诚实标注对应 / 缺失）

四、运行流程：不是 ReAct，是分阶段门控工作流

4.1 模拟一次请求

用户输入 "Let's make a react todo list"：

[会话启动]
SessionStart hook → hooks/session-start 读取 using-superpowers
→ 包裹 <EXTREMELY_IMPORTANT> 注入模型上下文
▼
[用户消息]
using-superpowers 强制"做任何事前先检查技能"
→ 命中 brainstorming（frontmatter："任何创造性工作前必须用"）
▼
[① BRAINSTORMING]
探索上下文 → 逐个澄清 → 提 2-3 方案
→ HARD-GATE：未批准设计前禁写任何代码/脚手架
→ 写设计文档 docs/superpowers/specs/…-design.md 并 commit
→ 规格自检 + 用户复核
│ 用户批准
▼
[② WRITING-PLANS]
拆成 2-5 分钟粒度任务（精确路径 + 完整代码 + 验证步骤）
→ 写计划文档 docs/superpowers/plans/…-plan.md
│ 用户批准
▼
[③ EXECUTE]（二选一）
路径A: subagent-driven-development
每任务派"全新子代理"实现+测试+commit+自审
→ 生成评审包，派"任务评审员"做两阶段评审（规格+质量）
→ Critical/Important 问题 → fix loop（最多 5 轮）
→ 全部完成 → 派"整分支最终评审"（最强模型）
路径B: executing-plans
当前会话分批执行，带人工检查点（无子代理能力时）
▼
[④ FINISHING-A-DEVELOPMENT-BRANCH]
验证测试 → 给用户选项（merge / PR / 保留 / 丢弃）→ 清理 worktree

4.2 关于 Plan/Act/Observe/Reflect

本项目没有单层 ReAct 循环代码，但"规划-行动-观察-反思"在两个尺度上体现：

• 任务尺度（核心反射）：实现 → 评审 → 发现问题 → 修复 → 再评审，最多 5 轮（fix loop），第 5 轮未过进 breaker 裁决（park 或 STOP/BLOCKED）。
• 调试尺度：systematic-debugging 的 4 阶段根因法（root-cause-tracing / defense-in-depth / condition-based-waiting）。

诚实表述：Reflection 以"提示词工作流 + 评审闸门"的形式存在，而非代码模块。 这正是理解这个项目的核心——它证明了"Agent 的自我监督"可以不靠代码，靠可审计的提示词。

五、核心代码分析：入口、State、Tool

声明：没有 main.py → AgentExecutor → Planner → Tool 调用链。下面是本项目语境下的等价物。

5.1 真正的"启动链路"（Agent 入口）

宿主会话启动
└─ SessionStart hook (hooks/hooks.json 配置)
└─ run-hook.cmd (polyglot: 同时是 .cmd 和 bash)
└─ hooks/session-start (bash)
├─ 读取 skills/using-superpowers/SKILL.md
├─ escape_for_json() 转义
└─ 按宿主输出不同 JSON 形状：
Cursor → {"additional_context": "…"}
Claude Code → {"hookSpecificOutput": {"additionalContext": "…"}}
Copilot CLI → {"additionalContext": "…"}

这一步 = 把"你拥有 superpowers"注入模型，是整个系统的真正入口。它没有任何 LLM 逻辑，只是"读文件 + 拼 JSON + 按宿主格式输出"。

5.2 "路由核心"：using-superpowers

• 文件：skills/using-superpowers/SKILL.md
• 作用：元技能，强制"在任何响应/动作前先检查技能"，并带一张 Red Flags 表，专门捕获 Agent 的自我合理化（"这太简单不需要技能"、"我先看下代码" 都是 red flag）。
• 它不是代码，是提示词，但功能等价于一个前置拦截路由器。

5.3 "执行引擎"：subagent-driven-development + 脚本

控制器（主会话）
├─ scripts/sdd-workspace PLAN_FILE → 创建本计划的隔离 workspace
├─ scripts/task-brief PLAN_FILE N → 抽单任务简报（不把整个 plan 喂给子代理）
├─ 派发 implementer 子代理（携带 brief + report 路径）
├─ scripts/review-package PLAN_FILE BASE HEAD → 生成评审 diff 包
└─ 派发 task-reviewer / re-reviewer 子代理

三个工程要点：

5.4 State 设计（重点）

本项目没有运行时 State 类。 状态被显式外化到文件系统，原因写在 SKILL.md 里："Conversation memory does not survive compaction"（会话压缩后上下文会丢）。

设计哲学：运行时状态易失 → 把 source of truth 放磁盘文档，而非 Agent 内存。这与传统 Agent 把 state 放 State dict / checkpoint DB 思路一致，只是实现手段是纯文件 + Git。

5.5 Tool 系统

• 注册：不注册。工具是宿主原生的（Read/Write/Edit/Bash/Git/Task 子代理）；通过 references/<harness>-tools.md 做"动作→工具名"映射（如 "dispatch a subagent" → 调 Task）。
• 防止滥用：无代码级护栏。防线是 ① HARD-GATE ② 禁止多实现子代理并行 ③ 控制器自己不修 bug（"controller fixes skip review"）④ 依赖宿主权限系统。

六、工程可靠性（重点：诚实标注强项与缺位）

6.1 Guardrails

例外（真·代码级安全）：server.cjs 这个 WebSocket 服务极其扎实——

• per-session 随机 token（URL ?key= + HttpOnly SameSite Cookie 双通道）
• crypto.timingSafeEqual 常量时间比较（防时序攻击）
• isAllowedWebSocketOrigin 防 DNS 重绑定
• isRegularFileInsideContentDir 防路径穿越（拒符号链接/越界）
• idle timeout + ownerPID 看门狗（宿主死了/闲置自动关）
• MAX_FRAME_PAYLOAD 防超大帧

这证明作者懂代码级安全，只是把"Agent 行为护栏"放在了提示词层。这本身就是一个值得讨论的架构取舍。

6.2 Human-in-the-loop（最大强项）

闸门遍布阶段边界：brainstorming 设计批准（HARD-GATE）、规格复核、计划批准、finishing-a-branch 的 merge/PR/保留/丢弃 选项。

缺位：在 subagent-driven-development 下，任务之间不暂停询问（"Do not pause to check in"），追求自主连续执行。HITL 在阶段边界强、任务内部弱——这是吞吐与质量的平衡。可改进：高风险任务（生产库迁移、对外 API 变更）应加任务级确认。

6.3 Evaluation（本仓库缺失，外部有）

• 本仓库内：仅插件基础设施测试 + brainstorm server 的 Node 行为测试（auth/lifecycle/ws-protocol）。
• 外部：superpowers-evals 的 drill 工具——驱动真实 tmux 会话（Claude Code/Codex/Gemini CLI）+ LLM verifier 判定技能合规度。
• 准确率/成功率/工具调用成功率以"真实会话 + LLM 法官"为主；无独立幻觉检测模块，靠两阶段评审兜底。

6.4 Reflection（存在且成熟，全在提示词里）

• 任务级：fix loop（评审→发现→修复→再评审，5 轮）→ breaker 裁决。
• 调试级：systematic-debugging 4 阶段根因法。
• 反馈级：receiving-code-review / requesting-code-review（Critical 阻断）。
• 防自欺级：各 SKILL 的 Red Flags / Common Rationalizations 表（"close enough on spec compliance"、"reviews slow the loop down" 都是点名对象）。

七、源码阅读路线（7 天，不要从头读到尾）

• Day 1 定位与哲学：README.md → CLAUDE.md（94% 拒绝率那段）→ AGENTS.md。建立"行为塑造系统而非 runtime"的心智。
• Day 2 真正的运行时（注入机制）：using-superpowers/SKILL.md → hooks/session-start → hooks/run-hook.cmd → docs/porting-to-a-new-harness.md（Part 1–3：三组件、三形状、能力清单）。最该抠透。
• Day 3 工作流前半：brainstorming/SKILL.md（dot 图、HARD-GATE、Red Flags）→ writing-plans/SKILL.md。看人类闸门如何嵌进指令。
• Day 4 执行引擎：subagent-driven-development/SKILL.md（process.dot、fix loop、breaker、model selection）→ executing-plans → 三个脚本（sdd-workspace/task-brief/review-package）。
• Day 5 质量与可靠性：requesting-code-review/、receiving-code-review/、verification-before-completion/、systematic-debugging/、test-driven-development/。
• Day 6 唯一的真·代码：server.cjs（手写 WebSocket、鉴权、防重绑定、路径穿越、看门狗）→ 对照 tests/brainstorm-server/*（学怎么测安全）。
• Day 7 演进与评测：docs/plans/、docs/superpowers/specs/（看他们用自己这套方法迭代自己）→ tests/ 总览 → 去 superpowers-evals 了解 drill。

八、工程启示与演进方向

8.1 从 Superpowers 能学到的工程思想（10 点）

8.2 五个企业级演进方向

附：Agent 工程概念映射速查