Claudeコードのツール設計はなぜ「芸術」か｜Thariqが3つの試行錯誤で語るSee Like an Agent

Anthropicの社内チームでClaude Codeを開発しているThariq（@trq212）が、2026年2月にX上で「Lessons from Building Claude Code: Seeing like an Agent」と題した長文ポストを投稿した。インプレッションは396万に達し、エージェントハーネスの実装者・設計者にとって今年最も読まれた一次情報のひとつとなっている。

この投稿は「エージェント開発で最も難しいのはアクション空間の設計、すなわちツール群の取捨選択である」という主張を軸に、Anthropic社内で実際に起きた3つの試行錯誤を生々しく公開したものだ。AskUserQuestionツールが完成するまでの3回の失敗、TodoWriteからTask Toolへの進化、RAGを捨ててGrepを採用した理由——いずれもハーネスエンジニアリングの核心を突く意思決定の記録になっている。

本記事では、Thariqの英文ポストを日本語で再構成し、彼が繰り返し強調する「See like an agent（エージェントの目線で見る）」という設計哲学を、4つの具体例とともに解説する。Claude Codeの利用者にとっては「なぜこのツールはこういう挙動なのか」の答えが、ハーネス開発者にとっては「自分のエージェントをどう設計すべきか」の指針が得られるはずだ。

Claude Code全体の使い方は Claude Code完全ガイド2026：インストールから本番運用まで をご覧ください。

01 Thariqが公開した「ツール設計は芸術」という主張

ThariqはAnthropicでClaude Codeのコア開発に携わるエンジニアだ。彼が今回のポストで提示した命題はシンプルでありながら挑発的である。「エージェントハーネスを構築するうえで最も難しいのは、モデルが使うべきアクション空間（ツール群）を設計することだ」。プロンプトでも、モデル選択でも、メモリ管理でもない。ツール設計こそがエージェントの能力を決定づけるという主張だ。

そして彼はもうひとつ重要な前提を置いている——ツール設計は「科学」ではなく「芸術」である、と。これは無責任な放言ではなく、設計が「モデルの能力」「タスクの性質」「実行環境」の3変数に強く依存する以上、普遍的なベストプラクティスを宣言できないという誠実な観察である。Opus 4.5で最適だったツール構成は、Sonnet 4.7で最適とは限らない。コードベースを書くエージェントに最適な検索ツールは、リサーチエージェントに最適とは限らない。

この前提のもとでThariqが提案するのが「See like an agent」というメンタルモデルだ。実装者は人間の論理ではなく、エージェントが実際に受け取る入力・出力ストリームの中に身を置いて考えなければならない。具体的には次の3つの行動が要求される。

• エージェントの実行ログ（入出力すべて）を地道に読む
• ツールの応答フォーマットを変えて挙動の差分を観察する
• 「賢いモデルなら何を欲しがるか」ではなく「目の前のモデルが実際に何を呼ぶか」で判断する

Anthropic社内では、このアプローチが実際に何度も既存設計を覆してきた。次章以降ではその具体的な記録を見ていく。

02 数学問題で考える「エージェント目線」のフレームワーク

Thariqは「See like an agent」を直感的に理解するために、ひとつの思考実験を提示している。「もし自分が難しい数学問題を解くエージェントだったら、どんな道具を欲しがるか？」と問うものだ。

選択肢は段階的に並べられる。紙とペンだけでよいのか、電卓があれば十分か、Pythonが動くコンピュータが必要か、それともMathematicaのような数式処理系まで欲しいか。答えは「解こうとしている問題」と「自分がエージェントとしてどれくらい賢いか」の組み合わせで変わる。

たとえば中学レベルの一次方程式なら紙とペンで足りる。電卓を渡しても使い道がない。一方、大規模な数値計算が絡む問題ならPythonインタプリタが必須になる。さらに記号微分や代数構造を扱うなら数式処理系がないとつらい。ツールを増やせば賢くなるわけではなく、「呼び方を知っているツール」を「必要な分だけ」渡すのが最適という結論が導かれる。

このフレームワークはコーディングエージェントにそのまま転用できる。Claude Codeでツールを追加するとき、Anthropic社内ではいつも次の問いを並べる。

