ai-docs

Agent Harness Design: 3 Patterns for Harnessing Claude's Intelligence

Properties1
tagsagents, harness, context, tools, claude-code, prompting

原典: Agent Harness Design: 3 Patterns for Harnessing Claude’s Intelligence

一行要約

harness とは「Claude に何ができないか」についての仮定を software に固めたものであり、モデルが良くなるとその仮定が腐る。だから harness 設計の中心的な問いは「何を足すか」ではなく「何をやめられるか」になる。

This creates a challenge for building with Claude: agent harnesses encode assumptions about what Claude can’t do on its own, but those assumptions grow stale as Claude gets more capable.

これは Claude で構築する上での課題を生む。agent harness は「Claude が自力ではできないこと」についての仮定を埋め込んでいるが、Claude が有能になるにつれてその仮定は古びていく。

要点

harness の定義

An agent harness is the software scaffolding around a model: the loop, tools, context management, and guardrails that turn raw intelligence into a working agent.

agent harness とはモデルを取り巻くソフトウェアの足場である。すなわち、素の知能を動作するエージェントに変えるループ・ツール・context 管理・ガードレールのことだ。

Agent harness design is the practice of deciding what belongs in that scaffolding and, as models improve, what you can take out.

agent harness 設計とは、その足場に何が属するかを決め、そしてモデルが良くなるにつれて何を取り除けるかを決める実践である。

提示されるパターンは3つ。

use what it already knows, ask what you can stop doing, and carefully set boundaries with the agent harness

すでに知っていることを使う、何をやめられるかを問う、そして harness で境界を注意深く設定する

1. harness ではなくモデルに寄せる — Claude が既に知っているものを使う

We suggest building applications using tools that Claude understands well.

Claude がよく理解しているツールを使ってアプリケーションを構築することを勧める。

根拠として挙がるのは 当時の Claude 3.5 Sonnet で、bash とテキストエディタの2つだけで SWE-bench Verified 49%（当時の state of the art）に達した。Claude Code も同じ2つを土台にしている。

Bash wasn’t designed for building agents, but it’s a tool that Claude knows how to use and gets better at using over time.

bash はエージェント構築のために設計されたものではないが、Claude が使い方を知っていて、時間とともに上達していくツールである。

そして Agent Skills / programmatic tool calling / memory tool は、いずれもこの2つの合成として構築されている。

2. harness を削ぎ落とす — 何をやめられるかを問う

Agent harnesses encode assumptions about what Claude can’t do on its own. As Claude gets more capable, those assumptions should be tested.

agent harness は「Claude が自力ではできないこと」についての仮定を埋め込んでいる。Claude が有能になるにつれ、その仮定は検証されるべきである。

やめられる仮定として3つが挙がる。

(a) オーケストレーションを Claude に返す。 「すべてのツール結果は Claude の context window を通って次の行動を決めるべきだ」という仮定。

Rather than the harness deciding that every tool call result is processed as tokens, Claude decides what results to pass through, filter, or pipe into the next call without touching the context window.

すべてのツール呼び出し結果をトークンとして処理すると harness が決めるのではなく、どの結果を通すか・絞るか・context window に触れさせずに次の呼び出しへ流すかを Claude が決める。

BrowseComp で Opus 4.6 に自身のツール出力を絞らせたところ、精度が 45.3% → 61.6%。

(b) context 管理を Claude に返す。 「system prompt はタスク固有の指示で手作りすべきだ」という仮定。

every token added depletes Claude’s attention budget and it is wasteful to pre-load context with rarely used instructions

追加されたトークンはすべて Claude の attention budget を減らすし、めったに使われない指示を context に先読みさせるのは無駄である。

skill の YAML frontmatter だけを先読みし、本体は必要になったときに Claude 自身が読む（progressive disclosure）。context editing はその逆向きで、古くなった context を選択的に取り除く。subagent については、Opus 4.6 で BrowseComp が最良の single-agent 実行より 2.8% 改善した。

(c) context の永続化を Claude に返す。 「memory はモデルの周りの retrieval インフラに頼るべきだ」という仮定。

