Claude Codeのハーネス設計 ―― 3層構造で読み解く、LLMを「動くエージェント」に変える足場の正体

LLMをベースとした実用レベルの「動くエージェント」に変換するには、モデル本体とは別にハーネスと呼ばれる足場が必要です。

システムプロンプト、ツールセット、セッションを破綻させないコンテキスト管理の仕組みなどが噛み合うことで、初めて「自律的に作業を進めるエージェント」が成立します。

本記事では、Claude Codeのハーネスを構成要素ごとに分解し、各設計判断がなぜそうなっているのかを読み解きます。

なぜClaude Codeのハーネスが重要なのか

2024年以降、Cursor Agent、Cline、Aider、Devin、そしてClaude Code――エージェント型コーディングツールが一気に普及しました。

しかし、同じClaudeやGPT-5を使っていても、ツールごとに「安定して長時間動くもの」と「すぐに迷子になるもの」がはっきり分かれます。

この差を生んでいるのが、モデルの周囲を取り囲む ハーネスの設計です。

ハーネスとは、機械学習やエージェントの文脈では LLMという推論エンジンを実用システムに組み込むための実行基盤の総称 を指します。具体的には次の3つの層が含まれます。

• システムプロンプト(モデルへの恒常的な指示と振る舞いの規定)
• ツール層(モデルが世界に働きかけるためのインターフェース群)
• コンテキスト管理層(セッションの記憶・状態を維持する仕組み)

モデルの性能が同じでも、これら3層の設計次第で、エージェントの信頼性は10倍以上変わります。

Claude Codeは、この3層の仕組みを丁寧に設計しています。

AI社員で効率化！

Claude Codeのハーネスを構成する3つのレイヤー

Claude Codeのハーネスは、以下の3層が同心円状にモデルを取り囲む構造になっています。

レイヤー	役割	主な構成要素
① システムプロンプト層	振る舞いの規定とガードレール	ロール定義/ツール使用方針/禁止事項/応答スタイル
② ツール層	モデルの「手足」を提供	Read/Edit/Write/Bash/Grep/Glob/Task/TodoWrite/MCP
③ コンテキスト管理層	状態と記憶の維持	CLAUDE.md/スラッシュコマンド/サブエージェント/Hooks/トークン圧縮

そしてこの3層を貫いて回るのが エージェントループ です。簡略化すると次のように動作します。

ユーザー入力
↓
[システムプロンプト + 会話履歴 + コンテキスト]
↓
モデルが「次に何をするか」を推論
↓
ツール呼び出し or テキスト応答
↓
ツール結果を会話に追記
↓
(必要なら繰り返し)
↓
最終応答

このループ自体はシンプルですが、 「途中で迷子にならない」「破壊的な操作をしない」「長時間動いてもコンテキストが破綻しない」 という3つの非自明な性質を満たすために、ハーネス側に膨大な工夫が施されています。

システムプロンプト設計

エージェント開発においては、設計は長く書くほど精度が下がるという特徴があります。

Claude Codeのシステムプロンプトは、 「役割」「ツールの使い方」「やってはいけないこと」の3点に集中して設計されているので、ポイントに沿った定義づけが最もパフォーマンスを生み出せるようになります。

ロール定義は最小限に

ロール定義は 「ツールとしての自己紹介+ 動作ドメイン+ 応答スタイルの方針」の、合計3〜5行で十分 です。

書きたくなった指示の大半は、ツール定義の説明、ガードレール、CLAUDE.mdなど、適切な場所に記載しましょう。

「どこに書くか」を意識するだけで、システムプロンプトは劇的にスリムになります。

項目	書き方の傾向	具体例(Good)	具体例(Bad)
自己紹介	1文で簡潔に	「あなたはClaudeです。Anthropicが開発したターミナル上のCLIツールです」	「あなたは20年の経験を持つ世界トップクラスのシニアソフトウェアエンジニアであり、あらゆる言語に精通し…」
能力の宣言	書かない	(記述なし)	「あなたはコードを書くことができ、リファクタリングができ、テストが書け、ドキュメントが作成でき…」
態度・人格	書かない/最小限	「丁寧で正確に応答してください」	「常に親しみやすく、フレンドリーで、ユーモアを交え、絵文字を多用して、ユーザーを励まし続けてください」
出力フォーマット	簡潔なルールのみ	「簡潔に応答し、不要な前置きを避けること」	「必ず以下の構造で:①導入②背景③詳細④例⑤まとめ⑥参考資料…(以下20行)」
タスク範囲	動作ドメインを1行で	「ソフトウェアエンジニアリングタスクの支援が目的です」	(タスク範囲が書かれていない)
禁止事項の混在	ロール定義に混ぜない	(禁止事項は別セクションへ)	「あなたはClaudeで、絶対にrm -rf /を実行せず、シークレットをコミットせず、main にforce pushせず…」

