HN 日本語サマリー

← 一覧へ戻る
プログラミング

ソフトウェアファクトリーが失敗する理由(または:ハーネスエンジニアリングだけでは不十分)

Why Software Factories Fail (or: harness engineering is not enough) (github.com)

350 pointsby dhorthy247 コメント

要約

この記事は、AIコーディングエージェントを活用した「ソフトウェアファクトリー」の現状と課題について論じている。多くの企業がAIによるコード生成の高速化を目指す一方、コードレビューの質の低下やインシデントの増加といった問題が発生している。著者は、単にAIをループさせる「ハーネスエンジニアリング」だけでは、モデルの根本的な訓練や評価の問題を解決できず、コードベースの崩壊を防ぐには不十分であると主張している。

全文翻訳

wsff.md

ソフトウェアファクトリーが失敗する理由

あるいは、ハーネスエンジニアリングだけでは不十分

注記

私は人間/エージェントのコラボレーション分野でツールを開発する会社(HumanLayer)を経営しているため、以下に述べることはやや偏っているかもしれません。それでも、このテーマが皆様の参考になること、あるいは少なくとも私がそうであるように、皆様にとっても興味深いものであることを願っています。- Dex

ループ処理を導入する時が来たようです

私たちは皆、AIコーディングを本番環境に投入するために競い合っています。ループエンジニアリングについては多くのことが語られており、一般的な考え方は、もっと多くのループを書くべきだというものです。1

[画像: ループエンジニアリング -- もっとループを書くだけ]

StrongDMは、人間がコードを読まず、人間がコードを書かない「ライトオフ」ソフトウェアファクトリーについて書いています。

その物語は、おおよそ以下のようになります。

  1. ボトルネックはあなたです。
  2. モデルは十分に優れています。
  3. コードは無料です。
  4. とにかく、もっと多くのものを出荷しましょう。

OpenAIのRyan Lopopolo氏は2月にこのことについて書き4月には講演を行い、OpenAIのソフトウェアファクトリーであるSymphonyについて説明しました。

[画像: OpenAIのRyan Lopopolo氏、ハーネスエンジニアリングについて]

これらの人々は皆、非常に賢く、私は彼らに多大な敬意を払っています。しかし、ここで最も皮肉な見方は、これをVCマネーをさらに大量に注ぎ込むための、もう一つの言い訳と呼ぶことでしょう。

うーん…まあ、進んでいます

私たちの友人であるMario氏は、AI Engineer Europeで登壇し、立ち止まるように懇願しました -- なぜなら、コーディングエージェントのミスによって障害を起こすべきではない企業が、実際に障害を起こしているからですFTの記事。

Matt Pocock氏が言うように、コードベースはこれまで以上に速く崩壊しています。

StrongDMから、あのダークファクトリーがどうなったかについての決定的なデータや調査結果を見つけることができませんでした。weather-reportには、今年の2月から6月にかけての数件のまばらな更新があります。編集 - 7月23日のHacker Newsでのチームとの会話があります - 近いうちに正式なアップデートが得られるようです!

Faros AIのチームはレポートを発表しました:1月にこれらのAIコーディングツールを使い始めて以来、プルリクエストのレビュー品質は大幅に低下しています2。

  • コメントが増え、コメントが長くなり、レビューなしでマージされるPRが大量に出ています。
  • インシデントが大幅に増加しています。
  • 開発者あたりのバグ数が大幅に増加しています。

このレポートは、検証可能な決定的な証拠というよりは相関信号3ですが、この投稿の全体的な目的は、不確かなデータに注意することであり、私が目にしたものに基づけば、方向性としては有効だと感じられます。

「持ち方が悪い」(そうではない)

多くの人は、これがスキルの問題だと言うでしょう -- 結果が良くないのは、あなたのせいだと。しかし、あなたがどのように「持ち方」を選ぼうと、トークン最大化がうまくいかないのはあなたのスキルの問題だと言われることは保証されています。もっとトークンを使う必要があるのです。コードを読むのをやめましょう。そして、もしあなたがちょうど始めたばかりなら、それは進歩の一部だと約束します。私も昨夏の夏にそう思っていました。

残念ながら私のエゴにとっては、「持ち方を良くするには」という私が決めたくだらない発言が記録され、今ではYouTubeで数百万回の総再生回数を記録しています。自慢したいわけではありません。この共有は、私が長年コーディングエージェントを最大限に活用する方法を深く追求してきたことを示すためだけであり、多くの他の人が本当に役立つと見出したことを発見しました。

いずれにせよ、オンラインで私たちが耐えなければならなかった「もっとトークンを叩き込め」というおしゃべりの約束は、簡潔に言うとこうです:十分なハーネスエンジニアリングがあれば、両方の世界の最良の部分を得ることができます。

  • 10倍から100倍高速、
  • 高品質、そして
  • コードレビューという、皆が嫌うことを誰も行う必要がなくなる

