Claude Code アーキテクチャ深層分析 — AIコーディングエージェントの設計原理を推論する

投稿 2026/04/01

上級

By Sehyup

26 分読む時間

Claude Code アーキテクチャ深層分析 — AIコーディングエージェントの設計原理を推論する

前提知識 — 先にこちらをご確認ください

/posts/ClaudeCodeInsights/

Claudeの記憶システム徹底解析 — Auto Memory、... AIエージェントハーネスエンジニアリング深層解剖 — オーケスト...

TL;DR — 要点まとめ

Claude Codeを使いながら観察した動作と公式ドキュメント、公開された技術スタック情報をもとに内部アーキテクチャの設計原理を推論・分析する
コア設計軸はGeneratorベースのストリーミングクエリループ、Fail-Closedセキュリティモデル、構造化コンテキストコンパクションであり、これらのパターンは大規模AIエージェント構築の一般的な設計原理として活用できる
パワーユーザー向けの公式ドキュメントベースの活用ティップス — CLAUDE.mdのローディング優先順位、Hookイベント活用、環境変数チューニングなどを整理した

はじめに

Claude CodeはAnthropicが開発したCLIベースのAIコーディングエージェントである。ターミナルから直接コードを読み、修正し、ビルドし、テストまで実行するエージェント型ツールで、2025年以降急速に発展してきた。

この記事では、Claude Codeを長期間使用しながら観察した動作パターン、公式ドキュメント、そして公開された技術スタック（TypeScript、Bun、Inkなど）の特性をもとに内部アーキテクチャの設計原理を推論・分析する。

分析の根拠：

公式ドキュメントおよびブログポスト
CLI使用中に観察される動作パターン
公開されたnpmパッケージメタデータおよび依存関係ツリー
システムプロンプトで観察可能な構造
AIエージェント設計の一般的なパターンとベストプラクティス

注記：この記事は公開情報と使用経験に基づく推論であり、実際の内部実装とは異なる場合があります。

1. プロジェクト概要 — 技術スタックとスケール感

1-1. 公開された技術スタック

項目	技術
言語	TypeScript
ランタイム	Bun
UIフレームワーク	React + Ink（ターミナルTUI）
パッケージマネージャ	npm (@anthropic-ai/claude-code)
内蔵ツール	42個以上（Read、Write、Edit、Bash、Glob、Grep、Agentなど）
拡張	MCP（Model Context Protocol）サーバー連携

使用中に観察される動作から推察すると、かなりの規模のコードベースであることがわかる。起動時間の最適化、遅延読み込み、ツール別条件付き活性化など、大規模プロジェクトで見られるパターンが観察される。

1-2. 起動時間の最適化

CLIツールとして体感起動時間が非常に速い。--versionのような単純なフラグはほぼ0msに近い速度で応答する。

これは動的importを活用した遅延読み込みパターンを使用していることを示唆する：

単純なフラグ処理時に重いモジュールをロードしない
認証、設定読み込みなどの初期化作業を並列で実行
Bunランタイムの高速起動時間を活用

2. アーキテクチャ — リクエストからツール実行までの流れ

Claude Codeの動作を観察すると、以下のようなパイプライン構造を推論できる：

ユーザー入力
    ↓
[1] CLIブートストラップ — 認証、モデル選択、権限モード設定
    ↓
[2] TUI（ターミナルUI） — React/Inkベースの対話型インターフェース
    ↓
[3] クエリエンジン — システムプロンプト組立、メッセージ正規化
    ↓
[4] API呼び出し + ツール実行ループ
    │   ├→ Anthropic API（SSEストリーミング）
    │   ├→ ツール実行（42+内蔵ツール + MCPツール）
    │   ├→ 自動コンテキスト管理（コンパクション）
    │   └→ メモリシステム
    ↓
[5] 結果をユーザーにレンダリング

2-1. ビルドタイムフィーチャーゲーティング

Bunのバンドリング機能を活用したビルドタイムDead Code Eliminationが適用されているようだ。特定の機能はビルド時点で有効化/無効化され、該当機能のコードが最終バンドルから完全に除去される。

この方式の利点：

ランタイム条件分岐なしでコードサイズ最適化
内部専用機能と外部公開機能のクリーンな分離
バンドルサイズの最小化

3. Toolシステム — ツールの型設計

3-1. ツールインターフェースパターン

Claude Codeの各ツール（Read、Write、Edit、Bashなど）は共通インターフェースに従っていると観察される。一般的なAIエージェントツール設計を参考にすると、以下のような契約（contract）が必要である：

ツールインターフェース（推論）：
├── name: ツール名
├── call(): ツール実行 + 結果返却
├── checkPermissions(): 権限確認
├── description(): ツール説明生成
│
├── isReadOnly(): 読み取り専用かどうか
├── isConcurrencySafe(): 同時実行可能かどうか
├── isDestructive(): 破壊的操作かどうか
│
├── renderToolUseMessage(): ツール使用時のUI表示
├── renderToolResultMessage(): 結果UI表示
│
└── maxResultSizeChars: 結果サイズ制限

3-2. Fail-Closedデフォルト

