harness-engineering

Harness：エージェントファーストのエンジニアリング基盤

ハーネスとは、リポジトリ内でコーディングエージェントが効果的に機能するための基盤です。 エージェントがリポジトリ自体からビジネス領域全体を推論するために必要な知識、境界、ルールを組み込みます。

基本理念は、エージェントが実行し、人間が舵を取ることです。エンジニアの仕事はコードを書くことではなく、環境を設計し、意図を明確にし、フィードバックループを構築することです。これを可能にするのがハーネスです。

重要な理由

エージェントの視点では、実行中にコンテキスト内でアクセスできないものは、事実上存在しません。Slack での議論、Google Docs、チームに暗黙的に蓄積された知識などは、すべて見えません。ハーネスは、こうした知識をリポジトリ内に置かれ、バージョン管理された成果物として組み込むことで、エージェントが把握できるようにします。

適切にハーネスが整備されたリポジトリは、エージェントに次のものを提供します。

• 地図（AGENTS.md）— 覚えるべきことではなく、調べる場所
• 境界（ドメイン仕様）— 何が何に依存できるか
• ルール（ゴールデンプリンシプル）— 強制可能な不変条件として組み込まれた判断基準
• 品質の基準値（スコアリング）— どこにギャップがあるか

この基盤がなければ、エージェントは見つけたパターンを、悪いものも含めてそのまま再現します。エントロピーの累積を防ぐのがハーネスです。

ハーネスの成熟度モデル

ハーネスは段階的に構築します。各レベルは前のレベルを土台とします。レベル 0 からレベル 4 へ一度に飛び越えようとしないでください。現在のレベルを評価し、次のレベルを目指して構築します。

レベル	名前	実現できること	主な成果物
0	ハーネスなし	エージェントはすべてを推測する — 地図もルールもない	なし
1	地図	エージェントが調べる場所とコードベースの内容を把握できる	AGENTS.md、ARCHITECTURE.md、docs/
2	ルール	エージェントが許可されることと禁止されることを把握できる	.harness/principles.yml、enforcement.yml、domains.yml
3	フィードバック	品質シグナルとプロセスパターンを通じて、エージェントが自ら修正できる	.harness/quality.yml、ドキュメントの手入れ、GC スイープ
4	自律性	定義されたエスカレーション境界のもと、エージェントが独立して動作できる	ワークツリーの分離、エスカレーションルール、エージェント間レビュー

各レベルの効果は積み重なります。レベル 1 がないままレベル 2 に達したリポジトリには、誰も見つけられないルールがあります。レベル 2 がないままレベル 3 に達したリポジトリには、品質評価はあっても改善を強制する方法がありません。まず基盤を構築してください。

評価（フェーズ 1）では、現在の成熟度レベルを判断します。計画（フェーズ 2）では、すべてのレベルを一度に目指すのではなく、次のレベルを目標にします。ハーネスのワークフローを繰り返して、段階的に進めます。

重要な例外：エージェントが積極的にコードを書いているリポジトリ（エージェントファースト、またはエージェント支援型）では、アーキテクチャ上の境界（ドメイン定義と一方向のみの依存ルール）を、知識レイヤーと同時に共同で作成する必要があります。これを別のレベル 2 の段階まで先送りしてはいけません。この記事が明確に述べているように、厳格なアーキテクチャは、エージェント主導の開発における初日からの前提条件であり、規模拡大の際に考慮するものではありません。境界がなければ、エントロピーを抑制できる速度を超えて、エージェントがコードを生成してしまいます。

複数ターンのワークフロー

ハーネスの構築は対話的に進めます。以下のフェーズに沿って作業し、各フェーズの区切りで結果を提示して、ユーザーの確認を待ちます。ユーザーがフェーズの省略、順序変更、拡張を希望する場合があります。その意向に従ってください。

Phase 1: Assess    → Analyze the repo, report agent readiness
Phase 2: Plan      → Propose a tailored harness, user confirms
Phase 3: Knowledge → AGENTS.md, docs/, ARCHITECTURE.md
Phase 4: Domains   → Identify domains, map layers, generate .harness/domains.yml
Phase 5: Enforce   → Golden principles, rules → .harness/principles.yml, enforcement.yml
Phase 6: Quality   → Grade domains → .harness/quality.yml
Phase 7: Process   → Doc-gardening, GC, review patterns
Phase 8: Verify    → Cross-check everything, report completeness

深さ優先のブートストラップ

幅優先ではなく、深さ優先でハーネスを構築します。初期のハーネス構築には想定以上に時間がかかります。リポジトリに問題があるからではなく、環境の仕様が十分に定まっていないからです。各フェーズを完了すると、次のフェーズに進めるようになります。

