Claude Codeのソースコードを解析した論文から読み解く、AIエージェントの設計思想

毎日 Claude Code を使っているのに、中身はほとんど知らないまま使っている――自分もそうでした。

「なんでここで許可を求めてくるんだろう」「コンテキストが詰まると何が起きているんだろう」「/compact って何をしているんだろう」。使えば使うほど疑問が積み上がっていくのに、公式ドキュメントを読んでも設計の根拠まではわかりません。

そこに、ちょうどよい論文が公開されました。Jiacheng Liu らが Claude Code の TypeScript ソースコード（v2.1.88）を実際に解析し、その設計思想をまとめた研究論文 “Dive into Claude Code: The Design Space of Today’s and Future AI Agent Systems”（arxiv: 2604.14228）です。

この記事では、その論文の要点を噛み砕いて解説します。Claude Code ユーザーが「なぜこう動くのか」を理解するための手がかりになれば、と思います。

中核は「シンプルなループ」

論文が最初に指摘するのは、Claude Code の実行モデルの単純さです。

コアのロジックは、こう表現できます。

while true:
    モデルを呼び出す
    ツールを実行する
    繰り返す

モデルに状況を伝え、モデルが次のアクションを決め、ツールを実行し、結果をモデルに返す。これだけです。LLM を使ったエージェントの基本形は、どれもこのループが核になっています。

では、Claude Code のコードの大部分は何に使われているのか。論文によれば、それはすべて「周辺システム」です。

• 安全性（人間が意図しない操作を防ぐ）
• コンテキスト管理（トークン上限との戦い）
• 拡張性（MCP やフックで機能を足せるようにする）

「シンプルなコアに、複雑な周辺を積み上げる」。これが Claude Code の設計の基本形です。

設計の根っこにある 5 つの価値観

論文は、Claude Code の設計全体を貫く 5 つの価値観を抽出しています。コードを読んでいくと、すべての設計判断がこの価値観に基づいていることがわかると言います。

たとえば「許可を求めてくる」という動作は、「人間の決定権」と「安全保障」が具体化されたものです。「MCP でツールを追加できる」のは「能力の拡張」と「文脈適応性」から来ています。

価値観を知ると、個々の動作がなぜそうなっているかが腑に落ちてきます。

許可システム：5 つのモード

Claude Code が「このコマンドを実行していいですか？」と聞いてくる動作は、許可システムによって制御されています。論文はこのシステムを 5 つのモードとして整理しています。

さらに、ML 分類器を使う auto モードと、サブエージェント向けの内部 bubble モードも存在します。

重要なのはデフォルトの設計哲学です。「人間が主導権を持つ」を基本姿勢にしているため、デフォルトモードでは不確かな操作は必ず止まって確認を求めます。自動化を進めたい場合は acceptEdits や dontAsk に変更しますが、それは明示的な選択として行う設計になっています。

--dangerously-skip-permissions を使ったことがある方は、これが bypassPermissions に相当します。「危険に」という言葉をあえて名前に入れているのも、価値観としての人間の決定権を守るためだと思うと、設計の一貫性が見えてきます。

コンテキスト管理：5 層のパイプライン

Claude Code を長時間使っていると、「コンテキストが満杯に近づいています」というメッセージが出て、自動的に /compact が走ることがあります。このとき、内部では何が起きているのでしょうか。

論文によれば、コンテキスト管理は 5 つの層が順番に動くパイプラインになっています。

コストの低い層から順番に試し、それでも足りなければより重い層へ進む、という設計です。

自分が体験したことで言うと、長い会話でファイルを何度も読んだり編集したりしていると、コンテキストが急速に減っていきます。Budget reduction がツール出力を削っている段階では気づかず、Snip や Microcompact が走り始めると「なんか動作が変わった？」という感覚になり、Auto-compact が走るときに初めて「圧縮しました」と通知が出る、という体験が論文の説明と符合します。

この設計のポイントは「段階的なコスト配分」です。毎回フルの圧縮をかけるのではなく、必要に応じて軽い処理から始める。これは LLM 呼び出しのコストを最小化しながら、できるだけ長い会話を維持するための合理的な判断です。

4 つの拡張メカニズム

Claude Code に機能を追加する方法は 4 つあります。論文はこれらを「層状のメカニズム」として整理しています。

なぜ単一の API ではなくこの 4 層構造なのか。論文は「異なるコンテキストコストがある」と説明しています。

MCP は常時ロードされてコンテキストを消費しますが、どのプロジェクトにも使いまわせます。Hooks はコンテキストコストゼロで特定のイベントに反応できますが、LLM の判断を介しません。Skills はコンテキストに展開されますが、モデルの判断を活かした柔軟な動作ができます。

それぞれが異なるトレードオフを持ち、用途によって使い分ける、という設計です。自分の場合、繰り返す定型処理は Hooks に書き、プロジェクト固有の手順は Skills に書く、という使い方がちょうどこの設計に合致していると気づきました。

マルチエージェント：サブエージェントの委譲

Claude Code は、タスクを別のエージェントに委譲できます。論文はこの仕組みも詳しく分析しています。

核心は「ワークツリー分離」です。サブエージェントが作業するとき、親エージェントとは別の Git ワークツリーが作られます。これにより、サブエージェントのファイル変更が親の作業空間に干渉しません。

設計上の重要な点は「スコープの管理は親エージェントが行う」ことです。サブエージェントは自分に与えられたタスクを実行するだけで、タスクの範囲を広げることはできない。これも「人間の決定権」という価値観の具体化で、エージェントが勝手に作業範囲を拡大しないための安全機構です。

比較から見える「設計空間」という概念

論文のもう一つの貢献は、OpenClaw という別のオープンソースエージェントシステムとの比較です。

Claude Code はローカル開発に特化した CLI ツールです。対して OpenClaw は多機能なパーソナルアシスタントゲートウェイで、異なる文脈で使われます。

論文はこの比較を通じて「繰り返し設計質問」を抽出しています。すべてのエージェントシステムが答えなければならない問いです。

「同じ問いに、異なる文脈では異なる答えが生まれる」。これが論文の主張する「設計空間」という概念です。Claude Code の設計が唯一の正解ではなく、ローカル開発という文脈に最適化した一つの選択だ、ということです。

まとめ

論文が示した Claude Code のアーキテクチャをまとめると、こうなります。

• コア: シンプルな while ループ（モデル呼び出し → ツール実行）
• 価値観: 人間の決定権・安全保障・信頼できる実行・能力の拡張・文脈適応性
• 許可システム: 5 モードで「人間が主導権を持つ」を実装
• コンテキスト管理: 5 層のパイプラインで段階的に圧縮
• 拡張機構: MCP・Plugins・Skills・Hooks の 4 層
• マルチエージェント: ワークツリー分離でサブエージェントを安全に隔離

設計思想を知ると、ツールの使い方が変わります。「なぜここで止まるのか」「なぜコンテキストがこのタイミングで圧縮されるのか」が理解できると、ツールに翻弄されるのではなく、意図して使える感覚になります。

論文全文は arxiv で公開されています（arxiv.org/abs/2604.14228）。TypeScript のソースコードを追いながら読むと、さらに理解が深まります。