エージェントハーネスを構築する上で最も難しい部分の 1 つは、そのアクションスペースを設計することです。
Claude はツール呼び出しを通じて動作しますが、Claude API では bash、スキル、最近ではコード実行などのプリミティブを使ってツールを構築する方法がいくつかあります（Claude API でのプログラムによるツール呼び出しの詳細は、@RLanceMartin の新しい記事をご覧ください）。
これらすべての選択肢を考慮すると、エージェントのツールをどのように設計すればよいでしょうか？コード実行や bash のようなツールが 1 つだけで十分ですか？エージェントが遭遇する可能性のあるユースケースごとに 50 のツールがあったらどうでしょうか？
モデルの立場に立って考えるために、難しい数学の問題を与えられたと想像してみてください。それを解くためにどのようなツールが必要でしょうか？それはあなた自身のスキルによります！
紙が最低限ですが、手計算に制限されます。電卓の方が良いですが、高度なオプションを操作する方法を知っている必要があります。最速で最も強力なオプションはコンピュータですが、コードを書いて実行する方法を知っている必要があります。
これはエージェントを設計するための有用なフレームワークです。エージェントの能力に合わせたツールを与えたいものです。しかし、その能力をどうやって知るのでしょうか？注意を払い、出力を読み、実験します。エージェントのように見ることを学びます。
以下は、Claude Code を構築する際に Claude に注意を払って学んだ教訓です。
エリシテーションの改善と AskUserQuestion ツール
AskUserQuestion ツールを構築する際、私たちの目標は Claude が質問をする能力（しばしばエリシテーションと呼ばれる）を改善することでした。
Claude はプレーンテキストで質問することもできましたが、それらの質問に答えるのに不必要に時間がかかっているように感じました。どうすればこの摩擦を減らし、ユーザーと Claude の間のコミュニケーションの帯域幅を増やせるでしょうか？
試行 1 - ExitPlanTool の編集
最初に試したのは、ExitPlanTool に計画と一緒に質問の配列を持つパラメータを追加することでした。これは実装するのが最も簡単でしたが、計画と計画に関する質問セットを同時に求めているため、Claude を混乱させました。ユーザーの回答が計画と矛盾した場合はどうなるでしょうか？Claude は ExitPlanTool を 2 回呼び出す必要があるでしょうか？別のアプローチが必要でした。
（ExitPlanTool を作成した理由の詳細は、プロンプトキャッシングに関する記事をご覧ください）
試行 2 - 出力形式の変更
次に、Claude の出力指示を変更して、質問をするために使用できる少し修正されたマークダウン形式を提供することを試みました。例えば、括弧内に選択肢がある箇条書きの質問リストを出力するように指示できます。その後、その質問を解析して UI としてフォーマットし、ユーザーに表示できます。
これは私たちが行える最も一般的な変更であり、Claude もこれを出力するのが得意そうに見えましたが、保証されていませんでした。Claude は余分な文を追加したり、オプションを省略したり、まったく異なる形式を使用したりしました。
試行 3 - AskUserQuestion ツール
最終的に、Claude がいつでも呼び出せるツールを作成することに落ち着きましたが、特に計画モード中に呼び出すように促されました。ツールがトリガーされると、モーダルを表示して質問を表示し、ユーザーが回答するまでエージェントのループをブロックしました。
このツールにより、Claude に構造化された出力を促すことができ、Claude がユーザーに複数のオプションを提供することを保証するのに役立ちました。また、ユーザーがこの機能を構成する方法も提供しました。例えば、Agent SDK で呼び出したり、スキルで参照したりできます。
最も重要なのは、Claude がこのツールを呼び出すのを好んでいるように見え、その出力がうまく機能することがわかったことです。最もよく設計されたツールでも、Claude がそれを呼び出す方法を理解していなければ機能しません。
これが Claude Code におけるエリシテーションの最終形態でしょうか？わかりません。次の例でわかるように、あるモデルに有効なものが別のモデルには最適でない場合があります。
機能の更新 - タスクと Todo
Claude Code を初めてリリースしたとき、モデルが軌道に乗るために Todo リストが必要であることに気付きました。Todo は開始時に書き込まれ、モデルが作業を行うにつれてチェックされていきます。これを行うために、Claude に TodoWrite ツールを与えました。これは Todo を書き込んだり更新したり、ユーザーに表示したりします。
しかしそれでも、Claude がやるべきことを忘れているのをよく見かけました。適応するために、5 ターンごとにシステムリマインダーを挿入して、Claude に目標を思い出させました。
しかしモデルが改善されるにつれて、Todo リストを思い出させる必要がなくなっただけでなく、それが制限になっていることに気付きました。Todo リストのリマインダーを送られると、Claude はリストを変更するのではなく、それに固執しなければならないと考えてしまいました。また、Opus 4.5 がサブエージェントを使用するのがはるかに上手くなっているのを見ましたが、サブエージェントは共有の Todo リストでどのように調整すればよいでしょうか？
これを見て、TodoWrite を Task ツールに置き換えました（タスクの詳細はこちらをご覧ください）。Todo がモデルを軌道に乗せることに関するものだったのに対し、タスクはエージェント同士のコミュニケーションを支援することに重点を置いていました。タスクには依存関係を含めたり、サブエージェント間で更新を共有したり、モデルが変更や削除を行うことができました。
モデルの能力が向上するにつれて、かつて必要だったツールが今では制約になっている可能性があります。どのツールが必要かについて、以前の前提を常に見直すことが重要です。また、比較的類似した能力プロファイルを持つ少数のモデルにサポートを絞ることが有用な理由でもあります。
検索インターフェースの設計
Claude にとって特に重要なツールセットは、自身のコンテキストを構築するために使用できる検索ツールです。
Claude Code が最初に登場したとき、Claude のコンテキストを見つけるために RAG ベクトルデータベースを使用していました。RAG は強力で高速でしたが、インデックス作成とセットアップが必要で、さまざまな環境で脆弱になる可能性がありました。さらに重要なのは、Claude がこのコンテキストを与えられていたのであって、自分で見つけていたわけではないことです。
しかし、Claude がウェブを検索できるのであれば、なぜコードベースを検索できないのでしょうか？Claude に Grep ツールを与えることで、ファイルを検索し、自分でコンテキストを構築できるようにしました。
これは、Claude が賢くなるにつれて、適切なツールを与えられればコンテキストを構築するのがますます上手くなるというパターンです。
Agent Skills を導入したとき、プログレッシブディスクロージャーの考え方を形式化しました。これにより、エージェントが探索を通じて関連するコンテキストを段階的に発見できるようになります。
Claude はスキルファイルを読み取ることができ、それらのファイルはモデルが再帰的に読み取れる他のファイルを参照できます。実際、スキルの一般的な使用法は、API の使用方法やデータベースへのクエリ方法の指示を与えるなど、Claude にさらに検索機能を追加することです。
1 年の間に、Claude は自分でコンテキストを構築することがほとんどできなかった状態から、数層のファイルにわたってネストされた検索を行い、必要なコンテキストを正確に見つけられるようになりました。
プログレッシブディスクロージャーは現在、ツールを追加せずに新機能を追加するために使用する一般的な手法です。
プログレッシブディスクロージャー - Claude Code Guide エージェント
Claude Code には現在約 20 のツールがあり、それらすべてが必要かどうかを常に自問しています。新しいツールを追加するハードルは高く設定されています。なぜなら、モデルに考えるための選択肢がもう 1 つ増えるからです。
例えば、Claude が Claude Code の使い方を十分に理解していないことに気付きました。MCP の追加方法やスラッシュコマンドの機能を尋ねても、答えられませんでした。
この情報すべてをシステムプロンプトに入れることもできましたが、ユーザーがこれについて尋ねることは稀であるため、コンテキストロットを引き起こし、Claude Code の主要な仕事であるコード作成を妨げる可能性がありました。
代わりに、プログレッシブディスクロージャーの一形態を試しました。Claude にドキュメントへのリンクを与え、それを読み込んで詳細情報を検索できるようにしました。これは機能しましたが、Claude が正しい答えを見つけるために多くの結果をコンテキストに読み込むことがわかりました。実際に必要なのは答えだけだったにもかかわらずです。
そこで、Claude Code Guide サブエージェントを構築しました。Claude は自分自身について尋ねられたときにこれを呼び出すように促されます。このサブエージェントには、ドキュメントを適切に検索する方法と何を返すべきかに関する広範な指示があります。
これは完璧ではありません。Claude はセットアップ方法を尋ねられたときにまだ混乱することがありますが、以前よりははるかに良くなっています！ツールを追加せずに Claude のアクションスペースに機能を追加することができました。
科学ではなく芸術
ツールの構築方法に関する厳格なルールセットを期待していたなら、残念ながらこのガイドはそうではありません。モデルのツールを設計することは、科学であると同時に芸術でもあります。使用しているモデル、エージェントの目標、動作環境に大きく依存します。
頻繁に実験し、出力を読み、新しいことを試してください。エージェントのように見てください。
