コード例: code/ 実践プロジェクト: プロジェクト 01. プロンプトのみ vs ルール優先

講義 01. 強いモデルは信頼できる実行を意味しない

あなたは AI の世界にかなり慣れているつもりです。Claude Pro を契約し、GPT-4o API キーを持ち、SWE-bench のリーダーボードも覚えている。ある日、ついに本物のプロジェクトを AI エージェントに任せます。自信満々です。結果はどうでしょう。機能を追加したがテストを壊す。バグを直したが 2 つ増やす。20 分走って誇らしげに「完了」と言う。そしてコードを見ると、そもそも頼んだものではありません。

最初の反応は「このモデルはまだ足りない。アップグレードしよう」かもしれません。少し待ってください。財布を開く前に、問題はモデルではない可能性があります。

数字を見てみましょう。2025 年後半時点で、最強クラスの coding agent でも SWE-bench Verified ではおおむね 50-60% 程度です。しかもこれは、明確な issue 説明と既存テストがある、慎重に選ばれたタスクでの数字です。日常の開発環境、つまり曖昧な要求、既存テストなし、暗黙のビジネスルールが散らばった環境に移ると、その数字はさらに下がります。

しかし、この数字の裏には直感に反する真実があります。

同じ馬、違う運命

Anthropic は制御実験を行いました。同じプロンプト（「2D レトロゲームメーカーを作る」）、同じモデル（Opus 4.5）。1 回目は bare、支援なし。20 分、9 ドル、ゲームの中核機能はまったく動きませんでした。2 回目は完全な harness（planner + generator + evaluator の 3 エージェント構成）。6 時間、200 ドル、ゲームはプレイ可能でした。

モデルは変えていません。Opus 4.5 は同じ Opus 4.5 です。変わったのは鞍です。

OpenAI の harness engineering 記事ははっきり言っています。よく harness されたリポジトリでは、Codex は「不可靠」から「可靠」へ変わる。表現に注目してください。「少し良くなる」ではなく、質的な変化です。サラブレッドのようなものです。鞍なしでも乗れますが、遠くへは行けず、速くも走れず、落ちても不思議ではありません。harness はその鞍です。つまり、モデル重みの外側にあるエンジニアリング基盤のすべてです。

エージェントは実際どこで詰まるのか

具体的には何が起きるのでしょうか。

最も多いのは、タスクを明確に定義していないことです。「検索機能を追加して」と言うと、エージェントの理解はあなたとまったく違うかもしれません。何を検索するのか。全文検索か構造化検索か。ページネーションは。ハイライトは。指定しなければ、エージェントは推測します。当たれば運、外れれば最初に具体化するより高くつきます。レストランで「魚をください」と言うようなものです。煮魚か蒸し魚か鍋かは運任せです。

指定したとしても、プロジェクトにはエージェントが知らない暗黙のアーキテクチャ慣習があります。チームは SQLAlchemy 2.0 構文で統一しているのに、エージェントはデフォルトで 1.x のコードを書く。全 API は OAuth 2.0 認証必須なのに、そのルールはあなたの頭の中と 3 か月前の Slack にしかない。エージェントには見えません。従いたくないのではなく、文字通りそのルールの存在を知りません。

環境も罠です。不完全な dev 環境、欠けた依存関係、違うツールバージョン。エージェントは本来の課題ではなく、pip install の失敗や Node バージョン不一致に貴重なコンテキストを燃やします。腕のいい大工を雇ったのに、ハンマーも釘も水平な作業台も渡さないようなものです。どれほど有能でも仕事はできません。

さらに多いのは、検証する方法がないことです。テストがない。lint がない。検証コマンドをエージェントに伝えていない。エージェントはコードを書き、眺め、問題なさそうだと判断して「完了」と言います。答え合わせなしで宿題を提出させるようなものです。本人は正しいと思っていますが、採点すると間違いだらけです。Anthropic は、エージェントがコンテキスト不足を感じると急いで終わらせ、検証を飛ばし、最適解より簡単な解を選ぶ現象も観察しています。彼らはこれを「context anxiety」と呼びます。試験時間が残り少ないと気づいて、残りの選択問題を適当に埋めるのと同じです。