リンターをもっと設定し、「敵対的レビュー」のような魔法の言葉を十分なPRレビューボットに散りばめるだけで、私たちのソフトウェアは問題なく喜んで自己構築してくれるでしょう。

これはスキルの問題ではない

私が皆さんに納得させようとしているのは、どんなに多くのハーネスエンジニアリングやループ最大化も、根本的にモデルトレーニングの問題を解決することはできないということです。

これを理解するために、コーディングモデルが実際にどのようにトレーニングされ、評価されているのか -- RLVRとベンチマークの両方の側面から -- を掘り下げる必要がありました。

この記事では、以下の点について説明します。

  1. ソフトウェアファクトリーは1968年に遡る、どのように進化してきたか、そしてAIはそれをどう変えたか
  2. モデルはなぜ、ベンチマーク(最新の「フロンティア」ベンチマークでさえ)を楽々クリアしても、大量のゴミを生成できるのか
  3. それにもかかわらず、コードベースを燃やすことなく、かなり速く進むことができる

私は、毎日のように登場するスキルプラグインの誇大広告や、AI精神病的なトークン最大化アドバイスのパンデミックを切り抜け、特定のスキルやフレームワークに言及することなく、機能するものの種類について一般的な言葉で話そうと思います。

動画版: この投稿は、AI Engineer World's Fair 2026での私の基調講演に基づき(そしてそれを拡張して)います。

余談:これはバイブコーディングとは関係ない

Addy Osmani氏が強調する価値のあることを解きほぐしました。

数人が実行するだけのサイドプロジェクトをバイブコーディングしている開発者と、10年前のエンタープライズシステムをもう四半期生き延びさせるチームは、名前を挙げる価値のある制約をほとんど共有しておらず、流通しているアドバイスのほとんどは、一方の人がもう一方に生き方を伝えているようなものです。

バイブコーディングが好きな方は、どうぞバイブし続けてください。私もまだ多くのことをバイブコーディングしていますが、私は生産ソフトウェアのメンテナンスも行っています(そしてHumanLayerを通じて、他の何千人ものエンジニアが同じことをするのを支援しています)。そのため、残りは複雑なコードベースで困難な問題を解決している人たちを対象としています。

私は「ブラウンフィールド」という言葉をこの分割を説明するためによく聞きます。歴史的にはそれは10年前のJavaの何かを意味していましたが、私たちが今出荷できるペースでは、エージェント構築のコードベースは3〜6ヶ月後には苦労し始めると感じます -- 速度が落ち、新しいものを追加する方法を変えなければならなくなります。

ソフトウェアファクトリーの簡単な歴史

私はキャリアを通じてソフトウェアファクトリーを構築し、研究してきましたが、最近知ったことがあります:この用語は1968年のNATO会議に遡ります -- 「ソフトウェアエンジニアリング」が生まれたのと同じ会議です。

それ以降、私が非常に興味深いと感じるもう一つの点は、米国国防総省がDoDがJenkinsをもっとうまく使う必要があるという31ページのPDFを書いたことです。

2022年のソフトウェアファクトリー

AI以前の2022年頃を中心に、「ソフトウェアファクトリー」の定義を整理しましょう。

  • 人々が何を作るかを決定する -- エンジニア、PM、ビジョンを推進するリーダーシップ
  • トラッカーに入る -- Linear、Jiraなど:何が必要かを示すステートマシン
  • 誰かがチケットを取得して構築する -- おそらく手動/自動テストも行う
  • プルリクエスト -- 自動チェック、人間によるコードレビュー、場合によってはテストのためにプルダウンする
  • 何か問題があるか? 「誰かがそれを作る」に戻る
  • 本番にデプロイ -- ユーザーと接触する
  • 監視を追加する -- 何かが壊れたときにエンジニアを夜中に呼び出すために、全体的な産業が構築されている
  • ユーザーが不平を言う -- 要求したり、バグを見つけたり、機能リクエストを提出したり → チームに戻ってトラッカーに追加する

wsff-boxes-2x.mp4[動画]

そして、この繰り返しです。まだAIに触れていませんが、この図にはすでにいくつかのループがあります。

アライメントのフロントローディング

チームが数十年前から気づいていたこと:構築には数時間または数日かかり、レビューにも同様です。

[画像: 構築とレビューの両方に数時間または数日かかる]

そこで、私たちは作業をフロントロードします -- 計画、アーキテクチャ提案、スプリント計画 -- 全体として、チームとして行います。これは意味します。

  • 手戻りの削減、コードを書く前に合意したため
  • すべての行をレビューする時間の削減、長くてよくできたPRを読んだことがあるなら、ほぼ完璧なレビューがどれほど速いかを知っているでしょう

