Harness エンジニアリング12の心得——Google プリンシパルエンジニアの1年間の実践を、そのまま真似できる手順とテンプレートに凝縮
- Ryan Lopopolo は現在 Google Cloud のプリンシパルエンジニア。その前は OpenAI にいました。この1年の仕事を12の心得にまとめ、公開リポジトリとして整えています。自分の Agent にそのまま参考資料として渡せる形式です。12条の実証の多くは OpenAI 時代の経験に基づきます。
- 中核の作法は直感に反します。選んだモデルとコーディング Agent は変更不能なブラックボックスとして固定し、その周囲にある2つ——コンテキストとツール——だけを変えます。
- 12条は3層構成です。3条が境界を引きます（worker を固定、社内固有のプロセスデータを届ける、実測結果で測る）。6条がテコになります（仕事は丸ごと1体の Agent に、コンテキストは必要時に配送、能力は実際に使える形に、リポジトリ自身に教えさせる、権限を明文化、本番環境で立証）。3条が複利を管理します（フィードバックをインフラ化、長期の一貫性を守る、方向が決まった仕事は常駐ループに）。
- この主張を支える実証——社内プロダクト1本が5か月で空のリポジトリから約100万行、マージ済み PR 約1500本まで成長。すべて Codex が書き、人間は1行も手書きしていません。
- そのまま持ち帰れるもの——6ステップの改善プロセス、穴埋めテンプレート3種、「何を主張するならどこで証拠を取るか」の11行対照表、「あなたの比較実験が無効になる条件」9項目リスト。
12の心得と、誤訳されがちな1語
まず語の意味を正します。ここでの harness は馬具のこと。鞍、手綱、蹄鉄、引き革の一式です。リポジトリ紹介文の冒頭にも馬の絵文字が置かれています。「束縛」と読まれがちですが、意味は真逆です。
馬はすでに十分速く走れます。足りないのは鞍と手綱と走路。馬の力を地面に伝え、行くべき方向へ向かわせるものです。harness engineering がやるのは、この一式を用意することです。
これを書いたのは Ryan Lopopolo。現在は Google Cloud のプリンシパルエンジニアで、agentic GCP を担当しています。その前は OpenAI にいて、シアトルオフィスの立ち上げと企業向け OpenAI Frontier の構築に参加。仕事の中身はまさに、Agent にコンテキスト、ツール、権限、評価、可観測性、オーケストレーション、フィードバックループを与えることでした。12条の実証の多くはこの時期に由来します。それ以前は Snowflake でデータマーケットプレイスのテックリード、Brex では40人のチームを率いて350人規模のエンジニアリング組織を支え、Stripe ではインフラと決済のテックリードとして、会社が600人から6000人に成長する過程を経験しています。趣味では Rust で Ruby 実装を書いていて、名前は Artichoke といいます。
この12条を公開したとき、彼はこう述べています——これは過去1年の仕事であり、実践であり、技術でもある、と。
彼は自身の実践を12の心得に凝縮し、証拠、事例、実行可能な手順とあわせて公開リポジトリに置きました。リポジトリ自作のコンテンツは CC BY 4.0 ライセンスです。使い方は2通り。人が直接読むか、改善したいシステムと一緒にコーディング Agent へ渡し、中の振り分けインデックスに沿って Agent 自身にどの条を読むべきか探させるかです。
読む価値がある理由：12条それぞれに検証可能な実証がついています。社内プロダクト1本が5か月で空のリポジトリから約100万行、マージ済み PR 約1500本に成長し、コードはすべて Codex が書いて人間は1行も手書きしていない。60時間、3億トークン超の大改修が、初回プロンプトと2回の追加指示だけで完了した。コード検査ルール（lint。規約違反の書き方を自動的に見つけるツール）を1本有効にしたところ、約600か所の違反が同一 PR 内で修正され、テストも揃えられた——といった具合です。
以下が12条の全体像です。3層に分けたのは、条どうしの関係を掴むため。上の3条が境界を引き、真ん中の6条が実際のテコ、下の3条がこの仕組みを時間とともに積み上げられるかを決めます。ここから1条ずつ見ていきます。
第1条：働き手を固定する
1回の評価またはデプロイのサイクル中は、モデル、コーディング Agent のランタイム、ネイティブのツールインターフェース——この3つを固定します。どれか1つでも変わったら、たとえ世代交代であっても、環境一式を検収し直します。
ブラックボックスを固定する見返りは、失敗の原因が特定できるようになることです。明らかに能力のある Agent が仕事をやり切れないとき、原因はたいてい5つのどれかに落ちます。関連する組織のコンテキストが足りない、実際に使える能力が足りない、有用なフィードバックループがない、権限がない、出口で証拠が足りない。この5つはすべてデプロイ環境の属性であり、調べられるし直せます。ブラックボックスを固定しなければ、「モデルが悪いのか、自分の設定が悪いのか」の間で永遠に堂々巡りです。
自分が積み上げてきた経験も、検収し直す対象に入ります。旧世代のモデルに教え込まれた癖——タスクをどこまで細かく切るか、どれだけオーケストレーションが要るか、内側のループをどこまで待てるか、どこは人が見張るべきか——をそのまま新世代に持ち込むと、新モデルが増やした実力は丸ごと無駄になります。逆に、マイナーバージョンごとに全次元で強くなっていると仮定するのも、反対方向の誤りです。
彼自身が書き留めた観察が1つ。GPT-5.3 は GPT-5.2 より、難しい仕事に手をつけたがらない。これは単発の使用観察であって、トレンドを構成するものではありません。
世代交代がどれだけ差を生むか、数字が2つあります。GPT-5.2 のリリース時、彼は休暇中でした。戻ってみると、環境への追加投資がまったくない状態で、エンジニア1人あたり1日に PR が1〜2本増えていた。その後、Symphony 環境の改修を単独で行った際には、エンジニア1人あたり週の PR 数が10倍に増えたと報告されています。前者はモデルの世代交代、後者は環境の改修によるもので、この2つは別勘定にする必要があります。ブラックボックスを固定する意義はまさにここにあります。
GPT-5.2 リリース期、環境は一行も変えず。
1人1日あたり PR が1〜2本増加。
Symphony での介入、worker は据え置き。
1人あたり週の PR 数が10倍に増加と報告。
内側のループの遅延も検収の範囲です。Agent がどこまで推論できるかは、この1回の走行（トラジェクトリ。Agent が1つの仕事を最初から最後までやり切る過程全体）が破綻するまでにどれだけフィードバックを受け取れるかで決まります。GPT-5.2 時代の Codex 環境にはバックグラウンドシェルがなく、Agent はブロッキングするビルドスクリプトを律儀に待っていました。GPT-5.3 でバックグラウンドシェルが加わると、待たなくなった。チームは1週間かけて、リポジトリのビルドを自作スクリプトから専用のビルドツールへ乗り換えました（Bazel、Turbo、Nx を順に試行）。手を止める条件は、フルビルドが1分を切ること。この1分を上限として固定し、破ったら手元の作業を止めてビルドグラフを分解しにいきます。
検収には引き算も含まれます。Agent に画面を見せるため、チームは仮想ディスプレイと画面録画の仕組みを自作していました。モデル自身が画面を見てマウスを操作する能力（computer use）が登場したあと、この一式は削除されています。それでエンドツーエンドの検証が失われることはありませんでした。
第2条：私有プロセスデータの水面下へ届ける
汎用モデルの重みに入っているのは、組織の知識の先端だけです。仕事に本当に要るものは水面下にあり、しかもそれは私有で、変わり続けています。
この条が求めるのは、2つの体系を明示することです。1つはデータのオントロジー——どんなエンティティ、指標、識別子があり、それらがどう関係するか。もう1つは仕事のオントロジー——どんな成果、ワークフロー、役割、ツール、例外、証拠、承認関係があるか。
よくわかる例があります。社内のデータ Agent には、データウェアハウスの権限を与えるだけでは足りません。「売上」と「アクティブユーザー」という2語が社内で食い違っている問題は解けないからです。さらに必要なのは、会社にどんな製品ラインがあるか、顧客はどう階層分けされているか、どんなチームがあるか、どの顧客が試験導入中か、現在の計画は何か、共有された指標定義はどう書かれているか。こうした関係が揃って初めて、この会社に固有の答えが出せます。
現在の記録はデータウェアハウス、チケットシステム、ドキュメントシステム、ログ、コードベース、顧客システムに置いたまま。検索とコネクタで承認済みのスライスを取りにいき、いずれ古くなる複製を second copy として作らないことです。
組織の形については、そのまま真似できるやり方が1つあります。Basis という会社にはリポジトリが2つあります。Arnold が本番用のモノレポ、Atlas が2つめのリポジトリで、本番コードツリーの外に会社のコンテキストだけを置く場所です。Codex は個人のメモ、会社の運用知識、本番コードを組み合わせて使えて、しかもこの2種類の情報はそれぞれ独立した更新経路を保てます。実装の形は素朴で構いません。彼の言葉では「Codex と、Markdown で満たした Git リポジトリが1つあるだけ」です。
もう1つこの層に属することがあります。安定した意思決定は、それが効力を持つ層まで昇格させること。あるチームがセキュリティ部門と一緒に、承認済みの暗号実装を選定しました。その決定は Slack に埋もれたままでした。のちに新任のエンジニアが Codex で作業したとき、Codex は別の npm 暗号パッケージを入れてしまった。チームはこの決定を掬い上げてリポジトリにガードルールとして書き、その変更を走らせ直しました。
第3条：1体の Agent が仕事を丸ごと引き受ける
委任するのは結果です。1本のメイントラジェクトリに全権を渡します——分解、実行、統合、立証、安全な後始末。手順はそれ自身に決めさせます。人が手を出すのは3か所だけ——方向、判断、そして結果を伴う承認です。
彼はしばしば、ほぼ制約ゼロのプロンプトを与えます。これを「怠惰なプロンプト」と呼んでいて、怠惰なのは方法を空白にしている点。どうやるかは Agent が決めます。疎な委任はテスト手段でもあります。測っているのは、本当の要求を Agent 自身が拾い直せる環境になっているかどうか。Agent が読み違えたとき、そこで露わになるのは環境のどこが作られていないかです。組み合わさるループは「提示、観察、改善、再走行」——トラジェクトリを最後まで見て、環境を直し、今回の成果は捨て、もう一度走らせます。