harness-roles

name	harness-roles
description	帽子系统执行引擎。接收 harness-onboard 输出的 resolved_slots JSON，逐插槽串行调度新鲜 subagent，追踪 token 消耗换算估算费用，按 overdraft 策略处理超预算，在 milestone 节点等待用户确认。

harness-roles：帽子系统 + 预算管理

输入

由 harness-dev 调用，接收 harness-onboard 输出的 JSON（字段说明见 harness-onboard Step 7）：

{
  "work_type": "...",
  "requirement": "...",
  "impact_analysis": "...",
  "resolved_slots": [...],
  "role_config": { ... },
  "overdraft": "ask|allow|deny",
  "session_overrides": "..."
}

---

执行流程

按 resolved_slots 顺序逐插槽执行，不跳过，不改变顺序（顺序由 harness-onboard 已确定）。

---

角色调度原则

每个角色是一个新鲜 subagent，通过 Claude Code 的 Agent 工具派发，不继承主会话历史（防止 context rot）。

模型选择：Claude Code Agent 工具当前不支持直接指定模型。通过在 prompt 开头注入角色指令来引导行为风格，但无法强制约束实际使用的模型。

⚠️ 已知限制：model 字段是行为风格指引，不保证实际路由到对应模型。实际模型由 Claude Code 根据任务复杂度自动选择。费用估算基于 model 字段计算，若实际路由到更便宜的模型，实际费用会低于估算；若路由到更贵的模型，则可能超支。

Role prompt injections (English — these are instructions to the model):

• Planner：You are the Planner for this development session. Think deeply, reason step by step. Output a complete design document and implementation plan.
• Builder：You are the Builder. Focus on efficient implementation. Follow TDD strictly: write the test first, then the minimum code to pass it. Output working, tested code.
• Critic：You are the Critic — an external reviewer with no knowledge of the design intent. You see only the diff and the requirement. Judge independently and critically.
• Finalizer：You are the Finalizer. Your job is clean and efficient: create the PR and update documentation. Complete the task with minimal fuss.

上下文注入规则（每个角色只收到它需要的信息）：

角色	收到什么	工具白名单	Turn 限制
Planner	需求 + 影响面分析 + constraints.md	Read, Glob, Grep, WebSearch, Write	30
Builder	需求 + Planner 产出的计划 + 相关代码	Read, Write, Edit, Glob, Grep, Bash	80
Critic/Evaluator	diff + 需求 + constraints（不给设计方案）	Read, Write, Bash, WebSearch	40
Finalizer	需求 + 全部角色产出摘要	Read, Write, Bash	20
checkpoint	无 subagent	—	—

MCP 配置（按需启用）：

角色	MCP Server	用途
Evaluator（对抗视角）	playwright	黑盒测试，从不读 src/ 目录
Evaluator	github	查询 CI 状态，评论 PR
Planner	websearch	调研技术方案

evaluator 黑盒约束（绝对禁止）：

Evaluator 在 Playwright MCP 模式下，禁止读取以下目录的源码：

src/, app/, lib/, components/, pages/, ui/

违反此约束的 Review 结果无效，必须重新运行。

---

插槽执行循环

对 resolved_slots 中的每个插槽：

1. 启动提示（非 checkpoint 类型）

🎩 {角色帽子} {角色名} 启动  [{slot.name}: {skill 简称}]  ({model} · 预算 ${budget} 估算)

2. checkpoint 类型处理

若 slot.type == "checkpoint"：

⏸ 检查点：{slot.message}

确认后继续？(y / 有问题说一下)

等待用户输入后进入下一插槽。不消耗预算，不派发 subagent。

3. skill 类型处理

Skill 解析 + Fallback 逻辑：

slot.skill = "superpowers:brainstorming"
    ↓
检查 ~/.claude/skills/superpowers:brainstorming/ 是否存在
    ↓
存在 → 使用该 skill
不存在 → 检查 slot.fallback 字段
    ↓
fallback = "brainstorming"
    ↓
检查 ~/.claude/skills/brainstorming/ 是否存在（Superpowers 内置名）
    ↓
存在 → 使用 fallback
不存在 → 使用内置 fallback prompt（见下方 fallback prompt 表）

Fallback prompt 表（当 skill 和 fallback 都不可用时）：

skill	fallback prompt
brainstorming	引导式提问 → 方案设计 → 保存到 .harness/plans/
subagent-driven-development	按 plan 执行任务，遵守 TDD，self-verify 后交接
finishing-a-development-branch	验证测试 → 展示 merge/PR/keep/discard 选项

派发 subagent：通过 Agent 工具派发，带工具白名单、Turn 限制、MCP 配置（见上方 per-agent 配置）。

构造 subagent prompt（按上方上下文注入规则 + 工具白名单），通过 Agent 工具派发。