ツール使用に関するメタ指示

Claude Codeのプロンプトで特徴的なのは、ツールの単純なリストではなく、 どのツールをどんな状況で優先するかのメタ指示が含まれている点です。

たとえば次のような方針が組み込まれています。

• ファイル検索には find ではなく Glob を使う
• 文字列検索には grep ではなく Grep ツールを使う
• ファイル閲覧には cat ではなく Read を使う
• ファイル編集には sed / awk ではなく Edit を使う

Bashでgrepを回すよりGrepツールの方が、 権限管理・タイムアウト・出力フォーマット制御 といったハーネス側の最適化が有効です。

さらに重要なのは、ツール呼び出しの「意図」がトレースしやすくなることです。

Bash("grep foo")とGrep("foo")は機械的には同じことをしますが、後者の方が「検索を意図した」ことが明示的で、ログを読む人間にもエージェントの後続意思決定にも有利に働きます。

ガードレール：何をしないか

Claude Codeのプロンプトには、明示的な禁止事を指定しておきます。

• git push --force をmain/masterに対して実行しない
• --no-verify でフックをスキップしない
• .env や認証情報を不用意にコミットしない
• 既存ファイルを編集する前に必ずReadしておく
• ユーザーが明示的に頼んでいないのにコミットを作らない

これらは、エージェントの暴走を防ぐ手段です。

重要なのは、 「やってよいこと」を白リスト的に書くのではなく、「やってはいけないこと」を書くスタイルが、コーディング領域では機能するという点です。

Less is moreの原則
最後に、プロンプト全体を通して 過度なフォーマット指示を避けることも徹底されています。
「リストや見出しを乱用するな」「絵文字は使うな」「カジュアルな会話では数文で答えろ」――これらは出力の品質を直接左右します。プロンプトが冗長だとモデル出力も冗長になる、という相関を逆手に取った設計です。

Claude Codeのツール設計：なぜこの粒度なのか

Claude Codeのツールセットは10種類前後で、他のツールに比べても少ないくらいです。

それでも実用的なコーディング作業の大半をカバーできているのは、 粒度の選定が適切である部分が大きいです。

Read / Edit / Write の役割分離

Claude Codeの一般的なファイル操作系は3つに分かれています。

ツール	役割
Read	ファイルを読む(行番号付き、画像・PDF対応)
Edit	既存ファイルの一部を置換する(差分のみ送信)
Write	ファイルを丸ごと新規作成・上書きする

Editは差分のみを送るのでトークン消費が小さい一方、ファイル丸ごと書き換える操作ならWriteの方が記述量が少なく済みます。

意図が違う操作には違うツールを適用するのがClaude Codeのツール設計の核心原則です。

さらに、Editには「事前にReadしていないと失敗する」という制約が組み込まれています。これはエージェントが「ファイル内容を確認せずに編集する」という典型的な事故を防いでいるのです。

制約をツール側に埋め込むことで、システムプロンプトの記述量を減らしつつ安全性を高める ――この発想は自前ハーネスを作る際にも非常に参考になります。

Grep / Glob を独立させる意味

なぜBashでgrepさせずに、専用のGrepツールを用意するのでしょうか。

以下に理由を4つあげました。

• ripgrepベースで高速かつ大規模リポジトリに強い
• 出力モードを構造化できる(マッチ行のみ/ファイル名のみ/件数のみ)
• 権限制御がツール単位で行える
• モデルの「検索意図」をログに残せる

特に4番目が重要です。エージェントが何を探していたのかが構造化されることで、後からトレースして「ここで方向を間違えた」と分析できます。

Bashツールの自由度と制約

Bashツールは「最後の砦」として、他のツールではカバーできない操作のために用意されています。

完全に自由にすると暴走し、完全に縛ると役に立たない――この両極端を避けるために、Claude Codeは 「与える自由」と「課す制約」を意図的に切り分け ています。