[画像: 計画のフロントローディング:約1時間の事前作業で手戻りが減り、レビューが6時間から20分に短縮]

後で戻ってきます -- エージェントコーディングを導入した場合に何が起こるか見てみましょう。

エージェント型ソフトウェアファクトリー

今や、あらゆる会社が --

この1年の大半を、彼らが75%ものコードを出荷するエージェントファクトリーを構築した方法を説明することに費やしてきました。

エージェント型ファクトリーは、主に「誰かがそれを作る」を「エージェントがそれを作る」に置き換えるものです -- オーケストレーション、ハーネス、サンドボックス、モデル、コンピューター利用などの要素がいくつかあります。それらの詳細には深入りしません。なぜなら、正直に言って、それについて読むのにうんざりしていますし、あなたもそうでしょう。

[画像: エージェント型ソフトウェアファクトリー -- エージェントがそれを作る]

エージェントがそれを作ると:

  • 構築時間は数時間または数日から数分または数時間に短縮されます。
  • レビューには依然として数時間または数日かかります。人間はまだコードを読み、変更をテストする必要があります。したがって、レビューがボトルネックになります。

[画像: 構築は数分または数時間、レビューは依然として数時間または数日]

そこで、レビューも高速化します。

  • スタイル、バグ、セキュリティを検出するためのエージェント型コードレビュー。
  • ブラウザやコンピューター利用で外部からそれを試し、完了時にかわいい小さなビデオを送ってくれるかもしれない、エージェント型回帰テスト。

[画像: エージェント型レビューと回帰テスト -- より高速ですが、依然としてボトルネック]

レビューは今や高速ですが、おそらく依然としてボトルネックです。しかし、もっと多くのループを実行できます。

次に、インシデントをファクトリーにルーティングできます。夜中に誰かを呼び出す代わりに、すでに修正されているかもしれないPRで目を覚まします。

[画像: インシデントをファクトリーにルーティング]

ユーザーからのフィードバックもファクトリーにルーティングできます。人々が何かを求め、それが構築されます。

[画像: ユーザーフィードバックをファクトリーにルーティング]

その時点で、仕事は2つの質問になります:キューにどれだけ詰め込めるか、そして出てきたものをどれだけ速くレビューしてテストできるか?

[画像: キューにどれだけ詰め込めるか、そして出てきた変更をどれだけ速くレビューできるか]

これがライトオフソフトウェアファクトリーにつながります。

ライトオフソフトウェアファクトリー

Dan Shapiro氏がこの用語を造語し、Simon Willison氏がStrongDMの実装について書きました -- コードを読まなくなるものです。

あなたの美しいソフトウェアファクトリーを見ます。それは、厄介なコードレビューという小さなステップによって台無しにされており、あなたは言います:知るか、人間がすべての変更を読むということをやめよう。

[画像: ライトオフソフトウェアファクトリー -- 人間のレビューがスクラッチで書かれている]

そこで、それをドロップし、労力を別の場所に費やします。

  • テストへの投資と、エージェントに自身の作業をテストさせること
  • サンドボックスとオーケストレーションへの投資
  • 自動レビューへの投資
  • 監視への投資
  • ロールアウトへの投資
  • ユーザーからのフィードバックシグナルの収集

[画像: テスト、監視、ロールアウトに投資]

そして今、仕事は本当に一つの質問になります:エージェントにどれだけのものを構築させることができるか? 海をどれだけ沸騰させたいか?

[画像: 仕事は今や一つの質問 -- キューにどれだけ詰め込めるか]

これはうまくいくでしょう(そうはならない)

私は、潜在的に物議を醸すことを提唱します:ライトオフファクトリーは機能しません。

ソフトウェアファクトリーが失敗する理由を掘り下げてみましょう。

我々はこれを試した

2025年7月、私たちは完全にライトオフになりました。仕様とチケットを読むだけで、小さな/中規模のものはすべてバックグラウンドエージェントで処理し、すべてを実行しました。

真剣に数ヶ月試したことがあるなら、その結末はすでに知っているでしょう。エージェントが解決できない、少なくとも1つの厄介な問題に遭遇します -- 最も高度なプロンプトとワークフローを使ってもです。

  • 深いコンテキスト認識リサーチを行い、正しい部分をすべてスマートゾーンに集めてモデルが分析できるようにします。
  • エージェントに10通りの方法で再現させます。

最終的には、3ヶ月前に読むのをやめたコードベースを掘り下げて、何が壊れているのかを理解しなければならなくなります。

そしてその間に:

  • あなたのサイトはダウンしていました。
  • ユーザーは怒っていました。
  • そしてあなた(私と同じような人なら)は惨めでした -- システムに忍び込ませたゴミコードをすべて読んでいました。

