はじめに
「Claude Codeを使っています」—では、どの部分がClaude Code本体なのか、即答できるでしょうか？
多くの人は「AIモデルが本体で、CLIはただのフロントエンド」と思いがちです。しかし実際は逆で、Claude Codeの本体はモデルの外側にある「ハーネス」と呼ばれる仕組み全体です。
私はClaude CodeのドキュメントをGitHub Pagesとして公開・運用していますが、その基礎概念の章を整理し直した際、この「ハーネス」という視点が初心者向けの最重要概念だと再認識しました。本記事では、tool calling / 自律ループ / サーキットブレーカという頻出3用語を軸に、ハーネスの考え方を解説します。
1. 「本体」はモデルではなくハーネス
LLMそのものは、テキストを受け取ってテキストを返すだけの存在です。単体ではファイルを読めず、シェルを実行できず、記憶も保持できません。
それを「ファイルを編集して、テストを走らせて、結果を見て直す」エージェントに変えているのがハーネスです。馬を制御する馬具（ハーネス）のイメージで、LLMという力持ちの馬に方向を与える鞍と手綱に相当します。
具体的には、ハーネスが担うのは次のような処理です。
- システムプロンプトの組み立てと、会話履歴の管理
- モデルからの「ツールを使いたい」という要求の解析と実行
- ツール実行結果を次の入力への再送（コンテキスト管理）
- 危険な操作の確認・停止といった安全装置
npm install で入ってくるのはCLIを含むこのハーネス側であり、モデル本体はAPIの向こう側にいます。「モデルの能力」より「ハーネスの出来」でエージェントの実力が決まる、と言っても過言ではありません。
2. 頻出用語集
| 用語 | 一言でいうと | ハーネス内での役割 |
|---|---|---|
| tool calling | モデルがツール利用を構造化データで要求する仕組み | 「Readツールでこのファイルを見たい」とJSON形式で指示を出し、ハーネスが実行する |
| 自律ループ（agent loop） | 目標達成まで処理を繰り返すサイクル | 応答→ツール実行→結果再送→応答…を自動で回し、人間の指示回数を減らす |
| サーキットブレーカ | 異常時にループを強制停止する安全装置 | 無限ループや連続失敗を検知して中断し、APIクレジットやファイル群を守る |
3つの関係はシンプルです。tool callingが部品、自律ループがそれを回すエンジン、サーキットブレーカがブレーキ。この比喩を押さえると、MCP（外部ツールを標準プロトコルで接続する仕組み）も「tool callingに差し込む部品の拡張」だと位置づけられます。
3. サーキットブレーカがなぜ重要か（コードで理解する）
自律ループは強力ですが、モデルが「同じ修正を繰り返す」「失敗したツール呼び出しを延々再試行する」ような状態に入ると、ループが止まりません。実害は明確で、API利用料の消失と作業ディレクトリの意図しない大量書き換えです。
サーキットブレーカの本質は「連続失敗を数えて、閾値超過で一定時間遮断する」だけのシンプルな仕組みです。最小実装はこうなります。
import time
class CircuitBreaker:
def __init__(self, max_failures: int = 3, cooldown_sec: int = 60):
self.failures = 0
self.max_failures = max_failures
self.cooldown_sec = cooldown_sec
self.opened_at: float | None = None
def allow(self) -> bool:
"""ループの継続可否を判定する"""
if self.opened_at is None:
return True
if time.time() - self.opened_at >= self.cooldown_sec:
self.opened_at = None # 冷却期間を過ぎたら再開（半開状態）
return True
return False
def record(self, success: bool) -> None:
if success:
self.failures = 0
self.opened_at = None
else:
self.failures += 1
if self.failures >= self.max_failures:
self.opened_at = time.time()
エージェントループの各イテレーションで allow() を確認し、ツール実行の成否を record() に渡す。たったこれだけで「暴走したら60秒止めて人間に判断を戻す」が実現できます。Claude Codeが「タスクが長時間止まらないか？」と確認を求けてくる挙動も、この系譜の安全装置です。
実運用では、この安全装置の存在が長時間の自律実行を心理的に可能にする点が重要です。ブレーキがあるからアクセルを踏める、という構造です。
おわりに
本記事の要点をまとめます。
- Claude Codeの本体はモデルではなく、モデルをエージェントに変えるハーネス
- tool calling（部品）/ 自律ループ（エンジン）/ サーキットブレーカ（ブレーキ）の3点セットを押さえると全体像が見える
- ブレーキの存在が、安全な自律実行を可能にする
ハーネスという視点を持つと、日々のアップデートの位置づけも見えてきます。実際、私のリポジトリでは最近、主力モデルのコンテキスト窓が200Kから1Mトークンへ拡張されたことに伴い、ドキュメント全体の記述を見直しました。これは「モデル側の変化を、ハーネス側の設定と理解が追従する必要がある」好例です。
用語の正体を知ることは、道具を「便利な魔法」から「設計されたシステム」に変えてくれます。本記事がその最初の一歩になれば幸いです。
本記事は個人Zennでも公開しています。