第1章ハーネスとは何か

はじめに

Claude Code を使っていると、「モデルが賢い」だけでは説明できない挙動に気づきます。
ファイルを読み、コマンドを実行し、危険な操作の前に許可を求め、長い会話を自動で要約する——これらはすべて、モデル本体ではなく ハーネス（Harness） と呼ばれる実行基盤の仕事です。

本章では、ハーネスとは何か、なぜ重要なのかを整理し、以降の章で扱うコンポーネントの全体像を示します。

1.1 モデルとハーネスの関係

LLM（大規模言語モデル）そのものは「テキストを入力すると、テキストを出力する関数」にすぎません。
ファイルシステムへのアクセスも、コマンド実行も、記憶の保持もできません。

ハーネス は、このモデルを現実世界に接続するための「足回り」です。
馬具（harness）が馬と馬車をつなぐように、ハーネスはモデルとOS・ファイルシステム・外部サービスをつなぎます。

flowchart LR
    subgraph Harness["ハーネス（Claude Code CLI）"]
        direction TB
        SP["システムプロンプト<br/>CLAUDE.md 注入"]
        TL["ツール実行<br/>エンジン"]
        PM["パーミッション<br/>管理"]
        CM["コンテキスト<br/>管理"]
    end
    User["ユーザー"] --> Harness
    Harness <-->|"API リクエスト /<br/>レスポンス"| Model["Claude モデル<br/>（Opus / Sonnet / Haiku）"]
    Harness <--> FS["ファイルシステム"]
    Harness <--> Shell["シェル（Bash）"]
    Harness <--> Ext["MCP サーバー /<br/>外部サービス"]

役割分担を整理すると次のようになります。

責務	モデル	ハーネス
何をすべきか考える（推論）	✅	—
どのツールを呼ぶか決める	✅	—
ツールを実際に実行する	—	✅
実行前に許可を確認する	—	✅
会話履歴・コンテキスト管理	—	✅
設定・フックの適用	—	✅

1.2 エージェントループ

ハーネスの中核は エージェントループ です。
Claude Code は次のサイクルを、タスクが完了するまで自動で繰り返します。

flowchart TD
    A["1. ユーザーの指示を受け取る"] --> B["2. ハーネスがシステムプロンプト・<br/>設定・CLAUDE.md を組み立てて API へ送信"]
    B --> C["3. モデルが応答<br/>（テキスト or ツール呼び出し）"]
    C --> D{"ツール呼び出し？"}
    D -->|はい| E["4. ハーネスがパーミッションを確認"]
    E --> F["5. ツールを実行し、<br/>結果を会話に追加"]
    F --> B
    D -->|いいえ| G["6. 最終回答をユーザーに表示"]

ポイントは、モデルは「Bashでこのコマンドを実行したい」と宣言するだけ で、実際に実行するのはハーネスだという点です。
この分離があるからこそ、ハーネス側で以下のような制御を挟み込めます。

実行前の許可プロンプト（パーミッションモード）
実行前後のカスタム処理（フック）
サンドボックス内での実行
実行結果の整形・切り詰め

1.3 ハーネスを構成するコンポーネント

Claude Code のハーネスは、大きく次のコンポーネントで構成されます。
それぞれ以降の章で詳しく解説します。

コンポーネント	役割	解説章
コンテキスト管理	システムプロンプト・CLAUDE.md・自動コンパクション	第2章
ツール実行エンジン	Read / Edit / Bash などの組み込みツールの実行	第3章
パーミッションシステム	許可・拒否ルール、パーミッションモード、サンドボックス	第4章
フック	ツール実行前後などに任意のシェルコマンドを差し込む仕組み	第5章
拡張機構	MCP サーバー・スキル（スラッシュコマンド）による機能追加	第6章
サブエージェント	独立したコンテキストで動く子エージェントの起動・管理	第7章
設定システム	settings.json の階層と優先順位	第8章

1.4 どこで動くか — 実行環境のバリエーション

同じハーネスが、複数の形態で提供されています。

CLI（ターミナル） — 最も基本的な形態。
ローカルのファイルとシェルに直接アクセスします。
デスクトップアプリ / IDE 拡張（VS Code・JetBrains） — CLI と同じハーネスを GUI から操作します。
Web（claude.ai/code）/ クラウド実行 — サンドボックス化されたクラウド環境上でハーネスが動きます。
Claude Agent SDK — ハーネスそのものをライブラリとして組み込み、独自エージェントを構築できます。

まとめ

ハーネスは、モデルを現実世界（ファイル・シェル・外部サービス）に接続する実行基盤である
モデルは「何をするか」を決め、ハーネスが「実際に実行し、制御する」
エージェントループの各所（実行前・実行後・コンテキスト構築時）に、設定やフックで介入できる
次章以降で、各コンポーネントを具体的な設定例とともに掘り下げる