これが最初に起こったとき、私はそれを振り払いました。クロードのスパゲッティを2週間近く掘り下げて過ごしたにもかかわらず、「ダウンサイドリスクはベロシティに見合う」と考えました。11月頃の3回目には、最初から書き直す方が簡単だろうと判断し、私の共同創設者は2週間まるまるVS Code(Cursorでさえなく)で手作業でパターンをすべて配線しました。

モデルは時間とともにコードベースの品質を低下させる

私が言いたいのはこれです:モデルには欠点があります。それらは、かなりの人間の指示なしには、コードベースの品質を維持・改善できません4。

保守性と言うとき、私はコードベースの一部分を変更すると別の部分が壊れるのが非常に困難になる、という特定のことを意味します。これはMartin Fowlerのショットガン手術です。

保守性についてはこれ以上多くは言いません。それについては、たくさんの本を読むことができます。

では、なぜモデルはソフトウェアの保守性を実行できないのでしょうか?

「しかし、モデルはそれ以来改善されたはずだ」

この時点で、あなたは言いたくてたまらないかもしれません:しかしDex、モデルは7月以来ずっと良くなったはずだ

ある意味では良くなりました。他の意味ではほとんど変わりません。

  • 単発の問題を解決する、あるいは新しいマーケティングサイトをバイブコーディングする? はい。ずっと良くなりました。
  • 時間とともにコードベースの品質を改善する? 私が見る限り、あまり良くなっていません。

[画像: 単発の問題解決は2025年から2026年にかけて急増しましたが、コードベースの品質改善はほとんど動きませんでした]

これを証明することはできません。あなたも証明できません。モデルのコードベース品質維持能力に関する良いベンチマークはありません。(後でそのことについて詳しく説明します。)

モデルのコードベース品質維持能力に関する良いベンチマークはありません

しかし、コーディングエージェントをしばらく使っている人なら -- そして多くの人がまさにこのことについて投稿しています -- おそらくその感覚は掴んでいるでしょう:それらは時間とともに状況を悪化させ、コードベースを扱いにくくする傾向があります。

では、なぜこれが起こるのかを理解するために、最初の偉大なコーディングエージェントまでズームアウトしてみましょう。

Claude Codeはハーネス内の強化学習によって勝利した

Claude Codeは、わずか1年足らずでゼロから約40億ドル -- 現在は約90億ドル -- の収益を上げました。

[画像: Claude Codeの実行レート]

これは少し驚くべきことです。なぜなら、すでに優れたCLIエージェントが存在していたからです。aider、cline、codebuff -- これらはすべてClaude Codeより前に存在し、すべて実際に優れたコンテキストエンジニアリングが組み込まれており、Claude Codeに帰属する可能性のある同じツールセットを持っていました:読み込み、書き込み、編集、grep、bash。私はそれらを使用しました。それらは良かった。しかし、ツール使用は時々うまくいかなくなりました -- それが同じ編集を3回試みて失敗するのを見て、自分でエディタを開き直すことになります。

2024年のSWE-Agent論文は、ツールの形状の小さな変更が顕著な違いを生むことを概説しています。例えば、ReadFileの結果にファイル番号を含めたり、Editツールを検索/置換から行範囲編集に変更したりします。

[画像: SWE-Agentツールの形状比較:編集ツールなし vs リントなしの編集 vs リントありの編集 -- ツールの形状の小さな変更がエージェントの動作に大きな違いを生む]

そしてClaude Codeがリリースされ、急速に垂直方向に伸びました。これを配布として片付けることもできますが、一般的に受け入れられている説明は、Claude Codeが優れていたために勝利したということであり、Anthropicがモデルをハーネス内でRLしたため優れていたということです -- ラボが、出荷する正確なツールに対してモデルをトレーニングしたのはこれが初めてでした。そして、エージェントループでそれらのツールを呼び出すのが非常に、非常に上手になりました。

ツールの定義と評価を、モデルが最も好む形状が見つかるまでいじくり回すのは一つのことです -- 私は様々なユースケースでこれを試して数週間を費やしました。重みを所有し、特定のツールセットに対してモデル自体を変更できるチームには、まったく異なるゲームです。

OpenAIチームは11月に講演を行い、このことをかなりうまく表現しました:ハーネスを構築しても重みを所有せず、その中でモデルをRLできない場合、両方を所有するチームに対して常に不利になります。

コーディングエージェントRLを60秒で

このトピックについて多くの調査を行い、説明するための多くのビジュアライゼーションを作成しましたが、Calvin French-Owen氏(CodexチームのMTS、Segmentの創設者)がAI Councilでの講演で、はるかにうまく、よりクリーンに説明していることに気づきました。そのため、彼のスライドに触発されたこのアニメーションをここに掲載します。

rl-traces.mp4[動画]

