<a href=Claude Codeの内部設計から学ぶAIエージェント設計パターン">

Claude Codeの内部設計から学ぶ、AIエージェントの作り方【5つの設計パターン】

2026年3月31日、Claude Codeのnpmパッケージに含まれていた.mapファイル（ソースマップ）経由で、内部のソースコードが一時的に閲覧可能な状態になりました。Anthropicは数時間で該当バージョンを削除しソースマップも除去しましたが、その間に多くの開発者がコードを分析し、AIエージェント設計の教科書レベルの実装パターンが複数発見されています。

この記事では、Claude Codeの内部設計から読み取れる5つの設計パターンを解説します。自作のAIエージェントを設計する際に、そのまま応用できる実践的な知見です。

この記事のポイント: Anthropicのソースコードそのものは引用しません。公開されたシステムプロンプト（Piebald-AI/claude-code-system-prompts）と、複数の分析記事をもとにした設計パターンの考察として構成しています。

この記事でわかること

  • Claude Codeが採用するコンテキスト圧縮の3段階戦略
  • MEMORY.mdベースの永続メモリシステムの設計思想
  • Coordinator + Worker型マルチエージェント協調の仕組み
  • パーミッション3段階モデルのセキュリティ設計
  • 未公開のフィーチャーフラグから見える今後のロードマップ

背景：なぜClaude Codeの設計が「教科書」なのか

Claude Codeのアーキテクチャ

Claude Codeは、2026年現在もっとも実用性が高いと評価されるAIコーディングエージェントのひとつです。ターミナルで動作し、ファイル編集・コマンド実行・Web検索などを自律的に行います。

しかし、これまでその内部がどう設計されているかは完全にブラックボックスでした。今回のソースマップリークにより、プロダクションレベルのAIエージェントがどのような設計判断をしているかが初めて明らかになりました。

特に注目すべきは、単なる「LLMにツールを渡す」以上の緻密なエンジニアリングが施されている点です。コンテキストウィンドウの管理、メモリの永続化、マルチエージェントの協調——いずれも、自作エージェントを「動くだけ」から「実用レベル」に引き上げるために不可欠な設計パターンです。

パターン1：コンテキスト圧縮の3段階戦略

なぜ重要か

LLMのコンテキストウィンドウには上限があります。Claude Codeが使うClaude Opus 4でも200Kトークンが上限です。長い開発セッションでは、ファイルの読み書き・コマンド実行の履歴がすぐにこの上限に達します。

多くの自作エージェントが「コンテキストが溢れて動かなくなる」問題に直面しますが、Claude Codeはこれを3段階の圧縮戦略で解決しています。

Claude Codeの設計

第1段階：ツール結果の選択的クリア（〜160Kトークン）

コンテキストが一定量に達すると、まず古いツール呼び出しの結果を選択的に削除します。重要なのは「すべて消す」のではなく、結果だけを消してツール呼び出しの事実は残す点です。これにより「何をしたか」の履歴は保持しつつ、トークンを節約できます。

第2段階：thinking（推論トレース）の削除（〜170Kトークン）

次に、モデルの内部推論（thinking/reasoning）のテキストを削除します。これは人間には見えない部分で、削除しても会話の流れに影響しません。しかしトークン消費は大きいため、効果的な圧縮になります。

第3段階：自動コンパクション（〜180Kトークン）

最後の手段として、LLM自身に「これまでの会話を要約して」と依頼します。要約結果を新しいコンテキストとして使い、元の会話履歴を捨てます。Claude Codeではこの閾値が約180Kトークンに設定されています。

自作エージェントへの応用

# コンテキスト圧縮の実装イメージ（疑似コード）

def manage_context(messages, token_count):
    if token_count > THRESHOLD_1:  # 80% of limit
        # ツール結果だけクリア（呼び出し記録は残す）
        for msg in messages:
            if msg.type == "tool_result" and msg.age > 10:
                msg.content = "[結果省略]"

    if token_count > THRESHOLD_2:  # 85% of limit
        # thinking/reasoningを削除
        for msg in messages:
            if msg.type == "thinking":
                messages.remove(msg)

    if token_count > THRESHOLD_3:  # 90% of limit
        # LLMに要約を依頼して会話をリセット
        summary = llm.summarize(messages)
        messages = [system_prompt, summary]

ポイントは段階的に圧縮することです。一気にすべてを消すのではなく、影響の小さいものから順に削除していきます。これにより、できる限り長くフルコンテキストを維持できます。

パターン2：MEMORY.mdベースの永続メモリシステム

メモリシステム設計

なぜ重要か

LLMは基本的にステートレスです。セッションが終われば全てを忘れます。しかし実用的なエージェントには「このプロジェクトのビルドコマンドはnpm run build」「テストはpytestで実行する」といったプロジェクト固有の知識を覚えておく能力が必要です。

Claude Codeの設計

Claude Codeの永続メモリは、驚くほどシンプルな設計です——MEMORY.mdというマークダウンファイルに書くだけ。

