Spec・Context・Harness三層分離の背景とAIエージェント開発の構造変化

Spec・Context・Harness三層分離の背景とAIエージェント開発の構造変化

AIコーディングエージェントの能力が急速に向上した2025年から2026年にかけて、開発現場ではモデル性能だけでは解決できない構造的な課題が浮き彫りになりました。単発のプロンプトでコードを生成する段階を超え、数時間から数日にわたる自律的な開発セッションが求められるようになった結果、仕様をどう書くか（Spec）、文脈をどう届けるか（Context）、制御構造をどう組むか（Harness）という3つの設計領域が明確に分離しました。この三層構造は特定の企業が発明したものではなく、Anthropic・OpenAI・LangChain・Thoughtworksといった複数の組織が独立して到達した共通解です。本章では、なぜこの三層分離が必然だったのかを、技術的な背景と開発チームの実態から解説します。

プロンプトエンジニアリングだけでは破綻した2025年後半の長時間エージェント運用実態

2025年後半、Claude CodeやGitHub Copilotの普及により、多くの開発チームがAIエージェントに複雑なタスクを委任し始めました。しかし、プロンプトを工夫するだけでは長時間の自律動作を安定させることが困難だという現実に直面しています。エージェントに30分以上のコーディングセッションを任せると、コンテキストウィンドウが埋まるにつれて推論精度が低下し、タスクの途中で全く関係のないファイルを編集し始めたり、完了を自己宣言して実際には未完成のまま停止したりする事象が頻発しました。

この問題は「コンテキスト腐敗」と呼ばれ、ツール呼び出しの結果やエラーログが蓄積してウィンドウを圧迫することで発生します。プロンプトの文言をどれだけ最適化しても、コンテキストウィンドウという物理的な制約を超えられません。さらに、エージェントが自分の生成したコードを自己評価する際には承認バイアスが働き、明らかに不十分な成果物でも「問題ありません」と報告する傾向がありました。こうした構造的な障害を解消するには、プロンプトの改善だけでなく、文脈の管理と制御構造の設計を別のレイヤーとして独立させる必要があったのです。

Hashimotoが提唱したハーネス概念と従来のワークフロー自動化との違い

2026年2月、TerraformやGhosttyの開発者として知られるMitchell Hashimotoが「ハーネスエンジニアリング」という概念を提唱し、この用語が業界に急速に浸透しました。彼の核心的な主張は「エージェントがミスをしたとき、次はうまくやれと期待するのではなく、その特定のミスが構造的に再発しにくい環境を設計せよ」というものです。この考え方は、従来のCI/CDパイプラインやワークフロー自動化とは根本的に異なります。

従来の自動化は、人間が書いたコードに対してリンターやテストを実行する仕組みでした。一方、ハーネスエンジニアリングではAIエージェントそのものの動作環境を設計対象とします。具体的には、エージェントが参照できるドキュメントの配置方法、ツール呼び出しの権限制御、生成物の検証ゲート、セッション間の状態引き継ぎ構造までを包括的に設計するのがハーネスの役割です。プロンプトが「何を頼むか」を決め、コンテキストが「何を知らせるか」を決めるのに対し、ハーネスは「何ができて何ができないか」を構造的に規定します。この三者の役割が明確に分かれたことで、開発者は各レイヤーを独立して改善できるようになりました。

Anthropic・OpenAI・LangChainが三層構造に収斂した技術的背景

三層構造への収斂は偶然ではなく、各組織が同じ壁にぶつかった結果として生まれています。Anthropicは長時間コーディングエージェントの研究で、コンテキストリセットとアーティファクト引き継ぎの仕組みがなければセッション間の一貫性が維持できないことを実証しました。OpenAIはCodexの運用を通じて、エージェントの実行環境を意図的に設計しなければ100万行を超えるコードベースの品質を維持できないと報告しています。LangChainはエージェントハーネスの解剖として、ファイルシステム・コード実行・サンドボックス・メモリ・コンテキスト管理の5つのプリミティブが不可欠だと整理しました。

Thoughtworksも独自にハーネスエンジニアリングの概念を体系化し、コンテキストエンジニアリング（文脈設計）、アーキテクチャ制約（決定論的なリンターや構造テスト）、エントロピー管理（ドキュメント劣化の修復）の3つの柱を提示しています。注目すべきは、これらの組織が互いに独立して到達した結論がほぼ一致している点にあります。モデルの知能がいくら向上しても、適切な文脈なしには正しい判断ができず、構造的な制約なしには信頼性を担保できないという事実が、三層設計の必然性を裏付けているのです。

Agent＝Model＋Harnessの定義が開発チームの責任分界をどう変えたかの具体例

LangChainが提唱した「Agent＝Model＋Harness」という定義は、開発チームの役割分担に直接的な変化をもたらしました。従来のAI開発では、モデルの選定とファインチューニングがエンジニアの主要な責務でした。しかしこの定義が浸透してからは、モデルは所与の前提として扱い、その周辺に構築するハーネスの設計こそがチームの成果物の品質を左右するという認識が広がっています。

実際にOpenAIのCodexチームでは、当初3名のエンジニアがハーネス設計を担当し、1人あたり1日3.5件のプルリクエストをマージする生産性を達成しました。チームが7名に拡大した後も生産性は向上しており、ハーネス設計の改善が追加メンバーの貢献を倍増させる効果を持つことが示されています。この事例が示唆するのは、モデルの性能向上に投資するよりも、ハーネスの設計改善に投資するほうが費用対効果が高い局面が多いという点です。開発チームの責任分界は「モデルを作る人」と「ハーネスを作る人」に再編されつつあります。

三層分離によって初めて解消されたコンテキスト喪失・自己評価バイアス・早期停止の3大障害