モデルをコーディングにうまくするには、以下を行います。

  1. 問題(例:テストを修正する)を解決するためのコーディングエージェントのトレースを生成します。
  2. いくつかの基準(検証者)に基づいてトレースをスコアリングします。
  3. 良いトレースをより可能性が高く、悪いトレースをより可能性が低くなるようにモデルの重みを更新します。

そして、これを数週間または数ヶ月にわたって何百万回も繰り返します。

しかし、これらのことの「スコアリング」部分は、しばしば気まぐれに一次元的になりがちです。

悪い設計に対するペナルティがない

SWE-bench Multilingualを見てみましょう。タスクは小さく -- 15分程度の作業 -- Redis、jq、Djangoなどのオープンソースリポジトリからスクレイピングされています。報酬は、以下の基準に基づいて1または0です。

  • FAIL_TO_PASS - 修正を依頼されたものを修正しましたか?
  • PASS_TO_PASS - 他のものを壊さずにそれを実行しましたか?

これは実際の例です、fastlane__fastlane-19304、fastlane -- Rubyプロジェクトです。そのzipアクションは2つのオプションパラメータを取得し、すぐに.empty?を呼び出すため、includeとexcludeを省略した瞬間に、それは失敗します。

'zip_command': undefined method 'empty?' for nil:NilClass

この特定の問題をクローズした人間の修正は2行です(デフォルトのnilを空の配列に設定):

# fastlane/lib/fastlane/actions/zip.rb
-      @include = params[:include]
-      @exclude = params[:exclude]
+      @include = params[:include] || []
+      @exclude = params[:exclude] || []

評価中、モデルは

  1. ベースコミットから開始します -- その修正が適用される直前のリポジトリの状態です。
  2. バグレポート -- この場合は'zip_command': undefined method 'empty?' for nil:NilClass

エージェントはコードを書き始めます。ゴールデンパッチやグレーダーとして機能するテストパッチを見ることはありません。

# fastlane/spec/actions_specs/zip_spec.rb
+  it "sets default values for optional include and exclude parameters" do
+    params = { path: "Test.app" }
+    action = Fastlane::Actions::ZipAction::Runner.new(params)
+    expect(action.include).to eq([])
+    expect(action.exclude).to eq([])
+  end

次に:

  1. 生成されたパッチを保持し、次に
  2. テストファイルに加えられた変更をすべて破棄します(モデルが静かに失敗テストをコメントアウトしたり、テストを無効にするモックを挿入したりするのを検出しました)。
  3. ベンチマークのテストパッチをその上に適用し、
  4. すべてのスイートを実行します:既存のzipテスト(PASS_TO_PASS)と新しいテスト(FAIL_TO_PASS)の両方がパスするかどうかを確認します。

[画像: SWE-bench Multilingualタスクの採点方法、実際のfastlane行で:エージェントはバグレポートとコードベースを取得し、パッチを書き、サンドボックス内でベンチマークのテストパッチが適用され実行される -- パス → 1、それ以外は0]

余談 - ベンチマークは検証者ではありません -- 実際、それらは互いに分離されなければなりません(テストでトレーニングしない、など) -- 主に「コーディングエージェントのトレースの品質を判断する」という形状とその限界を伝えるためにこれを意味します。

モデルが正しい答えにたどり着いた方法は関係ありません。テストがパスすれば、私たちは勝ちですが、コードベースの保守性を損なうことに対するペナルティはありません。

コードベースの保守性を損なうことに対するペナルティはありません

それが、すべてをtry-catchで囲む理由です。

[画像: JSONパースの周りのtry-catch]

そして、型システムを持つこと自体の利点をすべて損なうような、怠惰な型キャスト。

[画像: 怠惰な型キャスト]

品質検証は「テストがパスしたか」よりも桁違いに難しい

テストを実行すると、約数秒でクリーンなパスまたはフェイルが得られます。だからこそ、RLは各モデル生成を最適化するために何百万ものループを実行できるのです。

しかし、悪いアーキテクチャのコスト関数は、数週間、数ヶ月、あるいは数年で測定されます。それは、誰かがそのファイルを一行の変更のために開いたときに、一行ではできないと気づいたときに起こります -- 誰かがこれを少しやりすぎた(vibed too hard)ので、11箇所で同じ変更をしなければならず、3つのファイルオーバーで何も静かに壊れないことを願うことになります。

[画像: 悪い決定はランダムなゴミにつながり、数週間または数ヶ月後にバグ/インシデントにつながる -- そして、インシデントを原因となった決定にバックプロパゲートする方法はない]

テストは数秒でフィードバックを提供しますが、悪いアーキテクチャのコスト関数は数週間、数ヶ月、あるいは数年で測定されます。

[画像: ソフトウェアは進行中に問題を検出しますが、現代のほとんどのベンチマークでさえ、問題全体を事前に開示します -- 「変更/調整が容易か」を最適化する理由はありません]