• AGENTS.md によって docs/ が整います（エージェントが詳細なコンテンツの配置場所を把握できます）
• docs/ によってアーキテクチャを把握できます（エージェントがドメインの背景を読めます）
• アーキテクチャ仕様によって、ドメインを正しく特定できます
• ドメイン仕様によって、有意義な適用ルールを定められます
• 適用ルールによって、品質を評価できます（確認できないものは評価できません）

何かがうまくいかないとき、解決策はほとんどの場合「もっと頑張る」ことではありません。**不足している機能やコンテキストは何か？**と問いかけてください。そして、まずその部分を構築します。

既存のハーネスを更新する場合も同じフェーズを適用しますが、現状の評価では .harness/ 内の仕様との差分を確認し、乖離している部分だけを更新します。

フェーズ 1：評価

ハーネスの各レイヤーにわたってリポジトリを調査します。目的は、すぐに問題を修正することではなく、何があり、何が不足し、何が適合していないかを把握することです。

調査する内容：

領域	確認する内容
構造	ディレクトリ、言語、パッケージマニフェスト、モノレポか単一パッケージか
技術スタック	フレームワーク、ビルドシステム、デプロイ先、依存関係マネージャー
エージェント設定	AGENTS.md、CLAUDE.md、.cursor/、.github/copilot/、既存のエージェント向け指示
ドキュメント	README、docs/、アーキテクチャドキュメント、ADR、コード内のドキュメントコメント
コード構成	ドメイン構造、モジュールの境界、インポートパターン、依存関係グラフ
テスト	フレームワーク、カバレッジ、CI のゲート、テストの構成
可観測性	ロギングパターン（構造化されているか）、メトリクス、エラー処理、トレーシング
プロセス	PR テンプレート、レビューのワークフロー、CI/CD の設定
チーム設定	エージェントファースト（コードの 90％以上をエージェントが作成）、エージェント支援型（混在）、またはエージェント対応型（将来のエージェント利用に向けた準備中）
依存関係	外部ライブラリはエージェントにとって理解しやすいか。安定した API、充実したドキュメント、学習データでの表現があるか

詳細なチェックリストと評価基準については、references/assessment.md を読んでください。

チーム設定に応じてハーネスの内容は変わります：エージェントファーストのリポジトリには、初日から強力な適用と GC が必要です。エージェント支援型のリポジトリには明確な境界が必要ですが、より多くを人間のレビューに委ねられます。エージェント対応型のリポジトリで主に必要なのはナレッジレイヤーです。

成果物： エージェント対応状況レポート。各レイヤーの現状、主な調査結果、推奨するハーネスの構成要素（優先順位付き）をまとめたものです。

レポートを提示し、計画を立てる前にユーザーの確認または修正指示を待ちます。

フェーズ 2：計画

このリポジトリに合わせたハーネス計画を提案します。すべてのリポジトリにすべての構成要素が必要なわけではありません。評価結果に基づいて適切な規模に調整します。

成熟度レベルに応じた規模：

現在のレベル	目標	構築するもの
0 → 1	マップ	AGENTS.md、ARCHITECTURE.md、基本的な docs/ の構成
1 → 2	ルール	.harness/domains.yml、principles.yml、enforcement.yml
2 → 3	フィードバック	.harness/quality.yml、ドキュメント整備、GC パターン
3 → 4	自律性	Worktree による分離、エスカレーションの境界、エージェントレビュー

リポジトリの規模も考慮してください。小規模なリポジトリ（5k LOC 未満）ではレベル 1～2 だけで十分な場合があります。一方、大規模なコードベース（50k LOC 以上）では、4 つすべてのレベルが効果を発揮します。

計画には、作成または更新する成果物をすべてフェーズごとにまとめ、それぞれの役割を簡潔に記載します。ユーザーが承認、変更、または削減できるチェックリスト形式で提示します。

実装に進む前に、確認を待ちます。

フェーズ 3：ナレッジレイヤー

エージェントがコードベースの全体像を把握するための成果物を構築します。

AGENTS.md（約100行）

最も重要なファイルです。これは百科事典ではなく、ルーティングテーブルです。

以下を含めてください。

• 妥協できないルールを3～5個（違反した場合に最も大きな損害を招くもの）
• 詳細なドキュメントへのリンク：ARCHITECTURE.md、docs/、進行中の計画
• 作業の検証方法（ビルド／テストコマンド）
• リポジトリの内容と構成（2～3文）

それ以外はすべてdocs/に置きます。AGENTS.mdが約100行を超える場合は長すぎるため、 ドキュメントに分割し、リンクを記載してください。

