ソフトウェア工場が失敗する理由：開発の現場に光を取り戻す

これは『ソフトウェア工場が失敗する理由』のパート2です。

この記事のトーク版は YouTube で公開されています：https://www.youtube.com/watch?v=Ib5GBkD555M

再び明かりを灯す

パート1では、なぜモデルが長期的にコードベースの品質を維持するために信頼できないのか、深く掘り下げました。なぜハーネスエンジニアリングやトークンマキシングをいくらやっても、モデルトレーニングとベンチマークの問題は解決できないのか。なぜコード品質の「モデル審査員」方式が、一部の人々が言うほど効果的ではないのか。

今のところ、審査員はあなた自身です。なので、コードレビューを復活させましょう。

私たちは、AI 以前からずっとやってきたこと、つまり、事前に少し計画を立てることで、長くて困難なレビューになる可能性を減らす、というアプローチを再び採用します。

てこ（レバレッジ）を見つけ、AI を活用して、それを以下の4つのフェーズで支援します。

• プロダクト要件
• システムアーキテクチャ
• プログラム設計
• 垂直スライス

プロダクトレビュー

すべてはプロダクトレビューから始まります。それは、何を 構築するのか、そしてなぜ 構築するのかを確定する短いドキュメントです。目標は、2つの文章や長いボイスメモの内容を、半構造化されたものに変換できるようにすることです。

まず、解決すべき問題 に合意します。ユーザーの言葉で表現された、実際のユーザーのペインです。次に、成功の姿 を定義します。出荷後に何を確認すれば、その成果物が構築する価値があったと判断できるか、です。理想的には、「XYZ ワークフローをより短時間で実行できるようになる」や「オンボーディングのマイルストーン ABC に早期に到達する」といったユーザーアウトカムです。時には、エラーレートやレイテンシー数値のような低レベルのものや、単に「X に関するサポートチケットがなくなる」といった場合もあります。

ここでは、プロダクト領域にかなり根ざした内容に留め、技術的な話には深入りしないようにします。プロダクトと技術の両方の世界に足を踏み入れている者として、私はよくここで技術的な詳細に流れてしまいがちです。そうなった場合は、とりあえず後続のフェーズ用にメモしておき、ユーザーが実際に体験することに話を戻すようにしています。技術的な判断がプロダクトの判断を妨げている場合は、今あるものを確定し、アーキテクチャに進むか、実現可能性についてのプロトタイプ調査をさらに行います。

そして、これはほとんどがユーザーが見るものに関するものなので、私は説明する代わりにモックアップを作成します。実際の画面のざっくりとした HTML モックアップがあれば、3段落の説明で長引くような議論も解決できます。

進行中の実際の例です。このドキュメントは、JSON のアウトラインで機能を定義し、次に実際の画面の2つのざっくりとした HTML モックアップを示しています。

https://x.com/dexhorthy/status/2078592010852982977

もちろん、すべてにプロダクトレビューが必要なわけではありません。コピーの微調整、使い捨てスクリプト、明らかな再現手順があるバグなどは、今でもそのままエージェントにワンショットで渡します。プロダクトレビューは、エージェントが私たちの意図を誤解するとコストがかかるような変更に対して行います。

このシリーズのすべてのドキュメントと同様に、私たちは著者オプトインのレビューを採用しています。レビューの時間を節約したい場合は、PR をレビューする人を選び、プロダクト/技術仕様を一緒に確認します。非同期でドキュメントコメントを使って行うか（私たちはこのために HumanLayer をドッグフーディングしていますが、Github/Notion/Plannotator などでも同様に簡単にできます）、直接話し合っても構いません。

システムアーキテクチャ

プロダクトレビューが確定したら、システムアーキテクチャに進みます。これは特に目新しいものではなく、バイブコーダーでさえも重要性を認識し始めているものです。

レビューの時間を節約したいなら、コードを書き始める前に、PR をレビューする人を選び、プロダクト/技術仕様を一緒に確認しましょう。

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

コントラクト / エンドポイントの形状：

データモデルと変換：

Mermaid もここでは有効ですが、やりすぎになることもあり、また、合意できているという誤った安心感を与える可能性もあります。アーキテクチャはかなりレバレッジが高く、このフェーズで多くの潜在的に悪いモデルの癖を事前に防ぐことができます。しかし、高品質なコードを生成するには不十分です。そのためには、プログラム設計 が必要です。

プログラム設計

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

ほとんどの人は、アーキテクチャが正しければ、モデルがうまくやってくれると考えています。実際にそうしてみても構いませんが、おそらく気に入らない結果が返ってくるでしょう。