compaction について、BrowseComp で compaction budget を変えても Sonnet 4.5 は 43% で頭打ちだったのに対し、Opus 4.5 は 68%、Opus 4.6 は 84% まで伸びた（同一条件）。memory folder では BrowseComp-Plus で Sonnet 4.5 が 60.4% → 67.2%。

Pokémon の長時間プレイの対比が具体的で、Sonnet 3.5 は 14,000 ステップ後に31ファイル（うち2つはイモムシ系ポケモンのほぼ重複）を書いて2つ目の街にいた。Opus 4.6 は同じステップ数で10ファイルをディレクトリに整理し、ジムバッジ3つと、自身の失敗から蒸留した learnings ファイルを持っていた。

3. harness の境界は注意深く引く

harness が担うのは UX・コスト・セキュリティの強制である。

キャッシュヒットを最大化する context 設計。 Messages API はステートレスなので、毎ターン過去のすべてを詰め直す必要がある。

Since cached tokens are 10% the cost of base input tokens

キャッシュされたトークンは基本入力トークンの 10% のコストなので

原則内容
Static first, dynamic last安定した内容（system prompt、ツール）を先に置く
Messages for updatesprompt を編集せず、messages に <system-reminder> を追加する
Don’t change modelsセッション中にモデルを切り替えない。キャッシュはモデル固有で、切り替えると壊れる。安いモデルが要るなら subagent を使う
Carefully manage toolsツールはキャッシュ前置に入る。追加・削除で無効化される。動的な発見には tool search を使う（キャッシュを壊さず追加できる）
Update breakpoints複数ターンのアプリケーションでは breakpoint を最新メッセージへ動かす。auto-caching を使う

専用ツールへの昇格は、境界を引きたいときに使う。

Claude doesn’t necessarily know an application’s security boundary or UX surface.

Claude はアプリケーションのセキュリティ境界や UX の表面を必ずしも知らない。

Promoting actions to dedicated tools gives the harness an action-specific hook with typed arguments it can intercept, gate, render, or audit.

アクションを専用ツールに昇格させると、harness は型付き引数を持つアクション固有のフックを得る。それは捕捉・ゲート・描画・監査ができる。

bash はコマンド文字列というどのアクションでも同じ形しか harness に渡さないのが、専用ツールとの違い。判断基準として挙がるのは可逆性で、取り消しにくいアクション（外部 API 呼び出しなど）はユーザー確認でゲートする。edit のような書き込みツールには staleness チェックを入れ、最後に読んでから変わったファイルを上書きしないようにする。

ただしこの昇格の判断も固定ではない。Claude Code の auto-mode は bash に対して「別の Claude がコマンド文字列を読んで安全か判定する」という境界を与えており、専用ツールの必要性を減らしうる。

結論 — dead weight を刈る

In an agent we built for long-horizon tasks, Sonnet 4.5 would wrap up prematurely as it sensed the context limit approaching. We added resets to clear the context window in order to address this “context anxiety.” With Opus 4.5, the behavior was gone. The context resets we built to compensate had become dead weight in the agent harness.

長時間タスク向けに作ったエージェントでは、Sonnet 4.5 は context 上限が近いと察知して早々に切り上げてしまった。この「context 不安」に対処するため context window をクリアするリセットを入れた。Opus 4.5 ではその挙動は消えていた。埋め合わせのために作った context リセットは、agent harness の中で死重になっていた。

Over time, the structure or boundaries in our applications should be pruned based the question: what can I stop doing?

時間とともに、アプリケーションの構造や境界は次の問いに基づいて刈り込まれるべきである。何をやめられるか？

（based the question は原文ママ。based on の脱字と思われる。）

そのまま使える具体例

キャッシュを壊さない配置の順序:

[system prompt] → [tools] → [過去のメッセージ] → [新しい入力] —— 左ほど静的、右ほど動的に置く。

prompt を書き換える代わりに messages 側へ追記する:

<system-reminder> を messages に append する。system prompt を編集すると、キャッシュ前置が無効化される。

原典で言及されている関連文書

バックリンク