docs/ ディレクトリ

docs/
├── design-docs/
│   ├── index.md              # Catalogue with verification status
│   └── core-beliefs.md       # Agent-first operating principles
├── exec-plans/
│   ├── active/               # In-flight work
│   ├── completed/            # Done work (context for future agents)
│   └── tech-debt-tracker.md  # Known debt with priority
├── generated/                # Auto-generated (DB schema, API specs)
├── product-specs/
│   ├── index.md              # Feature catalogue
│   └── <feature>.md
├── references/               # External docs in agent-friendly format
├── PRODUCT_SENSE.md          # Product principles, personas, domain sensitivity
└── <DOMAIN>.md               # Domain guides (only those relevant to the repo)

docs/内の各ファイルは、次の段階的開示の構成に従ってください。

1. 概要（2～3文）— エージェントがこのファイルに関連性があるか判断できるだけの情報
2. 主要な決定事項 — 特に重要な3～5項目を冒頭に記載
3. 詳細 — さらに深く知る必要があるエージェント向けの全文
4. リンク — さらに詳しい情報を得るための関連ドキュメントへのリンク

これにより、ファイル単位で「巨大なAGENTS.md」の問題が再発するのを防げます。 エージェントはすべてのファイルをコンテキストに読み込まず、各ドキュメントの概要だけを読んで、 適切なドキュメントへ進めるようになります。

リポジトリが実際に必要とするものだけを作成してください。各ファイルには定型文ではなく、 評価に基づく実質的な内容を記載してください。

ARCHITECTURE.md

ドメインとは何か、ドメイン同士がどう関係するか、依存関係のルール、新しいコードをどこに配置するかを示す、トップレベルのドメインマップです。

テンプレートと記述ガイドについては、references/knowledge-layer.mdを読んでください。 コアとなる信念のテンプレートと内容ガイドについては、references/core-beliefs.mdを読んでください。

フェーズ4：アーキテクチャ層

ドメインの境界と依存関係のルールを、機械可読な仕様として定義します。

ドメインの特定

ドメインとは垂直スライスです。データの形からユーザーに見える出力まで、すべての統合レイヤーをエンドツーエンドで貫くトレーサーバレットです。水平な技術レイヤーではありません。

判定基準：UIからランタイム、サービス、リポジトリ、型まで、ユーザーの操作をたどることができ、その経路が一貫したビジネス概念の範囲内に収まっているでしょうか。そうであれば、それはドメインです。

CORRECT (vertical slices):        WRONG (horizontal layers):
┌─────────┐ ┌──────────┐         ┌──────────────────────────┐
│ Billing  │ │ Onboard  │         │ controllers/             │ ← NOT a domain
│ ┌─────┐  │ │ ┌─────┐  │         │ models/                  │ ← NOT a domain
│ │Types│  │ │ │Types│  │         │ services/                │ ← NOT a domain
│ │Confg│  │ │ │Confg│  │         │ utils/                   │ ← NOT a domain
│ │Repo │  │ │ │Svc  │  │         └──────────────────────────┘
│ │Svc  │  │ │ │UI   │  │
│ │UI   │  │ │ └─────┘  │
│ └─────┘  │ └──────────┘
└─────────┘

技術的な機能ではなく、ビジネス概念に注目してください。

• 「請求」、「オンボーディング」、「検索」＝ドメイン（垂直で、スタック全体を所有する）
• 「コントローラー」、「ユーティリティ」、「テスト」、「ツール群」＝レイヤーまたは関心事（水平）

詳細な特定のヒューリスティクスとトレーサーバレットテストについては、 references/architecture-layer.mdを読んでください。

レイヤー構造

各ドメイン内では、コードはレイヤーに分けて整理されます。

Types → Config → Repo → Service → Runtime → UI

重要なルール：依存関係は一方向にのみ流れます。 typesモジュールが serviceからインポートすることはありません。認証、テレメトリー、機能フラグなどの横断的関心事は、Providersという単一の明示的なインターフェースを通じて取り込みます。

すべてのドメインにすべてのレイヤーがあるとは限りません。CLIツールであれば、Types → Config → Service → Runtimeのみの場合があります。ライブラリであれば、Types → Serviceのみの場合があります。実在する構成をマッピングしてください。

.harness/domains.yml を生成する

ドメイン仕様を作成します。スキーマについてはreferences/yml-schemas.mdを、 特定のヒューリスティクスについてはreferences/architecture-layer.mdを読んでください。

フェーズ5：適用層

アーキテクチャ上の方針を、機械可読なルールとして定義します。目標は、境界を中央で適用し、各所では自律性を認めることです。

