Claude Codeの深層：エージェント型ハーネスの内部構造と技術的制約の全貌

多くのエンジニアがClaude Codeを「魔法のコーディングツール」として利用し、その自律的な挙動に驚嘆しているが、その裏側で何が起きているのかを理解している者は意外と少ない。シニアエンジニアとして私が強調したいのは、Claude Codeの本質は「モデルそのもの」ではなく、モデルを囲い込み、ステートレスなAPIをステートフルなエージェントへと昇華させる「ハーネス（Harness）」の設計にあるという点だ。Claude API（Messages API）は、本質的に会話履歴を保持しないステートレスな存在である。この制約を回避するために、ハーネスは毎回、システムプロンプト、過去の全メッセージ、そして今回の入力を連結した巨大なペイロードを構築し、APIへ送信している。この「毎回全量送信」という力技こそが、エージェントの自律性を支える基盤なのだ。

しかし、この設計は計算コストという巨大な壁に直面する。会話が長引けば長引くほど、ペイロードは肥大化し、トークン消費量は指数関数的に増大する。ここで登場するのが「プロンプトキャッシュ」という技術だ。ハーネスは、ペイロードの先頭部分が前回と同一であれば、サーバーサイドで処理結果を再利用させるよう指示を出す。このキャッシュの境界管理こそが、Claude Codeのパフォーマンスを左右する心臓部である。キャッシュの有効範囲を制御するcache_controlパラメータの挿入タイミングを誤れば、キャッシュヒット率は低下し、コストは跳ね上がる。我々エンジニアが意識すべきは、この「キャッシュの境界」がどこに引かれているかという点だ。ハーネスは、tools、system、messagesの順に連結されたペイロードに対し、最大4つのキャッシュポイントを動的に配置している。この仕組みを理解していれば、なぜ特定の操作で急激にコストが変動するのか、その技術的背景が自ずと見えてくるはずだ。

Claude Codeの自律性は、ハーネス側の「行動ループ」と、モデル内部の「推論（thinking）」という二重構造によって実現されている。まず、ハーネス側のループについて見てみよう。ユーザーが1回のリクエストを投げると、ハーネスはモデルからのtool_use要求を待ち受ける。モデルが「Bashコマンドを実行せよ」と指示すれば、ハーネスはローカル環境でそれを実行し、その結果をtool_resultとして再びモデルに投げ返す。この往復運動こそが、エージェントが「考えて、動いて、検証する」というサイクルを回す正体だ。ここで重要なのは、モデルはあくまで「次の行動を提案する」だけであり、実際の実行権限と環境へのアクセス権はすべてハーネスが握っているという点だ。この分離により、モデルの暴走をハーネス側で安全に制御することが可能になっている。

一方で、モデル内部のthinkingは、1回のAPI応答内で完結する推論プロセスである。これはループではなく、回答を生成する前の「思考の深掘り」だ。Claude 4.6世代以降で導入されたadaptive thinkingは、モデル自身が思考の深さを判断する仕組みであり、effortパラメータによってそのコストと精度を調整できる。この「思考」に費やされるトークンもまた、出力トークンとして課金対象となる。つまり、モデルが深く考えれば考えるほど、我々の財布は軽くなるというトレードオフが存在する。以下の表は、Claude Codeのアーキテクチャを構成する3層構造の役割を整理したものだ。

この構造を理解することは、単なる知識の習得ではない。例えば、/clearや/compactといったコマンドが、セッションログのどの部分を操作し、結果としてAPIへのペイロードをどう変化させているのかを想像できるようになる。これは、障害発生時や予期せぬ挙動に直面した際、デバッグの糸口を掴むための必須スキルである。AIが「サボり出す」あるいは「無限ループに陥る」といった現象は、このハーネスとモデルの間の通信プロトコルにおける、コンテキストの汚染やキャッシュの不整合が原因であることが多いのだ。

Claude Codeの内部構造を紐解くと、我々エンジニアが今後向き合うべき課題が浮き彫りになる。それは「AIをツールとして使う」という段階から、「AIというエージェントの挙動を設計・管理する」という段階へのシフトだ。セッションログがJSONL形式で保存され、それが連結リストとして管理されている事実は、我々がAIの「記憶」を直接操作し、修正し、あるいは削除できることを意味している。AIが誤った推論を繰り返すとき、それはモデルの知能の問題ではなく、ハーネスが提供したコンテキストの「ノイズ」が原因である可能性が高い。我々は、AIに何を読ませ、何を隠し、どのタイミングでキャッシュをリセットすべきかという「コンテキストのエンジニアリング」を習得しなければならない。

また、Claude Codeが提供するCLAUDE.mdのような仕組みは、AIに対する「プロジェクトの憲法」とも言える。これを適切に記述し、AIの行動指針を明確にすることは、現代のソフトウェア開発における重要なドキュメント作成業務となった。しかし、AIが自律的にコードを書き換える世界では、従来のコードレビューの概念も再定義を迫られる。AIが生成したコードの正当性を、人間がどの粒度で検証すべきか。AIが「サボり」や「無限ループ」を起こした際、その責任の所在はどこにあるのか。これらの問いは、単なる技術的な議論を超え、我々のキャリアそのものを揺るがすものだ。

明日からあなたが取るべき対策は明確だ。まずは、自身のプロジェクトでClaude Codeの/contextコマンドを叩き、トークン消費の内訳を直視すること。そして、セッションログの構造を理解し、AIがどのような「思考の軌跡」を残しているのかを追跡することだ。AIをブラックボックスとして崇めるのではなく、その内部の「ハーネス」を理解し、制御下に置くこと。それが、AI時代を生き抜くシニアエンジニアの生存戦略である。あなたは、AIという「優秀だが時に気まぐれな部下」を、いかにして自律的かつ効率的に使いこなす準備ができているだろうか？