しかし、私が効果的だと感じているのは、誰か（人間であれエージェントであれ）が実装を書き始める前に、アーキテクチャから一段階下りて、コードの形状、つまり、型、メソッドシグネチャ、プログラムのレイアウト、コールスタックを定義することです。

私たちのプログラム設計スキルの最初のバージョンはひどいものでした。読みにくく、疲れるものでした。Mermaid も試しましたが、それはそれで役割はあります。しかし、私たちが実際に気に入っているのは、擬似コードによる軽量な視覚化です。

コールスタックツリー：オーケストレーションや制御フローの変更がある場合に使用します。変更点が重要な部分である場合は、差分構文を使用します。

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

ファイルツリー差分：コードベースのレイアウトと、どこに何があるかを把握し続けるために使用します。

主要な新しい関数の型とメソッドシグネチャ：アーキテクチャドキュメントに記載するには内部的なものすぎるが、エージェントが間違える可能性があるもの。

これらはどれも作成に時間はかかりません（モデルがドラフトを作成し、あなたがそれと議論します）。そして、これらのそれぞれは、そうでなければコードレビュー中に暗黙のうちに行っている判断であり、考えを変えるのに最もコストがかかるタイミングでの判断なのです。

垂直スライス

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

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

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

実際には、これは、作業を進めながらソリューションを「触って」確認する本当の方法がないことを意味します。コードでテストすることはできますが、私がこれまでに構築したほとんどすべての機能において、テストを読むことは出発点ではあっても、ブラウザで何かを表示したり、作業中に curl で叩いたりすることは、常に頻繁に行うワークフローの一部でした。

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

私が慣れていたものとの違いに気づくまでに時間がかかりました。AI 以前にコードを書いていたときは、いつも真ん中から始めて外側に向かって作業していました。大まかには：

1. API コントラクトを作成し、モックデータを提供し、curl でテストする
2. モックデータを消費するフロントエンドを作成し、ブラウザで反復・洗練する
3. API をサービス層に接続する（サービスはモックデータ/動作を提供する）
4. データベースマイグレーションを追加し、サービスをデータベースに接続する
5. ビジネスロジックを大量に追加する
6. エラーハンドリングを大量に追加する

そして、各ステップでテスト、反復、洗練を行っていました。

コードに強いこだわりがある場合や、コードベースのこの部分でモデルが良い仕事をする能力に懐疑的な場合は、各ステップでコードもレビューします。100〜200行をチェックして方向修正する方がはるかに安上がりです。

ここで、私はそうするでしょう。ほとんどのフロンティアモデルは、人間の誘導なしにはこのような計画を設計しません。また、コードベースやタスクごとに一般化するのは難しいため、私はここでループ内に留まることを好みます。信じてください。もし考えることを外部委託できたなら

30分の計画で、何時間ものレビューを節約できる

そこで、もしあなたが、後から山のような質の低いコードを片付けるのに苦労することなく、人間に近いレベルの品質を維持したいのであれば（つまり、本当に高速に進みたいのであれば）、人間がループ内にいる必要があると私が主張するいくつかのステップがあります。

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

もちろん、出荷するすべてのものに対してこの全プロセスを実行するわけではありません（以下のサイドクエストを参照）。おおよその分布は次のようになると思います。

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

そして、ほとんどの場合、モデルに1〜3スライスずつ送信し、コードを逐次レビューします。内部の実装であれ、実際の機能であれ、後で2000行以上のコードを前に何が壊れているかわからないという状況に陥るよりも、早い段階で方向修正する方がはるかに簡単です。

プルリクエストが多すぎると感じるかもしれません

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

私たちは皆、AI が登場するずっと前から、手直しが必要な PR をたくさんレビューしてきました。

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

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

時間を節約するために（もうすぐ終わりです）、これについてサイドクエストでさらに詳しく述べました。

「時間はどこへ行くのか」

制約理論（2026年版）

ここでの核となる主張に少しがっかりするのは簡単です。「今のところ、私たちはコードを読むことに縛られている」。

私は、物事を依頼するだけで、モデルに任せて、コードを読まずに、時間とともに進化し、劣化しない美しいプロダクションソフトウェアを手に入れられる世界をとても楽しみにしていました。

しかし、ここで私が最善を尽くして示したのは、制約に過ぎません。モデルは得意なこともあれば、そうでないこともあります。それらの制約を考慮して、どのようにプロセスを最適化するか？

モデルは得意なこともあれば、そうでないこともあります。それらの制約を考慮して、どのようにプロセスを最適化するか？

あなたは、10〜100倍のスピードを追求するあまり、コード品質はもはや重要ではないと自分に言い聞かせようとしているかもしれません。しかし、制約を受け入れ、安全に2〜3倍のスピードで進むこともできるのです。