per-agent 工具白名单约束：

Planner（planner）：
  allowedTools: Read, Glob, Grep, WebSearch, Write
  disallowedTools: Edit, Bash, NotebookEdit
  maxTurns: 30
  goal: Deep investigation + full plan. No code implementation.

Builder（builder）：
  allowedTools: Read, Write, Edit, Glob, Grep, Bash
  disallowedTools: NotebookEdit, WebSearch
  maxTurns: 80
  permissionMode: acceptEdits
  goal: Strict TDD. Write test first, then minimum code to pass it.

Evaluator/Critic（critic）：
  allowedTools: Read, Write, Bash, WebSearch
  disallowedTools: Edit, Glob, Grep, NotebookEdit
  maxTurns: 40
  mcpServers: playwright  # if Playwright MCP is available
  goal: Black-box evaluation. Judge by running results only. Never read source code.

Finalizer（finalizer）：
  allowedTools: Read, Write, Bash
  disallowedTools: Edit, Glob, Grep, NotebookEdit, WebSearch
  maxTurns: 20
  goal: Clean finish. Create PR and docs. No major rewrites.

⚠️ 预防性预算检查（在派发前执行）：

基于 skill 类型和任务复杂度，估算本角色本次消耗量：

skill 类型	典型输入 tokens	典型输出 tokens	估算单次消耗
brainstorming	~3,000	~1,500	$0.09 (sonnet)
subagent-driven-development	~5,000	~3,000	$0.15 (sonnet)
writing-plans	~4,000	~2,000	$0.12 (sonnet)
test-driven-development	~4,000	~2,500	$0.13 (sonnet)
harness-review	~3,000	~1,000	$0.08 (sonnet)
finishing-a-development-branch	~2,000	~500	$0.04 (sonnet)
其他 / 未知类型	~3,000	~1,500	$0.09 (sonnet)

检查逻辑：

• 估算消耗 ≤ 剩余预算的 80%：直接派发
• 估算消耗在剩余预算 80%~100% 之间：派发前预警，告知用户"即将超支"
• 估算消耗 > 剩余预算：触发透支询问（见透支处理），不先派发

⚠️ {角色名} 预算即将耗尽
  剩余：${remaining}（估算）
  预计消耗：${estimated}（估算）
  预计超出：${overage}

  A. 继续执行（超支约 ${overage}）
  B. 停在这里
  C. 降级到更便宜的模型（省约 {pct}%）

4. 执行与后置预算检查

派发 subagent。subagent 完成后，计算本角色实际消耗的 token 数，换算估算费用（见费用估算）。

后置检查（角色返回后）：

• 剩余 > 20%：继续
• 剩余 ≤ 20%：触发透支询问（见透支处理）
• 已超出：按 overdraft 策略处理

5. 里程碑节点

若 slot.milestone == true，在角色完成后强制暂停：

🏁 里程碑：{slot.name} 完成

  {角色产出摘要（前300字）}

  确认继续进入下一步？(y / 有问题说一下)

等待用户确认后进入下一插槽。

---

费用估算

价格表（用于 token → 美元换算）：

模型	输入 $/M tokens	输出 $/M tokens	估算均价 $/M
claude-opus-4-6	$15	$75	$30
claude-sonnet-4-6	$3	$15	$6
claude-haiku-4-5	$0.8	$4	$1.2

估算公式：cost ≈ (input_tokens × input_price + output_tokens × output_price) / 1,000,000

所有金额显示均附注"（估算）"，提示非精确计费。

---

透支处理

透支可能发生在两个阶段：预防阶段（派发前已预知会超支）和反应阶段（角色执行后才知道超支）。两种场景共用同一套策略。

剩余 ≤ 20% 时（反应性预警）：

⚠️ {角色名} 预算剩余约 ${remaining}（估算），预计还需约 ${needed}
继续透支？
  A. 透支继续（本次约 +${needed}）
  B. 停在这里，由我接手
  C. 降级到 {更便宜的模型} 完成剩余工作（省约 {pct}%）

overdraft 策略处理：

策略	预算耗尽时的行为
ask	展示上方透支询问，等待用户选择
allow	静默继续，完成后汇报实际超出金额
deny	立即终止角色，将已产出内容标记 [TRUNCATED] 传入下一插槽，输出：⛔ {角色名} 预算耗尽（deny 策略），已截断并跳至下一步

---

完成汇总

所有插槽执行完毕后输出：

✅ 所有角色执行完毕

💰 本次开发估算费用：
  {角色名}: ${actual} / ${budget} 估算
  ...
  ─────────────────────
  合计：${total_actual} / ${total_budget} 估算

{如有超预算角色}
  ⚠️ {角色名} 超出预算 ${overage}（估算）

然后将控制权返回给 harness-dev，由 harness-dev 执行 Step 4（上下文沉淀）。