先日の macOS 27 に標準搭載された ローカル AI に触れてから、ハーネスというものに興味を持って、いろいろ調べています。
3行まとめ
- 何が話題か: 海外のオープンLLMコミュニティ（r/LocalLLaMA）で、「モデルを変えても失敗続きだった実務タスクが、外枠の実行環境（ハーネス）を変えた瞬間に爆速で完遂した」という生々しい体験談が大きな議論を呼んでいる。
- 何が本質か: コーディングエージェントの実務性能を決めているのは、LLMモデル単体のIQ以上に「ハーネス（ツールの渡し方・コンテキスト管理・エラー自己修復ループ）」の設計である。
- 読者が持ち帰れるもの: なぜ同じモデルで天と地の差が生まれるのかのアーキテクチャ図解と、自分たちの開発環境（Cursor、Claude Code、自作エージェント等）を見直すための4つの具体的チェックポイント。
1. 「このモデル、全然使えないな」と感じたときの違和感
新しいモデルが登場するたびに、私たちはローカル環境やAPIで試しては一喜一憂しています。
- 「ベンチマークではGPT-4超えって言ってたのに、うちのコードベースに投げたら簡単なバグすら直せない」
- 「ファイルを1個直してほしいだけなのに、無関係なファイルを勝手に書き換えてプロジェクトを破壊した」
- 「エラーメッセージを渡すと、さっきと同じ間違ったコードを何度も吐いて無限ループにハマる」
そして最後には、こう結論づけてしまいがちです。
「やっぱりこのモデルは賢くない。もっと大きなモデル、別の商用モデルを待とう。」
でも、ちょっと待ってください。
本当にポンコツなのは、その「モデル」なのでしょうか？
RedditのローカルLLM専門コミュニティ（r/LocalLLaMA）で先日投稿されたスレッドが、この疑問に強烈な一撃を浴びせ、海外エンジニアたちの間で激論となっています。
Another "Harness matters" post (codex cli > pi and opencode)
（またしても「ハーネスがすべてだ」という話：Codex CLIがPiやOpenCodeを圧倒した件）
2. Redditで起きた「ハーネス論争」：ある開発者の衝撃体験
発端となった投稿者（OP）は、自宅にRTX 3090を2枚積み、ローカルLLM（Qwen 3.8 Flash Next等）をバリバリ動かしつつ、OpenAIの最新モデルも併用しているヘビーユーザーでした。
彼の悩みは明快でした。
「ローカルモデルは、3Dマリオのミニゲームを一発で作るような『おもちゃのデモ』なら動く。
でも、複数ファイルが絡み合う本番の実務コードベースでは、商用モデル（GPT-5系）に手も足も出なかった。
何度試しても途中でクラッシュし、ローカルLLMは実務じゃおもちゃだなと諦めかけていた。」
彼はずっと、エージェントの実行基盤（ハーネス）としてオープンソースの軽量CLIツール（pi.dev や opencode）を使っていました。
ところがある日、OpenAI公式が採用しているエージェント用CLI基盤 「Codex CLI」 をローカルLLM向けに設定し、全く同じローカルモデル（Qwen）を接続して実務プロジェクトを走らせてみたのです。
結果は衝撃的でした。
「何日も商業モデルが苦戦してスタックしていた実務タスクを、ローカルのQwenが圧倒的な速度と正確さで片付けてしまった。同じモデルなのに、まるで別物になったんだ。」
モデルの重み（Weight）は1バイトも変えていません。
変えたのは、モデルを取り囲んでいる 「ハーネス（Harness）」 だけです。
3. そもそも「ハーネス（Harness）」とは何なのか？
馬車を引く馬につける手綱や馬具のことを「ハーネス」と呼びます。どれほど力のある名馬でも、手綱がちぎれていたり鞍が曲がっていれば、荷物を運ぶどころか暴走して転倒します。
AIコーディングエージェントにおける「ハーネス」とは、LLM本体の周囲を取り囲む実行フレームワーク・環境全体を指します。
LLMそのものは、本質的に「渡された文字列に対して、確率的にそれらしい次の文字列を返すだけの計算機」です。
ファイルを開くことも、テストを実行することも、自分の書いたコードがSyntax Errorを起こしたことに気づくことすらできません。
それらすべてを裏で制御しているのがハーネスです。
| 責務 | ポンコツなハーネス | 優れたハーネス |
|---|---|---|
| ファイルの書き換え | ファイル全行をごっそり再出力させる（途中でトークン制限切れ・行欠落） | ユニークな差分検索・置換（Diff Patch）でピンポイントに修正 |
| コンテキスト管理 | 過去の会話やコマンドログを無加工で全部突っ込む（文脈溢れ・迷走） | タスクごとに要約し、不要なファイル出力を即座に切り捨てる（Pruning） |
| エラー時の挙動 | 「エラーになりました」とだけモデルに返して同じミスを反復させる | 直近のdiff、スタックトレース、関連シンボルだけを絞り込んで再入力 |
| KVキャッシュ保護 | 毎回プロンプトの先頭順序を変えてしまい、Prefill計算が再発 | 静的プロンプトを先頭に固定し、手元のGPU推論速度を最大化 |
4. コミュニティの激論：重量級フル装備 vs 軽量DIY
このReddit投稿に対して、世界中のエンジニアから170件を超える熱い反論と共感が寄せられました。議論の中で浮き彫りになったのは、「エージェントの思想的な対立」 です。
派閥A：「多少トークンを食っても、結果が出るリッチなハーネスが正義」
Codex CLIやClaude Codeのような洗練されたハーネスを支持する側の主張です。
- 「トークン消費をケチって動かないコードを出されるより、1回の指示で関連ファイルを先回りして読み、テストまで通してくれる方が開発者の時間は圧倒的に節約できる。」
- 「実務のコードベースは複雑怪奇だ。最低限のプロンプトと素朴なファイル書き込みツールだけで自律的にバグを直せるモデルなんて、現時点では世界に存在しない。」
派閥B：「重量級ハーネスは肥大化（Bloat）の塊であり、トークンの浪費だ」
Pi.devやAider、自作スクリプト等の軽量・最小構成を支持する側の主張です。
- 「リッチなハーネスは、たった1回のプロンプトで数万トークンを勝手に消費し、ローカルマシンのコンテキストウィンドウを一瞬で圧迫する。」
- 「ツール側で勝手な探索ロジックを回されると、KVキャッシュが無効化されてローカルGPUの推論が激重（Prefill地獄）になる。」
- 「優れたハーネスとは、ユーザーがパイプラインを1行単位で制御でき、必要な拡張だけを小さく組み込めるミニマルなものであるべきだ。」
Databricksの調査が突きつける現実
議論の中で、Databricksが数百万行のコードベースを対象に行ったコーディングエージェントのベンチマーク調査が引用されていました。
「コード効率（消費トークン数の少なさ）が高いエージェントほど、複雑なタスクにおけるコード品質（完遂率）は低下する傾向がある。」
つまり、「省エネで賢く動く魔法のエージェント」は幻想であり、「自律的に探索し、失敗したら自己修復するハーネス」はどうしてもトークンと計算資源を消費します。
実務で動くかどうかは、そのトレードオフをどう引き受けているかの設計次第なのです。
5. 明日から手元のエージェント環境を見直す「4つの改善ポイント」
もしあなたが、Cursor、Claude Code、Cline、あるいは自作のPythonスクリプトでエージェントを動かしていて、「モデルの賢さに限界を感じている」なら、モデルの乗り換えを検討する前に以下の4点を見直してみてください。
① ファイル編集を「全書き換え」から「差分置換」に変える
モデルにファイル全体のコードを出力させるのは、今すぐやめるべきです。途中でコードが省略されたり、閉じ括弧が合わなくなる最大の原因です。
編集ツールは、「置換前の数行（TargetContent）」と「置換後の数行（ReplacementContent）」だけを指定させるパッチ形式に統一します。これだけでモデルの編集成功率は跳ね上がります。
② エラーログをそのままモデルに投げ返さない
テストが落ちたとき、ターミナルのログ数百行をそのままプロンプトに流し込んでいませんか？
モデルはノイズの海に溺れ、直前の自分の変更を忘れてしまいます。
- 「どの行でコケたのか（スタックトレースの最深部）」
- 「直前に自分が書き換えた差分（git diff）」
この2点だけを抽出してモデルへフィードバックするハーネスを作ると、自己修正の成功率が劇的に上がります。
③ 会話履歴を垂れ流さず、タスク単位で要約する
エージェントが3往復以上ツールを叩いたら、過去のツールの細かい入出力テキストは捨てて、「何が分かり、何が完了したか」の一文サマリーに置き換えます。コンテキストの先頭を常にスッキリ保つことが、モデルの注意散漫（Attentionの希釈）を防ぐ唯一の方法です。
④ システムプロンプトの先頭を固定する（ローカルLLM勢向け）
ローカル環境でllama.cppやvLLMを使っている場合、プロンプトの先頭部分に動的な情報（現在時刻や開いているファイル名）を入れないでください。
静的な共通プロンプト（ツールの説明、基本ルール）を常に先頭に固定することで、KVキャッシュが100%効くようになり、2ターン目以降の推論開始までの待機時間がゼロになります。
6. まとめ
海外コミュニティの議論を追っていて痛感したのは、「私たちはモデルを評価しているつもりで、実はツールの出来栄えを評価していた」 という事実です。
「このモデルは使えない」と切り捨てるのは簡単です。
しかし、同じモデルでも、手綱（ハーネス）の引き方ひとつで、頼れるシニアエンジニアにもなれば、プロジェクトを破壊するモンスターにもなります。
モデルのパラメータサイズを追いかけるだけでなく、「いま手元にあるモデルの力を、外枠の設計でどう120%引き出すか」。
私の場合は、先日紹介した Mac に標準搭載されたローカル AI「Apple Foundation Models」をどうすれば適切に使えるか AI と一緒に試行錯誤中です。