整理すると次のようになります。

与えられている自由(できること)

できること	具体例	設計意図
任意のシェルコマンド実行	npm install / pytest / docker build / gh pr create	ファイル操作系ツールでカバーしきれない開発作業すべてを受け止める「逃げ道」が必要
パイプ・リダイレクトの利用	cmd1 | cmd2 > file	UNIXツール群の組み合わせ自体がコーディング作業の本体なので、これを禁じると無意味
任意の言語ランタイム呼び出し	python -c "..." / node -e "..."	スクリプトをひと回しして結果を確認するのは日常作業。専用ツール化するより自由度を残す方が現実的
環境変数・カレントディレクトリの利用	cd "path" / $HOME	開発作業はリポジトリ単位で文脈を持つため、シェル本来の機構をそのまま使えることが重要
任意のGitHub CLI操作	gh issue list / gh pr view	PR/Issue操作専用ツールを作ると粒度爆発するので、gh一本に集約

課されている制約(やってはいけない・できないこと)

制約	具体的な禁止例	なぜ縛るのか
破壊的Git操作の禁止	git push --force をmainへ / git reset --hard / git clean -f をユーザー指示なく実行	一度実行すると復元不能。エージェントの「ちょっと整える」判断で損失が起きやすい領域
フック・署名のスキップ禁止	--no-verify / --no-gpg-sign	プロジェクトの品質ゲートを勝手に迂回するのは設計違反
検索・閲覧系コマンドの制限	grep / find / cat / head / tail を使わず専用ツール(Grep/Glob/Read)を優先	構造化出力・権限制御・トレース性のため。3章で詳述したメタ指示と対応
文字列編集系コマンドの制限	sed / awk ではなく Edit ツールを使う	編集意図がツール側に明示化され、安全策(事前Read必須など)を効かせやすい
不可分の長時間コマンドへの注意	デフォルト2分でタイムアウト、長時間処理はrun_in_background必須	エージェントループを止めずに、終了通知で再開できる設計に誘導
cdの濫用回避	基本は絶対パスを使い、cdはユーザー指示時のみ	カレントディレクトリの状態がエージェント側で見えにくくなり、後続操作でバグが入りやすい
インタラクティブフラグの禁止	git rebase -i / git add -i	標準入力を要求するコマンドはエージェントセッションで詰む
秘匿情報を含むファイルの取り扱い	.env / credentials.json を不用意にgit addしない	取り返しのつかないセキュリティ事故を防ぐ

Bashは「他で代替できない自由」を保証するための逃げ道として残し、代替可能な操作はすべて専用ツールに切り出す ――この線引きこそがClaude Codeのツール設計の核心です。

専用ツールが増えるほど認知負荷は下がり、エージェントは安定して動作するようになります。

MCP(Model Context Protocol)による拡張
Claude Code自体のツールは絞り込まれている一方、 MCPサーバーを通じて任意のツールを後付けできる拡張アーキテクチャを備えています。SlackやNotion、独自社内APIなどをMCP経由で接続すれば、本体のツールセットを汚さずに機能拡張できます。

Claude Codeのコンテキスト管理

長時間動くエージェントの最大の敵はコンテキストウィンドウの枯渇です。

Claudeは200Kトークン程度扱えますが、それでも数時間のコーディングセッションでは余裕で埋まってしまいます。

Claude Codeはこの問題に対し、複数の仕組みで対応しています。

CLAUDE.md ―― プロジェクト記憶

CLAUDE.mdとは、 セッション開始時に必ず読み込まれるプロジェクト固有の指示書です。

ここに「このプロジェクトはPython 3.12を使う」「テストはpytest -xvsで実行」「コミットメッセージはConventional Commits形式」といった情報を書いておくと、毎回説明する手間が省けます。

「セッションごとに繰り返すべき指示」をシステムプロンプトから切り出して、プロジェクト単位で管理することができます。

スラッシュコマンド/カスタムコマンド

Claude Codeは、 繰り返し使う手続きを「短いコマンド一発で呼び出せるプロンプト」として保存・再利用する仕組み を持ちます。

組み込みコマンドに加えて、.claude/commands/ 配下にMarkdownファイルを置くだけで自前コマンドを追加できます。

コマンドの種類と代表例