Claude Codeの動作を観察すると、Fail-Closed原則が一貫して適用されている：

新しいツールはデフォルトで安全でないと仮定 — 同時実行不可、書き込み可能と見なす
明示的に安全だと宣言したツールのみ並列実行を許可
明示的に読み取り専用だと宣言したツールのみ自動許可対象

この原則はセキュリティ設計で非常に重要で、新しいツールを追加する際に安全性宣言を忘れても常に安全な方向で動作するためである。

3-3. ツールプール組立

内蔵ツールとMCP外部ツールを合わせて一つのツールプールを構成する。このとき名前順ソートが重要で、Anthropic APIのプロンプトキャッシュキーがツールリストの順序に影響を受けるためである。順序が変わるとキャッシュが壊れてコストが増加する。

3-4. ツール遅延読み込み

システムプロンプトで確認できるように、一部のツールは遅延読み込み（deferred）方式で動作する。すべてのツールを最初からロードするとシステムプロンプトが長くなりすぎるため、必要な時にスキーマを取得する方式である。

4. コア設計パターンの詳細分析

4-1. Bashセキュリティ — 多層防御モデル

Claude CodeのBashツールは最も強力でありながら最も危険なツールである。使用中に観察される動作から、多層セキュリティパイプラインが適用されていると推測される：

[1] 正規表現ベースの危険パターン検出
    - プロセス置換、コマンド置換などの危険構文検出
    - Unicode攻撃、制御文字フィルタリング

[2] ASTベースの構造分析
    - Bashコマンドをパースして抽象構文木（AST）を生成
    - 許可リストにない構造 → 自動拒否（Fail-Closed）
    - 単純コマンド（simple command）のみ自動処理対象

[3] 権限ルールマッチング
    - argv[0]と事前定義パターンのマッチング
    - settings.jsonのalwaysAllow / alwaysDenyルール適用

[4] ユーザー確認ダイアログ
    - 上記段階をすべて通過できない場合、ユーザーに直接確認

コア原則：「このコマンドから信頼できるargv[]を抽出できるか？」→ 可能ならルールマッチング、不可能ならユーザーに直接確認。理解できないものはブロックする。

4-2. プロンプトキャッシュ最適化

Claude CodeはAPI呼び出しコストを最適化するためにプロンプトキャッシュを積極的に活用している。

キャッシュキーの構成要素（Anthropic APIドキュメント基準）：

システムプロンプト
ツールリスト（順序含む）
モデル
メッセージプレフィックス

そのための観察可能な最適化：

ツールリストの決定論的ソート（名前順、ビルトイン優先）
システムプロンプトの静的/動的領域分離（キャッシュ可能領域の最大化）
サブエージェントのシステムプロンプトを親と同一に維持してキャッシュを共有

4-3. 構造化コンテキストコンパクション

会話が長くなるとClaude Codeが自動的にコンテキストを圧縮するのが観察できる。/compactコマンドで手動トリガーも可能である。

観察されたコンパクション動作：

自動トリガー：コンテキストウィンドウの一定割合を超えると自動実行
構造化された要約：単純な要約ではなく、複数のセクションに分かれた構造的圧縮
- ユーザーリクエストと意図
- 技術的概念
- ファイルとコードセクション
- エラーと解決策
- 残りのタスクと現在の作業状態
ユーザーメッセージ保存：ユーザーが提供したフィードバックと指示は圧縮時にも保存
画像処理：圧縮前に画像をテキストマーカーに置換してAPI呼び出しを最適化

4-4. トークン超過復旧戦略

API呼び出し時にトークン制限に達すると段階的な復旧戦略が適用される：

状況	復旧戦略
トークン超過（1回目）	リアクティブコンパクション — 会話履歴を構造化された要約に圧縮
トークン超過（2回目）	最大出力トークンを段階的に増加
トークン超過（3回目）	強制終了
コンテキストウィンドウ接近	事前的自動コンパクション
APIエラー	指数バックオフリトライ

4-5. メモリシステムの関連性検索

