Claude CodeやCodex CLIは、なぜ同じモデルをチャット欄で直接使うよりもずっと強いのでしょうか？答えはモデルそのものではなく、モデルを包み込む「Coding harness（コーディング実行フレームワーク）」という層にあります。本記事ではコーディングAgentの六大コアコンポーネントを分解し、Agentが素のモデルより使いやすい理由と、自分のコーディングAgentの構築方法を解説します。

コア概念：モデル vs Agent

まず三つの重要な概念を整理します。

• 大規模言語モデル（LLM）: 基盤モデル。その本質は次の単語を予測するエンジン
• 推論モデル（Reasoning Model）: 特殊な訓練を受けたLLM。より多くの計算資源を注ぎ込み、中間推論と自己検証を行う
• エージェント（Agent）: モデル＋ツール＋記憶＋環境フィードバックからなるループシステム

たとえるなら、LLMは普通のエンジン、推論モデルは爆速チューニングされた高馬力エンジン、そしてAgent harnessはそのエンジンを操るためのクルマまるごとのシステムです。

基盤モデル、推論モデル、Agentの関係。Agentは特定の環境の中でモデルを繰り返し呼び出し、実際の開発における複雑なタスクを処理します。

コンポーネント一：リアルタイムのコードリポジトリコンテキスト

これは最も重要で、かつ最も基礎的なコンポーネントです。「テストコードを直して」と言っても、モデルは真っ暗闇では困ります。次のことを知る必要があります。

• 今Gitリポジトリ内にいるか、どのブランチにいるか
• プロジェクトにどんなドキュメントや開発規約（AGENTS.md、READMEなど）があるか
• コードベースのファイル構造

Coding harnessは指示を受け取ると、まずこれらの情報を収集し、「ワークスペース概要」を生成します。こうしてモデルは毎回のプロンプトに対してゼロから始めずに済むのです。

Coding harnessはまずワークスペース概要を生成し、それをユーザーのリクエストとマージすることで、モデルに十分なコンテキストを与えます。

コンポーネント二：プロンプトキャッシュの再利用

コンテキストを集めたら、どう効率よくモデルに与えるか？毎回すべての情報を組み立て直していれば、計算資源とコストの無駄は甚大です。

コア戦略：プロンプトを「安定した部分」と「変化する部分」に分けます。

• 安定プレフィックス（ほぼ不変）：システム指示、ツール説明、ワークスペース概要 -- キャッシュして再利用
• 変化する部分（毎ターン更新）：短期記憶、直近の対話、最新の指示 -- 毎回再構築

プロンプトは安定プレフィックスと変化する部分に分かれます。主要なLLM APIはいずれもPrompt Cacheをサポートしており、安定プレフィックスをキャッシュすればコストを大幅に削減できます。

コンポーネント三：ツールの接続と呼び出し

Coding harnessに組み込まれたLLMは提案するだけでなく、実際にコマンドを実行することもできます。ただし無制限ではありません -- Harnessは事前定義済みのツールボックスを提供し、各ツールには明確な入力要件と境界があります。

ツール呼び出しの完全なフロー：

1. モデルが構造化されたアクションリクエストを出力する
2. Harnessがアクションを検証する（ホワイトリストに含まれるか？パラメータは妥当か？）
3. 高リスク操作は人間の承認が必要
4. アクションを実行し、結果をモデルに返す

# Harness 的安全检查逻辑
def validate_tool(action):
    if action.tool not in KNOWN_TOOLS:
        return reject("未知工具")
    if not action.params_valid():
        return reject("参数非法")
    if action.is_dangerous() and not user_approved():
        return reject("需要人工批准")
    if action.path_outside_repo():
        return reject("路径越界")
    return execute(action)

コンポーネント四：コンテキストのスリム化

コーディングAgentは普通のチャットよりコンテキストウィンドウを「食べ過ぎ」やすいものです。ファイルを頻繁に読み込み、ツール出力は往々にして冗長だからです。優れたHarnessは少なくとも二つの手段で対処します。

• クリッピング（Clipping）: 長すぎるドキュメント断片やツール出力を容赦なく切り詰める
• トランスクリプト削減（Transcript Reduction）: 完全な履歴を軽量な要約に凝縮する

核心の極意は、新しい出来事ほど詳細を残し、古いものほど強く圧縮すること。序盤に読み込んだ重複ファイルは重複排除処理を行います。

コンポーネント五：構造化されたセッション記憶

コーディングAgentは状態を二層に分けます。

ワーキングメモリと完全記録は通常、JSON形式でディスクに保存されます。Agentを閉じても、次回開けばシームレスに復元できます。

コンポーネント六：タスク委譲と制約付きサブAgent

一部のサブタスクをサブAgentに並列処理させれば、メインタスクを大幅に加速できます。ただし鍵となるのは制約です。

• サブAgentはファイルへの読み取り専用アクセスのみに限定する（または修正範囲を制限する）
• 再帰の深さを制限し、サブAgentの無限生成を防ぐ
• コンテキストサイズと実行時間を制限する

サブAgentには仕事ができるだけのコンテキストを継承させつつ、厳格に制約しなければなりません。これが設計上もっとも腕の見せどころです。

手を動かして実践

Sebastian Raschkaは純粋なPythonだけでMini Coding Agentをゼロから構築し、上記六大コンポーネントをすべて実装しました。外部依存は一切ありません。

• プロジェクトURL: https://github.com/rasbt/mini-coding-agent
• コアファイル: mini_coding_agent.py。コード内のコメントに六大コンポーネントの対応位置が示されています

コーディングAgentの内部メカニズムを深く理解したいなら、このプロジェクトのソースコードを読むことが最高の出発点になります。

Mini Coding Agentは、ミニマルでありながら機能的に完全なコーディングAgentの実装です。