制約による品質管理：

  • ファイルサイズ上限は約25KB（200行）
  • この制約があるからこそ、本当に重要な情報だけが残ります
  • 容量を超えると古い情報を統合・削除する圧力が自然に働きます

スコープの分離：

  • ~/.claude/CLAUDE.md — ユーザーグローバルな設定（全プロジェクト共通）
  • ./CLAUDE.md — プロジェクト固有の設定（リポジトリごと）
  • トピック別にファイルを分割可能（memory/ディレクトリ）

自動メモリ抽出：

会話の終了時に、Claude Code自身が「この会話で学んだ重要なことをメモリに追記すべきか」を判断し、自動的にMEMORY.mdを更新します。人間が明示的に「覚えて」と言わなくても、重要な情報が蓄積されていく仕組みです。

自作エージェントへの応用

多くの開発者がベクトルDBやRAGのような複雑な仕組みでメモリを実装しようとしますが、Claude Codeの設計は「プレーンテキストファイルで十分」という強いメッセージを送っています。

エージェントのメモリ設計で重要なのは以下の4点です。

  1. サイズ制限を設ける — 無制限に蓄積すると、ノイズだらけで使い物にならなくなります
  2. スコープを分ける — グローバル設定とプロジェクト設定は別ファイルに
  3. 自動更新の仕組み — セッション終了時に「学んだこと」を書き出すプロンプトを仕込みます
  4. 人間が読める形式 — デバッグや修正が容易です。ベクトルDBは中身が見えません

パターン3：Coordinator + Worker型マルチエージェント協調

なぜ重要か

複雑なタスク（「このリポジトリ全体をリファクタリングして」等）を1つのエージェントで処理するのは非効率です。コンテキストが溢れ、途中で迷子になり、結果の品質も下がります。

Claude Codeの設計

Claude CodeはCoordinatorモードと呼ばれるマルチエージェント機能を持っています。

アーキテクチャ：

  • Coordinator（指揮者）：タスクを分割し、ワーカーに配分し、結果を統合します
  • Worker（作業者）：個別のサブタスクを実行します。ツールセットが制限されています

ワーカーの制限が鍵：

ワーカーには意図的に使えるツールが制限されています。たとえば、ワーカーは新しいサブエージェントを生成できません（無限再帰の防止）。これは安全性と予測可能性のための設計判断です。

エージェント間メッセージング：

CoordinatorとWorker間は構造化されたメッセージでやり取りします。ワーカーの完了報告にはサマリーが含まれ、Coordinatorはそれを元に次のステップを判断します。

サブエージェントの種類：

分析によると、Claude Codeには用途別のサブエージェントプロンプトが存在します。

  • Plan（計画エージェント）— タスクの分解と実行計画の策定
  • Explore（探索エージェント）— コードベースの調査と理解
  • Task（実行エージェント）— 具体的な変更の実施
  • Security Monitor（セキュリティ監視）— 自律的な操作の安全性チェック

自作エージェントへの応用

マルチエージェント設計のポイントは4つあります。

  1. ワーカーの権限を制限する — すべてのツールを渡さず、必要最小限に絞ります
  2. 再帰を防止する — ワーカーが新しいエージェントを生成できないようにします
  3. サマリーベースの報告 — ワーカーの全出力をCoordinatorに渡すのではなく、要約だけを返します（コンテキスト節約）
  4. 役割を明確に分ける — 「計画」「探索」「実行」「監視」のように、専門性を持たせます

パターン4：パーミッション3段階モデル

パーミッション設計

なぜ重要か

AIエージェントがファイルを削除したり、外部APIを呼んだりする場合、すべての操作に人間の承認を求めると使い物になりません。かといって全自動にするとリスクが高い。このバランスをどう取るかは、エージェント設計の根本的な課題です。

Claude Codeの設計

Claude Codeは3段階のパーミッションモデルを採用しています。

1. Plan（デフォルト）

  • ファイルの読み取りは自由
  • 書き込み・コマンド実行は毎回ユーザーの承認が必要
  • もっとも安全ですが、承認の手間がかかります

2. Auto（自動承認）

  • 設定したパターンに一致する操作は自動承認
  • 例：*.test.tsファイルの編集は自動OK、*.envの編集は承認必要
  • パターンマッチによる柔軟な制御が可能です

3. bypassPermissions（完全自律）

  • すべての操作を承認なしで実行
  • セキュリティモニターエージェントが代わりに監視
  • エージェントの操作をブロック/許可ルールで制御します

注目すべきは、完全自律モードでもセキュリティモニターという別のエージェントが「この操作は安全か」をチェックする二重構造になっている点です。AIの行動をAIが監視する——これはプロダクションレベルのエージェントに不可欠な設計です。

自作エージェントへの応用

  • デフォルトは最も安全なモードにしましょう。ユーザーが明示的に緩和する構造にします
  • パターンマッチで自動承認の仕組みを入れます。ファイルパスやコマンドの種類で判定します
  • 完全自律モードには監視レイヤーを必ず設けてください。「AIがAIを監視する」は今やベストプラクティスです

パターン5：フィーチャーフラグから見える未来の設計

なぜ重要か