つまり「機能を増やす」のではなく「賢いエージェントが好んで呼ぶ最小集合」を探す作業がツール設計だ。Thariqはこれを「賢いインターン候補に何を持たせて出社させるか」のメタファーでも表現している。出社初日に道具を百個渡しても混乱するだけで、必要な3つを正しく渡したほうが成果が出る。

03 AskUserQuestionが3回の失敗で完成した記録

Thariqのポストでもっとも具体的かつ示唆に富むのが、AskUserQuestionツールの誕生秘話だ。これはClaude Codeがユーザーに対して構造化された選択肢付き質問を投げるためのツールで、現在ではモーダル表示でブロッキングする設計になっている。だが、ここに辿り着くまでにAnthropic社内で3回の異なる実装が試された。

試行1：ExitPlanToolにquestionsパラメータを追加

最初のアプローチはシンプルだった。すでに存在するExitPlanTool（計画モードを抜けるためのツール）にquestionsという追加パラメータを生やし、計画を提出する際にユーザーへの質問を同時に渡すというものだ。設計上はエレガントに見える。1つのツールで「計画提示」と「質問」が同時に処理できる。

しかし結果は失敗だった。モデルが「計画を確定する」と「質問する」という意図の異なる行為を、ひとつのツール呼び出しに混ぜてしまったのだ。本当はユーザーに方針を聞きたいだけなのに計画を確定させてしまったり、逆に計画提示時にどうでもいい質問を付け足したり、挙動が一貫しなくなった。

試行2：マークダウンで質問を整形させる

次に試されたのは、専用ツールを作らず、出力フォーマット側で質問を構造化する方針だった。「ユーザーに聞きたいことがある場合は、こういうマークダウン形式で書いてほしい」という指示をシステムプロンプトに加える。

これも長続きしなかった。形式が安定しないのだ。あるときは番号付きリストで、あるときは表で、あるときは普通の文章に紛れて、と一貫性が崩れた。フロントエンド側でも質問をハイライトしたり選択肢としてレンダリングしたりするのが困難で、結局は「質問のような文字列」が会話に流れていくだけになった。

試行3：AskUserQuestionツールを新設

最終的に採用された案が、独立したAskUserQuestionツールの新設だった。これはツール呼び出しの一種としてモデルが明示的に発火させ、引数として「質問本文」と「選択肢リスト」を渡す。フロント側はこの呼び出しを検知してモーダル表示でブロッキングし、ユーザーが選択肢をクリックするまでエージェントの実行を一時停止する。

ツールスキーマはおおよそ次のような構造で、選択肢を必須にすることで「自由記述の質問」に流れない仕掛けが入っている。

{
  "name": "AskUserQuestion",
  "description": "Ask the user a question with structured choices.",
  "input_schema": {
    "type": "object",
    "properties": {
      "question": { "type": "string" },
      "options": {
        "type": "array",
        "items": { "type": "string" },
        "minItems": 2
      }
    },
    "required": ["question", "options"]
  }
}

このツールに切り替えてからの効果は劇的だった。モデルは進んでこのツールを呼び、しかも適切な場面で呼ぶようになった。Thariqはこの結果から重要な教訓を引き出している——「Claudeが好んで呼ぶツールを作れたかどうかが、設計の成否を決める」。

何が成功要因だったか

3つの試行を比較すると、成功条件が浮かび上がる。

ポイントは、「機能を足すなら、独立したツールとして名前と境界を与えたほうが、結果としてモデルもフロントも幸せになる」という非自明な事実だ。試行1と試行2は実装コストが小さい順に並んでいたが、コストが小さい方法はモデルにとっての境界も曖昧で、結果的に動かなかった。

04 TodoWriteからTask Toolへ──モデルの進化に追従する

Thariqの2つ目の事例は、進捗管理ツールTodoWriteの運用変遷だ。Claude Codeを使ったことがある読者なら、画面上部に「TODOリスト」が表示され、タスクの完了状況が刻々と更新されていくUIを見たことがあるだろう。その裏側にあるのがTodoWriteである。

初期のTodoWrite設計