長時間稼働するAIエージェントが抱える根本的な課題は、大きく3つに集約されます。第一のコンテキスト喪失は、セッションが切り替わるたびにモデルが「記憶喪失」に陥る問題です。第二の自己評価バイアスは、モデルが自分の成果物を過大評価する傾向であり、不十分なコードでも「完成」と判定してしまいます。第三の早期停止は、複雑なタスクを途中で完了宣言してしまう現象で、機能の不足やテストの欠落につながります。

三層設計はこれらの障害それぞれに対して構造的な解決策を提供しました。コンテキスト喪失に対しては、Context層がセッション間で引き継ぐべき情報をファイルとして永続化し、次のセッション開始時に自動で注入する仕組みを担います。自己評価バイアスに対しては、Harness層が生成エージェントとは別の評価エージェントを配置し、独立した視点での検証を強制する仕組みを構築しました。早期停止に対しては、Spec層が仕様として機能一覧やテスト基準を明示し、完了条件を曖昧にしない設計を実現しています。これら3つの障害が個別のプロンプト改善では解消不可能だったからこそ、三層分離という構造的な解が必要になったのです。

仕様駆動のSpec層が果たす役割とプロンプト設計だけでは届かない品質の壁

三層設計の最上位に位置するSpec層は、AIエージェントが「何を作るべきか」を明確にするための仕様定義を担います。GitHubが2025年9月に公開したSpec Kitを皮切りに、仕様駆動開発という概念は急速に広まりました。従来のバイブコーディングでは曖昧なプロンプトからいきなりコード生成に入るため、出力が発散しやすいという課題がありましたが、仕様を先に固めてからコード生成に進むことで安定した品質を維持できるようになっています。本章では、Spec層の具体的な構成要素と、仕様駆動の適用範囲を見極めるための判断基準を掘り下げていきましょう。

Spec Kit4フェーズとOpenSpec軽量路線を比較した仕様駆動開発の選定基準

GitHubが公開したSpec Kitは、Specify（仕様定義）→Plan（実装計画）→Tasks（タスク分解）→Implement（実装）の4フェーズで開発を進める構造を採用しています。2026年初頭の時点でGitHubスターは8万を超え、対応するAIエージェントも24種類以上に拡大しました。一方、OpenSpecはSpec Kitを「ヘビーウェイト」と位置づけ、アーティファクト依存グラフと検証コマンドを中心とした軽量路線を打ち出しています。

両者の選定基準は、プロジェクトの規模と要件変更の頻度によって分かれます。Spec Kitは単一プロジェクトで仕様を段階的に詳細化していく場面に適しており、チーム間の認識を揃える効果が高い反面、セットアップのオーバーヘッドが小規模タスクには過剰になりがちです。OpenSpecは依存グラフの自動生成により仕様間の関係を可視化できるため、マイクロサービス構成のように仕様が分散するプロジェクトでの整合性管理に強みがあります。いずれのツールも仕様を自然言語で書く点は共通しており、AIエージェントが解釈しやすいフォーマットへの変換を内部で処理します。プロジェクトの特性に合わせて使い分けることが実務上の最適解です。

仕様をJSON・Markdown・YAMLで記述する際のメリットと運用の落とし穴

仕様の記述フォーマットは、エージェントの解釈精度とチームの運用効率に直結する重要な設計判断です。JSONはスキーマバリデーションが容易で、プログラムからの読み書きに適していますが、人間にとっての可読性が低く、コメントを記述できないため設計意図の伝達には不向きな側面があります。Markdownは人間の可読性が最も高く、GitHubやGitLabのプレビュー機能でそのまま閲覧できるため、チームレビューのハードルが最も低いフォーマットでしょう。

YAMLはJSONとMarkdownの中間に位置し、コメント記述が可能でありながら構造化データも表現できる点が特徴です。ただしインデントの誤りがパースエラーを引き起こしやすく、AIエージェントが生成するYAMLのインデントが微妙にずれるケースも報告されています。実務上の落とし穴として最も多いのは、フォーマットの混在です。仕様書はMarkdown、タスクリストはJSON、設定ファイルはYAMLのように分散すると、エージェントがどのファイルを参照すべきか迷い、コンテキストの無駄遣いが発生します。Spec Kitではプロジェクト全体のフォーマットを統一する方針が推奨されており、チーム内で事前にフォーマットを合意しておくことが安定運用の前提条件になります。

Plannerエージェントが1〜4文の入力を完全仕様に展開する処理フローと品質差の実測値

Anthropicの長時間エージェント研究では、Plannerエージェントが1〜4文の簡易な入力を受け取り、それを完全なプロダクト仕様に展開する仕組みが導入されました。Plannerの役割は、スコープを意図的に広げて野心的な機能セットを定義することと、技術的な実装詳細には踏み込まず製品コンテキストと高レベルの技術設計に集中することの2点に絞られています。この設計には明確な理由があり、Plannerが詳細な技術仕様まで決定してしまうと、そこに含まれる誤りが下流の実装全体に波及するカスケード障害のリスクが高まるためです。

Plannerを導入した場合と省略した場合の品質差は顕著でした。Plannerなしでは、Generatorエージェントが与えられた入力から直接ビルドを開始し、事前の計画を立てないまま実装に入るため、機能の網羅性が大幅に低下します。Anthropicの研究チームはこの現象を「アンダースコーピング」と呼んでおり、Plannerが生成する仕様書の有無によって最終成果物の機能数と完成度に明確な差が生じることを確認しています。つまり、Spec層の設計品質がプロジェクト全体のアウトプットを規定するという構造が実証されたのです。

仕様の粒度設計を誤った場合に発生するカスケード障害と手戻り工数の増大パターン

仕様の粒度は粗すぎても細かすぎても問題を引き起こします。粗すぎる仕様では、エージェントが解釈の余地を埋めるために独自の仮定を置き、開発者の意図とは異なる実装を生成するリスクが高まるでしょう。一方、過度に詳細な仕様は、前段のPlannerやアーキテクトが技術的な判断を固定してしまうため、後続のGeneratorエージェントが柔軟に問題を解決する余地を奪ってしまいます。

