エンジニアリングの制御：『エージェントファースト』の世界でCodexを活用する

過去五ヶ月、私たちのチームは実験を行いました：人工による記述がゼロ行という内部ベータ版のソフトウェア製品を構築し、公開することです。

この製品には内部の日次アクティブユーザーもいれば、外部のアルファテスターもいます。通常通りリリースされ、デプロイされ、クラッシュもし、修復もされました。唯一の違いは、アプリケーションロジック、テスト、CI 設定からドキュメント、観測性モニタリング、社内ツールに至るまで、すべてのコード行が Codex によって記述されたという点です。推計によると、これらすべてを完了するまでの時間は、純粋な手書きコーディングの十分の一に過ぎませんでした。

私たちはあえてこの制限を選びました。それは、工程速度を数桁向上させるための必要な基盤を構築することを強いるためです。数週間で最終的に百万行規模のコードを持つシステムを納品するためには、ソフトウェアエンジニアリングチームの主要な仕事がコードを書くことではなく、環境を設計し、意図を明確化し、Codex エージェント (Agents) が信頼して動作できるようにフィードバックループを構築することにシフトしたときに何が変わるのかを理解する必要があります。

この記事は、エージェントチームに頼って新製品を構築した経験から得た教訓——何が崩壊し、何が複利効果を生み、そして唯一真に希少なリソースである人間の時間と注意力をどう最大化するか——を記録しています。

私たちは空の Git リポジトリから始めました

2025 年 8 月下旬、空のリポジトリに最初のコミットが行われました。

初期のスクラッチ（スキャフォールディング）——リポジトリ構造、CI 設定、フォーマットルール、パッケージマネージャーの設定、そしてアプリケーションフレームワーク——はすべて、Codex CLI が GPT-5 の駆動により、少数の既存テンプレートに基づいて生成しました。エージェントがリポジトリ内でどのように動作するかを指示する初期の AGENTS.md ファイルさえもそうです。

システムには事前保存された人間のコードによるアンカー（拠り所）はありませんでした。最初からこのリポジトリはエージェントによって形成されました。

五ヶ月後、リポジトリにはアプリケーションロジック、インフラストラクチャ、ツールチェーン、ドキュメント、および内部開発ユーティリティを含め、約百万行のコードが蓄積されました。その間、Codex を駆使したエンジニアはわずか三人で、約 1,500 の PR（Pull Requests）を処理しマージしました。計算すると、一人のエンジニアが毎日平均 3.5 の PR を処理したことになります。驚くべきことに、チームが七人に拡大してもスループットはさらに向上しました。重要なのは、これは単なる数値稼ぎではないということです：数百人の内部ユーザーがこの製品を使用しており、その中には毎日重度に使用するコアユーザーも含まれています。

開発プロセス全体を通じて、人間が直接コードを貢献したことはありませんでした。これがチームの中心的な信条となりました：決して手動でコードを書かないこと。

自らコードを書くことをやめることは、システム、スキャフォールディング、レバレッジ（てこ効果）に焦点を当てた新しいタイプのエンジニアリングワークを生み出しました。

初期の進展は予想よりも遅れました。Codex の能力不足ではなく、環境定義が不十分だったのです。エージェントには、高レベルな目標を推進するために必要なツール、抽象化層、および内部構造がありませんでした。エンジニアリングチームの最優先課題は「エージェントへの権限付与」であり、彼らに価値ある作業を行わせることでした。

具体的には、「深さ優先」のアプローチを採用しました：大きな目標をより小さなブロック（設計、コーディング、レビュー、テストなど）に分解し、プロンプティング (Prompting) を通じてエージェントにこれらのブロックを構築させ、それらを解き放つことでより複雑なタスクへと繋げます。タスクが失敗した場合の修復策は決して「もう一度試す」ことではありません。作業を進める唯一の方法が Codex に手を動かさせることである以上、人間のエンジニアは介入し、「何が不足しているのか？この能力をどのようにすればエージェントにとって読み取り可能かつ実行可能にできるか？」と自問する必要があります。

