エージェントの視点：Claude Codeにおけるツールの設計手法
Seeing like an agent: how we design tools in Claude Code
この記事は 原文 を DeepL で機械翻訳したものである。正確な内容は原文を参照のこと。
エージェント・ハーネスを構築する上で最も難しい点の1つは、そのツールを構築することです。
Claude 完全にツールの呼び出しを通じて動作しますが、Claude APIでは、bash、スキル、コード実行といったプリミティブを用いて、さまざまな方法でツールを構築することができます。（Claude APIにおけるプログラムによるツール呼び出しの詳細については、@RLanceMartin氏の新しい記事をご覧ください）。
では、エージェント用のツールはどのように設計すればよいのでしょうか？bashやコード実行のような汎用ツールを1つ用意するべきでしょうか？それとも、ユースケースごとに1つずつ、計50個の専用ツールを用意するべきでしょうか？
モデルの立場に立って考えてみるために、難しい数学の問題を出されたと想像してみてください。それを解くために、どんなツールが必要だと思いますか？それは、あなた自身のスキルセット次第でしょう！
紙が最も手軽ですが、手計算に制限されてしまいます。電卓の方が良いですが、高度な機能の使い方を知っておく必要があります。最も速くて高性能なのはコンピュータですが、コードを書いて実行する方法を知っておく必要があります。
これはエージェントを設計する上で役立つ枠組みです。エージェントには、その能力に合わせたツールを与えたいものです。しかし、その能力が何であるかをどうやって把握すればよいのでしょうか？注意深く観察し、エージェントの出力を読み取り、実験を重ねるのです。そうすることで、エージェントの視点で物事を見ることを学ぶのです。
エージェントを構築する際、皆さんも私たちと同じような疑問に直面することになるでしょう。つまり、「いつツールを追加すべきか」「いつ削除すべきか」、そして「その判断基準は何か」といった点です。ここでは、Claude Codeを構築する過程で私たちがこれらの疑問にどう答えを出したか、そして当初どこで誤りを犯したかについても含めてご紹介します。
「ASKUSERQUESTION」ツールを活用した情報引き出しの改善
「AskUserQuestion」ツールを開発するにあたり、私たちの目標は、Claudeの質問機能（しばしば「エリシテーション」と呼ばれる）を向上させることでした。
Claudeでは、プレーンテキストで質問をすることも可能ですが、その質問に答えるのに不必要に時間がかかってしまうと感じました。この手間を軽減し、ユーザーとClaude間のコミュニケーションの効率を高めるにはどうすればよいでしょうか？
試行 1：ExitPlanTool の編集
最初に試みたアプローチは、ExitPlanToolにパラメータを追加し、計画書に加えて一連の質問を配列として渡すようにすることでした。これは実装が最も簡単な修正方法でしたが、計画書とその計画書に関する一連の質問を同時に要求することになったため、Claudeが混乱してしまいました。 もしユーザーの回答が計画の内容と矛盾した場合はどうなるのでしょうか？ClaudeはExitPlanToolを2回呼び出す必要があるのでしょうか？この手法ではうまくいかないことが分かっていたため、私たちは一から考え直すことにしました。（ExitPlanToolを作成した理由については、プロンプトキャッシュに関する記事で詳しく説明しています）
試行 2：出力形式の変更
次に、Claudeの出力指示を更新し、質問を生成するために使用できる、わずかに変更を加えたマークダウン形式を出力するようにしました。例えば、括弧内に選択肢を記載した箇条書き形式の質問リストを出力するよう指示することができます。その後、その質問を解析して、ユーザー向けのUIとしてフォーマットすることができます。
Claude 通常はこの形式で出力できたが、安定して動作するとは限らなかった。余分な文が追加されたり、オプションが省略されたり、あるいは構造そのものが完全に崩れてしまったりした。そこで、次のアプローチに移る。
試行 3: AskUserQuestion ツール
最終的に、Claudeがいつでも呼び出せるツールを作成することにしましたが、特にプランモード中にその呼び出しが行われるよう設計しました。ツールが起動すると、質問を表示するモーダルウィンドウを表示し、ユーザーが回答するまでエージェントのループをブロックするようにしました。
このツールにより、Claudeに対して構造化された出力を要求することが可能となり、Claudeがユーザーに複数の選択肢を提供できるようになりました。また、ユーザーはこの機能を組み合わせて利用できるようになりました。例えば、Agent SDK内で呼び出したり、スキル内で参照したりすることが可能です。
何よりも重要なのは、Claudeがこのツールの呼び出しを好んでいるようであり、その出力結果も問題なく機能したことです。結局のところ、たとえ最も優れた設計のツールであっても、Claudeがその呼び出し方法を理解していなければ、機能しないのです。
これがClaude Codeにおける情報引き出しの最終形態なのでしょうか？ そうは思えません。Claudeの機能が充実するにつれて、それを支えるツールも進化していかなければなりません。次のセクションでは、かつては役立っていたツールが、次第に邪魔になり始めた事例を紹介します。
機能の更新：タスクとToDo
Claude Codeを最初にリリースした際、モデルが予定通りに進めるためにはToDoリストが必要だと気づきました。ToDoは最初に作成し、モデルが作業を進めるにつれてチェックを入れていくことができます。このため、Claudeに「TodoWrite」ツールを搭載しました。このツールはToDoを作成・更新し、ユーザーに表示するものです。
しかし、それでもなお、Claudeがやるべきことを忘れてしまうことがよくありました。これに対応するため、5ターンごとにシステムによるリマインダーを挿入し、Claudeにその目標を思い出させるようにしました。
モデルの性能が向上するにつれ、彼らはToDoリストの限界に気づきました。ToDoリストのリマインダーを受け取ることで、Claudeは、方針の変更が必要だと気づいた際にリストを修正するのではなく、そのリストに固執しなければならないと考えてしまうようになったのです。また、Opus 4.5ではサブエージェントの活用が大幅に改善されましたが、サブエージェント同士が共有のToDoリスト上でどのように連携すればよいのでしょうか？
この点を踏まえ、TodoWrite機能を「タスク」ツールに置き換えました。ToDoはモデルを計画通りに進めることに重点を置いているのに対し、タスクはエージェント同士のコミュニケーションを促進するものです。タスクには依存関係を設定したり、サブエージェント間で最新情報を共有したりすることができ、モデル側でもタスクの変更や削除を行うことが可能です。
モデルの機能が高まるにつれ、かつてモデルに必要だったツールが、今ではモデルの足を引っ張っている可能性があります。どのようなツールが必要かというこれまでの前提を、常に再検討することが重要です。また、これが、機能プロファイルが比較的類似した少数のモデルに絞ってサポートを行うことが有用である理由でもあります。
検索インターフェースの設計
私たちが開発したツールの中で最も重要なものは、Claudeが自ら文脈を見出せるようにするものです。
Claude Codeが社内で初めてリリースされた当初、私たちはRAGを採用していました。具体的には、ベクトルデータベースがコードベースを事前にインデックス化し、ハーネスが関連するスニペットを取得して、各レスポンスの前にClaudeに渡すという仕組みでした。RAGは強力で高速でしたが、インデックス作成やセットアップが必要であり、さまざまな環境下では不安定になる可能性がありました。 最も重要な点は、Claudeがコンテキストを自ら見つけるのではなく、このコンテキストを提示されていたということです。
しかし、Claudeがウェブ上で検索できるのなら、コードベースも検索できないはずがないでしょう。Claudeにgrepツールを追加すれば、ファイルの検索やコンテキストの構築を自動的に行えるようになります。
Claudeがより賢くなるにつれて、適切なツールが与えられれば、文脈を構築する能力もますます向上していきます。
「エージェントスキル」を導入した際、私たちは「段階的開示」という概念を体系化しました。これにより、エージェントは探索を通じて関連するコンテキストを段階的に把握できるようになります。
Claude これにより、スキルファイルを読み込めるようになり、それらのファイルはモデルが再帰的に読み込める他のファイルを参照できるようになりました。実際、スキルの一般的な用途としては、Claudeにさらなる検索機能を追加することが挙げられます。例えば、APIの使用方法やデータベースへのクエリ方法に関する指示を与えるといったものです。
1年の間に、Claudeは、当初は独自のコンテキストを構築することさえほとんどできなかった状態から、複数のファイル階層にわたるネストされた検索を行い、必要なコンテキストを正確に見つけられるようになるまで進化しました。
プログレッシブ・ディスクロージャーは、ツールを追加することなく新機能を追加するために、現在広く用いられている手法です。次のセクションでは、その理由について説明します。
段階的情報開示：CLAUDE CODEガイドエージェント
Claude Code 現在、約20種類のツールが導入されていますが、Claudeを最大限に活用するために、これらすべてが必要かどうかについて、チームでは頻繁に見直しを行っています。新しいツールを追加するハードルは高く設定されています。なぜなら、ツールを追加すると、モデルが考慮すべき選択肢が一つ増えることになるからです。
例えば、ClaudeはClaude Codeの使い方を十分に理解していないことがわかりました。MCPの追加方法や、スラッシュコマンドの機能について尋ねても、回答することができませんでした。
この情報をすべてシステムのプロンプトに盛り込むこともできたが、ユーザーからこの件について質問されることはめったになかったため、文脈の肥大化を招き、Claude Codeの本来の役割である「コードの記述」の妨げになっていただろう。
そこで、私たちは「段階的な情報開示」という手法を試みました。具体的には、Claude にドキュメントへのリンクを提供し、必要に応じて読み込んで検索できるようにしたのです。この方法は機能しましたが、Claude では、ユーザーがたった一文で得られるはずの答えを見つけるために、文脈に合わせて大量のドキュメントが読み込まれてしまうという問題がありました。
そこで、私たちは「Claude Codeガイド」を構築しました。これは、ユーザーがClaude Code自体について質問した際に、Claudeが呼び出すサブエージェントです。このサブエージェントは、独自のコンテキスト内でドキュメント検索を行い、検索方法や抽出すべき内容に関する詳細な指示に従い、回答のみを返します。これにより、メインエージェントのコンテキストはクリーンな状態が保たれます。
これは完璧な解決策とは言えませんが（Claudeに自身の設定方法を尋ねると、依然として混乱してしまうことがあります）、新しいツールを追加することなく、Claudeのアクションスペースに機能を追加することができました。
エージェントのような視点を持つことは、科学ではなく芸術である
モデル用のツールを設計することは、科学であると同時に芸術でもあります。それは、使用するモデル、エージェントの目的、そしてエージェントが動作する環境に大きく左右されます。
私たちからの一番のアドバイスは？ 頻繁に試行錯誤し、その結果を分析し、新しいことに挑戦することです。そして何よりも重要なのは、エージェントの視点で物事を見るよう心がけることです。
今すぐClaude Codeを使い始めましょう。
著者について：タリク・シヒパー氏は、Anthropicの技術スタッフの一員であり、Claude Codeの業務に携わっています。