エージェントの目で見る: Claude Code におけるツール設計
エージェントハーネスを構築する上で最も難しいことの一つは、そのツールを作ることです。
Claude は完全にツール呼び出しを通じて行動しますが、Claude API では bash、Skills、コード実行などのプリミティブを使って、さまざまな方法でツールを構築できます（Claude API でのプログラマティックなツール呼び出しについては、@RLanceMartin の新しい記事で詳しく読めます）。
では、エージェントのツールをどう設計すればよいのでしょうか？ bash やコード実行のような汎用ツールを1つ与えるべきでしょうか？ それとも、ユースケースごとに50個の専門ツールを用意すべきでしょうか？
モデルの立場に立ってみてください。難しい数学の問題を出されたとします。それを解くためにどんなツールが欲しいですか？ それはあなた自身のスキルセット次第です。
紙が最低限ですが、手計算に制限されます。電卓があればもっとよいですが、高度なオプションの使い方を知っている必要があります。最速かつ最も強力なのはコンピュータですが、それを使ってコードを書き実行する方法を知っていなければなりません。
これはエージェントを設計するための有用なフレームワークです。エージェント自身の能力に合った形のツールを与えたいのです。しかし、その能力が何かをどう知ればよいのでしょうか？ 注意深く観察し、出力を読み、実験する。エージェントの目で見ることを学ぶのです。
エージェントを構築しているなら、私たちと同じ問いに直面するでしょう。いつツールを追加し、いつ削除し、その違いをどう見分けるか。ここでは、Claude Code を構築しながら私たちがどう答えてきたかを紹介します。最初に間違えたところも含めて。
AskUserQuestion ツールで引き出しを改善する
AskUserQuestion ツールを構築する際、私たちの目標は Claude が質問する能力（しばしばエリシテーションと呼ばれます）を向上させることでした。
Claude はプレーンテキストで質問することもできましたが、それらの質問に答えるのには不必要に時間がかかるように感じました。このフリクションをどう下げ、ユーザーと Claude 間のコミュニケーション帯域をどう広げられるでしょうか？
試み1: ExitPlanTool の編集
最初に試したアプローチは、ExitPlanTool にパラメータを追加して、プランと並んで質問の配列を持たせることでした。これは実装が最も簡単でしたが、プランと同時にそのプランに関する質問セットを求めることで Claude を混乱させました。ユーザーの回答がプランの内容と矛盾したらどうなるのか？ Claude は ExitPlanTool を2回呼ぶ必要があるのか？ この戦術は機能しないと分かり、最初からやり直しました（ExitPlanTool を作った理由については、プロンプトキャッシングに関する投稿で詳しく読めます）。
試み2: 出力フォーマットの変更
次に、Claude の出力指示を更新して、質問するために使えるわずかに変更された Markdown フォーマットを提供させることを試みました。例えば、括弧内に選択肢を含む箇条書きの質問リストを出力させることができました。それをパースしてユーザー向けのUIとしてフォーマットすることができます。
Claude はこのフォーマットを通常は生成できましたが、安定的にはできませんでした。余分な文章を追加したり、選択肢を落としたり、構造を完全に放棄したりしました。次のアプローチへ。
試み3: AskUserQuestion ツール
最終的に、Claude がいつでも呼び出せるツールを作成するに至りましたが、特にプランモードの際に呼び出すようプロンプトしました。ツールがトリガーされると、モーダルを表示して質問を表示し、ユーザーが回答するまでエージェントのループをブロックしました。
このツールにより Claude に構造化された出力を促すことができ、Claude がユーザーに複数の選択肢を提示することを確実にするのに役立ちました。また、Agent SDK での呼び出しや Skills での参照など、ユーザーがこの機能を組み合わせて使う方法も提供しました。
最も重要なのは、Claude がこのツールを呼び出すのを好んでおり、その出力がうまく機能したことです。結局のところ、どれほど優れた設計のツールでも、Claude がその呼び出し方を理解していなければ機能しません。
これが Claude Code におけるエリシテーションの最終形態でしょうか？ おそらく違います。Claude がより高性能になるにつれ、それに提供するツールも進化しなければなりません。次のセクションでは、かつて役立っていたツールが邪魔になり始めたケースを紹介します。
能力の向上に合わせた更新: Tasks と Todos
Claude Code を最初にローンチしたとき、モデルが軌道を維持するために Todo リストが必要であることに気づきました。Todo は開始時に書き込み、モデルが作業を進める中でチェックオフしていけます。そのために Claude に TodoWrite ツールを提供しました。これは Todo を書き込みまたは更新し、ユーザーに表示するものです。
しかし、それでも Claude がやるべきことを忘れてしまうことがよくありました。これに対応するため、5ターンごとに Claude の目標をリマインドするシステムリマインダーを挿入しました。
モデルが改良されるにつれ、Todo リストが制約になることが分かりました。Todo リストのリマインダーを送られると、Claude は方針を変える必要があると気づいたときでもリストに固執しなければならないと考えてしまいました。また、Opus 4.5 がサブエージェントの使用もかなり上手になりましたが、サブエージェント間で共有の Todo リストをどう調整できるでしょうか？
これを踏まえ、TodoWrite 機能を Task ツールに置き換えました。Todo がモデルを軌道に維持することに焦点を当てているのに対し、Tasks はエージェント間のコミュニケーションを支援します。Tasks には依存関係を含めたり、サブエージェント間で更新を共有したりでき、モデルはそれを変更したり削除したりもできます。
モデルの能力が向上するにつれ、モデルがかつて必要としていたツールが今や制約になっている場合があります。どのツールが必要かについての以前の前提を常に見直すことが重要です。これが、かなり類似した能力プロファイルを持つ少数のモデルセットをサポートすることが有用な理由でもあります。
検索インターフェースの設計
私たちが構築した中で最も影響の大きいツールは、Claude が自分自身のコンテキストを見つけられるようにするものです。
Claude Code が社内で最初にリリースされたとき、私たちは RAG を使用していました。ベクトルデータベースがコードベースを事前にインデックスし、ハーネスが各レスポンスの前に関連するスニペットを取得して Claude に渡していました。RAG は強力で高速でしたが、インデックス作成とセットアップが必要であり、さまざまな環境で壊れやすくなることがありました。最も重要なことに、Claude にこのコンテキストは与えられており、自らコンテキストを見つけているわけではありませんでした。
しかし、Claude がウェブを検索できるのなら、コードベースも検索できるはずではないでしょうか？ Claude に Grep ツールを与えることで、ファイルを検索し自分自身でコンテキストを構築させることができました。
Claude が賢くなるにつれ、適切なツールが与えられればコンテキストの構築がますます上手になります。
Agent Skills を導入した際、私たちは段階的開示（progressive disclosure）の考え方を形式化しました。これにより、エージェントは探索を通じて関連するコンテキストを段階的に発見できます。
Claude はスキルファイルを読むことができ、それらのファイルはモデルが再帰的に読める他のファイルを参照できます。実際、Skills の一般的な使い方は、API の使い方やデータベースへのクエリ方法の指示を与えるなど、Claude に検索能力を追加することです。
1年の間に、Claude はコンテキストを自分で構築することがほとんどできない状態から、必要な正確なコンテキストを見つけるために複数のファイル層にわたるネストされた検索ができるようになりました。
段階的開示は今や、ツールを追加せずに新しい機能を追加するために私たちが使う一般的なテクニックです。次のセクションでは、その理由を説明します。
段階的開示: Claude Code Guide エージェント
Claude Code は現在約20のツールを持っており、私たちのチームは Claude が最も効果的であるためにそれらすべてが必要かどうかを頻繁に見直しています。新しいツールを追加するハードルは高く、なぜならそれはモデルに考えるべき選択肢を1つ追加するからです。
例えば、Claude は Claude Code の使い方について十分な知識を持っていないことに気づきました。MCP の追加方法やスラッシュコマンドの機能について質問すると、回答できませんでした。
この情報をすべてシステムプロンプトに入れることもできましたが、ユーザーがこれについて尋ねることは稀であったため、コンテキストの腐敗を招き、Claude Code の主な仕事であるコードを書くことの妨げになったでしょう。
代わりに、段階的開示を試みました。必要なときに読み込み検索できるドキュメントへのリンクを Claude に与えました。これは機能しましたが、Claude はユーザーが1文で得られたはずの回答を見つけるために、大量のドキュメントをコンテキストに取り込んでしまいました。
そこで Claude Code Guide を構築しました。これは、ユーザーが Claude Code 自体について質問するたびに Claude が呼び出すサブエージェントです。サブエージェントは独自のコンテキストウィンドウでドキュメント検索を行い、検索方法と何を抽出すべきかについての詳細な指示に従い、回答だけを返します。メインエージェントのコンテキストはクリーンに保たれます。
これは完璧なソリューションではありませんが（Claude は自身のセットアップ方法を尋ねられると今でも混乱することがあります）、新しいツールを追加することなく Claude のアクションスペースにものを追加することができました。
エージェントの目で見ることはサイエンスではなくアート
モデルのためのツール設計は、サイエンスであると同時にアートでもあります。使用するモデル、エージェントの目標、そしてそれが動作する環境に大きく依存します。
私たちの一番のアドバイスは？ 頻繁に実験し、出力を読み、新しいことを試す。そして最も重要なこととして、エージェントの目で見ようとすることです。
今すぐ Claude Code を始めましょう。
著者について: Thariq Shihipar は Anthropic のメンバーオブテクニカルスタッフで、Claude Code に取り組んでいます。