OpenAIがエージェントだけで100万行のコードを作った秘密、ハーネスエンジニアリング5つの原則

最近、「ハーネス」という言葉を頻繁に目にするようになりました。OpenAIが公開したブログ記事が、この概念を明確に定義してくれました。エージェント時代にエンジニアが実際に何をすべきなのか、整理します。

ハーネス（Harness）は、AIエージェントが現実世界に影響を与えるためのツールの外殻です。推論モデルが脳だとすれば、ハーネスは手足です。ファイルを読み、コードを修正し、テストを実行し、デプロイまで行う, すべての行為がハーネスの中で起こります。

OpenAIの社内チームは2025年8月末に空のリポジトリからスタートし、100万行の新製品をCodexエージェントだけで構築しました。人間が直接コードを書かないという条件でした。手作業の10分の1の時間で完成したと発表しています。この過程で得られた原則が以下の5つです。

エージェントが見えない知識は存在しないのと同じ

Codexにとって、実行中にアクセスできない情報は存在しない情報と同義です。Google Docsにある企画書も、Slackで合意したアーキテクチャの方針も、誰かの頭の中だけにある暗黙知も、すべて見えません。3ヶ月後に入社する新人に見えないのと同じ状況です。

そこでチームは、あらゆる決定をリポジトリ内のマークダウン、スキーマ、実行計画書（ExecPlan）に落とし込みました。

• ExecPlanはPLANS.mdに定義された自己完結型の設計ドキュメント
• 初心者が読んで最後まで実装できなければ合格基準を満たさない
• Codexが単一プロンプトで7時間以上連続作業した事例も存在
• matkladのARCHITECTURE.mdの概念をエージェント向けに拡張した構造

「もっと頑張れ」ではなく「何の能力が足りないか」を問え

初期段階でエージェントの速度が期待より遅かったそうです。原因はモデルの性能ではなく、環境が十分に整っていなかったことでした。失敗するたびに「どの能力が欠けていて、どうすればエージェントが読み取り検証できるようになるか」を問いました。

• 外部ライブラリの代わりに自作の並行処理ヘルパーでOpenTelemetryと100%連携
• 業界でよく言われる「退屈な技術」がエージェントに有利（API安定性とトレーニングデータの表現度が高いため）

ドキュメントではなく機械的な強制がコードの一貫性を守る

ドキュメントだけでは、エージェントが生成したコードベースの一貫性が崩壊しました。そこでチームは、実装を細かく指示する代わりに不変のルールだけを機械的に強制する方式を選びました。データ境界でのパースを必須としつつ、どのライブラリを使うかはエージェントに委ねました。アーキテクチャも階層型ドメイン構造に固定し、依存関係の方向をリンターで検証しています。

• ビジネスドメインごとにProviders → Service → Runtime → UIの固定レイヤー
• Types、Config、Repoが下位で共有される横断的関心事の構造
• カスタムリンターと構造テストが違反時にビルドを即座に失敗させる
• リンター自体もCodexが作成

エージェントに目を与えれば6時間でも一人で働く

Chrome DevTools Protocolをエージェントのランタイムに接続し、DOMスナップショット、スクリーンショット、ナビゲーション機能をCodexに提供しました。作業前後のスナップショットを比較し、ランタイムイベントを観察した後、修正をクリーンになるまで繰り返すループ構造です。

オブザーバビリティツールも同じ方式で接続しました。git worktreeごとに一時的なオブザーバビリティスタックが起動し、作業完了後に消えます。

• Victoria Logs（LogQL）とVictoria Metrics（PromQL）でエージェントが直接ログとメトリクスを照会
• 「サービスの起動を800ms以内に終わらせろ」というプロンプトが実行可能に
• 単一Codex実行が6時間以上ひとつのタスクに集中するケースも定期的に観測

地図は渡せ、ただし1,000ページのマニュアルは渡すな

コンテキスト管理がエージェントの効果を左右します。最初は巨大なAGENTS.mdひとつにすべてを詰め込む方式を試みましたが失敗しました。matkladが2021年に書いたARCHITECTURE.mdの概念がここで真価を発揮しました。プロジェクト全体の構造を短く俯瞰し、めったに変わらないものだけを載せるという原則です。エージェントにも同様に適用されます。

• ARCHITECTURE.mdはコードマップであり、コード地図帳ではない
• アーキテクチャの不変ルールは「何かが存在しない」という形で表現されることが多い
• 境界（boundary）を明示すれば、その先の実装をすべて制約する効果がある

まだ解決されていない問い

このCodexチームにも、まだ答えの出ていない問いがあります。エージェントだけで構築されたシステムが何年にもわたってアーキテクチャの一貫性を維持できるかは、誰にもわかりません。モデルが進化し続ければ、このフレームワーク自体がどう変わるかも未知数です。

ひとつだけ確かなことがあります。コードをうまく書く時代は終わりつつあり、環境をうまく設計する時代が始まっています。