Anthropicの研究では、Plannerが詳細な技術仕様を前もって指定し、その内容に誤りが含まれていた場合、エラーが下流の実装に連鎖的に伝播するパターンが繰り返し観察されました。たとえば、データベーススキーマの設計をPlannerが決定してしまうと、Generatorがその設計に忠実に従おうとして非効率な実装を生み出し、最終的に全体の再設計が必要になるケースがあります。適切な粒度の目安として、Plannerは「何を達成するか」と「成果物の定義」に集中し、「どう実装するか」はGeneratorに委ねる分業が推奨されてきました。この役割分担を明確にしておくことが、手戻りを最小限に抑えるための設計指針となります。

探索的プロトタイプやバグ修正などSpec-firstを適用すべきでない3つの判断基準

仕様駆動開発は万能ではなく、適用すべきでない場面を正確に見極めることが実務では極めて重要です。第一の判断基準は「探索的プロトタイプ」で、何を作るか自体が不確実な局面では、仕様化のコストが学習速度を上回ります。このような場面ではバイブコーディングで素早く検証し、方向が定まってから仕様化する方が効率的です。

第二の判断基準は「小タスク」であり、バグ修正や設定変更のような軽微な作業にSpec-firstを強制すると、プロセスのオーバーヘッドが開発速度を圧倒的に低下させます。4つのユーザーストーリーを書いてからバグを1件修正するのは明らかに非効率でしょう。第三の判断基準は「リアルタイム性が求められる緊急対応」で、本番障害の復旧作業中に仕様書を整備している余裕はありません。これらの場面では、仕様を省略して即座に実装に入り、事後的に仕様を整備する逆順のフローが合理的です。問題サイズに応じたワークフロー選択こそが、三層設計を実務で活かすための前提条件となります。

Context Engineeringで制御すべき情報設計と文脈窓の運用判断基準

三層設計の中間に位置するContext Engineering（コンテキストエンジニアリング）は、AIエージェントが「何を知っているか」を設計する領域です。モデルの性能がどれだけ高くても、適切な情報が文脈に含まれていなければ正しい判断はできません。コンテキストウィンドウは有限のリソースであり、不要な情報で埋まれば推論精度が劣化します。本章では、文脈設計の具体的な技法と、実務での運用判断基準を体系的に整理していきましょう。

コンテキストウィンドウをRAMと見立てた場合に必要な圧縮・注入・永続化の3技法

LLMをCPU、コンテキストウィンドウをRAM、ハーネスをOS、エージェントをアプリケーションとする比喩は、ハーネスエンジニアリングの理解を助ける枠組みとして広く参照されています。この比喩に従えば、RAMであるコンテキストウィンドウの管理には、コンピュータサイエンスにおけるメモリ管理と同様の戦略が必要になります。第一の技法であるコンテキスト圧縮は、現在のタスクに関連する情報を保持しつつ全体のトークン数を削減する処理です。

第二の技法である動的コンテキスト注入は、すべての情報を初期プロンプトに詰め込むのではなく、エージェントの現在のタスクに応じて必要な情報を適時ロードする手法になります。第三の技法である知識永続化は、意思決定の履歴やタスク進捗をコンテキストウィンドウの外部にファイルとして保存し、セッションをまたいで復元可能にする仕組みです。この3つの技法を組み合わせることで、限られたウィンドウサイズの中で最大限の情報密度を実現できます。実務では、すべてをプロンプトに含めたくなる誘惑に負けず、コンテキストを「希少資源」として扱う姿勢が品質を左右するのです。

Memory BankとSpec文脈を分離する設計がセッション間の一貫性を担保する仕組み

長時間エージェント運用において、常時参照すべきプロジェクト全体の文脈（Memory Bank）と、特定タスクに紐づく仕様文脈（Spec文脈）を分離する設計パターンが有効性を示しています。Memory Bankには、コーディング規約・アーキテクチャ決定記録・チームの暗黙知などが含まれ、すべてのセッションで自動的に読み込まれる仕組みです。一方、Spec文脈には現在のタスクに必要な仕様書・テスト基準・依存関係のみが含まれ、タスクの切り替えに応じて動的に入れ替わります。

この分離が重要な理由は、両者を混在させるとコンテキストウィンドウの消費が加速し、推論精度の低下を招くためです。たとえば、フロントエンドの実装タスクを進めている最中に、バックエンドのAPI仕様やデータベーススキーマの全量がウィンドウに存在すると、エージェントの注意が分散して無関係なファイルへの干渉が発生します。Claude CodeではCLAUDE.mdファイルがMemory Bankの役割を果たし、エージェント起動時に自動読み込みされる設計を採用しています。セッション間の一貫性を保つためには、永続的な文脈と一時的な文脈を構造的に分けておく設計が不可欠です。

ツール出力のオフロードとCompactionでコンテキスト腐敗を防ぐ閾値設定の実務例

エージェントがツールを呼び出すたびにその結果がコンテキストウィンドウに蓄積され、有用な情報がノイズに埋もれていく現象がコンテキスト腐敗です。とくにテストスイートの実行結果は深刻で、4000行の成功テストログがウィンドウを占有し、エージェントが本来のタスクを見失ってハルシネーションを起こした事例も報告されています。この問題への対策として、ツール出力のオフロードとCompaction（圧縮）の2つの手法が実装されてきました。

ツール出力のオフロードでは、一定のトークン数を超える出力について、先頭と末尾のみをウィンドウに残し、全文はファイルシステムに退避させます。エージェントが詳細を確認したい場合はファイルを読みに行く設計になっており、必要な場合だけ情報にアクセスする仕組みです。Compactionはウィンドウが容量上限に近づいた際に、既存の文脈を要約して圧縮する処理になります。実務での閾値設定として、テストやビルドの成功結果はサイレントにし、失敗時のみ詳細を出力するルールが広く採用されています。この「成功は無音、失敗は饒舌」という原則が、コンテキスト腐敗を防ぐ最もシンプルかつ効果的な指針です。

