Thariq（Claude Code開発者）が語るエージェント設計｜Skills・キャッシュ・bash

Anthropicに所属しClaude Code開発を担うエンジニアThariq（@trq212）が、2025年9月から2026年5月までの間で公開した7本の長文スレッドは、合計1500万インプレッションを超えた。Skillsの設計、prompt cachingの運用、ツール設計の哲学、bashの活用、ファイルシステムの重要性、対話UI生成プラグイン、そしてHTML出力の有効性――どれも公式ドキュメントには書かれていない、社内エンジニアの「現場の判断」が凝縮された一次情報だ。

この記事は、その7本を体系的にまとめたピラー記事である。各スレッドの個別解説記事へのインデックスとして、また「Claude Code開発者がエージェントをどう設計しているか」という思想的全体像をつかむ入口として活用してほしい。

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

01 ThariqとAnthropic公式エンジニア発信の全体像

ThariqはMIT Media Lab出身、Y Combinator W20を経てAnthropicに加入したClaude Codeチームのメンバーである。彼が2025年後半から始めた「Lessons from Building Claude Code」シリーズは、社内で実装された設計判断をそのまま公開する一次情報として大きな反響を呼んだ。

シリーズ7本の概要を、公開順に並べる。

この7本は単発の記事ではなく、互いに相互参照する思想の塊だ。たとえばSkillsの記事は「Progressive Disclosure」を中核概念に据えるが、その根拠はファイルシステム記事で語られている。ツール設計の記事はprompt cachingに依存し、playgroundはSkillsを土台にしている。

シリーズ全体を通して繰り返される設計原則は3つに集約できる。

• キャッシュを壊さない設計：プロンプト構造、ツール集合、モデル選択をmid-sessionで変えない
• エージェント目線で見る：出力を読み、実験し、モデルが好んで呼ぶ形にツールを整える
• コンテキストを節約する仕組み：ファイル参照、Progressive Disclosure、bash活用、Plan Mode

この3点はClaude Code内部だけでなく、自作エージェント・他社フレームワークでも有効な普遍原則だ。

02 Skills 9カテゴリ──Anthropic社内で動く数百のスキルを分類する

シリーズで最大の反響（X 685万imp）を集めたのが、Skillsの運用ノウハウを9カテゴリで体系化した記事だ。Anthropic社内では数百のスキルが現役で動いており、それを分類することで「自分の業務にも欠けているスキルが何か」を可視化できる。

9カテゴリのうち主要なものを抜粋する。

• Library & API Reference：社内ライブラリ・CLI・SDKの使い方とgotchasを集約
• Product Verification：playwright/tmuxで成果物を実機検証
• Data Fetching & Analysis：Grafana・データ基盤への接続をパッケージ化
• Business Process & Team Automation：standup-post、weekly-recapなど反復作業を1コマンドに
• Code Quality & Review：adversarial-review、code-styleでレビューを自動化
• CI/CD & Deployment：babysit-prがflaky CIをリトライしマージまで完了させる
• Runbooks：障害対応の症状→ツール→クエリパターンを記述
• Infrastructure Operations：destructiveなオペレーションにガードレールを付けて安全実行

Thariqが繰り返し強調するのは「descriptionは要約じゃなく、いつ呼ぶかのトリガーだ」という点だ。Claude Codeはセッション開始時に全スキルのdescriptionをスキャンし、ユーザー入力にマッチするものを判断する。だから「何をするか」ではなく「どんな入力が来たら呼ぶべきか」を書く必要がある。

Skillsはマークダウンファイルではなく「フォルダ」だという認識も重要だ。スクリプト・テンプレート・ログファイル・config.jsonなど、Claudeが探索・操作できる構造を内包する。これがProgressive Disclosureを可能にし、必要な情報だけを段階的にロードできる。

詳細は ClaudeチームThariqが明かしたSkills設計9カテゴリ｜Anthropic社内で数百個動かす実践則 で逐条解説している。Skillsそのものの基本を抑えたい場合は Claude Skillsを徹底解説 を先に読むとよい。

03 Prompt Cachingがハーネス設計の中心──5原則で支えるClaude Code

X 232万imp、公式blogにも転載された「Prompt Caching Is Everything」は、Claude Codeのコスト構造を支える設計原則を5つにまとめた。

Thariqの主張をひと言でまとめると「キャッシュは前方プレフィックスマッチである。プレフィックスのどこかが変わると、その後ろ全部が無効になる」という1点に尽きる。これを徹底するため、Claude Codeのプロンプトは以下の順序で固定されている。

1. 静的systemプロンプト + ツール定義（グローバルキャッシュ）
2. CLAUDE.md（プロジェクト内キャッシュ）
3. セッションコンテキスト（セッション内キャッシュ）
4. 会話メッセージ

この順序を守るために、Claude Codeチームは以下の運用を徹底している。