主要原則（.harness/principles.yml）

このリポジトリ固有の、明確な見解を伴うルールを5～10個特定します。各原則には次が必要です。

• 内容：ルールそのもの
• 理由：なぜ重要なのか（守らないと何が問題になるか）
• 確認方法：lint、構造テスト、レビュー、または手動確認
• 例：このコードベースにおける具体的な良い例／悪い例

評価で判明した原則、つまり、すでに問題を引き起こしているパターンや、現在は手動で維持されているものの適用すべき不変条件から始めてください。

機械的なルール（.harness/enforcement.yml）

ツールで確認できる具体的なルールです。

• ファイル、型、関数の命名規則
• ファイルサイズの上限
• 構造化ログの要件
• インポート境界のチェック
• テストカバレッジの期待値

エージェントが理解しやすいエラーメッセージ

これは、ハーネス全体で最も効果の高いパターンの一つです。すべての 適用ルールには、次の4つの要素を含む violation_message テンプレートが必須です。

1. 何が問題か — 具体的な違反内容
2. なぜ重要か — 原則に結び付けた理由
3. 修正方法 — 具体的な修正手順
4. 参照先 — ファイルパスまたはドキュメントへの参照

リンターのエラーメッセージは、エージェントがまさに必要とする瞬間に、 修正手順をコンテキストに注入するための手段です。一般的なメッセージ （「X で境界違反」）は、ほとんど役に立ちません。詳細なメッセージ （「X が Y からインポートしており、一方向のみのルールに違反しています。 修正方法：Providers 経由で注入してください。参照先：ARCHITECTURE.md#cross-cutting」）なら、 エージェントはすぐに自己修正できます。

適用コードを生成する

