Agent Harness

Agent Harness 🦾

「agent の output 品質は、agent そのものより harness で決まる。」

Core principle: agent が何を達成するかは、与えた action space / observation / recovery / context budget の 4 軸で 8 割決まる。 agent を改善するなら、まず harness を改善せよ。

いつ使うか

• AI agent (Claude Code subagent / VP Stand actor / 自作 LLM agent) の completion rate が低い
• agent が同じ tool を繰り返し叩く / drift する / 諦める
• 新しい agent を設計する (例: VP の Stand Actor Framework、 ccwire mesh の worker)
• 既存 agent の cost-per-task が高い

VP-D11 の StandActor trait 階層 (Renderable / Headless / Pty) や、VP worker lane の autonomous mode を設計するときの判断軸として使う。

いつ使わないか

Core Model — agent 品質の 4 軸

agent output の上限は次の 4 軸の 積 で決まる:

output_quality = action_space × observation × recovery × context_budget

どれか 1 軸でも壊れていると、他軸を上げても掛け算で頭打ちになる。

1. Action Space Quality

agent が呼べる tool / cmd の集合 の質。

設計原則

• stable, explicit な tool 名 — 動詞主体 (create_pane, send_message)、 sema 揺れない
• schema-first で narrow な input — Optional 多用は迷う、必須/任意を明示
• deterministic な output 形 — 同じ input は同じ shape を返す
• catch-all tool は最終手段 — do_anything は agent を迷わせる

Granularity rule

VP の Stand actor で言うと:

• Pty capability = micro (PTY 起動は high-risk)
• Renderable.render() = medium (普通の event handle)
• composite dispatch_event() macro は避ける (個別 tool で十分)

2. Observation Quality

tool response が agent に何を伝えるか。

すべての tool response に含めるべき field:

Observation の悪例 vs 良例

❌ 悪い: "OK"
❌ 悪い: "Error"
❌ 悪い: 1000 行の raw log dump

✅ 良い:
{
  "status": "warning",
  "summary": "Lane created but TopicRouter binding pending",
  "next_actions": ["call lane.bind_topic()", "verify with /api/lanes"],
  "artifacts": ["lane-abc123"]
}

3. Recovery Quality

error path で agent が自力で立ち直れるかどうか。

すべての error response に必須:

• root cause hint — 何が失敗したか (retry で解決するか、別 path が必要か)
• safe retry instruction — backoff 推奨、idempotency 保証の有無
• explicit stop condition — どこまで retry したら諦めるか

Recovery の悪例 vs 良例

❌ 悪い: { "error": "failed" }
❌ 悪い: { "error": "Internal Server Error" }

✅ 良い:
{
  "status": "error",
  "error_kind": "transient_network",
  "summary": "TheWorld /api/lanes timed out",
  "root_cause": "SP at port 33002 likely starting up",
  "retry": {
    "safe": true,
    "backoff_ms": 2000,
    "max_attempts": 3
  },
  "stop_if": "After 3 retries, call vp world status"
}

4. Context Budget Quality

agent の context window をどう使うか。

設計 rule

• system prompt は最小・不変 — 大きい guidance は skill に追い出す
• 長 document は inline せず file 参照 — Read("path") で必要時だけ
• phase boundary で compact — 任意 token threshold ではなく、論理境界で
• skill は on-demand load — Skill tool で必要時起動、常時 system prompt に積まない

VP の context budget 設計例:

• ECC plugin 全体 enable は ~150 skill が常時 context → disable で軽減
• creo-memories memory は search → get_memory で必要時のみ取得
• ccwire mesh は session 別 context、共有は memory + msgbox で

Architecture pattern guidance

VP の Stand Ensemble は Hybrid 型: HD (Claude CLI) は ReAct、 PP/GE/HP は Event-driven (function-call 寄り)。

Benchmarking

agent harness を変えたら、必ず metric を track:

creo-memories 連携

agent harness の改善は 再利用可能な学びになりやすい。memory に積極的に pin:

VP の Stand Actor Framework のような 長期育成する harness では、memory に history 残すと進化が tractable になる。

chronista 文脈での適用例

例 1: VP-D11 StandActor trait 階層の設計

D11-A で StandActor 基底 + Renderable / Headless / Pty trait を設計するとき:

• Action space: 各 trait が提供する method (handle / render / build_pty)
• Observation: Event payload (CreoContent envelope) で構造化
• Recovery: Stand failure 時の causation tree 経由 introspection
• Context budget: live_memory / snapshot_memory で per-pane scope に分離

→ agent-harness の 4 軸を design 議論の checklist として使う。

例 2: worker lane の autonomous mode

Worker が autonomous で走るとき:

• Action space: wire_send (Q&A) / wire_receive / 直接 tool 群
• Observation: 自分の tool result + lead からの reply
• Recovery: 判断迷ったら wire_send で lead に聞く ("safety valve")
• Context budget: lead が渡す指示 + worker local 作業 context

→ relay モード vs autonomous モードの harness 差 をこの 4 軸で記述すると整理しやすい。

例 3: Subagent 起動時の prompt 設計

Agent tool で subagent を起動するとき (例: council の Skeptic / Pragmatist / Critic):

• Action space: subagent_type で絞る (general-purpose vs Explore)
• Observation: 短く構造化された return format を強制
• Recovery: subagent が立ち往生したら return で escalate signal
• Context budget: parent の history を渡さない (anti-anchoring)

NG パターン

他スキルとの住み分け

発火の目安

• 新規 agent / Stand / worker を設計するとき
• 既存 agent の completion rate / pass@k が悪化
• 同じ failure mode が繰り返し発生
• benchmark で cost per task が上がっている
• VP のような 長期育成する harness の major version up

アンチパターン

Anti-pattern: Tool 過多

• 症状: 似た sema を持つ tool が 10 個以上
• 問題: agent が選択に迷う、systematic error 増
• 対策: 統合・rename、 micro/medium/macro 階層で整理

Anti-pattern: Opaque observation

• 症状: tool が "OK" "failed" のような不透明 string を返す
• 問題: agent が次 action を決められない
• 対策: status / summary / next_actions / artifacts 必須化

Anti-pattern: Error-only output

• 症状: error message だけで recovery hint なし
• 問題: agent が retry storm に陥る
• 対策: root_cause + retry policy + stop_if 必須

Anti-pattern: Context overload

• 症状: 関係ない reference を context に積む
• 問題: signal/noise が下がり quality 低下
• 対策: phase boundary で compact、 skill on-demand

クイックリファレンス

参考

• 元 skill: ECC agent-harness-construction (Everything Claude Code)
• 関連 design: VP の Stand × Pane × Lane (mem D11 Pane Revival)
• 姉妹スキル: agent-introspection, council, santa-method

Source: chronista-club/claude-plugin-chronista-style — distributed by TomeVault.