Agentのように考える：Claude Codeチームのツール設計哲学

ThariqはAnthropicのエンジニアであり、Claude Codeの中核的な構築者の一人です。2月末にXで長文を投稿し、Claude Codeを構築する過程でのagentツール設計に関する5つの実際のケースを共有しました——理論的なフレームワークではなく、現場で身をもって経験した教訓です。この記事は351万回の閲覧、209件の返信、9,691件のいいねを獲得し、質の高い議論を数多く生み出しました。

記事全体の核心となる問いを引き出すために、Thariqは非常に良いアナロジーを使っています。難しい数学の問題に取り組むとき、どんなツールが必要でしょうか？

紙とペンは最低限の構成——でも手計算に縛られます。電卓はより良い——でも高度な機能の使い方を知っている必要があります。コンピューターが最強——でもコードが書けなければなりません。

ツールの選択は使用者の能力に依存します。プログラミングができない人にコンピューターを渡すくらいなら、電卓を渡した方がましです。プログラマーに電卓を渡すと、むしろその力を制限してしまいます。

agentにとっても同じです。問いは「どのツールが最も強力か」ではなく、「どのツールがモデルの現在の能力に最もマッチしているか」です。この記事が共有するのは、Claude Codeチームがそのマッチングポイントを探す過程で踏んできた落とし穴です。

以下は、原文とコミュニティの議論から私が抽出した4つの発展的なテーマです。

---

少ない方が多い——ツール数の逆説

直感的には、ツールが多ければ多いほどagentの能力は高まると思いがちです。しかしClaude Codeチームの経験はまったく逆でした。

Claude Codeが現在持つツールはわずか約20個であり、チームはこれらすべてのツールが本当に必要かどうかを常に見直しています。新しいツールを追加するためのハードルは高く、それはモデルが考慮すべき選択肢を一つ増やすことを意味するからです——ツールが増えるほど、モデルが意思決定する際の「認知的負荷」が増えていきます。

この発見はコミュニティで強い共感を呼びました。leon.Mは自身の経験を共有しています：

AppleのCodeAct研究がこの見解に定量的な裏付けを提供しています：単一のコード実行プリミティブ（code execution primitive）は、複雑なタスクにおいて大規模な専用ツールセットより最大20%高いパフォーマンスを発揮します。少ない方が、確かに多いのです。

AskUserQuestionツールの3度の反復は、この原則を最もよく示すケースです。Claude Codeチームは、Claudeがユーザーに質問する能力を向上させたいと考えていました——Claudeは純粋なテキストで質問できますが、それらの質問に答えることが面倒に感じられました。摩擦を減らすにはどうすれば良いでしょうか？

1回目の試み：ExitPlanToolにパラメーターを追加し、計画を出力すると同時に一連の質問を付け加えるようにしました。結果——Claudeが混乱しました。計画と計画に関する質問を同時に出力するように求め、もしユーザーの回答が計画と矛盾したらどうなるのか？

2回目の試み：出力指示を変更し、Claudeが特定のmarkdown形式で質問し、フロントエンドがフォーマットを解析するようにしました。結果——不安定でした。Claudeは余分な文章を追加したり、選択肢を省略したり、まったく異なる形式を使ったりしました。

3回目の試み：独立したAskUserQuestionツールを作成しました。Claudeはいつでもそれを呼び出せ、呼び出すとポップアップウィンドウに質問が表示され、ユーザーが回答するまでagentループがブロックされます。成功しました。

Thariqは原文にとても興味深い一文を書いています：

Claudeはこのツールを喜んで呼び出しているようで、出力結果も良好だと分かりました。どんなに上手く設計されたツールでも、Claudeが呼び出し方を理解していなければ機能しません。

phuongが鋭く問いただしました：「『Claudeがこのツールを喜んで呼び出しているようだ』というのは、ここで最も興味深くかつ最も説明が不足している一文です。モデルのツールに対する『好感度』をどう検出しているのか——transcriptを読むことで？それとも内部の呼び出し頻度の指標で？このヒューリスティックをより具体的にできれば、すべての人がagentツールを設計する方法が変わるでしょう。」