Skillsの段階的開示がエージェント起動時のコンテキスト消費と性能劣化を防ぐ理由

エージェントに多数のツールやMCPサーバーを接続すると、起動時にそれらの仕様がすべてコンテキストに読み込まれ、実際の作業に入る前から性能が劣化する問題が発生します。たとえば、20個のMCPサーバーを接続した状態でエージェントを起動すると、各サーバーのツール定義だけで数千トークンを消費してしまい、肝心のタスク遂行に使えるウィンドウ容量が大幅に減少します。

この課題に対する解決策がSkillsによるプログレッシブディスクロージャーです。Skillsはハーネスレベルのプリミティブとして設計されており、エージェントの起動時にはSkillのフロントマター（概要情報）のみをコンテキストにロードし、実際に必要になった時点で詳細な手順やツール定義を段階的に開示します。モデル自身がSkillのフロントマターを起動時に読み込むよう選択したわけではありませんが、ハーネスがこの段階的開示を管理することでコンテキスト腐敗を未然に防止しています。この設計は、必要なものだけを必要なタイミングで提供するという、コンテキストエンジニアリングの核心原則を体現した仕組みといえるでしょう。

サブエージェントをコンテキストファイアウォールとして使う場合の分割粒度と失敗事例

サブエージェントは、コンテキスト制御の手段として非常に効果的ですが、使い方を誤ると逆効果になります。正しい使い方は「コンテキストファイアウォール」としての活用であり、親エージェントから独立したコンテキストウィンドウで個別タスクを実行させ、その結果のみを親に返す構成です。これにより、中間的なツール呼び出しやエラーログが親のウィンドウを汚染せず、長時間にわたるオーケストレーションの一貫性を維持できます。

一方で失敗パターンとして多いのが、役割ベースのサブエージェント分割です。「フロントエンドエンジニア」「バックエンドエンジニア」「データアナリスト」のように専門性で分けるアプローチは、一見合理的に思えますが、実際にはうまく機能しないことが報告されています。各エージェントが独自の文脈で作業するため、フロントエンドとバックエンドのAPI仕様に矛盾が生じたり、共有リソースの競合が発生したりするケースが頻出しました。効果的な分割の粒度は、専門性ではなく「1つのコンテキストウィンドウで完結するタスク単位」です。リサーチ、実装、テストといった作業種別で分割し、各サブエージェントのプロンプトと最終結果だけが親に見える構成が推奨されています。

Harness Engineeringで実現する自律エージェントの信頼性と制御構造

三層設計の基盤を構成するHarness Engineering（ハーネスエンジニアリング）は、AIエージェントが「何ができて何ができないか」を構造的に規定する領域です。プロンプトが行動を誘導し、コンテキストが判断材料を提供するのに対し、ハーネスはエージェントの動作範囲を物理的に制約し、検証と修正のループを組み込みます。本章では、ハーネスの構成要素と実装パターンを具体的なコード例とともに見ていきましょう。

決定論的ガードレール・LLM判定・人間レビューを組み合わせた3類型の検証ループ設計

ハーネスにおける検証ループは、決定論的ガードレール・LLMベースの判定・人間によるレビューの3つの類型を組み合わせて構築します。決定論的ガードレールとは、リンターや構造テスト、型チェックのように、実行結果が常に同じになる検証手段を指す概念です。これらはLLMの非決定性に依存しないため、最も信頼性が高い防衛線として機能するでしょう。

LLMベースの判定は、コードレビューや設計整合性の評価など、人間の主観的判断に近い検証で力を発揮する領域です。ただし、同一モデルが生成と評価を兼ねると自己承認バイアスが働くため、評価には別のモデルインスタンスや別のプロンプトを使用する必要があります。人間によるレビューは、ビジネスロジックの妥当性やユーザー体験の品質など、AIだけでは判断が難しい領域をカバーする最終防衛線です。重要なのは、この3つを排他的に選択するのではなく、開発タイムライン上のコスト・速度・重要度に応じて配置することにあります。決定論的ガードレールだけでは柔軟性が不足し、LLMだけでは信頼性が不足するため、3類型の組み合わせがハーネス設計の核心となるのです。

Hooksで実装するセキュリティスキャン・リンター・ポリシー適用の実行タイミングと順序

Claude CodeのHooks機能は、エージェントのライフサイクル上の特定のポイントにカスタムスクリプトを挿入できる仕組みです。この機能により、コード変更がコミットされる前にセキュリティスキャンを実行したり、ファイル保存時にリンターを自動適用したり、特定のディレクトリへの書き込みを禁止するポリシーを強制したりすることが可能になります。Hooksの設計で重要なのは実行タイミングの適切な選択です。

セキュリティスキャンはコミット前（pre-commit）に配置することで、脆弱性を含むコードがリポジトリに入ることを構造的に防止します。リンターはファイル変更時に自動実行し、コーディング規約の逸脱をリアルタイムで修正させる設計が効果的です。ポリシー適用については、エージェントがツールを呼び出す直前にフィルタリングを挟み、許可されていない操作を事前にブロックする方式が推奨されています。これらのHooksの順序設計も重要であり、高速で軽量なチェック（構文エラーや型チェック）を先に実行し、重いスキャン（セキュリティ監査やライセンス検証）を後段に配置することで、フィードバックの即時性を確保しつつ総合的な品質保証を実現可能です。

自己評価バイアスを回避するために生成と評価を分離するマルチエージェント構成の設計根拠

