ハーネスエンジニアリング: エージェント優先の世界でCodexを活用する

• OpenAIの社内チームが、5か月間一切手書きでコードを書かずにソフトウェア製品の内部ベータを構築・公開した実験事例で、すべてのコードをCodexエージェントが生成
• 3人のエンジニアで始め、約100万行のコードと1,500件のpull requestを処理し、エンジニア1人あたり1日平均3.5件のPRをマージ
• エンジニアの役割は直接コーディングすることから、環境設計、意図の明示、フィードバックループの構築へと移行し、エージェントが安定して作業できるスキャフォールディングの構築が核心
• AGENTS.mdは百科事典ではなく目次として活用し、構造化された文書・リンター・構造的テストを通じてアーキテクチャの一貫性を機械的に強制
• エージェントの自律性が高まるほど、エントロピー管理とガベージコレクション的な継続的整理が不可欠であり、ソフトウェア構築の規律はコードからスキャフォールディングへ移りつつある

---

空のgitリポジトリから始めた実験

• 2025年8月末、空のリポジトリに最初のコミットを行い、初期スキャフォールド（リポジトリ構造、CI構成、フォーマット規則、パッケージマネージャ設定、アプリケーションフレームワーク）は既存テンプレートを基にGPT-5を使ってCodex CLIで生成
• エージェントにリポジトリの扱い方を教える初期のAGENTS.mdファイルもCodexが直接作成
• 最初から人間が書いた既存コードはなく、リポジトリはエージェントによって形成
• 5か月後には、アプリケーションロジック、インフラ、ツーリング、ドキュメント、社内開発者向けユーティリティ全般にわたり約100万行のコードを含むようになった
• 3人の小規模チームが約1,500件のpull requestを開いてマージし、これはエンジニア1人あたり1日平均3.5件のPRの処理量に相当
• チームが7人に増えると、処理量はむしろ増加
• 数百人のユーザーが毎日社内で利用しており、社内のパワーユーザーも含まれる
• 開発プロセス全体を通して、人間がコードに直接貢献したことはない
• **「手書きしたコードはない」**ことがチームの中核的な哲学となった

エンジニアの役割の再定義

• 人が直接コーディングしないため、システム、スキャフォールディング、レバレッジ中心の別種のエンジニアリング作業が必要
• 初期の進行が予想より遅かった理由はCodexの能力不足ではなく、環境の未整備にあった
  • エージェントが上位目標を達成するためのツール、抽象化、内部構造が不足していた
• エンジニアリングチームの主要業務は、エージェントが有用な仕事をできるよう支援することへと移行
• 大きな目標を、設計、コード、レビュー、テストなどのより小さなビルディングブロックに分解し、エージェントがそれらを組み合わせてから、より複雑な作業を解く深さ優先の作業方式
• 失敗したときに重要なのは「もっと頑張る」ことではなく、**「どの機能が欠けていて、エージェントが読みやすく実行可能にするにはどうすべきか」**という問い
• 人間はほぼ全面的にプロンプトを通じてシステムと対話
  • 作業の説明、エージェントの実行、pull requestのオープンなどを指示
• PR完了のためにCodexへ、ローカルで自分の変更をレビューし、ローカルおよびクラウドでエージェントレビューを追加で依頼し、フィードバックに応答し、すべてのエージェントレビュアーが満足するまで繰り返すよう指示
  • 実質的にはRalph Wiggum Loop方式
• Codexはgh、ローカルスクリプト、リポジトリ内蔵スキルなど標準的な開発ツールを直接使ってコンテキストを収集
• 人間によるpull requestレビューは可能だが必須ではなく、時間の経過とともにレビュー作業のほぼすべてがエージェント間処理へと移行

アプリケーションの可読性向上

• コード処理量の増加に伴い、人的QA能力がボトルネックになった
• 人間の時間と注意力は固定の制約であるため、アプリケーションUI、ログ、アプリメトリクスなどをCodexが直接読んで理解できるようにし、エージェントに機能を追加
• git worktreeごとのアプリ起動機能により、Codexは変更ごとに別個のインスタンスを実行・制御可能
• Chrome DevTools Protocolをエージェントランタイムに接続し、DOMスナップショット、スクリーンショット、ナビゲーション作業用のスキルを作成
  • Codexがバグの再現、修正の検証、UI挙動について直接推論可能