この質問には答えが得られませんでしたが、重要な直感を指し示しています：ツール設計の成功基準は「人間が合理的と感じる」ことではなく、「モデルが使い方を理解し、使いたいと思う」ことです。

Emekaは企業向けツール開発の観点からとても率直な教訓を補足しました：「以前agentのツールを構築したとき、あらゆる入力と出力をコントロールしようとしましたが、モデルは……それを回避してしまいました。エンジニアリングの手間を省いて、モデルが曖昧さを処理できると信頼しましょう。」

---

ツールは陳腐化する——能力向上後の制約効果

「少ない方が多い」が空間的な認識に関するものだとすれば、「ツールは陳腐化する」は時間的な教訓です。

かつてモデルを助けたツールが、モデルの進化とともに制約になる場合があります。

Claude Codeの初期リリース時、チームはモデルが方向性を保つためにToDoリストが必要だと気付きました——開始時にタスクを書き込み、作業が完了するにつれて一つずつチェックを入れていくものです。そのためにClaudeにTodoWriteツールを提供しました。しかしそれでも、Claudeは自分が何をすべきか忘れることが多くありました。

チームの対応策は、5ターンごとにシステムリマインダーを挿入し、Claudeに目標を思い出させることでした。

しかしモデルの進化とともに、問題は逆転しました：モデルはToDoリストのリマインダーが不要になっただけでなく、それらのリマインダーを制約と感じるようになりました。ToDoリストを繰り返し思い出させることで、Claudeはリストをフレキシブルにではなくきっちり従わなければならないと感じるようになりました。 同時に、Opus 4.5はサブagentの活用において大幅に改善しましたが、サブagent間で共有されたToDoリストをどう協調させるのか？

そこでチームはTodoWriteをTask Toolに置き換えました。両者の違いは本質的です：Todosの役割はモデルを軌道に乗せることで——ボスが従業員のタスクリストを監視するようなもの；Tasksはagent間のコミュニケーションを支援することに重きを置き——チームのコラボレーションかんばんのようなものです。Tasksは依存関係をサポートし、サブagent間で更新を共有でき、モデルはそれらを修正・削除することもできます。

TodoWrite → 5ターンごとのリマインダー → Task Toolは、3度の再設計です。 以前の設計が「間違っていた」からではなく、モデルが成長したからです。

modiのコメントがこの現象を的確に要約しています：

これはまた興味深い論争も引き起こしました。Danny Cossonは、AskUserQuestionは「実は設計が悪い」と考えています——それはClaude Codeの非常にエレガントなテキスト入力/テキスト出力モデルを特定のインタラクションパターンに無理やり当てはめており、ほとんどメリットがないと主張しています。

しかし@Toongの反論は説得力があります：AskUserQuestionの価値は2点にあります——主導権（モデルに質問する権限があることを明確に伝える）と状態管理（標準的なテキスト出力と「ユーザーの介入を待つ」ブロッキング状態を明確に区別する）。

同じツールに対して、まったく異なる2つの評価があります。これはまさにThariqが結末で述べたことを証明しています：ツール設計はサイエンスではなくアートです。使用するモデル、agentの目的、そしてそれが置かれた環境によって異なります。

---

Agentに自分で答えを見つけさせる——「与える」から「自律的な探索」へ

これが全文の中で私が最も実用的だと思う部分です。

Claude Codeは当初、Claudeのコンテキストを見つけるためにRAGベクターデータベースを使用していました。RAGは強力で高速ですが、2つの問題がありました：一つはインデックス作成と設定が必要で、異なる環境では脆弱になる可能性があること；もう一つはより根本的な問題で——この方法はコンテキストをClaudeに提供するものであり、Claudeが自分で探しに行くものではないということ。