セッションをまたぐ長いタスクはさらに悪化します。前セッションの発見は失われ、新しいセッションはプロジェクト構造とコード構成を毎回探索し直します。永続状態を持たないエージェントは、30 分を超えるタスクで失敗率が急上昇します。

重要用語

こうした状況を踏まえると、次の概念は単なる流行語ではありません。

能力ギャップ: ベンチマーク上のモデル性能と実タスクでの性能の大きな差。SWE-bench Verified で 50-60% ということは、実 issue のほぼ半分は解けないということです。
Harness: モデルの外側にあるすべて。指示、ツール、環境、状態管理、検証フィードバック。モデル重みでなければ harness です。この講義で言う「鞍」です。
Harness 起因の失敗: モデルには能力があるのに、実行環境に構造的欠陥があるため失敗すること。Anthropic の制御実験がこれを示しています。
検証ギャップ: エージェントの出力への自信と実際の正しさの差。エージェントが「完了」と言うが完了していない。最も多い失敗モードです。
診断ループ: 実行し、失敗を観察し、特定の harness 層に原因を割り当て、その層を修正し、再実行する。harness engineering の中核手法です。
Definition of Done: 機械的に検証可能な完了条件。テスト通過、lint クリーン、型チェック通過。明示しなければ、エージェントは勝手に完了条件を作ります。

失敗したら、まず harness を直す

中核原則はこれです。失敗したら、まずモデルを替えるのではなく harness を確認する。 同じモデルが似た構造化タスクで成功するなら、harness の問題だと仮定します。車が止まったとき、いきなりエンジンを疑うのではなく、まずガソリン切れを確認するのと同じです。

具体的には次のように進めます。

すべての失敗を特定の層に帰属させる。 「モデルがだめ」と言わないでください。タスクが曖昧だったのか。コンテキスト不足だったのか。検証手段がなかったのか。各失敗を 5 つの層（タスク仕様、コンテキスト提供、実行環境、検証フィードバック、状態管理）に対応づけます。この習慣がつくと、「モデルが足りない」はログにだんだん出なくなります。

すべてのタスクに明示的な Definition of Done を書く。 「検索機能を追加して」ではなく、こう書きます。

Completion criteria:
- New endpoint GET /api/search?q=xxx
- Supports pagination, default 20 items
- Results include highlighted snippets
- All new code passes pytest
- Type checking passes (mypy --strict)

AGENTS.md を作る。 リポジトリルートに置き、技術スタック、アーキテクチャ慣習、検証コマンドをエージェントに伝えます。これは harness engineering の第一歩であり、最も ROI の高い手順です。高価なモデルへアップグレードするより、1 つの AGENTS.md のほうが効くことがあります。冗談ではありません。

診断ループを作る。 失敗を「またモデルが馬鹿をした」と扱わない。harness に欠陥があるという信号として扱います。失敗ごとに層を特定し、修正し、同じ失敗を繰り返さない。数回回すと harness は強くなり、エージェント性能は安定します。道路補修のように、穴を埋めるほど次の区間が滑らかになります。

改善を定量化する。 各タスクが成功したか失敗したか、どの層が原因だったかを簡単に記録します。数回後にはボトルネック層が見えてくるので、そこに力を集中します。

100 万行の実験

OpenAI は 2025 年に強烈な実験を行いました。空の git リポジトリから、Codex で完全な社内プロダクトを構築する。5 か月後、そのリポジトリにはおよそ 100 万行のコードがありました。アプリケーションロジック、インフラ、ツール、ドキュメント、社内開発ツール。すべてエージェント生成です。3 人のエンジニアが Codex を操作し、約 1,500 PR を作成してマージしました。1 人あたり 1 日平均 3.5 PR です。