.harness/*.yml の仕様はルールを記述します。しかし、何もチェックしない 仕様は、いずれ陳腐化するドキュメントにすぎません。それは、ハーネスが 防ぐよう設計されている問題と同じです。

すべての適用ルールについて、少なくとも1つの具体的な成果物も生成します。

• リンター設定：命名規則、インポート、または構造ルールを適用する ESLint／Ruff／Clippy の設定。エージェントが理解しやすいエラーメッセージを含めます
• CI ワークフロー：AGENTS.md のリンク、docs/ の相互参照、または ナレッジの鮮度を検証する GitHub Actions／CI ジョブ
• 構造テスト：アーキテクチャ上の不変条件 （例：インポートの方向、ドメイン境界の遵守）を検証するテストファイル
• スクリプト：ファイルサイズの上限、禁止パターン、または命名規則をチェックする 検証スクリプト

スタブ実装であっても、何もないよりは優れています。TODO を含むリンタールールは、 誰も参照しない、完璧に文書化された YAML 仕様より価値があります。

原則の一覧とパターンについては references/enforcement-layer.md を読んでください。 スキーマについては references/yml-schemas.md を読んでください。

フェーズ 6：品質スコアリング

標準化された指標に基づいて、各ドメインを評価します。

評価項目： コード品質、テストカバレッジ、ドキュメント、可観測性、 信頼性、セキュリティ。

尺度： A（優れている）から F（欠落／破損）まで。

初回のスコアリングはベースラインです。今後のハーネス更新では、改善の追跡や ドリフトの検出のため、現在の状態をこれらの評価と比較します。

スコア、ギャップに関する注記、レビュー日を記載した .harness/quality.yml を生成します。 評価基準については references/quality-scoring.md を読んでください。

フェーズ 6.5：運用の可読性（該当する場合）

実行可能なアプリケーション（Web アプリ、API、サービス）があるリポジトリでは、 エージェントがコードだけでなく、アプリケーションも観察できるかを評価します。 記事で紹介されたチームは、実行中のアプリケーションをエージェントが直接把握できるように しました。これにより、エージェントの6時間以上にわたる自律セッションが可能になりました。

評価して、推奨事項を提示します：

• Worktree での起動：各エージェントの実行に分離されたインスタンスを用意するため、 Git worktree ごとにアプリケーションを起動できますか？できない場合は、優先度の高い課題として指摘します。
• ブラウザー自動化：UI アプリの場合、エージェントは Chrome DevTools Protocol を介してアプリケーションを操作できますか （スクリーンショット、DOM スナップショット、ナビゲーション）？
• 可観測性：エージェントは自分のインスタンスから、ログ（LogQL）、メトリクス（PromQL）、 トレース（TraceQL）を照会できますか？
• 一時的な状態：エージェントのタスク完了時に、ログ、メトリクス、アプリケーションの状態は破棄されますか？

このフェーズは、実行可能なアプリケーションがあるリポジトリにのみ該当します。ライブラリ、 CLI ツール、インフラストラクチャのリポジトリでは省略できます。

フェーズ 7：プロセスパターン

ハーネス主導のコードベースを長期にわたって健全に保つパターンを文書化します。 これらは、適切な docs/ ガイドファイルに記載します。

• ドキュメントのメンテナンス：古くなった、または誤りのあるドキュメントを定期的に確認します
• ガベージコレクション：パターンのずれ、ヘルパーの重複、蓄積した「AI による粗雑なコード」を特定して解消します。これは緊急の作業であり、任意ではありません。自動 GC がなければ、エージェントが生成したコードベースは、手作業でのクリーンアップにエンジニアリング時間の 20% を費やすほど急速に劣化します
• エージェントレビュー：成熟度がレベル 3 以上の場合、エージェント間レビューを人間によるレビューの補助ではなく、主要な品質ゲートとするべきです。人間がレビューするのは、判断が必要な事項（ビジネスロジック、製品上の決定、アーキテクチャの方向性）のみです。段階的な進行は次のとおりです。レベル 1～2 では人間がすべてをレビュー → レベル 3 ではエージェントが事前レビューし、人間が抜き取り確認 → レベル 4 ではエージェント間レビューを行い、エスカレーション時のみ人間が対応します。
• マージの方針：短期間で完了する PR を優先し、いつまでもブロックするのではなく、後続の修正で対応します。前提条件：これは、自動適用の仕組みが導入されており（成熟度レベル 2 以上）、テストカバレッジでリグレッションを検出でき、エージェントが後続の修正を生成できる場合にのみ適切です。これらがなければ、マージ条件を緩和するのは無謀です。
• フィードバックのルール化：レビューコメントやバグを、ドキュメントの更新やルールに反映する方法
• エスカレーションの境界：人間の判断が必要な決定と、エージェントが自律的に解決できる決定を定義します。これにより、過剰な確認（遅延）と確認不足（危険）の両方を防ぎます

テンプレートについては references/process-patterns.md を参照してください。

フェーズ 8：検証

実装後、ハーネスに一貫性があることを検証します。

• AGENTS.md で参照されているすべてのパスが存在する
• docs/ 内のすべての相互リンクが解決できる
• .harness/*.yml ファイルの構造がすべて有効である
• domains.yml のドメインが実際のコードディレクトリに対応している
• ARCHITECTURE.md が実際のモジュール構成を反映している
• 特定したすべてのドメインについて、品質スコアが設定されている
• ナレッジベースの構成が knowledge.yml の設定と一致している

調査結果を報告します。ハーネスの完成とする前に、問題を修正してください。

更新フロー

既存のハーネスを更新する場合：

1. ずれを検出する：.harness/ の仕様と実際のコードベースを比較します
   • domains.yml に記載されていない新しいディレクトリやモジュール
   • 削除または移動されたファイルを参照しているドキュメント
   • 設定されたレビュー周期を超えて古くなった品質スコア
   • 最近追加されたコードで違反されている原則
2. 対象を絞った更新を提案する：再構築せず、ずれが生じた箇所だけを更新します
3. 変更を実装する：同じフェーズ構成を使用しますが、ずれが生じた箇所に範囲を限定します
4. 再検証する：検証チェックリスト全体を実行します

.harness/ ディレクトリ

機械可読なハーネス設定はすべて、リポジトリのルートにある .harness/ に格納されます。

.harness/
├── config.yml         # Harness metadata, version, tech stack summary
├── domains.yml        # Business domain definitions + layer rules
├── principles.yml     # Golden principles with rationale + examples
├── enforcement.yml    # Mechanical rules (naming, limits, logging, imports)
├── quality.yml        # Per-domain quality grades + gap tracking
└── knowledge.yml      # Knowledge base structure configuration

例を含む完全なスキーマについては references/yml-schemas.md を参照してください。

技術スタックに応じた適応

ハーネスは技術スタックに依存しませんが、実装はそれに応じて調整します。

• 命名規則：JS/TS では camelCase、Python/Rust では snake_case
• レイヤー名：異なる場合があります。「repo」が「repository」や「data-access」などになることがあります
• ビルドコマンド：技術スタックごとに異なるため、AGENTS.md に記録します
• 依存関係の適用：モジュールシステムによってインポートのスタイルが異なります
• ロギング：エコシステムごとに異なる構造化ロギングライブラリを使用します

評価中に技術スタックを特定し、それに応じてすべてのテンプレートを調整してください。 あるエコシステムの規約を、別のエコシステムに無理に適用しないでください。