AIモデルが自分自身の成果物を評価すると、明らかに不十分な出力であっても承認してしまう傾向があることは、Anthropicの研究で繰り返し確認されています。この自己評価バイアスは、プロンプトの工夫だけでは解消が困難な構造的な問題です。同一のモデルが出力を生成し、かつその品質を判定する場合、生成時の推論過程が評価時にも影響を及ぼし、自分の判断を正当化する方向にバイアスがかかります。

この問題に対するハーネスレベルの解決策が、Planner・Generator・Evaluatorの3エージェント構成です。Anthropicの長時間エージェント研究では、Plannerが仕様を策定し、Generatorが実装を担当し、Evaluatorが独立した視点で品質を検証する構成により、出力品質が大幅に改善されました。とくにEvaluatorは主観的な評価（UIの美しさやユーザー体験の質）を担当し、客観的な検証（テスト合格やビルド成功）は決定論的なガードレールに委ねる役割分担が効果的です。評価と生成を別のコンテキストウィンドウで実行することで、バイアスの伝播を構造的に遮断する設計が実現しています。

コンテキストリセットとアーティファクト引き継ぎで長時間セッションを安定させる実装手順

長時間のエージェントセッションでは、コンテキストウィンドウが肥大化するにつれてモデルの推論精度が劣化していきます。この問題に対処するため、Anthropicの初期のハーネス設計ではコンテキストリセットとアーティファクト引き継ぎを組み合わせた手法が採用されました。一定の作業単位が完了するたびにコンテキストをリセットし、次のセッションでは構造化されたアーティファクト（機能リスト、進捗ファイル、Gitコミット履歴）を読み込んで作業を再開する仕組みです。

具体的な実装手順としては、まず機能一覧をJSONファイルとして定義し、各機能の完了状態を記録する形式を取りました。次にセッション開始時に実行されるinit.shスクリプトを用意し、アプリケーションのビルドとテストを自動実行して動作可能な状態を保証します。そしてセッション間の引き継ぎにはGitコミットを活用し、差分を通じて前回の作業内容をエージェントに伝達する方式が採用されました。ただし、Opus 4.5の段階でコンテキスト不安の傾向はすでに大幅に解消されており、コンテキストリセットなしの連続セッションでも安定した動作が確認されました。さらにOpus 4.6ではスプリント構造自体を撤廃しても品質が維持されており、モデルの能力に応じてハーネスの複雑さを積極的に簡素化していく姿勢が重要です。

権限モデルをデフォルト読み取り専用にすることでファイル破壊を構造的に防ぐ設計思想

AIエージェントに無制限のシェルアクセスを与えることは、ファイルの誤削除・データベースの上書き・認証情報の漏洩といった深刻なリスクを伴う行為です。この問題に対し、Claude Codeでは権限モデルをデフォルトで読み取り専用に設定し、ユーザーが明示的に承認した場合のみ書き込みを許可する設計思想を採用しています。すべてのファイル編集は自動スナップショットによって可逆的であり、誤った変更があった場合にも即座にロールバック可能です。

この設計思想は「最小権限の原則」をAIエージェントに適用したものであり、エージェントの自律性を確保しつつも破壊的な操作を構造的に制限する仕組みです。実務においては、ファイル読み取り・コード生成・テスト実行は自動許可し、ファイル削除・外部API呼び出し・環境変数の変更には明示的な承認を要求するといった段階的な権限設定が一般的になっています。重要なのは、権限制御をプロンプトの指示ではなくハーネスの仕組みとして実装することです。プロンプトで「このディレクトリは編集しないでください」と書いても、モデルが従う保証はありません。権限制御はアーキテクチャレベルで強制されるべきであり、これがハーネスエンジニアリングの本質的な価値です。

三層設計を現場で機能させるためのCLAUDE.md・Hooks・Skills実装パターン

三層設計の理論を理解しても、実際のプロジェクトでどう実装すればよいのかが分からなければ現場では活用できません。本章では、Claude CodeやCursorなどの主要なコーディングエージェントが提供するハーネス機能を使い、Spec・Context・Harnessの三層を具体的にどう構成するかを実装パターンとして整理します。ファイル構成、Hooksの設計、Skillsの活用、ブートストラップスクリプト、CI/CD統合まで、すぐに導入できる実践的な設計例を提示します。

CLAUDE.mdを目次として設計しdocsディレクトリに知識ベースを分散配置する構成例

ハーネス設計における最も一般的な失敗は、CLAUDE.mdやAGENTS.mdに全情報を詰め込もうとすることです。OpenAIのCodexチームが指摘しているように、巨大な指示ファイルはタスク・コード・関連ドキュメントをコンテキストから押し出し、エージェントが重要な制約を見落としたり、誤った目標に最適化したりする原因になります。さらに、すべてが「重要」と書かれていると、何も重要でなくなるという逆説も生じます。

推奨されるアプローチは、CLAUDE.mdを百科事典ではなく目次として設計することです。プロジェクトの知識ベースは構造化されたdocs/ディレクトリに配置し、CLAUDE.mdにはディレクトリの構成と各ドキュメントの概要のみを記載します。エージェントは小さく安定したエントリーポイントから開始し、必要に応じて詳細ドキュメントを参照するプログレッシブディスクロージャーの形をとる設計です。この構成により、ドキュメントの鮮度管理も容易になるでしょう。ファイルが分散しているため、変更があった箇所だけを更新すればよく、モノリシックな指示ファイルの全面書き換えを避けられます。

Hooksのpre-commit・post-buildに組み込むチェック項目と優先順位

Hooksの設計は、チェック項目の選定と実行順序の最適化が品質を左右します。pre-commitフェーズに組み込むべきチェックとして、まず最優先は型チェックと構文検証です。これらは実行速度が速く、明確にパスかフェイルかが判定でき、エージェントへのフィードバックを即座に返せるため、開発ループの速度を維持したまま基本的な品質を保証できます。次にリンターによるコーディング規約の適用があり、チームのスタイルガイドとの整合性を自動で担保できる仕組みです。