Claude Codeの初期バージョン（Sonnet 3.5〜Opus 4初期世代）では、長時間タスクの進捗管理にこのツールが大きな役割を果たしていた。さらに「5ターンごとに進捗を見直してTodoを更新せよ」というシステムリマインダーが定期的に注入され、モデルの忘却を防いでいた。

これは当時のモデル能力に対しては正しい設計だった。Sonnet 3.5やOpus 4初期は長期計画を保持する力が相対的に弱く、明示的なTodo構造とリマインダーがないと途中で迷子になりやすかった。Todoリストはモデルの作業記憶を外部化する補助輪として機能していた。

Opus 4.5以降で起きた変化

ところがOpus 4.5、その後継のSonnet 4.7と世代が進むにつれ、状況が変わってきた。モデルが長期タスクを内部で計画・追跡する能力を持つようになり、TodoWriteの強制リマインダーが「外部から押し付けられる構造」として邪魔になり始めたのだ。

具体的には次のような症状が観察された。

• 自然な思考の流れが「Todo更新」というメタ作業で中断される
• 細かすぎるTodo分割で、本来一気にやるべき作業が分解される
• 5ターンごとのリマインダーがコンテキストを汚す

賢くなったモデルにとっては、Todoリストは補助輪ではなく拘束具になっていた。

Task Toolへの置き換え

そこでAnthropicは、TodoWriteを単独の進捗管理ツールから、サブエージェント間でコンテキストを共有するためのTask Toolへと進化させた。Task Toolはサブエージェント呼び出しの基盤になり、親エージェントが複数のサブエージェントを起動して並列に作業を進める際の「共通の作業台」として機能する。

つまりTodoWriteは消えたわけではなく、より大きな並列エージェントオーケストレーションの仕組みの一部に統合された。シングルエージェントの補助輪から、マルチエージェントの調整基盤へと役割を変えた。

教訓：モデルの進化に合わせてツールを見直す

Thariqがここで強調するのは、「モデルが進化したら、過去のモデルを前提に作ったツールの存在意義を疑え」という原則だ。新しいモデルが古い補助輪を必要としていないどころか、その補助輪に足を取られているケースが頻繁に起きる。ハーネスエンジニアにとっては、モデル更新のたびに既存ツールの「呼ばれ方」と「呼ばれない場面」を観察し直すのが日常業務になる。

ここでも基本動作は「ログを読む」ことに帰着する。新しいモデルがTodoWriteをどんな粒度で呼んでいるか、リマインダー後にどう挙動が変わるか、ログを並べると「邪魔になっている」ことが見えてくる。

05 RAGからGrepへ──検索インターフェース大転換

3つ目の事例は、コードベース検索のための情報取得（リトリーバル）インターフェースをめぐる意思決定だ。多くのコーディングエージェントは初期段階でRAG（Retrieval Augmented Generation）——ベクトルDBに事前にコードを埋め込んでおき、クエリに近い断片を返す方式——を採用するが、Anthropicはこのアプローチから大きく舵を切った。

RAG方式の問題点

Thariqが挙げるRAGの課題は3点ある。

• セットアップが重い：プロジェクトごとにembedding計算が必要で、時間とコストがかかる
• 環境差で壊れやすい：ファイル構成が変わるたびにインデックス再構築が必要
• Claude側で文脈を作れない：返ってくるのはベクトル類似度で選ばれた断片で、その周辺の依存関係を辿るのが難しい

特に3点目は決定的だった。コードベース理解は「ベクトル的に似ている断片」ではなく「意味的に関連する関数の連鎖」を辿る作業であり、その制御をモデル側に渡したほうが結果が良くなる、という観察だ。

Grepツールへの転換

そこで採用されたのが、シンプルなGrepツール（とGlob、Readの組み合わせ）の提供だ。Claude Codeのコードベース検索は基本的に正規表現で文字列を探し、ファイル名パターンで絞り込み、必要な箇所を直接読む構造になっている。インデックスは作らない。

{
  "name": "Grep",
  "description": "Search for a regex pattern across files.",
  "input_schema": {
    "type": "object",
    "properties": {
      "pattern": { "type": "string" },
      "path": { "type": "string" },
      "glob": { "type": "string" },
      "output_mode": {
        "enum": ["files_with_matches", "content", "count"]
      }
    },
    "required": ["pattern"]
  }
}

