
AIコーディングエージェントが失敗したら~モデルを替える前に「ハーネス」を直す~
【発端】 失敗の原因を、モデルの外に探す講座

最近、Walking Labsの英語講座「Welcome to Learn Harness Engineering」を読みました。AIコーディングエージェントを、講義14本、ハンズオンのプロジェクト、コピーして使えるテンプレートで学ぶ講座です。
エージェントが失敗したときの最初の一手が面白いです。「もっと高いモデルに替える」ではなく、「指示、環境、検証、記録のどこが欠けていたか」を先に調べます。
この記事は講座の要約ではありません。ハーネスとは何か、これまでの考え方とどう違うか、どんな部品で成り立つか、一次資料の実例、自分のリポジトリで試す一歩の順に、独自に整理します。
【基礎】 ハーネスとは、モデルの重み以外のすべて
モデルの賢さと、仕事の確実さは別のものです。仕事の確実さは、モデルの外側の作りで決まります。
講座はハーネスを、指示、ツール、環境、状態管理、検証のフィードバックと定義します。モデルの重み(学習で決まったパラメータ)でなければ、すべてハーネスです。
名前は馬具から来ています。馬(モデル)がどれだけ優秀でも、馬具(ハーネス)が悪ければ、まっすぐ走らせられません。
なぜ環境で結果が変わるのでしょうか。エージェントは同僚に質問できないからです。
使えるのは、プロンプト、リポジトリのファイル、ツールの出力だけです。
OpenAIの記事も同じ見方です。エージェントが実行中に文脈として触れないものは、事実上存在しません。
Slackの議論も、設計会議の結論も、リポジトリに書かなければ無いのと同じです。
【違い】 モデル交換から層の診断へ移る、失敗の扱い

講座の五層は、タスク仕様、文脈の提供、実行環境、検証フィードバック、状態管理です。これは新しい概念ではなく、失敗を診断するための区分です。
失敗した直後の一手
モデル中心の見方:より高性能なモデルを試す
ハーネス中心の見方:欠けていた層を特定する
「完了」を決める人
モデル中心の見方:エージェント本人の自己申告
ハーネス中心の見方:コマンドで確かめられる条件
知識の置き場
モデル中心の見方:人の頭、チャット、外部文書
ハーネス中心の見方:リポジトリ内のファイル
長い作業の記憶
モデル中心の見方:セッション内の会話
ハーネス中心の見方:進捗ファイルとgit履歴
改善の単位
モデル中心の見方:モデルの入れ替え
ハーネス中心の見方:失敗ごとに一つの層を直す
ハーネス中心の見方は講座の主張です。モデル中心の見方は、この記事で対比のために置いた見方です。
講座は、モデル交換を最も高くつく手段だと位置づけています。同じモデルが似た作業をうまくこなせるなら、まずハーネスを疑う、という順番です。
【仕組み】 欠けを補う五つの部品と、その欠けを見つける診断ループ
講座は、ハーネスを五つの部品に分けます。
指示
担当すること:目的と守る制約を伝える
講座が挙げる例:AGENTS.mdに概要、技術スタック、実行コマンド、必須の制約
ツール
担当すること:作業に必要な手段を渡す
講座が挙げる例:シェルを閉じない。ただし最小権限で開く
環境
担当すること:動く状態を再現可能にする
講座が挙げる例:依存の固定、ランタイムのバージョン指定、devcontainer(開発環境を定義する設定)
状態
担当すること:作業の続きを残す
講座が挙げる例:PROGRESS.mdに完了、作業中、ブロック中
フィードバック
担当すること:結果の正誤を知らせる
講座が挙げる例:テスト、型チェック、lint(書き方の自動検査)のコマンドを明記
講座は五つのうち、フィードバックを費用対効果が最も高い部品としています。検証コマンドを書くだけで、エージェントが「できた気がする」で止まるのを防げるからです。
講座が紹介する Guoらの論文 は、モデルの自信が実際の正解率より高くなりやすいことを示しています。
指示の書き方にも設計があり、AGENTS.mdは百科事典ではなく目次にします。
OpenAIのチームも、約100行の入口ファイルから docs/ディレクトリへ案内する形に落ち着きました。巨大な指示ファイルは、文脈を圧迫し、古い規則がたまり、機械的に検証しにくいからです。
「完了」の扱いも変わります。たとえば検索機能を頼むなら、「検索を追加して」では足りません。
エンドポイント、ページ分割、テストの通過、型チェックの通過まで、確かめられる条件で書きます。
作業の単位も絞ります。講座は、同時に進めるタスクを一つにすること(WIP=1、仕掛かりの数)を、安全な既定値としています。
機能リストには「振る舞い、検証コマンド、状態」の三点を持たせます。状態の更新は検証の成功を条件にします。
診断ループは単純で、実行して失敗を観察し、どの層の欠陥かを決め、その層を直して、もう一度実行する順です。
ログは「成功か失敗か、どの層が原因か」だけで十分だと講座は言います。数回回すと、詰まっている層が見えてきます。
【具体例】 同じモデルで20分9ドルと、6時間200ドルの差