post-buildフェーズでは、ユニットテストの実行、セキュリティスキャン、ライセンス検証といったより重い処理を配置します。これらはビルド成果物が生成された後に実行されるため、事前に検出できなかった問題をここで捕捉する設計です。チェック項目の優先順位付けにおいて守るべき原則は、高速で決定論的なチェックを先に、低速で確率的なチェックを後に配置することです。エージェントが即座にフィードバックを受け取れる環境を作ることで、修正の反復速度が向上し、最終的な成果物の品質も高まります。重いチェックを先頭に置くと、些細な構文エラーの修正にも長い待ち時間が発生し、開発効率が著しく低下してしまいます。

Skillsのフロントマターで段階的にツールを開示しコンテキスト消費を大幅に削減した事例

Skillsは、エージェントが利用可能なツールや手順を段階的に開示するためのハーネスプリミティブです。従来の設計では、エージェントの起動時にすべてのツール定義やMCPサーバーの仕様がコンテキストに読み込まれていましたが、Skillsを導入することで必要な情報だけが必要なタイミングで提供される構成に移行できます。

具体的な実装では、各Skillのフロントマターに名前・概要・トリガー条件のみを記載し、これをエージェント起動時にロードする仕組みです。エージェントが特定のタスクに着手する際に、該当するSkillの詳細手順が初めて展開される仕組みになっています。たとえば、ドキュメント生成のSkillは文書作成タスクが発生した場合のみ詳細が開示され、コーディングタスクの実行中にはフロントマターの数行しかコンテキストを消費しません。この設計を導入することで、起動時のコンテキスト消費量が大幅に削減され、その分だけ実際のタスク遂行に使えるウィンドウ容量が増加します。Skillsの活用は、コンテキスト管理の観点から費用対効果の高いハーネス最適化の一つといえるでしょう。

init.shスクリプトで毎セッション開始時にアプリ動作を保証するブートストラップ設計

長時間稼働するエージェントでは、セッションの切り替え後にアプリケーションが壊れた状態から作業を再開してしまうリスクがあります。前回のセッションで中途半端なリファクタリングが行われていたり、依存パッケージの更新が未完了だったりすると、エージェントは動作しないコードの修復に時間を浪費し、本来のタスクに着手できないまま貴重なコンテキストウィンドウを消費します。

この問題を防止するための仕組みが、init.shによるブートストラップ設計です。セッション開始時に自動実行されるこのスクリプトは、依存パッケージのインストール、アプリケーションのビルド、基本テストの実行を順に処理し、すべてが通過した場合にのみエージェントにタスクを渡します。Anthropicの長時間エージェント研究では、この仕組みにより「毎回のセッションが動作可能なアプリケーションから開始される」ことが保証され、エージェントの作業効率が大幅に改善されました。ブートストラップスクリプトの設計指針は、冪等性（何度実行しても同じ結果になること）と高速性（不必要な再インストールを避けること）の両立にあります。

構造テストとカスタムリンターをCI/CDパイプラインに統合して仕様逸脱を自動検出する方法

ハーネスエンジニアリングでは、エージェントの出力が仕様や設計方針から逸脱していないかを機械的に検証する仕組みが不可欠です。構造テストとは、コードの動作ではなく構造を検証するテストであり、特定のディレクトリにのみファイルが配置されているか、命名規則が守られているか、依存関係が許可された範囲内に収まっているかを確認します。これらは決定論的なチェックであるため、LLMの非決定性に影響されず、常に一貫した結果を返します。

カスタムリンターは、プロジェクト固有のルールを強制するための仕組みです。たとえば「このモジュールは外部APIを直接呼び出してはならない」「すべてのデータアクセスはリポジトリパターンを経由すること」といった設計方針をコードとして表現し、違反を自動検出する仕組みです。これらの構造テストとカスタムリンターをCI/CDパイプラインに組み込むことで、エージェントが生成するすべてのプルリクエストが仕様に準拠していることを保証できます。OpenAIのCodexチームでは、専用のリンターとCIジョブでドキュメントの鮮度や相互リンクの整合性まで機械的に検証しており、ドキュメント腐敗の防止にも同じアプローチを適用しています。

Spec・Context・Harness導入後に成果を出すチームと失敗するチームの設計差

三層設計を導入したすべてのチームが成功するわけではありません。ハーネスの過剰設計にリソースを費やして出荷速度が停滞するチームもあれば、最小限の構成で大きな生産性向上を実現するチームもあります。本章では、成果を出すチームと失敗するチームの設計アプローチの違いを具体的な事例と数値をもとに分析し、導入時に避けるべきアンチパターンと効果的な適用条件を明らかにします。

PR数3.5件/日を達成したOpenAI Codexチームのハーネス構成と人員体制

OpenAIのCodexチームは、ハーネスエンジニアリングの原則に基づいた開発体制で、5か月間に100万行以上のプロダクションコードをAIエージェントによって出荷しました。この成果を支えたのは、当初わずか3名のエンジニアで構成されたチームであり、1人あたり1日平均3.5件のプルリクエストをマージするという高い生産性を維持しています。チームが7名に拡大した後もスループットは低下せず、むしろ向上しました。

この生産性を支えたハーネス構成の特徴は3つあります。第一に、AGENTS.mdを目次として扱い、知識ベースをdocs/ディレクトリに分散配置することでコンテキストの効率的な管理を実現しました。第二に、専用リンターとCIジョブでドキュメントの鮮度を機械的に検証し、エントロピーの蓄積を防止する仕組みを構築しました。第三に、リポジトリ全体をエージェントの可読性を最優先に設計し、新しいメンバーのオンボーディングと同じ要領でエージェントに文脈を提供する方針を徹底しています。注目すべきは、ハーネス設計の改善が複利的に効果を発揮し、追加メンバーの貢献を増幅させた点でしょう。