これによってClaude自身が「まずクラス名で検索 → 該当ファイルを読む → そこから呼び出し元を逆引き → 必要なら型定義を辿る」という連鎖をその場で組み立てられるようになった。コンテキスト構築の主導権をモデル側に戻したのだ。

Skillsで形式化された「Progressive Disclosure」

このアプローチはのちに「Skills」（Claude Skillsとして公式に整理された機能）にも引き継がれている。SKILL.mdというMarkdownファイルが「目次」として機能し、必要に応じてその中の参照リンクを辿って詳細ファイルを読み込んでいく。情報を階層化し、必要になった時点で必要な分だけロードする——これがThariqが「Progressive Disclosure（漸進的開示）」と呼ぶ設計原則だ。

---
name: pdf-handling
description: Use when working with PDF files
---

# PDF Handling Skill

## 基本操作
PDFのテキスト抽出は `scripts/extract_text.py` を使う。

## 高度な操作
- フォーム入力 → @advanced/forms.md
- OCR処理 → @advanced/ocr.md
- 暗号化 → @advanced/encryption.md

このSKILL.mdは数百トークンほどのサイズで、最初から全部読み込まれる。実際にPDFのフォーム入力が必要になった時点で初めて@advanced/forms.mdが読まれる。「全部最初に渡す」と「必要になったら取りに行く」のあいだに、Progressive Disclosureという中間設計を置いたわけだ。

RAG・Grep・Skillsの比較

Anthropicがこの3つのうちGrepを基本に据え、Skillsを上に重ねたのは、「コーディングエージェントは情報を選び取る能力をすでに持っている」という観察があったからだ。能力のあるエージェントには、加工された結果ではなく原料を渡したほうが良い結果になる。

06 Claude Code Guide──ツールを増やさずProgressive Disclosureで能力追加

4つ目の事例は、ややメタ的な問題への対処だ。Claudeは「Claude Code自体の使い方」を知らない——少なくともClaude Codeに最適化された使い方を完全には知らない。なぜならClaudeはClaude Codeを使ってトレーニングされていない期間が長く、Claude Codeの細かい仕様（スラッシュコマンド、ファイル構造、フックの書き方など）はモデルの内部知識には十分には焼き付いていないからだ。

案A：システムプロンプトに全部書く

最も素朴な解決策は、Claude Codeの使い方をすべてシステムプロンプトに書き込むことだ。「TodoWriteとはこういうツールで、こういう場面で使うべき」「このスラッシュコマンドの意味は」と網羅的に書いていく。

しかしこれは2つの理由で却下された。

• システムプロンプトが肥大化し、コンテキストの大半を「メタ説明」が占有する
• いわゆる「context rot（文脈腐敗）」が起き、本業のタスク処理に集中できなくなる

ユーザーは「コードを直して」と頼んでいるのに、エージェントが頭の中で常に「俺はClaude Codeである」というメタ自己参照を回し続けるのは効率が悪い。

案B：Claude Code Guideサブエージェント

採用された案は、Claude Code Guideという別のサブエージェントを切り出す方針だ。本体のClaudeはタスク処理に集中し、Claude Codeの仕様について知る必要が出たときだけTask Toolを介してClaude Code Guideを起動する。

Claude Code Guideの内部にはClaude Codeのドキュメント全体への検索能力が与えられ、専門知識データベースのような役割を果たす。本体は「Claude CodeでXをやる方法を教えて」という疑問が湧いた瞬間にこのサブエージェントに質問を投げ、必要な情報だけを受け取る。

Progressive Disclosureとの関係

この設計はSkillsと同じ思想——Progressive Disclosureの応用だ。情報を最初から全部渡すのでも、無くて困るのでもなく、「ツール（=サブエージェント）として境界を切り、必要な時に呼べるようにしておく」。本体のシステムプロンプトはコンパクトに保たれ、必要な専門知識は別の階層に押し出される。

教訓：機能追加のデフォルトはツール追加じゃない

Thariqがこの事例で強調するのは逆説的なメッセージだ。「能力を追加したいときの最初の選択肢は、新しいツールを足すことではない」。情報の階層を作る、サブエージェントに切り出す、Progressive Disclosureで必要時にロードする——これらが優先候補になる。

