はじめに：なぜHarness Engineeringが必要なのか
なぜあなたにHarness Engineeringが必要なのか：Vibe Codingの甘い罠
この本を手に取ったあなたは、すでにVibe Codingの経験をお持ちのはずです。Vibe Codingは糖衣砲弾です。最初の体験は非常に良好で、Claude Codeに要件を伝えると、数分後に大量のコードが生成され、アプリケーションが起動します。さらに短い議論を重ねれば、次の要件も完了し、これまで数週間かかっていた作業がひと午後で片付きます。しかし短い蜜月期の後、問題が表面化し始めます。コードベースが大きくなるにつれ、Agentに既存コード上の一機能を修正させると、別の機能が壊れます。一通り修正すると、また新たなバグが湧き出ます。何十ラウンドもやり取りしてもバグが頑固に残り、腹を立ててソースコードを開くと、プロジェクト全体がすでに保守不能なコードの山になっています。ハードコードされたパス、大量の不要コード、同一関数に5つも6つも異なる実装があり、複数のモジュールから交差的に依存されている。整理・修正するコストは最初から作り直すより高い状態です。
過去二年間でモデルの能力は大きく飛躍しました。GPT-4、Sonnet 3.5、Opus 4.6と世代を重ね、それぞれ確実に強くなっています。より大きなcontext window、より優れた指令遵守、より高い知能。そしてあなた自身もpromptやcontextの技術を学び、より的確なコンテキストを提供できるようになりました。しかし同じ崩壊パターンが、より大きなスケールで繰り返し再現されます。プロジェクトがもう少し大きくなる、イテレーションがもう数回増える、すると Agent は以前に取り決めた規約を忘れ、修正すべきでないコードを変更し、産出物が期待から乖離し始め、最終的に保守不能になります。
大多数の開発者のAgent利用体験もこれと同じです。体感ではAIが百倍の速度でコードを生産していますが、総合的な生産性向上はそれほどでもないように感じます。しかし別の面では、少数の人々がまったく異なる成果を出しています。PingCAPのCTO黄東旭はAIを使ってTiDBのPostgreSQL互換レイヤーをRustで完全に書き直しました。Pigsty創設者の冯若航は一人でAIを活用し、460以上の拡張を統合したエンタープライズグレードのPostgreSQLディストリビューションを保守しており、日常的に十のAgentを同時に並行稼働させています。彼らの生産性向上は数十倍単位であり、プロダクションレベルの安定性を持つコードを産出しています。
同じモデル、同じツールで、数十倍の差がつく。差はエンジニアリング制度にあります。これはAIが複雑な大規模プロジェクトを処理できないということではなく、モデル能力やprompt技術の改善では根本的に問題が解決しないということです。Agentプログラミングは人間のプログラミングとはまったく異なる生産力であり、Agent固有の構造的特性があります。Agentを大規模に活用できているチームはすべて、Agentの構造的特性に対応した closed-loop control 体系を構築し、体系的な方法でAgent開発時の不確実性を制御しています。この体系的な方法を、私たちはHarness Engineering（約束工学）と呼んでいます。
AIの不確実性を制御するには、まずAIの不確実性の源泉を理解する必要があります。本書では、Agent開発における不確実性の構造的な源泉を体系的に分析します。そしてHarness Engineeringが各特性に対して、ソフトウェア開発の各段階でどのように体系的な制限と検査を行い、Agentが安定して高品質なプロダクション対応コードを納品できるようにするかを解説します。本書で紹介するすべての方法論はAgentsZoneコミュニティメンバーの実体験に基づき、大規模な実践と議論の中で有効性が証明されたものです。本書を読み終えた後、あなたはHarness Engineeringの基本原則を深く理解し、Agentソフトウェア開発が制御不能になる根本原因を正確に特定し、次々と登場するAgent管理フレームワークが真の問題を解決しているかどうかを判断できるようになります。同時に、具体的で実行可能な実践方法論を得て、真の生産性飛躍を実現できるでしょう。
Agentの構造的特性
Agentがもたらす不確実性を制御する方法を学ぶには、まずAgentの基本的な行動特性を理解する必要があります。Agentの基本能力は大規模言語モデル（Large Language Model/LLM）に由来します。LLMは入力内容に基づいて思考・判断し、ツールを呼び出してタスクを遂行します。Agentオーケストレーションフレームワークは上位層でLLMに外部世界との対話能力を提供します。Agentは指令を受け取り、次のアクションを推論し、ツールを呼び出し（ファイル読み取り、コマンド実行、API呼び出し）、ツールの返却結果を観察し、再び推論し、再びアクションを取ります。このサイクルはタスクが完了するまで続きます。
この小節では、AIを実行者とした場合の五つの構造的特性を紹介します。これらの特性はいずれもアーキテクチャに基づく内在的属性であり、モデル能力の向上によって消えるものではありません。Harness Engineeringの設計に礎石を提供します。
有限な処理容量
Agentの第一の特性は、ワーキングメモリにハード上限があり、実効容量は公称値をはるかに下回るということです。情報は多ければ多いほど良いという直感は誤りです。
Agentのワーキングメモリの全体がcontext windowです。あなたの指示、コードファイル、対話履歴、ツールの返却結果、すべての情報が一つのtokenシーケンスに連結されてモデルに送られます。このシーケンスには長さの上限があり、現在の主要モデルでは128Kから1M tokensの範囲で、一見すると大きく見えます。しかし公称容量と実効容量は別物です。LLMの基本原理に馴染みがない方のために、ここで重要な背景知識を補足します。現在のLLMはすべてTransformerと呼ばれるアーキテクチャに基づいており、このアーキテクチャの核心は「注意力（attention）」と呼ばれるメカニズムです。コンテンツを生成する際、LLMはプロンプトの全内容を本当に「読む」のではなく、モデル内部のアルゴリズムに基づいて入力の各tokenに「注意力」を計算します。「注意力」が高い内容はモデルの生成時に重点的に考慮されます。「注意力」のcontext上での配分は均等ではなく、研究によれば初期のLLMは先頭と末尾の情報への注意度が高く、中間部分の想起率は著しく低下します。もう一つの側面として、contextに含まれる情報が増えるほど各情報に割り当てられるattention重みは少なくなり、非常に重要な情報が内容が多すぎるために十分な「注意力」を得られず、ノイズの中に埋もれてしまう可能性があります。公称1M tokensのcontext windowでも、実効的に活用できる部分は半分以下かもしれません。
この制約が特に顕著に現れるシナリオが二つあります。
一つ目は大規模タスクです。小さなタスクは数ファイル、一つの機能に関わるだけで、関連情報がすべて実効的な注意範囲内に収まるため、Agentはよい結果を出します。大規模タスクではデータベーススキーマ、API契約、フロントエンドの状態管理、権限モデルを同時に考慮する必要があり、関連情報の総量が実効容量を超え、Agentはあちらを立てればこちらが立たない状態に陥ります。人間のプログラマーはシステム全体の永続的なメンタルモデルを持ち、局所のコードを扱いながらグローバルな一貫性を維持できます。Agentは毎回、限られたウィンドウの中でゼロから理解を構築し、収まりきらない部分は無視されます。
二つ目は長い推論チェーンです。Agentic Loopの各ステップがcontextに内容を追加するため、ウィンドウ内の情報は増え続けます。第5ステップで行ったインターフェース設計の判断は、第50ステップの時点では大量の対話記録やツール呼び出し結果の中に埋もれ、割り当てられるattention重みは非常に低くなっています。Agentが前半で宣言した重要な制約や情報は、後半で無声のうちに無視されます。
Harness Engineeringは体系的なコンテキスト制御メカニズムを提供し、適切な、タスクに関連するコンテキストのみが実行中のAIに注入されることを保証する必要があります。
忠実な実行
Agentの第二の特性は、与えられた入力を忠実に実行することです。訓練を通じてAIは非常に強い指令遵守能力を獲得し、指令に基づいて合理的な結果を出力します。これは両刃の剣です。入力が明確で完全であれば、AIは高品質な結果を産出します。しかし曖昧な点があれば、AIは常識に基づいて自身が合理的と考える情報で補完します。
人間のプログラマーが同じ曖昧な要件に直面した場合、同僚に尋ねたり、既存コードで類似機能がどう実装されているか確認したり、ミーティングで得た情報から推論したりします。Agentはこれらの補完ステップをすべてスキップし、曖昧な入力から確定的な出力を直接生成します。人間のプログラマーはcode review、スタンドアップ、日常の協業を通じて暗黙知を徐々に吸収します。しかしAgentにとっては、contextに書き込まれた知識だけが存在し、産出されるコードは明示的に提供されなかったすべての知識を機能的に正しく無視します。
Agentに「検索機能を追加して」と伝えたとき、検索対象は記事タイトルだけか全文か、結果はどの順序で並べるか、キーワードが空のときは何を表示するか。明示されなかった各ポイントについて、Agentは訓練データ中で最も確率の高い方案で埋め、忠実に実行します。
もう一つのより深刻な欠陥はコンテキストの矛盾です。提供した情報の中に互いに矛盾する内容が含まれている場合、AIは正しさを判断できません。先ほど議論したattentionメカニズムに基づき、どの情報もより多くの注意力を獲得することで生成時に勝ち残る可能性があり、制御不能な内容が生成されます。
Harness Engineeringフレームワークはプロジェクトに必要なcontextを体系的に定義し、すべての入力の完全性と正確性を検証する完備な方法を提供しなければ、AIの産出物が開発者の期待に合致することを保証できません。
記憶の蓄積がない
Agentの第三の特性は記憶の蓄積がないことです。セッションはあなたが指示を出した時点から始まり、セッション終了で閉じます。セッション中はすべての情報がcontext windowに蓄積されます。セッション終了後、contextはクリアされ、次のセッションは白紙から始まります。20分かけて教えたアーキテクチャ規約、踏んだ地雷、取り決めたインターフェース仕様。今日はすべてゼロに戻っています。100回目のセッションと1回目のセッションの出発点はまったく同じです。
人間のチームにおける知識の蓄積はまったく異なります。プログラマーはプロジェクトに長く携わるほど、プロジェクトへの理解が深まります。アーキテクチャ判断の歴史的経緯、各モジュールの脆弱な箇所、特定のビジネスシナリオにおける処理慣行。これらの知識の大部分はドキュメントに書かれたことがなく、チームメンバーの頭の中にあり、code review、スタンドアップ、日常の協業を通じて自然に伝達・更新されています。Agentを中心とした開発には、この自然な蓄積プロセスが欠けています。
モデルの基盤能力の進展に伴い、ますます大きなcontext windowが提供され、モデルが自然にあらゆるものを「記憶」できるようになっていますが、注意力の喪失とcontext windowのハード上限は常に避けて通れない課題です。Agentフレームワークはcompactionなどの機能を提供し、既存の対話を自動的に「圧縮」してcontextのスペースを確保しますが、それでも課題は残ります。
一つの単純な解決策は知識をドキュメントとして外部化して補うことですが、ドキュメント自体にも継続的なメンテナンスが必要です。人間の頭の中の知識はプロジェクトの進化に伴い自動的に更新されます。モジュールをリファクタリングすれば、そのモジュールに対する理解も同時に更新されます。ドキュメントは自動的には更新されません。古くなった不正確なドキュメントは前後矛盾する情報をAgentに注入し、Agentのパフォーマンス崩壊を招きます。
Harness Engineeringフレームワークは体系的な記憶管理・抽出メカニズムを提供し、記憶がソフトウェアの進化とともに効果的に発展し、必要な時に最も関連性の高い情報を効果的に抽出できるようにする必要があります。
結果への無自覚
Agentの第四の特性は結果への無自覚です。忠実な実行と同様に、Agentはあなたが与えたタスク目標を最善を尽くして完遂しますが、コードの長期的な保守性、技術的負債の蓄積度合い、アーキテクチャの一貫性といった次元は最適化目標に含まれていません。人間のプログラマーは三ヶ月後に自分がこのコードを保守することを想像し、可読性のために短期的な効率を犠牲にすることがあります。Agentの各実行は独立しており、現在のタスクの完了がすべての目標です。
この特性は自己強化ループを生みます。Agentは新しいコードを生成する際、コードベースに既存のパターンを参照します。以前急ぎで残したworkaroundは、Agentから見ればプロジェクトで確立された実装パターンであり、新しいコードに忠実にコピーされます。マージされたコードは以降の生成の参照セットとなり、悪いパターンが繰り返しコピー・増幅されます。人間のチームが同規模の技術的負債を蓄積するには通常数ヶ月から一年かかりますが、Agentを中心としたチームでは数週間でその水準に達する可能性があります。システムの中にリファクタリングや品質改善を推進する内在的な力は存在しません。
Agentはすべてのタスクに同等の注意と速度で取り組みます。表示ページの文言修正と決済処理のコアロジック変更は、実行レベルではまったく同じです。人間は高リスクな操作に直面すると本能的にペースを落とし、確認ステップを増やし、同僚に一緒に見てもらいます。Agentはすべてのタスクを一律に扱います。高リスクな操作は大量の低リスク操作の中に紛れ、同じ速度で処理されます。
Harness Engineeringフレームワークは完備な検収メカニズムを提供してAIが結果問題を克服できるよう支援し、適切なタイミングでリファクタリングを促し、高リスクな変更に確認・検収メカニズムを追加する必要があります。
高スループット・ゼロ限界コスト
Agentの前四つの特性はAI固有のものですが、人間が深く関与していれば越えられない問題ではありません。すべてのPRをレビューする時間があり、新しいセッションの開始時に重要な規約を教え直す時間があり、AIが期待から乖離した実装を産出したことに気づいて修正する時間があります。しかしAIの第五の特性、高スループット・ゼロ限界コストが、Human in the Loopモデルを持続不可能にします。Agentの出力速度は人間の百倍です。さらに、容易に並列インスタンス化できます。2番目、10番目、100番目のAgentインスタンスを起動するコストはほぼゼロであり、採用、研修、コミュニケーション調整は不要です。
この特性それ自体は新しい問題の種類を生みませんが、前四つの特性の影響を一桁から二桁増幅します。真の生産性飛躍を実現しようとするなら、大規模なAI自動化は避けられません。曖昧なドキュメントを単一のAgentが実行した場合、修正が必要な偏差は二つ三つで、プログラマーには一つずつ対処する時間があります。大規模な並列シナリオでは、一時間以内にそれぞれ偏差の異なる百もの実装が産出される可能性があります。
百倍速は、出力とレビューのリズムの均衡を壊します。最後の防衛線である手動レビューが、百倍の出力の前に崩壊します。百倍の出力を百倍の速度でレビューすることは不可能です。
Harness Engineeringフレームワークの観点からは、人間が検収すべき部分と自動検収が可能な部分を明確に定義し、明確な分類を通じて人間をプロダクションコードのクリティカルパスから可能な限り離脱させ、AI納品の障害にならないようにする必要があります。
Harnessの本質
この五つの特性が共通して指し示す要求があります。開発者には、外部の、自動化された、Agentから独立したHarness Engineeringフレームワークが必要です。Agentを真に駆使し、生産性の飛躍を実現するために。先ほど挙げた特性に加えて、Harness Engineeringの設計には二つの原則を考慮する必要があります。
closed-loop controlは、毎回の実行を確実にし、自動的に前進できることを保証します。閉ループは二つのことを行います。一つ目は、規約で「何が正しいか」を明確に定義し、あなたの頭の中の意図をAgentが対照・実行できる精確な記述に変換することです。一つの規約には、意図（何をするか、なぜするか）、受入条件（何をもって正しいとするか）、制約（変更の境界はどこか、何を変えてはいけないか）が含まれます。規約があれば、Agentの出力は予測不能なランダムから、検査可能な有限集合に変わります。二つ目は、検証で「正しくできたか」を確認することです。検証はAgentから独立した自動化チェック機構であり、偏差が発生した時点で捕捉・修正し、最終納品時に人間の肉眼で発見するのではありません。規約と検証が feedback loop を構成し、偏差は即座に発見・修正されます。
持続的な改善は、ソフトウェア工学の基本原則であり、Agentが長期保守可能なプロダクションレベルのコードを産出するための必要な手段です。ソフトウェアは開発されたその瞬間から負債になり、その後の機能イテレーション、要件変更こそが保守コストの大部分を占めます。Harness Engineeringは一度の生成で開発者の期待に合致するコードを保証するだけでなく、ソフトウェアのその後の進化プロセスにおいて閉ループそのものが劣化しないことも保証する必要があります。
これら二つの原則と、先ほど議論したAgentの根本的な特性を合わせたものが、本書におけるharness engineeringの完全な定義です。Harness Engineeringはprompt engineeringのトリックでも、システムレベルで透過的に提供できる監視機能でもなく、Agentの構造的特性に対応して設計された完全なエンジニアリング体系です。
本書の方法論を適用することで、私たちの第一線での実践経験と理論構築を一つ一つ共有していきます。Vibe Codingでは制御しきれなかったAI Agentを、真に安定した、信頼性の高い生産力デリバリーツールへと変えていきましょう。
全書ロードマップ
全書は生産性の階段に沿って展開し、各巻が一つの飛躍段階に対応します。
第一巻は信頼性を解決します。Agentの前に座って一問一答するスタイルは変わりませんが、出力は運任せからエンジニアリング的なデリバリーに変わります。規約の章では、曖昧な意図をAgentが精確に実行できる入力に変える方法を扱います。検証の章では、自動化手段で出力が意図に合致していることを証明する方法を扱います。この二章を習得すれば、単一のインタラクション層で閉ループが確立されます。
第二巻は規模を解決します。閉ループが確立されて初めて、Agentに自律的な実行を任せることが可能になります。閉ループのない自律実行はYOLO modeであり、破綻は確実です。第四章では長時間の実行におけるコンテキスト管理とクロスセッションメモリを扱い、一つのAgentが重要な情報を失わずに複雑なタスクを継続的に推進できるようにします。第五章ではマルチAgentの並列処理に拡張し、分離と統合の問題を解決します。あなたの役割はリアルタイムのオペレーターからタスクの設計者・検収者へと変わります。
第三巻は組織を解決します。個人の効率がボトルネックでなくなった後、ボトルネックはチームレベルに移行します。分業、プロセス、役割定義はすべて人間の実行速度を前提に設計されており、Agent時代のリズムに合わせて再設計する必要があります。第一巻と第二巻で確立したエンジニアリングプラクティスが組織レベルの協働の基盤インフラとなります。この基盤インフラなしには、チームレベルのAgent協働は成り立ちません。
三種類の読者がそれぞれ異なる入口から始められます。エンジニアで、自分でコードを書くスタイルからAgentにコードを書かせるスタイルへ移行中であれば、第一巻から始めて生産性の階段を順に上ってください。プロダクトマネージャーやプログラミング初学者で、すでにVibe Codingで動くプロダクトを作った経験があれば、第一巻の規約と検証がすぐに役立ちます。技術リーダーで、チームのAIトランスフォーメーションを推進中であれば、まず第三巻で組織レベルの課題を把握し、その後第一巻と第二巻に戻って組織変革を支えるエンジニアリング基盤を理解するのがよいでしょう。
Harness Engineering Playbook · AgentsZone Community