ソースコード内のフィーチャーフラグ（機能の有効/無効を切り替えるスイッチ）は、開発中の機能を示します。Claude Codeの未公開フラグからは、AIエージェントの次のフロンティアが見えてきます。

発見されたフィーチャーフラグ

PROACTIVE

  • エージェントがユーザーの指示を待たずに自発的に行動する機能です
  • 例：コードの問題を検知したら、聞かれる前に修正を提案します

KAIROS

  • 名前の由来はギリシャ語で「好機」。タイミングベースの行動トリガーと推測されています
  • スケジュールされたタスクの実行や、特定条件での自動起動に関連する可能性があります

VOICE_MODE

  • 音声入力/出力のサポートです。ターミナルでの対話を音声ベースに拡張します
  • 2026年3月のアップデートで一部機能が安定化しています

DAEMON

  • バックグラウンドで常駐するエージェントです。セッションを明示的に開始しなくても動き続けます
  • ファイル変更の監視、CIの状態監視などに使われる可能性があります

TEAMMEM

  • チームメモリです。複数のエージェント（または複数の開発者のClaude Code）間で記憶を共有します
  • 組織レベルの知識ベースとして機能する可能性があります

自作エージェントへの応用

これらのフラグが示す方向性は3つあります。

  1. プロアクティブ（先回り）行動 — 「聞かれてから答える」だけでなく、問題を検知して先に動く設計です
  2. 常駐型エージェント — セッションベースではなく、バックグラウンドで常に動いている設計です
  3. チーム間の知識共有 — 個人のメモリを超えて、組織の知識としてエージェントが学習する仕組みです

これらは2026年後半〜2027年にかけて、AIエージェントの標準的な機能になっていくでしょう。

5つのパターンのまとめ

パターン 課題 Claude Codeの解法 自作への応用
コンテキスト圧縮 ウィンドウ上限 3段階の段階的圧縮 影響小→大の順に削除
永続メモリ セッション間の記憶 MEMORY.md（25KB上限） プレーンテキスト+サイズ制限
マルチエージェント 複雑タスクの分割 Coordinator + 制限付きWorker 権限制限+再帰防止
パーミッション 安全性と利便性 3段階モデル+セキュリティ監視 デフォルト安全+パターンマッチ承認
フィーチャーフラグ 今後の方向性 PROACTIVE/DAEMON/TEAMMEM 先回り行動+常駐+チーム共有

実践：最小構成のAIエージェントに5パターンを適用する

これらのパターンを実際に適用するなら、以下の優先順位がおすすめです。

まず実装すべき（効果が大きい）：

  1. コンテキスト圧縮 — これがないと長いセッションで必ず破綻します
  2. 永続メモリ — MEMORY.mdファイルを1つ作るだけで劇的に改善します

次に実装すべき： 3. パーミッションモデル — 安全性の担保です。特に外部APIを呼ぶ場合は必須です 4. マルチエージェント — タスクの複雑度が上がってきたら導入しましょう

将来に備える： 5. プロアクティブ行動・常駐型 — まだ実験段階ですが、差別化の大きなポイントになります

注意点：ソースコードリークの倫理面

今回のリークは、npmパッケージにソースマップが含まれていたことによる意図しない公開です。Anthropicは迅速に対応し、該当バージョンを削除しています。

この記事では：

  • ✅ 設計パターンの分析・考察として記述しています
  • ✅ 公開済みのシステムプロンプト集からの情報を参照しています
  • ❌ Anthropicのソースコードの直接引用は行っていません

AIエージェント開発のエコシステム全体にとって、こうした設計知見が共有されることには大きな価値があります。ただし、リバースエンジニアリングの倫理的境界は常に意識すべきです。

よくある質問

Q: Claude Codeの設計パターンは、他のLLM（GPT-4o、Gemini等）でも使えますか？

A: はい、使えます。コンテキスト圧縮、メモリシステム、マルチエージェント協調はいずれもLLMに依存しない設計パターンです。どのモデルをバックエンドにしても適用可能です。

Q: MEMORY.mdのようなプレーンテキストメモリは、ベクトルDBより劣りませんか？

A: 用途によります。プロジェクト設定やコーディング規約など構造化された少量の情報にはプレーンテキストが優れています。人間が読めて、デバッグしやすく、バージョン管理もできます。大量のドキュメント検索にはベクトルDBが適しますが、まずプレーンテキストから始めるのが正解です。

Q: セキュリティモニターエージェントはどう実装すればいいですか？

A: 最もシンプルな実装は、ツール呼び出しの前にLLMに「この操作は安全か」を判定させる方法です。ブロックリスト（絶対禁止の操作）と許可リスト（自動承認の操作）を定義し、どちらにも該当しない場合にLLMが判断する構造にします。

Q: フィーチャーフラグのDAEMONモードは、今すぐ自作できますか？

A: 技術的には可能です。ファイルシステムの変更監視（fswatch等）をトリガーにしてエージェントを起動する仕組みで近い動作は実現できます。ただし、トークンコストの管理とレート制限の設計が課題になります。

関連記事