私の最後のアドバイスは、基本的に以下の通りです。

1. 制約をよく学び、モデルを多く使って直感を養う
2. これらの制約の範囲内でシステムを最適化する
3. レバレッジを求める
4. コードを読め

以上です。宣伝を聞きたい方は、読み進めてください。これがあなたの災害を防ぐ助けになるか、少なくとも可愛いアニメーションを楽しんでいただければ幸いです。

お読みいただきありがとうございます

-dex

追伸：私たちはこれに夢中です

私たちは humanlayer.com を構築しています。これは、人間（または人間にかなり近い）レベルのコード品質を維持しながら、2〜3倍の速度で進むことを可能にする、エージェンティック IDE およびコラボレーションプラットフォームです。

私たちは、「ソフトウェア工場のための構成要素」と「ソフトウェア保守性のためのより良い検証器」（おそらくより良いモデルも）という2つのアイデアに向けて開発を進めています。

HumanLayer は、最大3人の小規模チームには無料です。始めるためのサポートが必要な場合は、Discord に参加するか、founders@humanlayer.dev までご連絡ください。

インスピレーションを与えてくれた @calvinfo、共同創業者の @0xBlacklight、これらのアイデアを探求する場を提供してくれた @swyx と @aiDotEngineer のチーム、そして応援してくれるすべての素晴らしいお客様、投資家、友人、家族に感謝します。

もっと詳しく知りたい方は、私はこれについてほとんど話し続けているので、以下のリンクからこの投稿のすべてのリンクや、ポッドキャスト、ロングフォームホワイトボードなどへのマテリアルの他の展開を見つけることができます。

追追伸：その他のリソース

ポッドキャストと記事：

• Dex と Gergely がコンテキストエンジニアリングとソフトウェア工場について The Pragmatic Engineer で語る - 2026年7月
• Dex と Matt Pocock が不変の AI コーディングアドバイス（とラルフループ）について語る - 2026年1月

AI That Works のエピソード：

• ベンチマークは何も証明しない
• AI コーディングのためのプロダクト仕様書
• より良いバックプレッシャーのための学習テスト
• 12要素エージェントの原則を AI コーディングに適用する

この投稿からのリンク：

• ソフトウェア工場が失敗する理由 基調講演 — AI Engineer World's Fair 2026
• StrongDM の lights-off ソフトウェア工場
• OpenAI: ハーネスエンジニアリング (2026年2月)
• Ryan Lopopolo の Symphony について (トーク、2026年4月)
• AI Engineer Europe での Mario: 「スロップの世界で π を構築する」
• FT: コーディングエージェントの事故による Amazon の障害
• Matt Pocock: 崩壊するコードベース
• Faros AI: AI 加速むち打ちレポート
• コーディングエージェントのための高度なコンテキストエンジニアリング (トーク 8/25)
• バイブ禁止 (トーク 11/25)
• RPI について私たちが間違っていたすべてのこと (トーク 3/26)
• Awesome-RLVR - 強化学習リソース
• コーディングエージェントのための高度なコンテキストエンジニアリング (文書)
• 12要素エージェント
• Addy Osmani のバイブコーディング vs メンテナンスについて
• NATO ソフトウェアエンジニアリング会議、1968年
• DoD DevSecOps リファレンスデザイン (PDF)
• Ramp のコーディングエージェントプラットフォーム
• Stripe: Minions、ワンショットエンドツーエンドコーディングエージェント
• WorkOS: Project Horizon
• Brex (Latent Space)
• Dan Shapiro: ソフトウェア工場への5つのレベル
• Simon Willison の StrongDM のソフトウェア工場について
• 「海を沸騰させる」
• ショットガン手術 (refactoring.guru)
• John Ousterhout — ソフトウェア設計の哲学
• Robert C. Martin — クリーンコード
• Martin Fowler — リファクタリング
• aider
• cline
• codebuff
• SWE-Agent 論文 (2024)
• OpenAI Codex トーク (11月)
• Calvin French-Owen — AI Council トーク
• SWE-bench Multilingual (データセット)
• AIE Worlds Fair 2026 - グレートループス討論（「誇大広告が規律を追い越している」）
• SWE-Marathon (Abundant AI)
• DeepSWE (Datacurve)
• Frontier Code (Cognition)
• ミューテーションテスト (Wikipedia)
• Dillon Mulroy の計画におけるコールグラフについて
• Dex × Matt Pocock: 垂直スライス / トレーサー弾 (ライブストリーム、2026年1月)
• 「考えるというハードワークは外部委託できない」(Jake Nations)