原文: Harness engineering: leveraging Codex in an agent-first world | OpenAI
著者: Ryan Lopopolo（OpenAI テクニカルスタッフメンバー）
公開日: 2026年2月11日
OpenAIのエンジニアリングチームが、「人間はコードを1行も書かない」という縛りで5ヶ月間プロダクトを作り続けた。結果は100万行のコード、1,500件のPR、手作業比で約1/10の開発時間。しかも社内数百名が日常的に使うプロダクトとして動いている。
その過程で見えてきた方法論が「ハーネスエンジニアリング」だ。馬具（ハーネス）が馬の力を制御して有用な仕事に変えるように、エンジニアがAIエージェントの力を制御して信頼性の高いソフトウェアに変換する、というコンセプトである。
この記事では、原文の内容を7つのテーマに再構成して紹介する。
この記事でわかること
- ハーネスエンジニアリングとは何か
- AIエージェントで開発を回すために、OpenAIのチームが実際にやったこと
- うまくいったこと、失敗したこと、まだわかっていないこと
全体サマリー
チーム構成は最初3人、のちに7人。AIコーディングエージェント Codex だけを使い、1人あたり1日平均3.5件のPRを出し続けた。
核心のメッセージはこれだ。
人間が舵を取り、エージェントが実行する（Humans steer, agents execute）。
エンジニアの仕事は「コードを書くこと」から「エージェントが正しく動ける環境を作ること」に変わった。この環境設計の方法論がハーネスエンジニアリングである。
1. エンジニアの役割が変わる
何が起きたか
空のgitリポジトリに、最初のコミットからCodexがコードを書いた。CI設定、フォーマットルール、アプリケーションフレームワーク、AGENTS.mdまで全部エージェント生成だ。
ただし、最初はうまくいかなかった。進捗が想定より遅い。原因はCodexの能力不足ではなく、環境の仕様が足りなかったことにある。エージェントに必要なツールや抽象化が欠けていて、高レベルの目標に向かって進めなかった。
ここから、エンジニアの仕事が変わった。
| 従来の開発 | ハーネスエンジニアリング |
|---|---|
| コードを書く | 環境を設計する |
| バグを直接修正する | 「なぜエージェントが失敗したか」を分析して環境を改善する |
| レビューは人間がやる | エージェント間で処理させ、人間は例外だけ対応 |
何かが失敗したとき、「もっと頑張る」では解決しない。問いかけるのは常に「何の能力が欠けているのか、それをどう読みやすく・強制可能にするか」だった。
ここがおもしろい
エンジニアはプロンプトでシステムとやり取りし、タスクを記述し、エージェントを走らせ、PRの作成を許可する。レビュー作業すらエージェント間で回す方向に進んでいる。実質的に「Ralph Wiggumループ」（Codexが自分のPRを自分でレビューし、満足するまで修正を繰り返す）で動いているという表現が原文にある。
つまり、コードを書く力よりも、「何を作るか」「なぜ作るか」を言語化する力の方が重要になる。コーディングスキルが不要になるわけではないが、重心が明確に移動している。
2. エージェントに「目」を与える
何が起きたか
コードの処理量が増えるにつれ、ボトルネックは人間のQA能力になった。エージェントがコードを大量に書いても、人間がその動作を確認しきれない。
そこで、エージェント自身がアプリの動作を「見て」検証できるようにした。
具体的には2つのアプローチがある。
1. Chrome DevTools MCPによるUI操作
アプリをgitワークツリーごとに起動可能にし、Chrome DevToolsプロトコルを接続した。Codexがスクリーンショットを撮り、DOMを読み、UIを操作して、バグの再現と修正の検証を自力で行う。
2. フルオブザーバビリティスタック
ログ・メトリクス・トレースを提供するローカルのオブザーバビリティスタックも構築した。CodexがLogQLやPromQLでクエリを実行し、「サービスの起動を800ms以内にする」「この4つのユーザージャーニーのスパンが2秒を超えないようにする」といったパフォーマンス要件を直接扱える。
各ワークツリーに対してエフェメラル（一時的）なスタックが立ち上がり、タスクが終わったら破棄される。エージェント同士が互いの環境を汚染しない設計だ。
ここがおもしろい
単一のCodex実行が6時間以上かけて1つのタスクに取り組む、というケースが日常的にあるらしい。人間が寝ている間にエージェントが黙々と作業している。
人間の開発者がブラウザで動作確認し、ログを読み、パフォーマンスを計測するのと同じことを、エージェントにもやらせている。「コードを書く能力」だけでは足りなくて、「見る」「計測する」「検証する」能力をセットで渡す必要がある、というのが実感として伝わってくる。
3. 知識管理 ― 地図を渡せ、マニュアルではなく
何が起きたか
エージェントを大規模タスクに使う上で、コンテキスト管理が最大の課題の1つだった。チームが最初に学んだ教訓がこれだ。
Codexには地図を渡せ、1,000ページの取扱説明書ではなく。
最初は「1つの大きなAGENTS.md」に全部書くアプローチを試した。予想通り失敗した。
- コンテキストウィンドウは有限なので、巨大な指示ファイルがタスクやコードを押し出してしまう
- 全部「重要」だと何も重要じゃなくなる
- モノリシックなマニュアルはすぐ古くなる
- 1つの塊だと鮮度やカバレッジの自動チェックが難しい
Confluenceの巨大なドキュメントが誰にも読まれなくなるのと同じ構造だ。
解決策は、AGENTS.mdを「目次」にして、構造化されたdocs/を正式な記録システムにすること。
AGENTS.md ← 目次（約100行）
ARCHITECTURE.md ← ドメインとパッケージ階層のトップレベルマップ
docs/
├── design-docs/ ← 設計ドキュメント（索引付き）
│ ├── index.md
│ ├── core-beliefs.md
│ └── ...
├── exec-plans/ ← 実行計画（アクティブ/完了/技術的負債）
│ ├── active/
│ ├── completed/
│ └── tech-debt-tracker.md
├── generated/ ← 自動生成ドキュメント
│ └── db-schema.md
├── product-specs/ ← プロダクト仕様
│ ├── index.md
│ └── ...
├── references/ ← 外部ライブラリのLLM向けドキュメント
│ ├── design-system-reference-llms.txt
│ └── ...
├── DESIGN.md
├── FRONTEND.md
├── PRODUCT_SENSE.md
├── QUALITY_SCORE.md
├── RELIABILITY.md
└── SECURITY.md
「段階的開示（progressive disclosure）」のパターンで、エージェントは短いAGENTS.md（約100行）から始まり、必要に応じてより深いドキュメントをたどる。
ここがおもしろい
計画をファーストクラスのアーティファクトとして扱っている点が興味深い。小さな変更にはエフェメラルな軽量計画を、複雑な作業には進捗と意思決定ログを含む実行計画をリポジトリにチェックインする。アクティブな計画、完了した計画、技術的負債がすべてバージョン管理されている。
ドキュメントの鮮度を保つ仕組みもある。専用のリンターとCIジョブが知識ベースの整合性を検証し、定期的に「ドキュメント整備（doc-gardening）」エージェントが実際のコードと乖離したドキュメントをスキャンして修正PRを自動作成する。ドキュメントをコードの一部として扱い、陳腐化を自動検出・修正するわけだ。
4. エージェントの可読性を最優先にする
何が起きたか
リポジトリが完全にエージェント生成なので、まずCodexの可読性のために最適化されている。
ポイントは、エージェントの観点からは「実行中にコンテキスト内でアクセスできないものは存在しない」ということ。Google Docs、Slackスレッド、人の頭の中にある知識――これらはエージェントから見えない。
チームをアーキテクチャパターンに合意させたSlackの議論も、エージェントが発見できなければ、3ヶ月後に入社する新入社員に知られていないのと同じだ。
技術選定でも「エージェントにとっての可読性」が判断基準になった。「退屈な技術（boring technology）」を好む。理由は、APIが安定していてLLMのトレーニングデータに多く含まれているため、エージェントが正しいコードを生成しやすいからだ。
ここがおもしろい
実際に、汎用的なp-limitスタイルのパッケージを導入する代わりに、独自のmap-with-concurrencyヘルパーを自前実装したケースがある。OpenTelemetryインストルメンテーションと密に統合され、テストカバレッジ100%で、期待通りに動作する。外部ライブラリの不透明な挙動に悩まされるよりも、エージェントに再実装させた方が安上がりだったという判断だ。
新しいフレームワークを追いかけるよりも、「エージェントが正しく扱える技術かどうか」という基準が入ってくるのは、今後の技術選定に影響しそうな話だ。
5. アーキテクチャの規律を自動で強制する
何が起きたか
ドキュメントだけでは、エージェント生成コードベースの一貫性を保てない。チームが採用した方針は「不変条件を強制し、実装の細部は管理しない」。
各ビジネスドメインは固定されたレイヤー（Types → Config → Repo → Service → Runtime → UI）に分割され、依存方向が厳密に検証される。横断的関心事（認証、テレメトリ、フィーチャーフラグ等）はProvidersという単一のインターフェースを通じて入る。
これらの制約はカスタムリンター（もちろんCodex生成）と構造テストで自動的に強制される。カスタムリンターなので、エラーメッセージにエージェント向けの修正指示を注入できるのがミソだ。
たとえば、Codexにはバウンダリでデータの形状をパースすることを要求しているが、その方法は規定していない（結果的にモデルはZodを好んで使うようになったが、指定はしていない）。
ここがおもしろい
通常、厳格なレイヤードアーキテクチャは数百人のエンジニアを抱えるまで延期されることが多い。だがエージェント開発では初期の前提条件になる。制約があるからこそ、劣化なしにスピードを出せる。
原文の表現を借りれば「境界は中央で強制し、ローカルでは自律性を許容する」。大規模エンジニアリング組織のマネジメントと同じ原則がエージェント管理にも当てはまる。
マージ哲学も変わった。PRは短命で、テストのフレイク（不安定テスト）はフォローアップで対処する。「修正は安価であり、待つことは高くつく」という割り切り。低スループット環境では無責任に見えるかもしれないが、エージェントのスループットが人間の注意力をはるかに上回る世界では、これが合理的なトレードオフになる。
6. 完全自律と「AIスロップ」対策
何が起きたか
開発ループの多くの部分がシステムに直接エンコードされた結果、Codexがエンドツーエンドで新機能を推進できるようになった。1つのプロンプトから、コードベースの検証→バグ再現→ビデオ録画→修正実装→PR作成→フィードバック対応→マージまでを自律的に行う。
一方で、完全な自律性は新しい問題も生んだ。Codexはリポジトリに既に存在するパターンを複製する。たとえ不均一・最適でないパターンであっても。時間が経つと、これが必然的にドリフトにつながる。
当初、チームは毎週金曜日（週の20%）を「AIスロップ」のクリーンアップに費やしていた。当然スケールしない。
解決策は「ゴールデンプリンシプル（黄金原則）」をリポジトリに直接エンコードし、定期的な自動クリーンアッププロセスを回すことだった。
ゴールデンプリンシプルの例:
- 手作りのヘルパーよりも共有ユーティリティパッケージを使う（不変条件の中央集権化）
- データを「YOLO的に」プローブしない。バウンダリでバリデーションするか、型付きSDKに依存する
定期的にバックグラウンドのCodexタスクが逸脱をスキャンし、品質グレードを更新し、ターゲットを絞ったリファクタリングPRを自動作成する。ほとんどは1分以内にレビューでき、自動マージされる。
ここがおもしろい
このアプローチは「ガベージコレクション（GC）」に例えられている。手動メモリ管理（毎週金曜のクリーンアップ）からGC（定期的な自動クリーンアップ）への移行と同じ構造だ。技術的負債は高金利ローンのようなもので、蓄積させて一気に返済するより、小さく継続的に返す方がいい。
「エージェント生成」の範囲も広い。プロダクトコードとテストだけでなく、CI設定、リリースツール、内部開発者ツール、ドキュメント、評価ハーネス、レビューコメントと応答、リポジトリ管理スクリプト、本番ダッシュボード定義ファイルまで、全部がエージェント生成だ。人間は優先順位付け、ユーザーフィードバックの受入基準への変換、成果の検証を担当する。以前とは違う抽象化レイヤーで仕事をしている。
7. まだ学んでいること
何が起きたか
この戦略は内部ローンチと導入まではうまく機能した。ただし、まだわかっていないことが多い。
未解決の問い
- 長期的なアーキテクチャ一貫性: エージェント生成コードベースの品質は、数年単位でどう推移するのか
- 人間の判断の最適配置: 人間の判断が最もレバレッジを生む場所はどこか。その判断をどうエンコードすれば複利的に効果を発揮するか
- モデル進化への適応: モデルが高性能になったとき、今の制約やハーネスはどう変わるのか。不要になるものもあれば、別の制約が必要になるかもしれない
- 一般化の可能性: OpenAIの特定環境（Codexの内部利用）に依存した話なのか、広く適用できるのか
1つだけ明らかになったことがある。ソフトウェアの構築には依然として規律が必要だが、その規律はコードではなく「スキャフォールディング」――ツール、抽象化、フィードバックループの設計――に現れるようになっている。
まとめ: 5つの教訓
- 環境設計 > モデル能力。 進捗が遅い原因はAIの能力不足ではなく、環境の未整備だった
- 地図を渡せ、マニュアルではなく。 コンテキストは希少資源。段階的に必要な情報だけをロードする
- Human steer, Agent execute。 失敗したときは「何が足りないか」を問う
- セルフレビューループ。 エージェント自身がレビューし、満足するまで修正を反復する
- ドキュメント = コードの一部。 陳腐化を自動検出・修正する仕組みで鮮度を保つ
所感
この記事を読んで、さっそくClaude Codeに記事の内容を見せて自分の開発環境に適用してもらった。
やってみて感じたのは、「環境設計 > モデル能力」という教訓がそのまま当てはまるということだ。エージェントがうまく動かないとき、プロンプトを工夫するより、CLAUDE.mdの構造を見直したり、ドキュメントの配置を整理したりする方が効果が大きかった。
OpenAIだから特別にできた話、という部分ももちろんある。Codexの内部利用、大規模なコンピュートリソース、AIに精通したチーム。ただ、「地図を渡せ」「退屈な技術を好む」「ドキュメントの陳腐化を自動検出する」といった話は、Claude CodeやCursorを使っている普通のチームでもそのまま通用する。
個人的に一番刺さったのは「退屈な技術を好む」という判断基準だ。新しい技術を追いかけがちな文化の中で、「エージェントが正しく扱えるかどうか」が技術選定の軸に入ってくる。これは地味だけど、今後じわじわ効いてくる話だと思う。