チームは重要な転換を行いました：Claudeがウェブを検索できるなら、コードベースを検索できないのはなぜか？ClaudeにGrepツールを提供することで、Claudeが自分でファイルを検索し、自分でコンテキストを構築するようにしました。

Beaconのコメントが核心をついています：

1年の間に、Claudeはほぼ自律的にコンテキストを構築できなかった状態から、複数層のファイルをまたいでネストした検索を行い、必要なコンテキストを正確に見つけられるまでに進化しました。 この進化の鍵は、Claudeにより多くの情報を与えることではなく、より良い検索能力を与えることでした。

Claude CodeにAgent Skillsが導入された際、チームは正式に**漸進的開示（Progressive Disclosure）**の概念を提唱しました：agentが探索を通じて関連するコンテキストを段階的に発見できるようにするものです。

具体的な実装はエレガントです：Claudeはskillファイルを読み込め、それらのファイルはさらに他のファイルを参照でき、モデルはそれらを再帰的に読み込めます。skillの一般的な用途は、ClaudeにAPIの使い方やデータベースのクエリ方法に関する指示を与えるなど、より多くの検索能力を追加することです。

Brian Wagnerは、Claude Codeの考え方と完全に一致する3層の実践を共有しています：

SKILL.mdは簡潔に保ち（約100行）、重いコンテキストはClaudeが必要なときに発見するファイルに置いています。私はそれを第3層と呼んでいます。あなた方はそれを漸進的開示と呼んでいます。本質は同じです。

PrimeLineはさらに定量的な3層システムを構築しました：JSON設定（約500トークン）> スキーマサマリー（約300トークン）> 完全なmarkdown（約3Kトークン）。コンテキストルーターがタスクのキーワードに基づいてどの層を読み込むかを決定します。

この階層的戦略の核心的なロジックは：コンテキストは有限のリソースであり、限界効用は逓減するということです。すべての情報を一度にagentに詰め込んでも、トークンを無駄にするだけでなく、本当に重要な情報が希薄化されます。オンデマンドで提供し、agentが自分でより深い詳細が必要なタイミングを決める——これこそがスケーラブルな方法です。

Claude Code Guideサブagentは漸進的開示の別の巧妙な応用例です。チームはClaudeがClaude Code自体の使い方についての知識が不足していることに気付きました——MCPの追加方法や特定のスラッシュコマンドの機能について聞いても、答えられませんでした。

すべての情報をシステムプロンプトに詰め込むこともできましたが、ユーザーがこのような質問をすることは稀であり、そうするとコンテキストが汚染され、Claude Codeの主な仕事であるコードを書くことに支障をきたします。

まずClaudeにドキュメントリンクを与えて自分で検索させることを試みましたが——可能ではあるものの、Claudeは正しい答えを探すために大量の結果をコンテキストに読み込んでしまいます。最終的な解決策は、専用のサブagentを構築することでした：Claude Code Guideです。このサブagentは詳細な検索指示を持ち、ドキュメントを効率的に検索する方法と返すべき内容を把握しています。新しいツールを追加することなく、Claudeの行動空間を拡張しました。

Lance Martinはagent設計パターンに関する記事で補完的な視点を提示しています：agentに数十のツールを定義するのではなく、コンピューターを与えてコードでツールを編成させることを考えましょう。 Claude Codeの中核的な抽象化はCLIです——agentはあなたのコンピューター上に生き、bashとファイルシステムというプリミティブを通じて複雑なタスクを完遂します。少数のアトミックなツール（bashツールなど）は、膨大なツールセットよりも柔軟でトークン効率的です。

---

モデル共感——Agentのように考える

前述の3つのテーマ——少ない方が多い、ツールは陳腐化する、agentに自分で答えを見つけさせる——の背景には共通のメタ方法論があります。Thariqは記事の冒頭でそれを指摘しています：agentのように世界を見る。

これはルールのセットではなく、思考方法です。David Zhangがそれに名前をつけています：