重要な制約は、人間が直接コードを書かないことでした。これは見世物ではありません。エンジニアの主仕事がコードを書くことではなく、環境を設計し、意図を表現し、フィードバックループを作ることになったとき、何が変わるかを強制的に学ぶための設計でした。

初期の進捗は予想より遅かった。Codex が無能だったからではなく、環境が不十分だったからです。エージェントには高レベル目標を進めるためのツール、抽象、内部構造が足りませんでした。エンジニアの仕事は、大きな目標を小さな構成要素（設計、コード、レビュー、テスト）に分解し、エージェントに組み立てさせ、それらの構成要素でより複雑なタスクを解けるようにすることになりました。何かが失敗したときの修正は、ほぼ常に「もっと頑張れ」ではなく、「エージェントに足りない能力は何か、それを理解可能かつ実行可能にするにはどうするか」でした。

この実験は、本講義の中心命題を直接示しています。同じモデルでも、bare な環境と完全な harness を持つ環境では根本的に違う出力を出す。 モデルは変わっていません。環境が変わったのです。

Source: OpenAI: Harness engineering: leveraging Codex in an agent-first world

もっと身近な例

あるチームは Claude Sonnet を使って、中規模の Python Web アプリ（FastAPI + PostgreSQL + Redis、約 15,000 行）に新しい API endpoint を追加しようとしました。

最初は「/api/v2/users 配下に user preferences endpoints を追加して」という 1 文だけを渡しました。結果は、エージェントがコンテキストの 40% をリポジトリ探索に使い、見た目は妥当だがプロジェクトのエラーハンドリングパターンに従わず、古い SQLAlchemy 構文を使い、endpoint にランタイムエラーがあるのに完了宣言しました。次のセッションは探索をやり直す必要がありました。

その後、彼らは AGENTS.md（プロジェクト構造と技術スタックバージョンの説明）、明示的な検証コマンド（pytest tests/api/v2/ && python -m mypy src/）、ADR を追加しました。同じモデルは 3 回の独立実行すべてで成功し、コンテキスト効率は約 60% 改善しました。

モデルは変えていません。harness を変えました。

重要なポイント

モデル能力と実行信頼性は別物です。サラブレッドにも良い鞍が必要です。
失敗したら、まず harness を確認し、その後でモデルを疑います。モデル交換は最も高価な選択肢で、多くの場合はモデル問題ですらありません。
すべての失敗は信号です。harness に構造的欠陥があります。見つけて直してください。
5 つの防御層: タスク仕様、コンテキスト提供、実行環境、検証フィードバック、状態管理。医師が一般的な原因から除外するように、体系的に確認します。
1 つの AGENTS.md は、高価なモデルに替えるより効果的かもしれません。本当に。

参考資料

演習

比較実験: よく知っているコードベースと非自明な変更タスクを選びます。まず harness 支援なしでエージェントを実行し、失敗を記録します。次に明示的な検証コマンドを含む AGENTS.md を追加し、同じエージェントで再実行します。結果を比較し、各失敗を 5 つの防御層のどれかに帰属させます。
検証ギャップ測定: 5 つの coding task を選びます。各タスク後、エージェントが完了を主張したかを記録し、独立したテストで実際の正しさを確認します。完了と言ったが実際は完了していない割合を計算します。それが検証ギャップです。どの検証コマンドがこの割合を下げるか考えてください。
診断ループ練習: プロジェクト内でエージェントが繰り返し失敗するタスクを探します。1 回実行し、失敗を記録します。5 つの層のどれかに原因を割り当てます。その層を修正し、再実行します。3-5 回繰り返し、改善を記録してください。

講義 01. 強いモデルは信頼できる実行を意味しない ​

同じ馬、違う運命 ​

エージェントは実際どこで詰まるのか ​

重要用語 ​

失敗したら、まず harness を直す ​

100 万行の実験 ​

もっと身近な例 ​

重要なポイント ​

参考資料 ​

演習 ​