Claude Codeのメモリシステム（~/.claude/projects/*/memory/）は従来のベクトル検索ではなく、LLMベースの関連性判断を使用していると見られる。

観察された動作：

メモリファイルのヘッダー（name、description）を基に関連性判断
1ターンに最大少数のメモリのみ選択的にロード
すでに使用されたツールのリファレンスドキュメントは重複ロード防止
前のターンですでに提供されたメモリはフィルタリング

4-6. 大型ツール結果処理

ツール実行結果が非常に大きい場合（ファイル読み込み、検索結果など）、結果全体をコンテキストに入れずにディスクに永続化した後プレビューのみ伝達するパターンが観察される。

これはコンテキストウィンドウを節約しながらも必要時に全体の結果にアクセスできる合理的な設計である。

4-7. 選択的リトライ戦略

API過負荷（529）状況でのリトライ動作を観察すると：

ユーザーが待っているメインリクエスト：リトライ実行
バックグラウンドタスク（タイトル生成、要約など）：即時失敗（リトライなし）

これは過負荷時に不要なリトライが状況を悪化させるのを防ぐ設計で、「capacity cascadeにおける各リトライは3-10倍のgateway増幅を引き起こす」という原則に基づいていると見られる。

5. システムプロンプト構造

5-1. 静的/動的境界

システムプロンプトを観察すると静的領域と動的領域が分離されている：

[静的領域 — プロンプトキャッシュ可能]
  ├── ツール説明
  ├── 基本指示（# System、# Doing tasks、# Using your tools）
  ├── セキュリティ指示
  └── コードスタイル指示
──── （境界線） ────
[動的領域 — 毎ターン変更]
  ├── CLAUDE.md内容
  ├── git statusスナップショット
  ├── セッション別ガイダンス
  ├── メモリ（MEMORY.md）
  └── 言語設定、出力スタイル

静的領域を前方に配置するとプロンプトキャッシュヒット率が向上する。動的領域の内容が変わっても静的領域のキャッシュは維持されるためである。

5-2. CLAUDE.mdローディング優先順位

公式ドキュメントで確認可能なローディング順序：

/etc/claude-code/CLAUDE.md  — 管理者設定（最低優先順位）
~/.claude/CLAUDE.md          — ユーザーグローバル設定
{プロジェクト}/CLAUDE.md、.claude/CLAUDE.md、.claude/rules/*.md
{プロジェクト}/CLAUDE.local.md  — 最高優先順位

後からロードされたものがモデルに近い位置に配置され、より多くの注目を受ける。

6. 実践パワーユーザーティップス

6-1. 環境変数チューニング

公式ドキュメントおよび設定で確認可能な環境変数：

環境変数	機能
`DISABLE_AUTO_COMPACT=1`	自動コンパクト無効化
`CLAUDE_CODE_MAX_OUTPUT_TOKENS`	最大出力トークン設定

環境変数リストはバージョンによって変更される可能性があるため、公式ドキュメントを参照することを推奨する。

6-2. Hookイベント活用

公式ドキュメントで確認されたHookイベント：

PreToolUse / PostToolUse
Notification
Stop
SubagentStop

Hookが返却できるアクション：

approve / deny / block — ツール実行の許可/拒否/ブロック
reason — 決定理由
updatedInput — 修正された入力

Hookを活用すればツール実行を自動化したり、特定パターンのコマンドを自動承認/拒否できる。

6-3. エージェント活用最適化

システムプロンプトで確認可能なエージェントタイプ：

エージェント	用途	特徴
`Explore`	コードベース探索	`quick` / `medium` / `very thorough` 深さ指定
`Plan`	設計/計画	実装戦略設計に特化
`general-purpose`	マルチステップタスク	CLAUDE.md含む、最も汎用的

Exploreに探索深度を明示すると探索範囲が変わるため、単純な検索にはquick、深い分析にはvery thoroughを指定するのが効率的である。

7. セキュリティ設計原則

Claude Codeのセキュリティ設計で一貫して観察される原則：

7-1. Fail-Closed戦略

理解できないBashコマンド → ブロックしてユーザー確認要請
新しいツールのデフォルト権限 → 非許可（明示的許可必要）
同時性安全性未宣言 → シリアル実行

7-2. 多層防御（Defense in Depth）

Bashコマンド一つを実行するために正規表現フィルタ → AST分析 → 権限マッチング → ユーザー確認の多段階検証を経る。

7-3. ファイルシステム保護

.gitconfig、.bashrc、.zshrcなどのシステム設定ファイルと.git、.vscode、.claudeなどの重要ディレクトリに対する保護が観察される。

7-4. 5段階パーミッション決定フロー

ツール使用リクエスト
  ↓
① 静的ルール（settings.jsonのalwaysAllow/alwaysDeny）
  ↓
② Hook実行（外部プロセスフックが登録されている場合）
  ↓
③ 自動分類（安全なコマンドの自動判別）
  ↓
④ マルチエージェント委任（サブエージェントの場合）
  ↓
⑤ ユーザーダイアログ（最終確認）

8. おわりに

Claude Codeを深く使いながら観察した設計哲学は三つにまとめられる：

Fail-Closedセキュリティ：理解できないものはブロックする。Bashセキュリティ、権限システム全体がこの原則の上にある。
コスト最適化：プロンプトキャッシュ、選択的リトライ、ツール結果のディスク永続化、画像処理最適化など、トークン一つまで節約しようとする設計が随所にある。
段階的機能リリース：フィーチャーフラグで機能を隔離し、段階的にロールアウトする。観察されない機能がビルドに含まれている可能性もある。

これらの設計原理はClaude Codeだけに該当するものではなく、大規模AIエージェントを構築する際に普遍的に適用できるアーキテクチャパターンである。特にFail-Closedセキュリティモデルと構造化コンパクションはどのAIエージェントプロジェクトでも参考にする価値がある。

参考資料

Claude Code インサイト — Claude Codeの基本活用法
Anthropic Tool Use Documentation — 公式ツール使用ガイド
Claude Code 公式ドキュメント — 公式使用ガイド
Model Context Protocol — MCP公式ドキュメント

AI, Claude

この記事は著者の CC BY 4.0 ライセンスの下で提供されています。