ツールを増やすと「選択肢の数」が増え、モデルの判断負荷が上がる。階層化やサブエージェント化なら「呼び口」は1つのまま能力だけを増やせる。

07 「See like an agent」を実践する3つの行動指針

ここまで4つの実例を見てきた。AskUserQuestionの3回の試行錯誤、TodoWriteからTask Toolへの進化、RAGからGrepへの転換、Claude Code Guideサブエージェントの新設——いずれもAnthropicの実装者が「エージェントの目線」で観察し、決定を下した結果だ。最後に、Thariqが繰り返し示している「See like an agent」を実務で実践するための3つの行動指針をまとめる。

指針1：エージェントの入出力ストリームをすべて読む

最も基本にして最も実行されない行動が、ログを読むことだ。エージェントが受け取ったシステムプロンプト、ツール定義、過去のターン、そして自分が出力したツール呼び出しと自然言語の応答——これらをすべて時系列で並べて読む。「エージェントが見ている世界」を自分で再構成しないと、なぜそのツールが呼ばれない／誤用されるのかは分からない。

実務では次のような習慣が効く。

• 失敗ケースを最低5件、入出力フルログで保存する
• 成功ケースのログとdiffを取って何が違うかを言語化する
• 「自分が同じ入力を見たら同じ出力を出すか」を自問する

指針2：ツールの応答フォーマットを変えて挙動を観察する

ツール定義はスキーマだけでなく「応答フォーマット」もエージェントの挙動に強く影響する。同じGrepでも、結果をJSONで返すかテキストで返すか、ファイルパスを先頭に出すか末尾に出すかで、次のターンの挙動が変わる。

Anthropic社内では「フォーマットを少し変えて10件流して比較」という実験が日常的に行われている。理論より実測であり、「こうするとモデルが混乱しそうだから避ける」という事前の直感は、実験で覆ることが多い。

# Anthropic社内で実際に行われる実験パターン（疑似コード）
for fmt in ["json", "yaml", "markdown_table", "plain_text"]:
    results = []
    for query in benchmark_queries:
        response = run_agent(query, response_format=fmt)
        results.append(score(response))
    print(f"{fmt}: {mean(results)}")

指針3：モデルの賢さを所与とせず、現行モデルが好むものを選ぶ

3つ目の指針は、モデルへの過信と過小評価の両方を避けることだ。「賢いモデルだから細かい指示なくても分かるはず」という過信も、「説明を100行書かないと分からない」という過小評価も、どちらも観察を欠いている。

実際にやるべきは、現行モデルにツール候補をいくつか渡し、どれを好んで呼ぶか・どれを誤用するか・どれを無視するかを測ることだ。ツール設計の正解はモデルバージョンとともに動く動的な最適点であり、固定された正解は存在しない。

最後に：芸術であることを受け入れる

Thariqが繰り返したメッセージは「ツール設計に厳格なルールはない、これは芸術だ」だった。本記事で見てきたAnthropicの実装者たちのアプローチは、芸術というよりは「実験を高速で回す職人芸」に近い。理論的な正解を探すのではなく、実装→観察→修正のループを誰よりも速く回し、エージェントが実際にどう動くかから学んでいく姿勢だ。

ハーネスエンジニアリングをこれから始める読者にとっては、次の3つから始めるのが現実的だろう。

• まず1つのツールを作り、エージェントの実ログを最低20本読む
• ツール定義の応答フォーマットを変えて挙動の差分を見る
• 「呼ばれないツール」が出てきたら、削除か統合を検討する

Anthropicが社内で繰り返してきたのと同じプロセスを、自分のエージェントで再現すること——それが「See like an agent」の実践だ。

ハーネス設計の本番運用ノウハウは ハーネスエンジニアリング本番ガイド、Claude Code内部のシステム構造は Claude Codeアーキテクチャ完全解剖 で詳しく扱っている。Thariq本人の他の発言については Claude Code開発者Thariqが語るエージェント設計の全貌 も参照されたい。

参照ソース

• Thariq氏のX投稿（396万imp）「Lessons from Building Claude Code: Seeing like an Agent」
• Anthropic Claude Code Tool Useドキュメント