人間はほぼ完全にプロンプトを通じてシステムと対話します：エンジニアがタスクを記述し、エージェントを実行して PR を提出させます。PR を完了させるために、Codex にローカルで自身の変更をレビューさせ、特定のクラウドまたはローカルのエージェントに再レビューを依頼し、人間や他のエージェントからのフィードバックに応じ、すべてのエージェントレビュアーが満足するまで循環的に反復することを指示しました（本質的にはラルフ・ウィグム (Ralph Wiggum) ループです）。Codex は標準的な開発ツール（gh、ローカルスクリプト、リポジトリ内蔵のスキル）を直接使用してコンテキストを取得し、人間が CLI でコピー＆ペーストする必要はありません。

人間は PR をレビューできますが、必須ではありません。時間が経つにつれて、レビュー作業の大部分を「エージェント対エージェント」の相互レビューモードに委ねるようになりました。

コードのスループットが増加するにつれ、ボトルネックは人間の QA（品質保証）の精力に移行しました。制約要因が人間の時間と注意力である以上、私たちはエージェントがシステムをより深く知覚できるように強化することに注力し、アプリケーションの UI、ログ、メトリクスを Codex が直接「読み取れる」ようにしました。

例えば、各 Git Worktree で独立してアプリケーションを起動できるようにすることで、Codex は変更ごとにインスタンスを起動し、それを駆動できるようになります。また、Chrome DevTools プロトコルをエージェントランタイムに統合し、DOM スナップショットの取得、スクリーンショットの撮影、ナビゲーション処理などのスキルを実装しました。これにより、Codex はバグの再現や修正の検証、そして UI 動作そのものの推論が可能になります。

観測性ツールについても同様のアプローチを採用しています。ログ、メトリクス、分散トレーシングは、各 Worktree に対して一時的なローカル観測性スタックを通じて Codex に公開されます。Codex は完全に隔離されたアプリケーションバージョン上で作業を行い、タスク完了後は関連するログやメトリクスも同時に破棄されます。エージェントは LogQL を用いてログをクエリし、PromQL を用いてメトリクスをクエリできます。これらの文脈があれば、「サービスの起動時間を 800ms 未満に保つ」や「主要な 4 つのユーザーパスにおけるトレーススパンを 2 秒以内に抑える」といったプロンプトも扱いやすくなります (Tractable)。

Codex の単一実行が、通常は人間が睡眠中に行われる 6 時間以上にわたって一つのタスクを処理し続ける様子も珍しくありません。

リポジトリの知識を「唯一の信頼できる情報源」として構築する

コンテキストエンジニアリング (Context Engineering) は、エージェントが大規模で複雑なタスクを効果的に処理するための最大の課題の一つです。私たちが最初に学んだシンプルな教訓は、Codex に 1000 ページにも及ぶ説明書を与えるのではなく、地図を提供することです。

コンテキストリソースは希少です。膨大な説明書は、タスクの説明、コード、関連ドキュメントのためのスペースを圧迫し、結果としてエージェントが重要な制約を見落としたり、誤った目標を最適化したりする原因となります。

過度な指示は、指示がないのと同じです。すべてが「重要」である場合、何も重要ではなくなります。その結果、エージェントは意識的なグローバルナビゲーションを行うのではなく、局所的なパターンマッチングに陥ってしまいます。

ドキュメントはすぐに陳腐化します。モノリス型の説明書は、もはや有効ではないルールの墓場へと変貌します。エージェントは何が正しいのかを区別できず、人間によるメンテナンスが行われなくなれば、ファイルは魅力的なトラブルの種となります。

検証が困難です。巨大なテキストブロックでは、カバレッジ、鮮度、所有権、クロスリンクなどの機械的なチェックが難しく、現実との乖離は避けられません。

したがって、AGENTS.md ファイルにリポジトリの知識をすべて詰め込むのではなく、構造化された docs/ ディレクトリ内に主要な知識庫を構築します。