• 可観測性ツーリングにも同じ方式を適用
  • ログ、メトリクス、トレースは、各worktreeに対して一時的に保持されるローカル可観測性スタックを通じてCodexに公開
  • 作業完了後はログとメトリクスを削除
  • エージェントはLogQLでログを、PromQLでメトリクスをクエリ可能
• こうしたコンテキストがあれば、「サービス起動が800ms以内に完了するように」や「4つの主要ユーザージャーニーにおいて、どのspanも2秒を超えないように」といったプロンプトの処理が容易になる
• 1回のCodex実行で6時間以上（しばしば人が寝ている間）1つの作業を続行

リポジトリ知識を記録システムとして活用

• コンテキスト管理は、エージェントが大規模で複雑な作業を効果的に行ううえで最大級の課題の1つ
• 初期の教訓: Codexには1,000ページの説明書ではなく地図を渡すべき
• 「1つの巨大なAGENTS.md」アプローチを試した結果、予想どおり失敗
  • コンテキストは希少資源: 巨大な指示ファイルは作業・コード・関連文書を複雑化し、エージェントが主要な制約条件を見落としたり、誤った制約条件に最適化したりする
  • 指示が多すぎると指示にならない: すべてが「重要」なら重要なものは何もなく、エージェントは意図的な探索ではなく局所的なパターンマッチングを行う
  • あっという間に壊れる: 画一的な巨大マニュアルは古いルールの墓場へと変わり、エージェントは何がまだ有効か判断できない
  • 検証しにくい: 単一のブロブは機械的チェック（カバレッジ、新鮮さ、オーナーシップ、相互リンク）に不向きで、ドリフトは避けられない
• 解決策は、AGENTS.mdを百科事典ではなく目次として扱うこと
• リポジトリのナレッジベースは、構造化されたdocs/ディレクトリに記録システムとして管理
• 短いAGENTS.md（約100行）はコンテキストに挿入され、主に地図として機能し、より深く信頼できる情報源へ案内
• 設計ドキュメントには、検証状態とエージェント優先の運用原則を定義する中核的信念が含まれ、分類・索引化される
• アーキテクチャ文書は、ドメインとパッケージレイヤリングの最上位マップを提供
• 品質文書は、各製品ドメインとアーキテクチャレイヤーに等級を付け、時間とともにギャップを追跡
• 計画は第一級のアーティファクトとして扱う
  • 一時的で簡単な計画は小さな変更に使う
  • 複雑な作業は進捗と意思決定ログを伴う実行計画に含め、リポジトリに保存
  • 進行中の計画、完了した計画、既知の技術的負債はすべてバージョン管理され、同じ場所に配置
• これにより段階的公開が可能になる。エージェントは最初から負荷を抱えず、小さく安定した入口から始めて次の段階へ進める
• 機械的な実施として、専用リンターとCIジョブがナレッジベースの最新性、相互リンク、正しい構成を検証
• 定期実行される**「doc-gardening」エージェント**が古くなった、または無効な文書を見直し、修正用pull requestを開く

エージェントの可読性が目標

• リポジトリが全面的にエージェントによって生成されているため、第一にCodexの可読性へ最適化
• 人間のエンジニアの目標は、エージェントがリポジトリそのものから直接ビジネスドメイン全体を推論できるようにすること
• エージェントの観点では、実行時コンテキスト内でアクセスできないものは実質的に存在しないのと同じ
  • Google Docs、チャットスレッド、人の頭の中にある知識はシステムからアクセスできない
  • リポジトリ内のバージョン管理されたアーティファクト（コード、Markdown、スキーマ、実行計画）にしかアクセスできない
