この5か月間、私たちのチームはある実験に取り組んできました。それは、手書きコードを1行も使わずにソフトウェア製品を構築し、社内向けベータ版としてリリースするという実験です。
この製品には、社内の日常ユーザーと社外のアルファテスターがいます。製品は出荷・展開を経て、不具合が起こると修正されます。異なる点は、アプリケーションロジック、テスト、CI 設定、ドキュメント、監視機能、内部ツールに至るまで、コードの1行1行がすべて Codex によって記述されていることです。この構築に要した時間は、手作業でコードを記述した場合の約10分の1だったと推定しています。
人間が操縦し、エージェントが実行する。
私たちは、エンジニアリングの速度を飛躍的に向上させるために必要なものを構築できるよう、意図的にこの制約を選択しました。最終的に100万行に達したコードを出荷するまでに、数週間しかありませんでした。そのためには、ソフトウェアエンジニアリングチームの主な業務が、コードを記述することではなく、環境を設計し、意図を明確にし、Codex エージェントが信頼性の高い作業を行うためのフィードバックループを構築することになった場合、何が変化するのかを理解する必要がありました。
この投稿では、エージェントチームと共に全く新しい製品を構築する中で学んだこと、つまり何が問題となり、何が複雑化し、そして私たちの唯一の本当に希少資源である「人間の時間と注意力」を最大限に活用する方法について述べます。
空のレポジトリへの最初のコミットは2025年8月下旬に実施されました。
初期のスキャフォールド（リポジトリ構造、CI 構成、フォーマット規則、パッケージマネージャー設定、アプリケーションフレームワーク）は、少数の既存テンプレートを基に、Codex CLI が GPT‑5 を用いて生成したものです。リポジトリ内でエージェントの作業方法を指示する最初の AGENTS.md ファイルさえも、Codex によって記述されたものでした。
システムの基盤とすべき、事前に人間が書いたコードは存在しませんでした。当初から、リポジトリはエージェントによって形成されていました。
5か月後、リポジトリにはアプリケーションロジック、インフラストラクチャ、ツール、ドキュメント、内部開発者向けユーティリティにまたがる、およそ100万行のコードが含まれるようになりました。その期間中、Codex を推進するわずか3名のエンジニアからなる小規模チームによって、約1,500件のプルリクエストがオープンされマージされました。これは、エンジニア1人あたり1日平均3.5 PRsのスループットに相当します。驚くべきことに、チームが現在7人のエンジニアにまで拡大したにもかかわらず、スループットは増加しています。重要なのは、これは単なる成果のための成果ではなかった点です。この製品は社内で数百人のユーザーに利用されており、日常的に使用するパワーユーザーも含まれています。
開発プロセス全体を通じて、人間がコードに直接関与することは一切ありませんでした。手書きコード一切禁止、これがチームの核となる理念になりました。
人間による手作業のコーディングの削減は、システム、スキャフォルディング、そしてレバレッジに焦点を当てた新たな種類のエンジニアリング作業をもたらしました。
初期の進捗は予想より遅れましたが、それは Codex に能力がなかったからではなく、環境が十分に定義されていなかったためです。エージェントには、高度な目標に向けて進展を図るために必要なツール、抽象化、および内部構造が備わっていませんでした。私たちエンジニアリングチームの主な役割は、エージェントが有用な作業を行えるようにすることになりました。
実際には、これは深さ優先で作業することを意味していました。つまり、大きな目標をデザイン、コード、レビュー、テストなどの小さな構成要素に分解し、エージェントにそれらのブロックを構築させ、それらを用いてより複雑なタスクを達成するということです。何かがうまくいかなかったとき、解決策が「もっと頑張れ」となることはほとんどありませんでした。進歩を遂げる唯一の方法が Codex に作業を任せることだったため、人間のエンジニアは常にそのタスクに取り組み、「どのような機能が不足しているのか？そしてそれをエージェントにとって理解可能かつ実行可能にするにはどうすればよいのか？」と問いかけました。
人間はほぼ完全にプロンプトを通じてシステムとやり取りします。エンジニアはタスクを記述し、エージェントを実行し、プルリクエストをオープンすることを許可します。PR（プルリクエスト）を完了させるために、Codex に対してローカル環境で自身の変更点をレビューするよう指示し、ローカルおよびクラウド環境で追加の特定のエージェントレビューを要求し、人間またはエージェントからのフィードバックに対応し、すべてのエージェントレビュアーが満足するまでループで反復処理を実行します（これは実質的に Ralph Wiggum ループ（新しいウィンドウで開く）です）。Codex は、人間が CLI にコピー＆ペーストすることなく、標準の開発ツール（gh、ローカルスクリプト、リポジトリ埋め込みスキル）を直接使用し、コンテキストを収集します。
人間がプルリクエストをレビューする場合もありますが、必須ではありません。時間の経過とともに、レビュー作業のほぼすべてをエージェント間で処理するように移行してきました。
コードのスループットが増加するにつれて、ボトルネックは人間の QA 能力となりました。固定された制約が人間の時間と注意力であったため、アプリケーション UI やログ、アプリのメトリクスを Codex が直接読み取れるようにすることで、エージェントの機能強化に取り組んできました。
たとえば、Git ワークツリーごとにアプリを起動可能にしたため、Codex は変更ごとに1つのインスタンスを起動して操作できるようになりました。また、Chrome DevTools Protocol をエージェントのランタイムに組み込み、DOM スナップショット、スクリーンショット、ナビゲーションを扱うためのスキルを作成しました。これにより Codex はバグを再現し、修正を検証し、UI の動作について直接分析できるようになりました。
監視機能ツールについても同様の対応を行いました。ログ、メトリクス、トレースは、各ワークツリーごとに一時的なローカル監視スタックを介して Codex に公開されます。Codex は、そのアプリの完全に隔離されたバージョン（ログとメトリクスを含む）で動作し、タスクが完了すると、それらは破棄されます。エージェントは、ログを LogQL で、メトリクスを PromQL でクエリできます。このコンテキストが利用可能になると、「サービスの起動を800ミリ秒以内に完了することを保証する」や「これら4つの重要なユーザージャーニーのいずれにおいても、どのスパンも2秒を超えない」といったプロンプトが実現可能になります。
単一の Codex 実行が単一タスクに対して6時間以上（多くの場合人間が眠っている間）稼働するのを日常的に目の当たりにしています。
コンテキスト管理は、エージェントを大規模かつ複雑なタスクで効果的に機能させる上で最大の課題の一つです。私たちが最初に学んだ教訓の一つはシンプルでした。Codex には1000ページにも及ぶ取扱説明書ではなくマップを与えよ。
私たちは「1つの大きなAGENTS.md（新しいウィンドウで開く）」というアプローチを試みました。それは次のような予測可能な形で失敗しました。
- コンテキストは希少な資源である。巨大な指示ファイルがタスクやコード、関連ドキュメントを圧迫してしまい、そのためエージェントは重要な制約を見落としたり、誤った制約に対して最適化を開始したりします。
- 過度なガイダンスは指針を失う。すべてが「重要」であるときには、何も重要ではなくなります。エージェントは意図的にナビゲートするのではなく、局所的にパターンマッチングを行うことに終始することになります。
- マニュアルは即座に腐る。分厚いマニュアルは、古びた規則の墓場と化します。エージェントは真偽を見極められず、人間は更新を止め、ファイルは知らぬ間に厄介な存在となります。
- 確認するのは難しい。単一の塊では機械的なチェック（カバレッジ、鮮度、オーナーシップ、クロスリンク）に向かないため、乖離は不可避です。
したがって、AGENTS.md を百科事典として扱うかわりに、目次として扱います。
リポジトリのナレッジベースは、構造化された docs/ ディレクトリ内に存在し、記録システムとして扱われます。短い AGENTS.md（約100行）がコンテキストに挿入され、主にマップとして機能し、他の場所にあるより深い信頼性のある情報源への指針を提示します。
設計ドキュメントは、検証ステータスおよびエージェントファーストの運用原則を定義する中核的信念を含む形で、カタログ化および索引付けされています。アーキテクチャドキュメント（新しいウィンドウで開く）は、ドメインやパッケージの階層構造に関するトップレベルのマップを提供します。品質ドキュメントは、各製品領域とアーキテクチャ層を評価し、時間の経過に伴うギャップを追跡します。
計画は第一級の成果物として扱われます。小規模な変更には一時的な軽量プランを使用し、複雑な作業は進捗と意思決定ログを含む 実行プラン（新しいウィンドウで開く） に記録され、リポジトリにチェックインされます。アクティブな計画、完了した計画、既知の技術的負債はすべてバージョン管理され、同じ場所に集約されているため、エージェントは外部のコンテキストに依存せずに運用できます。
これにより段階的開示が可能になります。エージェントは小さく安定した入口から始め、最初から膨大な情報に圧倒されることなく、次にどこを見るべきかを教わります。
当社では、これを機械的に実行します。専用のリンターと CI ジョブにより、ナレッジベースが最新で相互参照され、適切に構造化されていることが検証されます。定期的に実行される「ドキュメント整備」エージェントが、実際のコード動作を反映していない陳腐化または廃止されたドキュメントをスキャンし、修正のためのプルリクエストをオープンします。
コードベースが進化するにつれて、Codex の設計判断のための枠組みも進化する必要がありました。
リポジトリは完全にエージェントによって生成されるため、まず Codex の認識可能性が最適化されています。チームが新規採用エンジニア向けにコードの操作性を向上させるのと同じように、私たち人間のエンジニアの目標は、エージェントがリポジトリ自体から直接ビジネスドメイン全体について推論できるようにすることでした。
エージェントの観点から見れば、実行中にコンテキスト内でアクセスできないものは、事実上存在しないも同然です。Google ドキュメントやチャットのスレッド、あるいは人々の頭の中に存在する知識は、システムからアクセスできません。リポジトリ内でバージョン管理されたアーティファクト（例：コード、マークダウン、スキーマ、実行可能プラン）のみを認識できます。
時間の経過とともに、リポジトリにますます多くのコンテキストを投入する必要があることを学びました。あの Slack の議論で、チームがアーキテクチャパターンについて合意した件は？これをエージェントが見つけられない場合、それは3か月後に入社する新入社員が知らないのと同じように理解不能です。
Codex により多くのコンテキストを与えるということは、場当たり的な指示でエージェントを圧倒するのではなく、エージェントが適切な情報を整理して提示し、その情報に基づいて推論できるようにすることを意味します。プロダクトの原則、エンジニアリングの規範、チーム文化（絵文字の好みなど）について新しいチームメンバーをオンボーディングするのと同様に、エージェントにこの情報を提供することで、より整合性のある成果が得られます。
この枠組みによって、多くのトレードオフが明確になりました。私たちは、リポジトリ内で完全に内製化し、推論可能な依存関係と抽象化を優先しました。「退屈」とよく形容される技術は、構成可能性、APIの安定性、およびトレーニングセットにおける表現により、エージェントがモデル化しやすい傾向があります。場合によっては、公開ライブラリの不透明な上流の挙動を回避するよりも、エージェントに機能の一部を再実装させる方がコストを抑えられました。たとえば、汎用的な p-limit スタイルのパッケージを導入する代わりに、独自の並行処理対応のマップヘルパーを実装しました。これは OpenTelemetry の計装と緊密に統合されており、テストカバレッジは100%で、当社のランタイムが期待する通りの動作を正確に実現します。
システムのより多くの部分をエージェントが直接検査・検証・変更可能な形態にすることでレバレッジが向上します。これは Codex だけでなく、同じコードベースで動作する他のエージェント（例：Aardvark）にも当てはまります。
ドキュメントだけでは、エージェントが生成したコードベースの一貫性を保つことはできません。実装を細かく管理するのではなく、不変条件を徹底することで、基盤を損なうことなくエージェントが迅速にリリースできるようにします。たとえば、Codex には境界でデータ形状を解析（新しいウィンドウで開く）することを要求していますが、その方法については規定していません（モデルは Zod を好むようですが、特定のライブラリを指定したわけではありません）。
エージェントは厳格な境界と予測可能な構造（新しいウィンドウで開く）を持つ環境で最も機能を発揮するため、私たちはアプリケーションを厳密なアーキテクチャモデルに基づいて構築しました。各ビジネスドメインは固定されたレイヤー群に分割され、依存関係の方向性は厳密に検証され、許容されるエッジは限定された集合で構成されます。これらの制約は、カスタムリンター（もちろん Codex 生成です）と構造テストによって機械的に適用されます。
下の図は、各ビジネスドメイン内のルールを示しています（例：アプリ設定）、コードは固定されたレイヤー群（型 → 設定 → リポジトリ → サービス → ランタイム → UI）の「前方」にのみ依存できます。横断的な関心事（認証、コネクタ、テレメトリ、機能フラグ）は、単一の明示的なインターフェースであるプロバイダーを通じて処理されます。それ以外のことはすべて禁止され、機械的に適用されます。
これは通常、数百人のエンジニアが揃うまで先延ばしにする類のアーキテクチャです。コーディングエージェントにおいては、これは初期の前提条件です。これにより、劣化やアーキテクチャドリフト（乖離）を防ぎつつ、スピードを維持できます。
実際には、カスタムリンターと構造テストに加え、少数の「好みに基づく不変条件」を用いてこれらのルールを適用しています。たとえば、構造化ロギング、スキーマや型の命名規則、ファイルサ例イズの制限、プラットフォーム固有の信頼性要件をカスタムリンターを用いて静的に強制します。リントがカスタムであるため、エラーメッセージを書き込んでエージェントコンテキストに修復手順を注入します。
人間中心のワークフローでは、これらのルールは細かいことにこだわっているように感じられたり、制約に感じられたりするかもしれません。エージェントを使用すると、それらは増幅器として機能します。一度エンコードされれば、あらゆる場所に同時に適用されます。
同時に、制約が重要となる領域とそうでない領域を明確に区別しています。これは、大規模なエンジニアリングプラットフォーム組織を率いることに似ています。境界を中央で管理し、自律性はローカルで許容します。あなたは境界、正確性、再現性を深く重視しています。その範囲内で、チーム（あるいはエージェント）が解決策を表現する方法について、かなりの自由度を容認します。
生成されたコードは、必ずしも人間のスタイルの好みに合致するとは限りませんが、それでも構いません。出力結果が正しく、保守可能であり、将来の実行エージェントが読み取れる限り、基準を満たしています。
人間の嗜好は継続的にシステムにフィードバックされ続けます。レビューコメント、リファクタリングのプルリクエスト、ユーザー向けのバグは、ドキュメントの更新として記録されるか、ツールに直接組み込まれます。ドキュメントが不十分な場合、そのルールをコードに昇格させます。
Codex のスループットが増加するにつれて、多くの従来のエンジニアリングの常識は逆効果をもたらすようになりました。
リポジトリは、ブロックを最小限にしたマージゲートで運用されています。プルリクエストは短期間で終了します。テストフレークは、進行を無期限に妨げるのではなく、フォローアップの実行によって対処されることが多いです。エージェントのスループットが人間の注意力をはるかに上回るシステムでは、修正は安価で、待機は高コストとなります。
低スループット環境ではこれは不適切な状態ですが、多くの場合、それが適切な妥協点となります。
コードベースが Codex エージェントによって生成されたという場合、私たちはコードベース全体を指しています。
エージェントが生成するもの：
- プロダクトコードおよびテスト
- CI 構成およびリリースツール
- 社内開発者向けツール
- ドキュメントと設計履歴
- 評価ハーネス
- レビューのコメントと回答
- リポジトリ自体を管理するスクリプト
- プロダクションダッシュボード定義ファイル
人間は常にプロセスに関与していますが、以前とは異なる抽象化の層で作業を行っています。私たちは作業を優先順位付けし、ユーザーのフィードバックを受け入れ基準に変換し、成果を検証します。エージェントが苦戦している場合、それをシグナルとして捉えます。不足している要素（ツール、ガードレール、ドキュメント）を特定し、Codex 自身に修正を記述させることで、それをリポジトリにフィードバックします。
エージェントは当社の標準開発ツールを直接利用します。レビューのフィードバックを抽出し、インラインで返信し、更新をプッシュし、しばしば自身のプルリクエストを圧縮してマージします。
開発プロセスループのより多くの要素（テスト、検証、レビュー、フィードバック処理、復旧）がシステムに直接組み込まれるにつれ、リポジトリは最近、Codex が新機能を設計から運用まで一貫してで実行できる重要な節目を迎えました。
単一のプロンプトで、エージェントは次のことが可能になりました。
- コードベースの現状を検証する
- 報告されたバグを再現する
- 不具合が発生する様子を動画で記録する
- 修正を実施する
- 修正を検証するためにアプリケーションを実行する
- 解決策を示す2つ目の動画を記録する
- プルリクエストを開く
- エージェントおよび人間のフィードバックに対応する
- ビルドの失敗を検出し、修正する
- 判断が必要な場合にのみ人間にエスカレーションする
- 変更をマージする
この動作は、このリポジトリの特定の構造とツールに大きく依存しており、同様の準備なしに一般化できると考えるべきではありません。少なくとも、現時点ではそうではありません。
エージェントの完全な自律性は、新たな問題を引き起こすこともあります。Codex はリポジトリに既に存在するパターンを複製します。不均一なものや最適とは言えないものも含まれます。時間の経過とともに、これは必然的にずれを生じさせます。
当初、人間がこれを手作業で処理していました。私たちのチームは、毎週金曜日（週の20％）を「AI が生み出す粗雑なコンテンツ」の後始末に費やしていました。当然ながら、それは拡張性に欠けていました。
その代わりに、私たちは「黄金の原則」と呼ぶものをリポジトリに直接組み込み、定期的にクリーンアップを行う仕組みを構築しました。これらの原則は、将来のエージェント実行を見据えて、コードベースの可読性と一貫性を維持するための、明確な方針に基づく機械的なルールです。例：（1）不変条件を一元管理するため、独自開発のヘルパーよりも共有ユーティリティパッケージを優先する、（2）データを「YOLO スタイル」で試すことはせず、境界を検証するか、型付き SDK を利用することで、エージェントが推測に基づく構造の上に誤って構築しないようにする。定期的に、逸脱を検出し、品質グレードを更新し、対象を絞ったリファクタリングの pull request を作成する Codex のバックグラウンドタスクを実行しています。これらのほとんどは1分以内にレビューでき、自動的にマージ可能です。
これはガベージコレクションのように動作します。技術的負債は高金利のローンに似ています。通常、複利で膨らんでしまってから痛みを伴う集中返済に追い込まれるよりも、常に少しずつ返済を続ける方が賢明です。人間の好みは一度取り込まれ、その後はコードの各行に継続的に反映されます。これにより、不適切なパターンがコードベース内で数日や数週間にわたって蔓延するのを防ぎ、日々それらを検知して解決できます。
この戦略はこれまで、OpenAI おける社内ローンチと導入に至るまでうまく機能してきました。実際のユーザー向けに本物の製品を構築することは、現実への投資を確固たるものとし、長期的な保守性へと導くことができました。
私たちがまだ解明できていないことは、完全にエージェント生成されたシステムにおいて、アーキテクチャの一貫性が何年にもわたってどのように進化するかです。人間の判断が最も効果を発揮する領域と、その判断の蓄積効果を生むエンコードの手法を、私たちはまだ学んでいるところです。また、モデルが時間の経過とともにより高度になるにつれて、このシステムがどのように進化するかも、私たちにはわかりません。
明らかになったのは、ソフトウェアの構築には依然として規律が必要ですが、その規律はコードそのものよりも、むしろスキャフォールディングに現れるということです。コードベースの一貫性を保つためのツール、抽象化、フィードバックループはますます重要になっています。
現在、私たちが直面している最も困難な課題は、エージェントが私たちの目標である大規模で複雑かつ信頼性の高いソフトウェアを構築し維持することを可能にする環境、フィードバックループ、制御システムを設計することです。
Codex のようなエージェントがソフトウェアライフサイクルのより大きな部分を担うようになると、これらの疑問はさらに重要性を増すでしょう。初期の教訓を共有することで、どこに労力を注ぐべきか考える手助けとなり、ただものづくりに専念できることを願っています。