• システムプロンプトにタイムスタンプを入れない（毎回キャッシュが無効化されるから）
• ツール順序を非決定的に並べない
• mid-sessionでモデルを切り替えない（モデルごとにキャッシュは別物）
• mid-sessionでツールを追加・削除しない

最も興味深いのはPlan Modeの実装だ。「読み取り専用ツールに切り替える」のが直感的だが、それはキャッシュを壊す。代わりにEnterPlanMode/ExitPlanModeをツールとして提供し、プロンプト構造は1ミリも変えない。

Tool Searchも同じ思想で実装されている。defer_loading=trueのstubsを送り、必要時のみ完全スキーマをロードする。これでプロンプトは安定したまま、数十のMCPツールを扱える。

Claude Codeチームはキャッシュヒット率にアラートを設定し、低下したらSEV扱いにする。これは単なるコスト最適化ではなく、サブスクプランのレートリミットを支える基盤になっているからだ。

詳細は Claude Codeハーネスはなぜprompt caching中心に設計されたか で逐条解説している。

04 See like an Agent──ツール設計を「芸術」と呼ぶ理由

X 396万impを集めた「Seeing like an Agent」は、エージェントハーネス設計で最も難しい「アクション空間（ツール群）」をどう構築するかを論じた記事だ。

Thariqが提示するフレームワークは「自分が難しい数学問題を解くとしたらどんな道具が欲しいか」というもの。紙だけ？電卓？コンピュータ？――その答えは「自分のスキルに依存する」。エージェントも同じで、モデルの能力プロファイルに合わせて道具を選ぶ必要がある。

記事では3つの試行錯誤の生々しい記録が公開されている。

• AskUserQuestionツール：3回の失敗を経て完成。最初はExitPlanToolにパラメータ追加→計画と質問が混乱。次に出力フォーマット修正→一貫性なし。最終的にツール化してモーダル表示でブロッキング
• TodoWrite → Task Tool：Opus 4.5でモデルが賢くなり、Todoが制約になった。サブエージェント間共有のためTask Toolに置換
• RAG → Grep：初期はベクトルDB→セットアップ重い、Claudeが自分でコンテキストを作れない。Grepツール提供でClaude自身がコンテキスト構築

「Claudeが好んで呼ぶツール」が成功条件――これが3つの実例から導かれた最重要メッセージだ。どれだけ完璧に設計しても、モデルが理解して使ってくれなければ意味がない。

もうひとつ重要な実例がClaude Code Guideサブエージェントだ。「Claudeが自身のドキュメントを知らない」という課題に対し、システムプロンプトに全部書く案ではなくProgressive Disclosure型のサブエージェントを採用した。ツールを増やさずに能力を追加するパターンとして参考になる。

詳細は Claudeコードのツール設計はなぜ「芸術」か で深掘りしている。ハーネスエンジニアリング全般の基礎が必要な場合は ハーネスエンジニアリング本番ガイド も併読を推奨する。

05 Playground──ClaudeにHTML対話UIを作らせる

X 84万impを集めた「Making Playgrounds using Claude Code」は、Claude Code公式プラグイン「playground」を紹介する記事だ。

Claudeにスタンドアロンの対話可能なHTMLファイルを生成させ、ブラウザで操作した結果をプロンプトとしてClaude Codeに貼り戻す――テキスト対話の限界を超える発想である。

/plugin marketplace update claude-plugins-official
/plugin install playground@claude-plugins-official

Thariq自身が試した5つの実例が紹介されている。

• AskUserQuestion Toolの新レイアウトを視覚的に試す
• SKILL.mdの校閲インターフェースをClaudeに生成させ、approve/reject/commentで意見を返す
• Remotion動画イントロのチューニング
• アーキテクチャ図にコメント可能な対話UI
• ローグライクゲームのデッキバランス調整

「テキストでは扱いにくい操作」をHTMLでブリッジするのがこのプラグインの本質だ。デザイン調整・ゲームバランス・図への注釈――どれも従来は何往復もチャットが必要だった作業を、1つの対話UIで片付けられる。

詳細は Claude Code開発者公式プラグイン「playground」 で5つの実例とSKILL.md設計を解説している。

06 File System──エージェント状態管理の最適表現

最も初期（2025-09）に公開され、後の全記事の思想的土台となったのが「Your Agent should use a File System」だ。X 17万impと数字は控えめだが、内容は強烈である。

“This is a hill I will die on. Every agent can use a file system.”

ファイルシステムが状態管理に向く理由を整理すると以下になる。

• 状態表現：会話履歴ではなくファイルとして残せば、長期実行でも復元できる
• 検証可能性：エージェント自身が出力ファイルを開いて確認できる
• コンテキスト効率：必要な部分だけRead で取り込める
• Progressive Disclosure：Skillsが採用した設計思想と同根
• デバッグ性：人間がファイルを覗けばエージェントの作業を追跡できる

この主張は後にSkillsの「フォルダ＝知識パッケージ」設計、Tasksの「ファイルベース状態管理」、Compactionの「中間結果をファイル化」に直結している。シリーズの中核思想の出発点だ。