種類	配置場所	例	使いどころ
組み込み	本体に同梱	/init / /review / /compact / /clear	初期化・レビュー・履歴圧縮など共通の定型作業
プロジェクトカスタム	.claude/commands/	/deploy / /release-notes	チームで共有するリポジトリ固有の手続き
ユーザーカスタム	~/.claude/commands/	/my-pr / /standup	個人の作業習慣に合わせた手続き

カスタムコマンドと CLAUDE.md の使い分け

配置場所	向いているもの	向いていないもの
CLAUDE.md	常に効かせたい前提(言語バージョン、ビルドコマンド、規約)	特定タイミングだけ必要な手順
カスタムコマンド	明示的に呼び出したい定型手続き(デプロイ、リリース)	プロジェクトの恒常的な前提情報

つまり 「常時効かせたい情報はCLAUDE.md、必要なときだけ呼び出す手続きはカスタムコマンド」 という棲み分けが基本です。

手続きをコマンドに切り出すことで、システムプロンプトを肥大化させず、再利用可能なワークフローをリポジトリにコードとして残せます。

サブエージェント

Claude Codeの最も強力な機能のひとつがサブエージェントです。

親エージェントから子エージェントを起動し、別のコンテキストウィンドウで作業させ、最終結果だけを親に返します。

この仕組みにより、 「探索的な読み込み」と「最終的な意思決定」のコンテキストを分離できます。

仕組みのポイント

• 親エージェントがTaskツールでサブエージェントを起動する
• サブエージェントは 親とは別のコンテキストウィンドウ で動く
• サブエージェントが読んだファイルや中間出力は親には流れ込まない
• 親が受け取るのは 最終的な要約・結論のみ
• 結果として、親のコンテキストウィンドウは温存される

何が嬉しいのか

• コンテキスト圧迫を防げる:数十ファイルを読む調査でも、親には要約だけ残るためトークン枯渇を回避
• 意思決定に集中できる:親は「探索の生データ」ではなく「整理された結論」を扱えるので判断品質が上がる
• 暴走の影響を局所化できる:サブエージェントが迷走しても、親のコンテキストや進行中タスクは汚染されない
• 並列実行が可能:独立した調査を複数同時に走らせて待ち時間を短縮できる

典型的なユースケース

• 「認証周りの実装を理解したい」など、多数のファイルを横断する 調査タスク
• 「この設計の代替案を3つ出して比較したい」など、 並列に複数案を検討するタスク
• 「変更を独立した観点でレビューしてほしい」など、 親の文脈に引きずられず判断させたいタスク
• 「特定のシンボルが定義されている場所を網羅的に探したい」など、 広範囲のサーチ作業

サブエージェントの種類(代表例)

• general-purpose:汎用の調査・実装・マルチステップ作業
• Explore:ファイル検索・シンボル特定に特化した読み取り専用エージェント
• Plan:実装プランの設計・アーキテクチャ判断に特化
• code-reviewer:コードレビュー専門。親の意図と独立した視点を提供
• general-purpose以外は ツールや権限が用途に合わせて絞り込まれている ため、システムプロンプトを軽くしつつ精度を上げられる

設計上の教訓

• 「読む量が多い作業」は 原則サブエージェントに切り出す
• 専用エージェントを増やすことは、 システムプロンプトを肥大化させずに専門化する 唯一現実的な手段
• 自前ハーネスを作る場合も、 マルチエージェント構造を最初から前提に置く ことを推奨

トークン圧縮(/compact)
それでもコンテキストが膨らんできたら、/compact コマンドで会話履歴を要約圧縮できます。要約は別のClaude呼び出しで行われ、過去のやり取りを圧縮しつつ「重要な意思決定」「現在の作業状態」を残します。
このような 「圧縮 → 継続」の手続き をハーネス側に組み込んでおくことが、長時間セッションを安定動作させる鍵です。

ハーネス設計はモデル選びより重要かもしれない

エージェント開発では「どのモデルを使うか」が話題になりがちですが、実用性能を決めているのはハーネスの設計品質です。

これらはClaude Codeに限らず、 あらゆるLLMエージェント設計に応用できる設計原則 です。

エージェント開発トレンドは「より長時間動く・より自律的なエージェント」に向かいますが、その方向性で先に進むためにも、まずClaude Codeのハーネス設計を見直してみましょう。

📌 本記事の情報は2026年5月時点のものです。 Claude Codeはアップデートが頻繁なため、最新の仕様は公式ドキュメントをあわせてご確認ください。