Claude Codeチームがツールを3回作り直して学んだ設計原則4つ

ツールを減らしたら、AIの性能が上がった。エージェントを作るとき、最も自然な本能は「機能が足りなければツールをもう一つ追加しよう」だ。AnthropicチームがClaude Codeを1年間開発して発見したのは、その逆だった。ツールが一つ増えるたびに、AIが「これを呼ぶべきか否か」と迷うコストも一緒に増えていく。

自分でエージェントを作りながら同じ罠にはまったからこそ、この話が身に染みた。Claude Codeチームの開発者Thariqがツールを追加・削除・再設計した過程を時系列で整理する。

一つのツールに二つの役割を入れるとAIが止まる

Claude Codeチームが最初にぶつかった問題だ。ユーザーに質問する機能が必要で、「計画作成」ツールに質問機能を一緒に入れた。実装は速かったが、AIが計画を立てながら同時に質問を作ろうとすると、ユーザーの回答が計画と矛盾したとき自分で判断できなかった。

2回目の試みでは、マークダウン形式で質問を出力させた。AIが勝手にフォーマットを変えてしまった。3回目でようやく質問専用ツールAskUserQuestionを分離し、そこで初めて安定的に動作し始めた。一つのツールに一つの役割。単純な原則だが、実際にぶつかって初めて実感できる。

• 計画+質問の合体 — AIが同じツールを2回呼び出すエラー
• マークダウン形式出力 — AIが文章を付け加えたりフォーマットを無視
• 専用ツール分離 — 構造化された応答がようやく安定的に出力
• 設計がどんなに良くても、AIが呼びたがらなければ意味がない

うまく動いていたツールがある日足枷になる

ツールをきちんと分離して作ったら終わりではない。これを「ツールの賞味期限（tool decay）」と呼びたい。かつて必須だったツールが、モデルのアップグレード後にかえって足を引っ張る現象だ。

初期のClaude Codeにはタスクリストツールがあり、5ターンごとに「今のタスクを忘れないで」とシステム通知まで送っていた。モデルが良くなった後、この通知が逆効果になった。AIがリストを修正すべき場面でも元の計画に固執した。Opus 4.5でサブエージェント連携が可能になったとき、既存のTodo構造ではエージェント間のタスク共有自体ができなかった。

結局、Task Toolに全面的に置き換えた。

• TodoWriteからTask Toolへ移行 — エージェント間の依存関係共有が可能に
• 「このツールはまだ有効か？」の定期的な点検が、新ツール追加と同じくらい重要
• サポートするモデル数を少なく保つことで、この判断速度が上がる
• ツールの数よりモデルの能力に合ったツールの形が優先

AIにコンテキストをお膳立てすると逆に性能が落ちる

ツールを追加・削除する過程で、Claude Codeチームがより根本的なパターンを発見した。AIに情報を注入するより、自分で見つけさせる方が良いということだ。

最初はRAGベクトルデータベースでコンテキストを事前に注入した。高速で強力だったが、環境ごとにインデキシングが壊れ、AIが「もらった情報」だけに頼る問題があった。Grepツールを与えてコードベースを直接検索させたところ、コンテキストの質が向上した。さらにSkillsファイルを加え、AIがファイル内で参照されている別のファイルを再帰的に探索する構造を作った。

これを**段階的コンテキスト発見（progressive disclosure）**と呼ぶ。情報を一度に渡すのではなく、AIが必要なものを自分で見つけていく方式だ。

• RAG — 環境依存性が高く、AIが受動的にコンテキストを消費
• Grep + Skills — AIが複数層のファイルを能動的に探索
• 1年で「コンテキストを作れないAI」から「自分で見つけるAI」へ変化
• ツールを追加せずSkillsファイルだけで機能拡張が可能

ツールを追加せずにAIの能力を拡張する方法

この段階的コンテキスト発見パターンが威力を発揮した事例がもう一つある。Claude Codeの使い方を聞いても答えられない問題があった。システムプロンプトに使い方を全部入れることもできたが、その質問はたまにしか来ない。めったに使わない情報がコンテキストウィンドウを常時占有すると、コード作成という本業の性能が落ちる。これを**コンテキストノイズ（context rot）**と呼ぶ。

解決策は専用サブエージェントだった。使い方の質問が来たときだけ、ガイドエージェントがドキュメントを検索して回答だけを返す構造に変えた。ツール数はそのままで、AIができることが増えたのだ。

• システムプロンプトに全情報 — コンテキストノイズでコード品質が低下
• ドキュメントリンクだけ提供 — AIが結果をコンテキストに載せすぎ
• 専用サブエージェント+検索指示 — 必要な答えだけクリーンに返却
• ツールを増やす代わりに構造を変えて解決した事例

正解の公式はない

ツールを追加し、削除し、再設計するこのプロセスに正解の公式はない。モデルが変われば道具も変わるべきで、昨日正しかった構造が明日はボトルネックになりうる。

Anthropicチームが1年間繰り返したことが一つある。AIの出力を読み、実験し、また直すこと。結局、優れたエージェントを作る人は、AIの立場から物事を見ることができる人だ。