「Claude Code」の設計思想：AIの裁量を支える最強の「ハーネス」

目次

現在、最も注目を集めるコーディングエージェントの一つである「Claude Code」。その驚異的な能力の源泉は、単なるプロンプトの工夫ではありません。最新の解析結果（論文[1]）により、その内部構造のコードのうち、AIが「次に何をすべきか考える」部分はわずか1.6%であり、残りの98.4%はAIを安全かつ快適に動作させるための「ハーネス（環境・制御機構）」で構成されていることが明らかになりました。

本記事では、AIモデルに大きな裁量を与えつつ、破綻させないための高度なアーキテクチャについて深掘りします。

概要と技術的背景

「Claude Code」のアーキテクチャは、「モデルを呼ぶ・ツールを実行する・繰り返す」というシンプルなループを基本としています。しかし、その周辺を固める「ハーネス」こそが、実用性を分ける鍵となっています。

従来のAIエージェント開発では、AIを強力なプロンプトや「足場（Scaffolding）」でガチガチに縛る手法が主流でした。しかし、Claude Codeは逆の戦略を採っています。AIモデルには広い裁量を与え、その代わりに取り巻く環境を徹底的に作り込むことで、柔軟性と安全性を両立させています。この構造により、セキュリティのダブルチェックや高度なコンテキスト管理が可能になっています。

詳細解説

Claude Codeを支える「ハーネス」の主要な機能は以下の5点に集約されます。

1. パーミッションシステム

「Deny → Ask → Allow」の順で処理される、徹底した拒絶優先の設計です。Anthropic社の調査[4]によると、ユーザーは求められた許可の約93%を思考停止で承認してしまいます。この「判断疲れ」を防ぐため、Claude Codeでは以下の工夫がなされています。

  • サンドボックス内での自己解決。
  • メタ的なLLMを用いた危険性の自動分類による確認回数の削減。

2. 4段階の拡張性

コンテキストウィンドウの消費量に応じて、以下の4つの拡張手段を使い分けています。

  • フック: コンテキスト消費ゼロ。
  • スキル: 説明文のみ（消費：小）。
  • プラグイン: 消費：中。
  • MCP (Model Context Protocol): ツールスキーマ定義が巨大（消費：多）。

3. 高度なコンテキスト圧縮

「Lazy Degradation（段階的な劣化）」という思想に基づき、以下の5段階のプロセスで圧縮を実行します。一気に要約せず、軽い処理から順に試すことで文脈を維持します。

  1. シンプル削減: 巨大な出力を参照情報に置き換え。
  2. 履歴の切り落とし: 古い会話やツール実行履歴を削除。
  3. microcompact: 詳細不明だが古いtool_resultを消去する仕組み。
  4. context collapse: 会話ラリーを簡潔な要約に置き換え。
  5. auto-compact: ある時点以前の全履歴を要約（最終手段）。

4. RAGを排したメモリ管理

ベクター検索は使用せず、プレーンテキストのMarkdown（CLAUDE.md）を階層構造で管理しています。

  • 思想: `CLAUDE.md`はシステムプロンプトではなく「ユーザーメッセージ」として渡されます。
  • 役割分担: `CLAUDE.md`の指示は「お願い（ガイダンス）」、確実に守らせるルールは「決定論的なパーミッションルール（強制）」と、意図的に分離されています。

5. サブエージェントとセッション

  • Git worktreeの活用: サブエージェントの分離に重いコンテナではなくGit worktreeを使用。ファイルレベルの分離を実現し、親には要約のみを返すことでコンテキストを節約します。
  • JSONLによる永続化: 会話はappend-onlyのJSONL形式で保存され、再開や分岐が容易です。ただし、セキュリティ上、再開時に過去の「許可」は復元されず、信頼はセッションごとに再構築（establish）されます。

クイック対談

エンジニア

AIが考えるコードは全体のわずか1.6%で、残りのほとんどがコンテキスト管理や権限チェックに割かれているのは驚きだ。モデルの賢さに依存しすぎない、堅牢なシステム設計の鑑だね。

デザイナー

ユーザーが93%の確率で許可ボタンを思考停止で押してしまうというデータに基づき、自動分類で確認回数を減らすUX設計は、安全性と利便性のトレードオフをうまく解決しているね。

実装・利用例

以下は、Claude Codeの「ハーネス」思想（原因と実行の分離）を模したシンプルなエージェント・ループのPython実装イメージです。

class PermissionGate:
    """deny-firstの権限判定を行うハーネス"""
    def __init__(self, mode="auto"):
        self.danger = {"rm", "sudo", "curl", "shutdown"}
        self.mode = mode

    def decide(self, action):
        # 1. ハードデナイ（NGリスト）
        if action.get("tool") == "run_command":
            exe = action["args"]["argv"][0]
            if exe in self.danger:
                return "deny", f"Dangerous command blocked: {exe}"
        
        # 2. 自動許可またはユーザー確認
        if self.mode == "auto":
            # 特定の安全なコマンドのみ自動許可するロジック
            return "allow", "Auto-approved by policy"
        
        return self.ask_user(action)

    def ask_user(self, action):
        print(f"Permission request: {action}")
        return ("allow", "approved") if input("Allow? [y/N]") == "y" else ("deny", "rejected")

class Agent:
    """思考（Model）と環境（Harness）を分離したループ"""
    def run(self, max_turns=12):
        for turn in range(max_turns):
            # 1. LLMが次にすべきことを考える (1.6%の部分)
            action = llm.generate_action(self.context)
            
            if action["type"] == "finish":
                break

            # 2. ハーネスが許可を出す (98.4%の部分)
            decision, reason = self.gate.decide(action)
            
            # 3. 許可された場合のみ外界へ干渉（Tools）
            if decision == "allow":
                result = self.tools.run(action)
                # コンテキスト管理（圧縮ロジックがここに入る）
                self.context.add_and_compress(result)
            else:
                self.context.add({"error": reason})

まとめ

  • Claude Codeの正体: 高品質な「ハーネス」によって守られた、自由度の高いAIモデルの実行環境である。
  • コンテキスト最適化: 貴重な枠を賢く使うため、5段階の圧縮処理や拡張手段の使い分け（MCP等）が徹底されている。
  • 強制とガイダンスの分離: 安全性はプロンプト（お願い）ではなく、決定論的なパーミッションルール（強制）によって担保されている。

モデルが決まったレールの上を走るよう縛るのではなく、AIが思う存分働ける「安全な環境」をひたすら作り込む。この「ハーネス」中心の設計思想こそが、次世代のAIエージェント開発におけるスタンダードとなるでしょう。

コメントを残す

入力エリアすべてが必須項目です。メールアドレスが公開されることはありません。

内容をご確認の上、送信してください。