AGENTS.md 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 │ ├── new-user-onboarding.md │ └── ... ├── references/ │ ├── design-system-reference-llms.txt │ ├── nixpacks-llms.txt │ ├── uv-llms.txt │ └── ... ├── DESIGN.md ├── FRONTEND.md ├── PLANS.md ├── PRODUCT_SENSE.md ├── QUALITY_SCORE.md ├── RELIABILITY.md └── SECURITY.md

設計ドキュメントは目録化・索引付けされ、検証ステータスと「エージェント優先」の操作原則を定義するコア信念が含まれます。アーキテクチャドキュメント（Architecture Document）は、ドメインとパッケージ階層のトップレベルマップを提供します。品質ドキュメントでは、各製品領域とアーキテクチャレイヤーに対してスコアリングを行い、時間経過に伴うギャップを追跡します。

「計画」はファーストクラス citizen として扱われます。小規模な変更には一時的で軽量な計画が用いられ、複雑な作業は実行計画（Execution Plans）に記録され、進捗と意思決定のログが含まれてリポジトリにチェックインされます。アクティブな計画、完了した計画、既知の技術的負債はすべてバージョン管理され、一緒に配置されることで、エージェントが外部コンテキストに依存せずに操作できるようになります。

これにより漸進的な開示（Progressive Disclosure）が実現します。エージェントは小さく安定したエントリポイントから始め、最初から情報で圧倒されるのではなく、次にどこを見るべきかを教えられるのです。

私たちはこれを機械化によって強制しています。専用のリンターと CI タスクが、ナレッジベースの最新性、クロスリンクの正確さ、構造のコンプライアンスを検証します。また、コードの実際の動作を反映しなくなった過剰なドキュメントをスキャンして修正 PR を提出する定期的な「ドキュメント・ガーデナー」エージェントも存在します。

コードベースが進化するにつれて、Codex の設計意思決定フレームワークも進化しなければなりません。

リポジトリが完全にエージェントによって生成されるため、まず Codex による可読性の最適化が行われます。チームが新入りのエンジニアにコードを理解させるために最適化するのと同様に、私たち人間エンジニアの目標は、エージェントがリポジトリそのものからビジネスドメイン全体のロジックを直接推論できるようにすることです。

エージェントにとって、実行時にコンテキストから取得できない情報は、実質的に存在しないのと同じです。Google Docs やチャットログ、あるいは人の頭脳に保存された知識にはシステムはアクセスできません。見えているのはリポジトリローカルのバージョン管理されたアーティファクト（コード、Markdown、スキーマ、実行可能な計画）のみです。

私たちは、時間とともにリポジトリにコンテキストを徐々に押し込む必要があることに気づきました。例えば、Slack 上でアーキテクチャパターンについてチームが合意した内容であっても、エージェントが発見できないのであれば、新入社員が入社して3ヶ月経ってもその事実を知らないのと同じくらい無効です。

Codex により多くの文脈を与えることは、組織化して適切な情報を公開し、一時的な指示で埋め尽くすのではなく、その情報に基づいて推論できるようにすることです。新入りのチームメンバーに製品原則やエンジニアリング規範、チーム文化（さらには絵文字の好みまで）を紹介するのと似ています。これらの情報を智能体（エージェント）に提供することで、より一貫した成果が得られます。

このフレームワークは多くのトレードオフを明確にします。私たちは、リポジトリ内で完全に内化・推論可能な依存関係や抽象化を好みます。「地味」と呼ばれる技術ほど、コンポーザビリティが高く、API が安定しており、トレーニングデータセットでの出現頻度が高いため、智能体によってモデル化されやすい傾向があります。場合によっては、不透明な外部ライブラリの挙動を迂回するよりも、一部の機能を智能体に再実装させる方がコストが低くなることもあります。例えば、汎用的な p-limit ライブラリを導入しませんでした。

システムのより多くの部分を、智能体が直接チェック・検証・修正できる形式に変換することは、Codex のレバレッジ効果を高めるだけでなく、コードベース上で作業する他の智能体（Aardvark など）にも恩恵をもたらします。