ハーネス最適化に時間を費やしすぎてコード出荷が止まる過剰設計の兆候と回避策

ハーネスエンジニアリングには「最適化の罠」が存在します。エージェントのセットアップを改善することに夢中になり、実際にコードを出荷する時間よりもハーネスの調整に費やす時間が長くなるという本末転倒な状況です。この罠に陥ったチームでは、ハーネスの設計そのものが目的化し、エージェントの出力品質が実際に改善されたかを検証しないまま次の最適化に着手するパターンが繰り返されます。

過剰設計の兆候として典型的なのは、ハーネス設定ファイルの変更頻度がプロダクトコードの変更頻度を上回ること、エージェントが生成するコードよりもハーネスのドキュメントの方が分量が多くなること、そしてチーム内でハーネスの仕様についての議論がプロダクトの仕様についての議論を圧倒し始めることです。回避策として推奨されるのは「出荷バイアス」のアプローチであり、ハーネス最適化はエージェントが実際に失敗した場面でのみ行い、その失敗が再発しないようにする最小限の修正に留めるという方針です。予防的な最適化ではなく、実際の障害に対する反応的な改善に集中することで、投資対効果の高いハーネス設計を維持できます。

問題サイズに応じてバイブコーディングとSpec-firstを切り替える判断基準

三層設計の導入において最も見落とされがちなのが、すべてのタスクに同じワークフローを適用しようとする一律適用の誤りです。仕様駆動開発は中〜大規模の機能開発に適していますが、小さなタスクに適用するとプロセスのオーバーヘッドが開発速度を大幅に低下させます。問題サイズに応じた使い分けが不可欠です。

実務上の切り替え基準として、以下の3段階の分類が有効になってきました。

この使い分けを明文化してチーム内で共有することが、三層設計を形骸化させずに運用する上で極めて重要になります。中規模タスクでは仕様を先に固めてからエージェントに実装させることで手戻りを防止でき、大規模タスクではPlannerによる仕様策定からEvaluatorによる品質検証まで一貫したパイプラインの構築が求められるでしょう。

doc-gardeningエージェントでドキュメント腐敗を自動修復する仕組みと導入コスト

ハーネスの効果を長期的に維持するうえで最大の障害となるのがドキュメント腐敗です。プロジェクトの進行に伴い、コードは更新されても関連ドキュメントが追従せず、エージェントが参照する情報と実際のコードベースの間に乖離が生じます。この乖離が蓄積すると、エージェントは古い情報に基づいて実装を行い、結果として品質が徐々に劣化していきます。

この課題に対処するためにOpenAIのCodexチームが導入したのが、doc-gardeningエージェントです。このエージェントは定期的にリポジトリをスキャンし、コードの実態を反映していないドキュメントを検出して修正プルリクエストを自動生成します。一度セットアップすれば自動で運用されるため、継続的な人的コストは最小限に抑えられるでしょう。ただし、ドキュメントの構造が整理されていないプロジェクトでは、まずディレクトリ構成の標準化から着手する必要があります。doc-gardeningの効果を最大化するためには、ドキュメントにオーナーシップとフレッシュネスの指標を付与し、機械的な検証が可能な状態を整えることが前提条件です。

整合性駆動開発CoDDが要件変更時の影響分析を自動化し手戻りを減らした適用条件

Spec KitやOpenSpecが「最初に仕様を書く方法」を提供する一方で、要件変更が発生した際にどの設計書が影響を受け、どのテストが壊れ、どのAPIを修正すべきかを自動的に特定する仕組みは長らく存在していませんでした。この空白を埋めるために登場したのが、整合性駆動開発（CoDD: Coherence-Driven Development）です。CoDDは設計書間の依存関係をフロントマターとして明示的に管理し、変更影響の分析と検証を自動化する方法論になります。

CoDDの中核機能は4つのコマンドで構成されました。codd-scanが依存グラフを構築し、codd-impactが変更影響を分析し、codd-validateがフロントマターの整合性を検証し、codd-generateがWave順で設計書を生成します。各設計書にはCoDDフロントマター（node_id、type、依存メタデータ）が自動付与され、人間がメタデータを手動で管理する必要はありません。ただし、CoDDの適用が効果を発揮するのは、設計書の数が一定以上あり依存関係が複雑なプロジェクトに限られます。小規模プロジェクトでは導入コストが便益を上回る可能性が高く、まずはSpec KitやOpenSpecで基本的な仕様管理を確立してから段階的にCoDDを導入する戦略が現実的です。

モデル進化に伴う三層設計の再構成とHumans on the Loopへの移行判断

AIモデルの能力は急速に向上しており、ハーネスが補っていた機能の一部がモデル自身に吸収されつつあります。Opus 4.6への移行時にスプリント構造を撤廃しても品質が維持された事例が示すように、モデルの進化に合わせてハーネスの構成を見直す作業は継続的に必要です。同時に、人間の役割も「コードを1行ずつ確認する存在（in the loop）」から「制御構造を設計・改善する存在（on the loop）」へと変化しています。本章では、この移行をいつ・どのように進めるべきかの判断基準を提示します。

Opus 4.6移行時にスプリント構造を撤廃しても品質が維持された検証結果と再設計の手順

Anthropicのハーネス設計研究において、モデルの進化がハーネスの簡素化を可能にした象徴的な事例がOpus 4.5からOpus 4.6への移行過程です。初期のハーネスではSonnet 4.5を使用しており、コンテキストの限界に近づくとモデルが慎重になりすぎる「コンテキスト不安」の傾向がありました。Opus 4.5ではこの傾向が大幅に解消され、コンテキストリセットなしの連続セッションが実現しています。