悪い設計は、今日のベンチマークが評価できない唯一のものです。そして、わかっています、わかっています、RL != ベンチマークですが、これがRLで解決されていたなら、ベンチマークのデザインにも現れ始めるはずです。

いずれにせよ、私は個人的に、モデルが突然コードベースをスロップアップするのに長けているという兆候として、今日のベンチマークの改善を信頼していません。

フロンティアはゆっくりと改善している

もちろん、多くの賢い人々がこれに取り組んでいます。私のポイントは、それが不可能だということではなく、誇大広告が規律を追い越しているということです。

正しい方向に向かっていると思ういくつかの取り組みがあります。

  • SWE-Marathon (Abundant AI):約400時間のタスク、「Excelの全機能クローン」など -- 単一のパス/フェイルビットではなく、複合報酬チャネル付き。
  • DeepSWE (Datacurve):現実世界で実際に構築されなかったOSSリポジトリ上の大きなタスク。そのため、構築上、トレーニングセットにすでに含まれていることはありません(汚染は解決しますが、品質は解決しません)。
  • Frontier Code (Cognition):マルチPRタスク、そして決定論的に品質を評価する巧妙な動き -- モデルがパッチ適用前のコードで失敗しないテストを書いた場合にペナルティを与えます(ミューテーションテストについて聞いたことがなければ、楽しい乗り物になるでしょう5)。また、コード品質ルールをチェックする差分に対してジャッジモデルを実行します。

[画像: Frontier Code: 人間が問題履歴を問題 + そのSHAでのコードベース、ゴールデンソリューション、コード品質ルールにキュレーションする -- エージェントのコードは、検証者、回帰テスト、ジャッジモデル、および新しいテストがパッチ適用前のコードで失敗するかどうかによってスコアリングされる]

しかし、品質を判断するモデルは、ある程度までしか機能しません。

実際、モデルが信頼性高く良いコードと悪いコードを区別できるなら、最初から良いバージョンを書いたかもしれないと想像するのは難しくありません。RLには高速で信頼性の高いオラクルが必要ですが、保守性についてはまだ持っていません。

モデルが信頼性高く良いコードと悪いコードを区別できるなら、最初から良いバージョンを書いたかもしれないが、保守性には高速なオラクルがないため、RL中にそれを報酬として与えることはできない。

もちろん、より多くのレビューエージェントとより多くのトークンは役立ちます -- それらはフロアを上げ、愚かなものをキャッチします。

しかし、それらは天井を動かしません。なぜなら、天井は私たちがモデルにRLで教え込めたものだからであり、良い設計はまだ教え方がわからないものだからです。

だから、私はまだこれらのどれにも私のコードベースを賭けません。しかし、それらは私がこれまで見た中で、パス/フェイルで止まるのではなく、保守性をスコアリングしようとさえしている最初の評価です。

余談 将来のモデルがこれを理解し、私たちがやめることができるかもしれません。GPT-7が出荷されるまでプロンプトをヨーロして見つけたいなら、どうぞ -- しかし、苦い教訓はさておき、私たちは今解決すべき問題を持っており、それをどのように行うかを説明します。

ライトを再び点ける

今のところ、ジャッジはあなたです -- だから、コードレビューを元に戻します。

[画像: lights-on-agentic-1]

私たちは、AI以前から行ってきたのと同じことを受け入れます。つまり、長い、困難なレビューの可能性を減らすために、事前に少し計画を立てることです。

私たちはレバレッジを見つけ、AIを活用してこれを4つのフェーズで行います。

  • 製品要件
  • システムアーキテクチャ
  • プログラム設計
  • 垂直スライス
製品レビュー

すべては製品レビューから始まります:何を構築し、なぜ構築するのかを明確にする短いドキュメントです。目標は、2つの文または長いボイスメモのつぶやきを、半構造化されたものに変えられるようにすることです。

まず、解決すべき問題 -- 実際のユーザーの苦痛を、ユーザーの言葉で -- に合意します。次に、成功がどのように見えるか -- デプロイ後に、そのものが構築する価値があったと判断するために何を読むことができるか。理想的には、「XYZワークフローをより短い時間で実行できる」や「オンボーディングマイルストーンABCをより早く達成する」といったユーザーのアウトカムです。時には、エラー率やレイテンシーの数値のような低レベルなもの、時には単に「Xに関するサポートチケットが止まる」といったこともあります。

私たちはこれを製品領域にしっかりと根ざすように努め、技術的な詳細には踏み込みません。製品の世界と技術の世界に片足を置いている者として、私はしばしばここで技術的な詳細に迷い込みます。そうなったときは、後でフェーズのために書き留めておき、ユーザーが実際に体験することに戻るようにしています。技術的な決定が製品の決定を妨げている場合は、持っているものをコミットし、アーキテクチャに入るか、実現可能性に関するプロトタイプリサーチをさらに行います。