文書だけでは、完全に智能体によって生成されたコードベースの一貫性を維持することはできません。実装の詳細を細かく管理するのではなく、不変性（Invariants）を強制することで、基盤を損なうことなく快速に成果物を提供できるようにしています。例えば、Codex には境界でデータ形状を解析させるよう要求していますが、具体的な方法までは指定していません（モデルは Zod を好むようですが、そのライブラリを指定したわけではありません）。

厳格な境界と予測可能な構造を持つ環境において、智能体は最も効率的に動作します。そのため、私たちは厳格なアーキテクチャモデルを中心にアプリケーションを構築しています。各ビジネスドメインは固定された階層に分割され、厳密に検証された依存関係の方向性と限られた許可されるエッジ（接続点）を持ちます。これらの制約は、カスタム Linter（もちろん Codex によって生成されたものです！）と構造テストによって機械的に強制されます。

以下の図はこのルールを示しています：各ビジネスドメイン（アプリケーション設定など）内では、コードは「Types → Config → Repo → Service → Runtime → UI」という固定された層に対してのみ、「前方」に依存することができます。認証、コネクタ、テレメトリ、機能フラグなどの横断的関心事項は、一意の明示的なインターフェースである Providers を通じてのみアクセス可能です。それ以外の依存関係は禁止されており、機械によって強制されます。

このようなアーキテクチャは、通常数百名のエンジニアを抱える組織になってから導入されるものです。しかし、コーディング用の智能体にとっては、これは早期の前提条件です。まさにこれらの制約こそが、速度を維持しつつ腐敗やアーキテクチャのドリフトを防ぐことを可能にしています。

実際には、私たちはカスタム Linter と構造テスト、そして少量の「品味に関する不変性」を組み合わせてこれらのルールを執行しています。例えば、構造化ログ記録、スキーマと型の命名規則、ファイルサイズの制限、特定のプラットフォームにおける信頼性の要件などを静的に強制しています。Linter はカスタムであるため、エラーメッセージを作成する際に、修復指示を直接智能体の文脈に注入します。

人間中心のワークフローでは、これらのルールは古風あるいは制約的に見えるかもしれません。しかし、智能体にとっては増幅器となります：一度コード化されれば、それらはすべての場所で同時に適用されます。

同時に、どこで制約が重要で、どこで重要でないかを明確に区別しています。これは大規模なエンジニアリングプラットフォーム組織を率いるのに似ています：中央では境界を強制し、地方では自治を許可します。あなたは境界、正確性、再現性を深く懸念しますが、その境界内では、チーム（または智能体）が解決策の表現方法において大きな自由度を持つことを許容します。

生成されたコードは必ずしも人間のスタイルの好みに合致するわけではありませんが、それは問題ありません。出力が正しく、保守可能であり、将来の智能体にとって「明確に見える」ものであれば、要件を満たしています。

人間の「品味」はシステムに継続的にフィードバックされます。レビューコメント、PR のリファクタリング、ユーザー向けのバグは、ドキュメントの更新として捕捉されるか、あるいは直接ツールにコード化されます。ドキュメントが行動を規範化するのに不十分な場合、ルールはコードへと昇格します。

Codex のスループットが増加するにつれ、多くの従来のエンジニアリング規範が逆効果になりつつあります。

リポジトリの運用では、ブロック的なマージの障壁を最小限に抑えます。PR の生存期間は非常に短くなります。テストの不安定性（フラッキ）は、通常、無限に進行を阻害するのではなく、後続の実行によって解決されます。人間の注意力を遥かに上回るスループットを持つシステムでは、修正は安価ですが、待機は高価です。

低スループット環境では、このアプローチは無責任と見なされるでしょう。しかしここでは、これが通常は正しいトレードオフとなります。

コードベースが Codex エージェントによって生成されると言うとき、私たちはコードベース内のすべてを指しています。

評価ハーンセス（Evaluation harnesses）

人間は常にループ内（Human-in-the-loop）にいますが、私たちは過去よりも高い抽象レベルで作業を行っています。私たちが担当するのは優先順位の決定、ユーザーフィードバックの受入基準への変換、そして結果の検証です。エージェントが struggling するときは、それをシグナルとして捉え、不足しているもの——ツール、ガードレール、ドキュメント——を特定し、これらのフィードバックをリポジトリに戻します。もちろん、修正作業自体は Codex が自ら記述します。