非コーディングエージェントにも適用できる。データ分析エージェントがanalysis_results.csvを作成→次のエージェントが読む、というシンプルなパターンが、長期実行と監査可能性を両立させる。

詳細は ThariqがXで断言「全エージェントはファイルシステムを使え」 で実装パターン付きで解説している。

07 Bash──30社のヒアリングで導いた「ユニバーサルアダプター」

X 29万imp、Thariqが「過去数週間で汎用エージェントを作る企業30社とコールした結果、アドバイスはほぼ “use the bash tool more” だった」と語る記事だ。

専用ツールを大量に作るより、bashツール1つで多くのことができる。理由は明快だ。

• bashはユニバーサルアダプター――あらゆるCLIツール・スクリプト・パイプラインを叩ける
• メールエージェントなら notmuch/grep/sort/wc でメール検索・統計・フィルタが完結
• jq でJSONレスポンスを整形、curl で外部API、awk/sed でテキスト処理
• ツール数を増やすとClaudeの選択コストが増える（context rot）
• bash 1つで多目的、Progressive Disclosureが効く

Thariq自身がメールエージェントを作っており、その実装はほぼbashだけで動いている。これは「Claudeコードが特別だからbashが効く」のではなく、汎用エージェント全体に当てはまる設計則だ。

安全制約はallowed-tools: Bash(notmuch *) Bash(jq *) Bash(curl *)のように個別コマンドを制限すれば実現できる。Skillsで「メール集計手順」をbashコマンド付きで書いておけば、bash×Skillsの強力な組み合わせになる。

詳細は Thariq「非コーディングエージェントこそbashを使え」 で実装パターンを解説している。エージェントハーネス全般の基礎は Agentハーネスの基礎 を参照。

08 HTML出力──MarkdownでなくHTMLをエージェントの第一出力にする

シリーズ最新作（2026-05公開）は「The Unreasonable Effectiveness of HTML」だ。エージェントの出力先としてMarkdownではなくHTMLを推奨するという、地味だが射程の広い主張である。

Thariqの論点は明快だ。

• Markdownは100行を超えると人間が読み切れない
• 図・色・インタラクションを表現できない
• HTMLならSVG・CSS・JavaScriptが使え、情報密度が圧倒的に高い
• ブラウザで開いてそのまま共有できる

参考デモサイトでは20種類のユースケース（コード方針の3案横並び比較、PR用の注釈付き差分ビュー、Linearチケットのドラッグ並べ替えなど）が公開されている。Claude Codeへの指示は「HTMLファイルで作って」と書くだけで十分とThariqは述べる。

人間が直接編集する文書はMarkdown、エージェントが生成して読ませる成果物はHTML──という棲み分けが浮上している。これはplaygroundの発想と通底し、ファイルシステム重視の設計とも符合する。シリーズ全体の「ファイル＝交換フォーマット」という思想がHTML出力に結実した形だ。

詳細は Claude CodeはなぜMarkdownでなくHTMLを出力すべきか で9ユースケースに分けて解説している。

09 7本を貫く設計哲学とClaude Code開発者の頭の中

ここまで7本のクラスタ記事を概観した。最後にシリーズ全体を貫く思想を整理する。

Thariqの設計哲学は3つの軸で表現できる。

それぞれの軸で具体的なテクニックを整理すると以下になる。

この3軸は互いに補強し合う。キャッシュを壊さないためにツールを増やさず、ツールを増やさないためにbash＋Skills＋ファイルシステム＋HTML出力でコンテキストを節約し、その節約はエージェント目線で「Claudeが好む形」に整えることで成立する。

Claude Codeを単なるツールとして使うだけでも有用だが、自作エージェントを設計する人にとっては、これら7本のスレッドが「設計判断の生データ」になる。Anthropic公式エンジニアが半年以上かけて公開した一次情報を、本シリーズで日本語に体系化した。

各クラスタ記事のリンクを再掲する。気になるテーマから読み進めてほしい。

• ClaudeチームThariqが明かしたSkills設計9カテゴリ｜Anthropic社内で数百個動かす実践則
• Claudeコードのツール設計はなぜ「芸術」か｜ThariqのSee Like an Agent
• Claude Codeハーネスはなぜprompt caching中心に設計されたか
• Claude Code開発者公式プラグイン「playground」
• ThariqがXで断言「全エージェントはファイルシステムを使え」
• Thariq「非コーディングエージェントこそbashを使え」
• Claude CodeはなぜMarkdownでなくHTMLを出力すべきか

Claude Codeアーキテクチャ完全解剖や Claude Codeのベストプラクティス完全ガイド2026年版 も併読すると、設計則と実装の両面から理解が深まる。

参照ソース

• Thariq氏のXハイライト
• Lessons from building Claude Code: Prompt caching is everything（公式blog）
• Anthropic Claude Code 公式ドキュメント
• Thariq氏 個人サイト