そして、これのほとんどはユーザーが見るものに関するものなので、私はそれを説明しません -- それをモックアップします。実際の画面のラフなHTMLモックアップは、3段落では長引くだけの議論を解決します。

現在進行中の実際の例です -- ドキュメントはJSONアウトラインで機能をピン留めし、次に実際の画面の2つのラフなHTMLモックアップ(クリックしてズームイン):

もちろん、すべてが製品レビューを受けるわけではありません。コピーの微調整、単発のスクリプト、再現が明らかなバグ -- これらはすべて、依然としてエージェントに直接送信します。これは、エージェントが私たちの意図を誤解することが高価になる変更のためのものです。

このシリーズのすべてのドキュメントと同様に、私たちは著者オプトインレビューを行います。レビュー時間を節約したい場合は、PRをレビューする人を選び、コーディング部分に入る前に、製品/技術仕様をその人と一緒に確認します。非同期でドキュメントコメント(私たちはこのためにhumanlayerをドッグフードしていますが、github/notion/plannotator/etcでも同様に簡単にできます)で行います。

システムアーキテクチャ

製品レビューが確定したら、システムアーキテクチャを行います。これは特に新しいものではなく、バイブコーダーでさえ信奉し始めているものです。

レビュー時間を節約したい場合は、PRをレビューする人を選び、コーディング部分に入る前に製品/技術仕様をその人と一緒に確認します。

このフェーズでは、プログラム設計の詳細に入ることなく、サービス、エンドポイント、スキーマ、キュー、ストアが互いにどのように通信するかを合意します。人間<>エージェントの通信帯域幅を最大化するために、ここでは視覚化を多用します -- 例えばシーケンス図です。

sequenceDiagram
  participant UI
  participant API
  participant ResourceService
  participant Store
  UI->>API: PUT /resources/:slug
  API->>ResourceService: create(input)
  ResourceService->>Store: insert resource
  ResourceService-->>UI: 201 resource

ロード中

契約/エンドポイントの形状:

PUT /api/resources/:slug
  request:  { destination: string }
  response: { resource: Resource }

データモデルと変換:

-- new tables
CREATE TABLE resource (
  slug         TEXT PRIMARY KEY,
  destination  TEXT NOT NULL,
  created_at   TIMESTAMPTZ NOT NULL DEFAULT now()
);

-- new query shapes
-- SELECT ... FROM ...

Mermaidはここでは問題ありませんが、時には過剰であり、合意しているという誤った感覚に陥らせることがあります。アーキテクチャは比較的レバレッジが高く、このフェーズで回避できる潜在的に悪いモデルの癖がたくさんあります。しかし、高品質なコードを生成するには不十分です。そのためにはプログラム設計が必要です。

プログラム設計

アーキテクチャの後、私はエージェントコーディングにおいて、ひどく軽視されていると思うこのことを行います:プログラム設計。

ほとんどの人は、アーキテクチャが正しければ、モデルは調理できると想定しています。あなたはそうすることができますが、返ってきた結果を気に入らないかもしれません。

しかし、うまく機能していると私が目にするのは、誰か(人間またはエージェント)が実装を書く前に、アーキテクチャから一段階下のコードの形状 -- 型、メソッドシグネチャ、プログラムレイアウト、およびコールスタック -- に入ることです。

私たちのプログラム設計スキルの最初のバージョンはひどいものでした。読みにくく、疲れるものでした。Mermaidを試しましたが、それはその場がありますが、私たちが本当に愛しているのは、擬似コードでの軽い視覚化です。

コールスタックツリー、あらゆるオーケストレーションまたは制御フローの変更に対して。興味深い部分が変化していることである場合は、差分構文を使用します。

 entrypoint
   runCommand
+    handleCreateResource
+      ResourceClient.create(input)
+        POST /resources
+      renderResult
-    legacyCreateFlow

Dillon Mulroy氏は、計画プロセスの一部としてコールグラフを使用することについて話しており、それはまさに正しいと思います。

[画像: Dillon Mulroy氏、計画でのコールグラフの使用について]

ファイルツリーの差分 -- コードベースのレイアウトとファイルがどこにあるかを把握できるようにします。

 src
 └── resource
+    ├── resource-client.ts      # NEW - API契約呼び出しをラップ
+    ├── resource-client.test.ts # NEW - リクエスト/レスポンスマッピングをカバー
~    └── resource-route.ts       # MODIFIED - UIに作成アクションを配線

主要な新しい関数の型とメソッドシグネチャ -- アーキテクチャドキュメントには内部的すぎるが、モデルがまだ間違える可能性のあるもの。

interface Item {
  id: ItemId
  parentId: ItemId | null
  // ...
}