エージェントは私たちが使用する標準的な開発ツールを直接利用します。彼らはレビューフィードバックを取得し、行内で返信し、更新をプッシュし、頻繁に自分自身の PR を圧縮してマージ（Squash and merge）します。

テスト、検証、レビュー、フィードバック処理と回復といった多くの開発サイクルがシステム内に直接コード化されるにつれ、リポジトリは最近、画期的な閾値を越えました。Codex はエンドツーエンドで新機能を駆動できるようになったのです。

プロンプトを与えられれば、エージェントは現在、以下のようなことができます：

この動作は、リポジトリ固有の構造とツールに強く依存しており、同様の投資なしに他の場所で再利用できるとは現時点では仮定できません。

完全なエージェントの自律性も新たな問題をもたらします。Codex はリポジトリ内に既に存在するパターン——不均衡なものや最適化されていないものさえも——を複製します。時間が経つにつれ、これは必然的にドリフト（drift）を引き起こします。

当初は人間が手動でこの問題に対処していました。私たちのチームは過去、毎週金曜日（つまり週の 20% の時間）に「AI スロップ（AI slop）」の掃除を行っていました。当然のことながら、これはスケーラブルではありませんでした。

その代わり、私たちはいわゆる「ゴールデンルール」をリポジトリに直接コード化し、循環的なクリーンアッププロセスを構築しました。これらの原則は独断的かつ機械的な規則であり、コードベースが将来のエージェント実行に対して明確で一貫性を持つように維持することを目的としています。例えば：(1) 不変性の集中を保つため、手書きのヘルパー関数よりも共有されたツールキットを優先します。(2) データを「YOLO スタイル」で試行しません——境界を検証するか、型付けされた SDK に依存し、エージェントが推測に基づく形状に基づいて誤ってコードを構築しないようにします。一定のリズムで、一組のバックグラウンド Codex タスクが逸脱をスキャンし、品質スコアを更新し、ターゲットを絞ったリファクタリング PR を開始します。ほとんどの PR は 1 分以内にレビューされ、自動的にマージされます。

これはガベージコレクション（GC）メカニズムに似ています。技術的負債は高利貸しのようであり、継続的な少額返済が、利子がついて膨れ上がり、苦痛を伴う一度きりの解決よりも常に優れています。人間の品味は一度捕捉され、その後すべてのコード行で継続的に強制されます。これにより、不良パターンが数日または数週間コードベースに蔓延するのを防ぐのではなく、毎日発見して解決することが可能になります。

この戦略は、OpenAI 内部での公開と採用の段階において効果的でした。実際のユーザー向けに真のプロダクトを構築することは、投資を実際の文脈に固定し、長期的な保守性へと導くのに役立ちました。

完全なエージェント生成システムにおいて、アーキテクチャの一貫性が数年間にわたってどのように進化するかについては、まだ分かっていません。私たちは、人間の判断力がどこで最大のレバレッジを生み出すか、そしてその判断力を複利効果を生むようにコード化する方法をまだ学習中です。また、モデルの能力が時間とともに強化されるにつれてこのシステムがどう進化するかについても不明です。

現時点で明確なのは、ソフトウェア構築には依然として規律が必要であるという事実ですが、その規律はコードそのものよりも「足場」に多く現れます。コードベースの一貫性を保つためのツール、抽象化、フィードバックループは、ますます重要になっています。

現在、私たちの最も困難な課題は、エージェントが私らの目標を達成するための環境、フィードバックループ、および制御システムの設計に集中しています：大規模で複雑かつ信頼性の高いソフトウェアの構築と維持です。

Codex などのエージェントがソフトウェアライフサイクルのより大きな部分を担うようになるにつれ、これらの問題はますます重要になっていきます。私たちが共有するこれらの初期経験が、どこに注力すべきかを考える際の参考となり、あなたが創造することに集中できる（just build things）ことを願っています。