さらにOpus 4.6への移行時には、スプリント構造を完全に撤廃しても品質が維持されることが確認されました。研究チームはPlanner・Generator・Evaluatorの3エージェント構成のみでハーネスを再構成し、ハーネスの複雑さが大幅に低減されたにもかかわらず出力品質は同等以上を維持しました。この事例から得られる教訓は、ハーネスの各コンポーネントが「モデルの限界を補うために存在するのか、それとも本質的に必要な制御構造なのか」を常に問い直す姿勢が重要だということです。PlannerとEvaluatorはモデル能力が向上しても引き続き明確な価値を提供しているため、撤廃の対象にはなりませんでした。

新モデルリリースごとに実施すべきハーネス監査の5項目チェックリストと簡素化判断

モデルのメジャーアップデートが行われるたびに、既存のハーネス構成を監査して不要な要素を除去することが推奨されています。この監査を怠ると、すでに不要になったハーネスコンポーネントがコンテキストを消費し続け、かえってエージェントの性能を阻害する状況が生まれます。

監査で確認すべき項目は以下の5つです。

• コンテキストリセットの必要性：新モデルが長いコンテキストでも安定して動作するなら、リセットの頻度を下げるか撤廃が可能
• タスク分割の粒度：モデルの計画能力が向上していれば、より大きなタスク単位での委任が可能になる
• 自己検証能力の評価：モデルが自身のミスを検出できるようになっていれば、外部Evaluatorの介入頻度を削減できる
• コンテキスト圧縮の閾値：ウィンドウサイズの拡大やモデルの長文理解力の向上に応じて設定を緩和できる
• プログレッシブディスクロージャーの段階数：モデルが大量のツール定義を処理できるようになっていれば、開示の段階を減らしてアクセス速度を向上させられる

これら5項目を新モデルのリリースごとに検証し、不要と判断されたコンポーネントは積極的に除去してください。ハーネスの複雑さが増すほどメンテナンスコストも上昇するため、シンプルな構成を維持する姿勢が長期的な運用成功の鍵となるでしょう。

in the loopからon the loopへの移行時に残すべき承認ゲートの設計指針

Humans on the Loopとは、人間がコードを1行ずつレビューする存在から、制御構造そのものを設計・改善する存在へと移行する概念です。この移行は段階的に進めるべきであり、すべての承認ゲートを一度に撤廃すると品質管理の空白が生じます。どの承認ゲートを残し、どれを自動化に委ねるかの判断が移行の成否を左右するでしょう。

残すべき承認ゲートの判断基準は3つあります。第一に、ビジネスロジックの妥当性に関わる判断は人間が保持すべきです。技術的な正しさはテストやリンターで検証できますが、「この機能はユーザーにとって価値があるか」という判断はAIには困難な領域です。第二に、セキュリティに関わる変更、とくに認証・認可・暗号化に関する実装は、人間による最終確認を維持する価値が高いといえます。第三に、アーキテクチャレベルの設計変更は長期的な影響が大きいため、人間の判断を経るべきです。一方、コーディング規約の準拠確認、テストカバレッジの検証、ドキュメントの整合性チェックなどは完全に自動化が可能であり、人間がレビューに費やす時間を削減して、より高次の設計判断に集中するための環境を整えることが on the loop への移行の本質になります。

モデル能力の向上でハーネスに吸収される機能と依然として外部制御が必要な領域の線引き

モデルが進化するにつれて、以前はハーネスで補完していた機能の一部がモデルに内蔵されるようになってきました。具体的には、計画能力の向上により外部Plannerの必要性が減少し、自己検証能力の向上により評価ループの頻度が低減し、長文脈での安定性向上によりコンテキストリセットが不要になるケースも見られるようになっています。Opus 4.6のリリースノートでも、計画の精度・長時間タスクの持続力・大規模コードベースでの信頼性が改善された点が報告されました。

しかし、モデルがどれだけ進化しても外部制御が必要な領域は依然として存在するでしょう。権限管理はモデルの善意に依存すべきではなく、ファイルシステムやAPI呼び出しの権限はアーキテクチャレベルで制限しなければなりません。セッション間の状態永続化もモデル内部では実現できないため、ハーネスが外部ストレージを管理し続ける必要があります。また、チーム固有のコーディング規約やビジネスルールの強制は、モデルの汎用的な学習データからは導出できないため、ハーネスのカスタムリンターとして実装する必要があるでしょう。ハーネスエンジニアリングの価値はモデルの欠点を補う側面だけでなく、モデルの知能を活用して全体の信頼性を高めるシステム設計にもあるのです。

三層設計の導入ロードマップを3か月で構築するための優先順位と最小構成の定義

三層設計を一度に完全導入しようとすると、ハーネス設計のオーバーヘッドに圧倒されて挫折するリスクが高まります。3か月の段階的な導入ロードマップとして、最小構成から始めて徐々に拡張するアプローチが最も成功率が高い方法です。

1. 1か月目（Context層の基盤構築）：CLAUDE.mdまたはAGENTS.mdをプロジェクトに導入し、コーディング規約・ディレクトリ構成・主要な設計判断を記載する。Spec層やHarness層の高度な機能は導入せず、エージェントが参照すべき基本情報の整備に集中すること。
2. 2か月目（Harness層の基本要素追加）：pre-commitフックでリンターと型チェックを自動実行する設定を導入し、テスト実行の自動化とセキュリティスキャンの基盤も整えること。
3. 3か月目（Spec層の仕様駆動フロー導入）：新機能の開発にSpec Kitまたは同等のツールを適用し、仕様→計画→タスク分解→実装の流れを1つのプロジェクトで試行する。

この順序で進める理由は、Context層が最も低コストで最大の効果を発揮し、かつ後続のHarness層とSpec層の基盤となるためです。最初のContext層整備だけでもエージェントの出力品質は目に見えて改善されるため、チーム内での三層設計に対する理解と支持を早期に獲得できるでしょう。