• Slackで合意されたアーキテクチャパターンも、エージェントが検索できなければ判読不能
• Codexにより多くのコンテキストを与えるとは、その場しのぎの指示で負荷をかけることではなく、正しい情報を整理・公開してエージェントが推論できるようにすること
• 製品原則、エンジニアリング規範、チーム文化（絵文字の好みを含む）について、新しいチームメンバーをオンボーディングするようにエージェントへ情報提供すると、より良い成果が得られる
• リポジトリ内で完全に内在化して推論できる依存関係と抽象化を好む
• 「地味な」技術は、結合性、API安定性、学習設定内での表現のしやすさのおかげで、エージェントにとってモデル化しやすい傾向がある
• 場合によっては、公開ライブラリの不透明なupstream挙動に頼るより、エージェントが機能のサブセットを自前で再実装した方が安い
  • 例: 汎用のp-limitスタイルパッケージの代わりに独自のmap-with-concurrencyヘルパーを実装し、OpenTelemetry計測と密接に統合し、テストカバレッジ100%を確保し、実行時に期待どおり正確に動作
• システムをエージェントが検査・検証・直接修正できる形へより引き上げるほど、Codexだけでなく他のエージェント（例: Aardvark）でもレバレッジが増す

アーキテクチャと好みの強制適用

• ドキュメントだけでは、エージェントが生成したコードベースを完全に一貫した状態に保てない
• 実装を細かく管理せずに不変条件を強制することで、土台を堅牢に保ちながらエージェントが素早くリリースできる
  • 例: Codexには境界でデータ形状をパースしてほしかったが、その方法（特定ライブラリ）までは具体的に指定しなかった（モデルはZodを好む傾向がある）
• エージェントは厳密な境界と予測可能な構造を備えた環境で最も効果的
• 厳格なアーキテクチャモデルを中心にアプリケーションを構築
  • 各ビジネスドメインは、厳しく検証された依存方向と限定された許可エッジ集合を用いて固定されたレイヤー集合に分離
  • Types → Config → Repo → Service → Runtime → UI の順でコードが流れる
  • 横断的関心事（認証、コネクタ、テレメトリ、機能フラグ）は、Providersという1つの明示的インターフェースを通じて流入
  • それ以外はすべて許可されず、機械的に強制
• こうした制約は、Codexが生成したカスタムリンターと構造的テストによって適用
• このレベルのアーキテクチャは通常、数百人規模のエンジニア組織になるまで先送りされがちだが、コーディングエージェントにとっては初期前提条件
• カスタムlintにより、構造化ログ、スキーマおよび型の命名規則、ファイルサイズ制限、プラットフォーム別の安定性要件を静的に適用
  • lintがカスタムであるため、エラーメッセージを書いてエージェントのコンテキストに修正指示を注入できる
• 人間中心のワークフローではこうしたルールは細かすぎたり制約的に感じられるかもしれないが、エージェント活用時には効果を何倍にも増幅する
• 制約条件は、何が重要で何が重要でないかを明確に区別する
  • 大規模エンジニアリングプラットフォーム組織の運営に近い: 中央で境界を設定し、ローカルで自律性を許す
• 結果のコードが人間の文体上の好みと常に一致するとは限らないが、出力が正確で保守可能であり、エージェントの実行時に読みやすければ基準を満たす
• 人間の好みは継続的にシステムへフィードバック
  • レビューコメント、リファクタリングPR、ユーザー側バグはドキュメント更新として記録されるか、ツーリングに直接エンコードされる
  • ドキュメントが不十分ならルールをコードへ昇格させる

マージ哲学の変化

• Codexの処理量が増えるにつれ、従来のエンジニアリング規範がむしろ逆効果になった
• リポジトリは最小限のブロッキングマージゲートで運用
• pull requestは寿命が短く、テストの不安定さは進行を無期限に止めるのではなく、後続実行で解決する
• エージェントの処理量が人間の注意力を大きく上回るシステムでは、修正コストは安く、待ち時間は高い
• 処理量の少ない環境では適さない可能性があり、適切なトレードオフが必要

「エージェント生成」の実際の範囲

• コードベースがCodexエージェントによって生成されるとは、コードベース内のあらゆるものを意味する
  • 製品コードとテスト
  • CI構成とリリースツーリング
  • 社内開発者ツール
  • ドキュメントと設計履歴
  • 評価ハーネス
  • レビューコメントと応答
  • リポジトリ自体を管理するスクリプト
  • 本番ダッシュボード定義ファイル