interface Cursor {
  position: ItemId
  direction: 'up' | 'down'
  // ...
}

resolveTarget(items: Item[], cursor: Cursor) -> ItemId | null

これらのどれも作成に時間がかかりません(モデルがドラフトを作成し、あなたはそれと議論します)。そして、それらのそれぞれは、コードレビュー中に暗黙的に行われるであろう決定です -- あなたの考えを変えるのに最も高価な時間です。

垂直スライス

次に、私たちが「垂直スライス」と呼ぶものを好んで行います -- Matt Pocock氏と私は、2026年1月のライブストリームで垂直スライスまたは「トレーサー弾」についてチャットしました -- これはトレーサー弾とも呼ばれます。

モデルは、私が「水平計画」と呼ぶものを好みます -- スタック順に物事を行うことです。

  1. データベースマイグレーション
  2. サービスレイヤー
  3. API
  4. フロントエンド

horizontal-slices.mp4[動画]

実際には、これは、進行中にソリューションに「触れる」本当の方法がないことを意味します。コードでテストすることはできますが、私が構築したほとんどの機能について、テストを読むことは始まりでしたが、ブラウザで何かをプルアップしたり、作業中にcurlでヒットしたりすることは、常にワークフローの一部でした。

AI以前は、誰かが2000行以上のコード、あるいは500行以上のコードを書く前に、途中で何かを確認することは稀でした。

私が以前のAI以前のコーディングの習慣と、AI後のコーディングの習慣との違いに気づくまでには時間がかかりました。AI以前は、私は常に中央から始めて外側に向かって作業していました。大まかに言うと:

  1. API契約を作成し、モックデータをサーブし、curlでテストする。
  2. モックデータを消費するフロントエンドを作成し、ブラウザでイテレーションと洗練を行う。
  3. APIをサービスレイヤーに接続する(サービスはモックデータ/動作をサーブする)。
  4. データベースマイグレーションを追加し、サービスをデータベースに接続する。
  5. 多くのビジネスロジックを追加する。
  6. 多くのエラーハンドリングを追加する。

そして、各ステップでテスト/イテレーション/洗練を行っていました。

vertical-slices.mp4[動画]

コードを非常に気にする場合や、このコードベースの部分でのモデルの作業能力に懐疑的な場合は、各ステップでコードもレビューします。100〜200行をチェックして方向転換するのは、はるかに安価です。

ほとんどのフロンティアモデルは、人間の指示なしにはこのような計画を設計しません。また、コードベースごと、あるいはタスクごとに一般化するのが難しいため、私はここでループにとどまることを好みます。私を信じてください。もし私がここで思考をアウトソースできれば、そうするでしょう。

計画の30分がレビューの数時間を節約する

したがって、人間が関与する必要があるステップがいくつかあります。もし、後で片付けるための大量のゴミコードに悩まされることなく、人間レベルに近い品質を維持したいなら(つまり、本当に速く進みたいなら)。

  1. 製品設計
  2. システムアーキテクチャ
  3. プログラム設計
  4. 垂直スライス

明らかに、出荷するすべてのものにこのプロセス全体を行うわけではありません(AIコーディングレバレッジにおける80/20ルールを参照)。分布はおおよそ次のようになると推測します。

  • 約40%のタスクはワンショット、または1〜2回の軽いフィードバックでワンショットされます。
  • 中規模のタスクでは、製品/システム設計をすべて1つの計画ドキュメントで行い、作業をフェーズに分割することはしません。
  • 大規模なものについては、すべてのステップを行います。製品部分は、大きなリファクタリングなど、意味をなさない場合はスキップします。

そしてほとんどの場合、私はモデルに一度に1〜3スライスを実行させ、レビューしながら進めます。内部的なものか実際の機能的なものかに関わらず、2000行以上のコードの反対側にいるときに何が壊れているのかわからないよりも、早期に方向転換する方がはるかに簡単です。

おそらくプルリクエストが多すぎると感じている

PRが多すぎるのではありません。悪いPRが多すぎるのです。

AI以前から、私たちは多くの手直しが必要なPRをレビューしてきました。

しかし、素晴らしいPRはレビューするのが楽しいものです。すべてのファイルをスクロールし、コードはクリーンで、あなたの決定/議論/ソフトウェアのあるべき姿についての苦労して得た意見にすべて従っています。

一方、プルリクエストが20%の手直しを必要とする場合(これは寛大で、ほとんどのAIワンショットPRは50%に近い傾向があると思います)、それは提出者とレビューアの両方にとって、知的負担であり感情的負担です。(提出者がAIであっても、誰かがこの作業を開始したか、AIの結果をバイブで洗練したか、少なくとも結果を気にしている可能性があります。)

時間を節約するために(ほぼ終わりに近づいています)、この件についてサイドクエストでさらに長々と話しました:[