差を作ったのはモデルではなく、計画役、生成役、評価役という分業と、実装前の合意でした。
Anthropicの記事(2026年3月)に、2Dレトロゲーム制作ツールを作らせた実験があります。モデルは Claude Opus 4.5 です。
単独実行:20分、9ドル。画面は出るが、配置したキャラクターが入力に反応せず、遊べない
完全なハーネス:6時間、200ドル。計画役、生成役、評価役の三体構成で、遊べる状態に到達
評価役は、Playwrightという、ブラウザを自動で操作する道具で、動くアプリを実際に触ります。合否と指摘を返します。
実装の前には、生成役と評価役が「何をもって完了とするか」を合意します。記事はこれをスプリント契約と呼んでいます。
同じ予算での比較ではありません。費用は20倍以上かかっています。
講座も、一つの部品の寄与を切り出した実験ではないと明記しています。
同じ記事の続きでは、Opus 4.6 でスプリントの分割をやめ、構成を簡素にしました。
ブラウザ上で動く音楽制作ソフトの作成は、約4時間、約124.7ドルでした。
講座は、ハーネスの部品はどれも「モデルが単独ではできないこと」への仮定だと説明します。モデルが変われば仮定も古くなります。
だから、部品を一つずつ外して、役に立っているものを確かめます。
長い作業の引き継ぎについては、別のAnthropicの記事(2025年11月)が具体的です。最初のセッションで初期化役が、200を超える機能を「失敗」として機能リストに書き出します。
あわせて起動スクリプト、進捗ファイル、最初のgitコミットも用意します。以降のセッションは、リストの項目を一つずつ進めます。
【関連概念】 上に積み上がるループとグラフ、点検で軽くなる足場
ハーネスは終点ではなく土台です。
コンテキスト不安:文脈の上限が近づくと、エージェントが作業を急いで終わらせようとする現象です。Anthropicの観察では、要約で圧縮する方法(コンパクション)より、新しいセッションに切り替えて引き継ぎファイルから再開する方法(リセット)が役立つ場合があり、その強さはモデルによって違います
途中の情報は拾われにくい:長い文章の中ほどにある情報は、先頭や末尾より使われにくいと報告されています(Lost in the Middle)。重要な制約を、長い指示ファイルの中ほどに埋めない理由です
ループ(講義13):目標、検証、停止条件を渡して、条件を満たすまで繰り返させる設計です。作る役と確かめる役を分けることが前提になります
グラフ(講義14):ノード(作業単位)、エッジ(受け渡し)、共有状態、ルーティング規則で、複数の担当をつなぐ設計です。講座は「プロンプト、文脈、ループ、グラフ」を積み重なる四層とみなし、ハーネスをその土台に置きます
反復が増えると、見えにくい費用も増えます。講座は、検証の負債、コードを理解できなくなること、判断の丸投げ、トークンの膨張を挙げています。
足場がいつも役立つとは限りません。講座が紹介する ETH Zurichの研究 では、リポジトリの文脈ファイルは、評価した条件で成功率を一律には上げず、推論コストを20%以上増やしました。
Lullaらの論文 では、AGENTS.mdがある場合に、実行時間の中央値が約29%短くなりました。機能としての正しさは、測定の範囲外です。
どちらも、自分のタスクで測る必要があることを示しています。
講座が紹介する LangChainの報告 では、モデルは gpt-5.2-codex のまま、ハーネスの変更で Terminal Bench 2.0(89問の作業ベンチマーク)の得点が52.8%から66.5%へ上がった、と報告しています。進捗ファイルだけの効果ではありません。
参考情報・参考書籍(PR)
本記事をより深く理解するために、概念マップスライドを作成しました。こちらをみることで理解の補助になるはずです。
『LLMのプロンプトエンジニアリング ―GitHub Copilotを生んだ開発者が教える生成AIアプリケーション開発』(John Berryman、Albert Ziegler、訳は服部佑樹、佐藤直生):文脈に何を入れ、どう構造化するかという、指示と文脈の層を、LLMの仕組みから理解する助けになります。
『カンバン仕事術』(Marcus Hammarberg、Joakim Sundénほか):エージェントに同時に一つの作業だけ進めさせる考え方の、人間のチーム向けの基本を押さえられます。
『入門 監視 ―モダンなモニタリングのためのデザインパターン』:実行時の信号を集めて、何が起きたかを知る、という観測の基本に通じます。
関連記事
【まとめ】 一つの層を直したあとの、同じタスクでの比較

いきなり仕組みを作らず、いまの環境でどの層が薄いかを調べるところから始めます。
次の三つは、講座の演習をもとにしたこの記事の整理です。筆者自身が実行して効果を確かめたものではありません。
新しいセッションに五つ聞く:このシステムは何か、どう構成されているか、どう動かすか、どう検証するか、いまの進捗はどこか。リポジトリの内容だけで答えられるかを見て、答えられなかった問いを地図の空白とみなします
入口ファイルに検証コマンドを書く:概要、起動方法、テストと型チェックのコマンドを、約100行以内の AGENTS.mdに置きます。詳細は別ファイルへ案内します
失敗を層で記録する:次の数回の失敗を、「タスク仕様、文脈、環境、検証、状態」のどれかに分類して残します。偏りが見えたら、その層だけ直して同じタスクを再実行します
講座に出てくる成功率の数値(たとえば20%から100%近くへ)は、教材用の仮定の例で、実測ではありません。