• 人間は常にループ内にいるが、以前とは異なる抽象化レイヤーで作業している
  • 業務の優先順位付け、ユーザーフィードバックの受け入れ基準への変換、結果の検証
• エージェントが苦戦したら、それをシグナルとして受け取り、ツール、ガードレール、ドキュメントなどの欠落を特定し、常にCodex自身に修正を書かせてリポジトリへ戻す
• エージェントはレビューのフィードバック取得、インライン応答、更新のpush、自分のpull requestのsquash・mergeまで実行

自律性レベルの上昇

• テスト、検証、レビュー、フィードバック処理、復旧など、より多くの開発ループがシステムに直接エンコードされるにつれ、重要な臨界点に到達
• エージェントが1回のプロンプトで実行可能な作業:
  • コードベースの現在状態を検証
  • 報告されたバグを再現
  • 失敗状況を示す動画を録画
  • 修正を実装
  • アプリケーションを実行して修正を検証
  • 解決策を示す2本目の動画を録画
  • pull requestを開く
  • エージェントおよび人間からのフィードバックに応答
  • ビルド失敗を検知して修正
  • 判断が必要な場合にのみ人間へエスカレーション
  • 変更をマージ
• こうした挙動はこのリポジトリ特有の構造とツーリングに大きく依存しており、同様の投資なしに一般化できると考えるべきではない

エントロピーとガベージコレクション

• エージェントの完全自律は新たな問題を引き起こす: Codexはリポジトリ内にすでにあるパターン（不均一だったり最適でなかったりするものを含む）を複製するため、時間とともに必然的にドリフトが発生する
• 初期には人間が手動で対処し、毎週金曜日（週の20%）を「AIスロップ」の整理に費やした
  • 予想どおりスケールしなかった
• 代替策として、**「黄金律」**をリポジトリに直接エンコードし、定期的な整理プロセスを構築
  • (1) 不変条件を中央管理するため、自作ヘルパーよりも共有ユーティリティパッケージを優先
  • (2) 「YOLO-style」でデータ探索を行わず、境界を検証するか型付きSDKに依存して、エージェントが推測した形に基づいて誤って構築しないようにする
• 定期的に逸脱をチェックし、品質等級を更新し、対象を絞ったリファクタリングPRを生成するCodexバックグラウンドジョブを運用
  • 大半は1分以内にレビューでき、自動マージされる
• この方式はガベージコレクションのように機能する。技術的負債は高金利ローンのようなもので、利息が積み上がる前に少しずつ継続的に返済するのが効果的
• 人間の好みが一度取り込まれれば、コードの全行に継続的に反映され、悪いパターンが数日から数週間広がる前に毎日捉えて解決できる

現在進行中の学びと今後の課題

• この戦略はOpenAIにおいて、社内リリースと導入段階まではうまく機能している
• 実際のユーザー向けの実際の製品を構築することで、投資を現実に着地させ、長期的な保守可能性を確保している
• まだ分かっていないのは、完全なエージェント生成システムにおいてアーキテクチャの一貫性が数年単位でどう進化するかという点
• 人間の判断が最も大きな影響力を持つ部分と、その判断をどうエンコードして複利的に活用するかについて、なお学習中
• モデルの能力が向上し続けるなかで、このシステムがどの方向へ進化するかも未知数
• ソフトウェア構築には依然として規律が必要だが、その規律はコードよりもスキャフォールディングにより強く表れる
• コードベースの一貫性を維持するツーリング、抽象化、フィードバックループの重要性はますます高まっている
• 現在もっとも難しい課題は、エージェントが複雑で安定したソフトウェアを大規模に構築・保守するのを助ける環境、フィードバックループ、制御システムを設計すること

[ragingwind]

40日、100万行、130億トークン — Lablupのシン・ジョンギュ代表が見出したエージェント型ワークフローの実体 - パク・ジェホンのシリコンバレー - https://wikidocs.net/blog/@jaehong/8206/