モデル共感（Model Empathy）——人間の視点から「合理的な」ツールを設計するのではなく、モデルの視点から、それが実際に何を見ているか、どのように理解するか、どのように使うかを考えることです。

Terminally Driftingはすべてのagentチームが経験する同じ教訓を3ステップに精製しています：

1）人間のためにツールを設計する 2）モデルが管理者権限を持ったアライグマのようにそれらを使う 3）トークンエコノミーと予測可能な副作用のために再設計する

「agentのように考える」ことがその重要なブレークスルーです。

Vishは転換点の体験を共有しています：「私たちはずっと人間にとって合理的に感じるツールインターフェースを構築してきて、agentがなぜ奇妙な選択をするのか分かりませんでした。一度心のモデルを転換して、モデルがツール定義の中で実際に何を見ているかを考えると、すべてが変わりました。」

Emekaは企業向けツール開発の観点から同じことを述べています：「デフォルトはすべて人間の心的モデルです——スキーマ、フィールド名、フロー、すべてが人間が読むために最適化されています。しかしagentにとって、これは間違ったフレームワークです。」

この「心的モデルの転換」は口で言うのは簡単ですが、実践には継続的な練習が必要です。agentの出力を注意深く読む必要があります——何を正しくできたかを見るのではなく、なぜある選択をしたのか、どこで迷ったのか、どこで遠回りしたのかを見ることです。こうした「異常な行動」はしばしばモデルのバグではなく、ツール設計のバグです。

コミュニティの議論には、いくつかの考察すべき補足視点も現れました。

OAIRは盲点を提起しています：これらのツールの反復はすべて、agentがステートレスであることを前提としています——各セッションはゼロから始まります。もし最も重要な「ツール」が行動空間の中にあるのではなく、このコードベースがどのように機能するかについての永続的なメモリにあるとしたら？ Claude Codeはその後CLAUDE.mdファイルとmemoryシステムでこの問題に部分的に対応しましたが、永続的な状態管理はagent設計のオープンな課題であり続けています。

Clinkerは別の設計原則を提示しています：生の能力ではなく回復可能性（recoverability）を最適化する——明示的なツールの前提条件、観察可能な状態、低コストな再試行は、より多くのツールを素早く追加するよりも効果的であることが多い。 これはソフトウェアエンジニアリングの「エラーフリーではなくフォールトトレラントなシステムを作る」という理念と一脈相通じます。

范式折叠の総括が最も鋭い：

Action Space設計は本質的に権限設計です——AIに何の権限を与えるかで、それがどんな役割になるかが決まります。チームのマネジメントとまったく同じで：ボトルネックが人の能力にあると思っていたら、実はボトルネックは自分が引いた権限の境界にあるのです。

---

おわりに

Thariqの結語に戻りましょう：

たくさん実験して、出力を読んで、新しいことを試してみてください。agentのように観察しましょう。

Claude Codeのヘビーユーザーとして、この記事を読んで一番強く感じたことは：一見「自然に」見える機能の背後には、無数の「これはうまくいかない、別の方法を試そう」という反復があるということです。 AskUserQuestionは3度試み、TodoWriteは3度再設計され、RAGはGrepに置き換えられました。毎回の改善は、よりスマートな解決策を思いついたからではなく、モデルの実際の行動を注意深く観察したからです。

この記事のサブタイトルは「Seeing like an Agent」——agentのように世界を見ること。しかし別の角度から見れば、これはすべての良いエンジニアリング実践の本質でもあります：自分の視点からシステムを設計するのではなく、使用者の視点から設計する。 ただ今回は、使用者がAIモデルであるというだけです。

将来、agentを構築するすべての開発者は、David Zhangが言う「モデル共感」を習得する必要があるかもしれません。これは神秘的な能力ではなく、核心は3つのことです：モデルの実際の行動を観察し、その出力を読み、見たものに基づいて設計を調整する。

agentのように観察しましょう。

---

関連記事：