harness-engineering

ハーネスエンジニアリング

基本原則

リポジトリがハーネスです。エージェントの失敗はハーネスの失敗です。エージェントがルールに違反したら、エージェントではなくハーネスを修正します。

柱	解決する問題
コンテキストエンジニアリング	エージェントの幻覚、誤ったツール使用、古いドキュメント
アーキテクチャ上の制約	境界違反、気付かれないリグレッション、曖昧な失敗
ガベージコレクション	エントロピーの蓄積、デッドコード、ドキュメントの乖離

適用するタイミング

状況	対応
AI 開発用の新しいリポジトリをセットアップする	初日から3つすべての柱を適用する
エージェントがツールや API について繰り返し幻覚を起こす	柱1：AGENTS.md にツールの宣言を追加する
エージェントがモジュールの境界を越える	柱2：境界を強制する構造テストを追加する
エージェントが CI を通過するが規約に違反するコードを生成する	柱2：規約をリンタールールまたは構造テストにする
ドキュメントが実装と乖離する	柱1：CI に相互リンク検証を追加する
コードベースが拡大し、エージェントの品質が低下する	柱3：デッドコードや未使用のエクスポートを対象とする GC エージェントを定期実行する
エージェントが AGENTS.md の指針を無視する	確認事項：指針は一般的なアドバイスか、それとも具体的な失敗から得た教訓か？失敗記録の項目として書き直す
エージェントが生成したコードでインシデントが発生した後	失敗を AGENTS.md に追加し、再発を防ぐ制約を追加する

柱1：コンテキストエンジニアリング

目標： エージェントが幻覚を起こさずに利用できるナレッジプロダクトとして、リポジトリを整備します。

1.1 失敗記録としての AGENTS.md

AGENTS.md のすべての行は、一般的なベストプラクティスではなく、実際に発生した失敗に基づく必要があります。

# Pattern
BAD:  "Follow clean code principles"
BAD:  "Use meaningful variable names"
GOOD: "Never import from packages/internal — agent imported shared/db directly on 2025-12-03, broke build"
GOOD: "Always use OrderService.create(), not Order.new — direct instantiation skips validation (incident #247)"

失敗記録の項目形式：

rule: Never call PaymentGateway directly from controllers
context: Agent bypassed service layer, sent duplicate charges (2025-11-15)
fix: Use PaymentService.charge() which handles idempotency

AGENTS.md を作成または更新するとき：

• ルールが具体的な失敗や制約に言及していない場合 → 削除する
• ルールに「すべき」とある場合 → 結果を明記して「必ず」に書き換える
• ルールに強制手段がない場合 → 柱2の制約と組み合わせる

1.2 ツール宣言の義務

宣言されていないツールは、エージェントにとって存在しません。利用可能なツール、コマンド、スクリプトを明示的に列挙します。

## Available Tools
- `bin/test` — Run test suite (prefer over raw pytest/rspec)
- `bin/lint` — Run linters with auto-fix
- `bin/db-reset` — Reset dev database
- `make deploy-staging` — Deploy to staging (requires approval)

## DO NOT USE
- `rm -rf` on any directory
- Direct database queries in production
- `curl` to external APIs without going through ApiClient

エージェントがこの一覧にないツールを使用した場合 → 有効であれば追加し、危険であれば DO NOT USE に追加します。

1.3 信頼できる情報源としてのドキュメント

RULE: docs/ is canonical truth
ENFORCEMENT: CI validates cross-links between docs/ and source code
MECHANISM:
  - Every public API must have a corresponding docs/ entry
  - CI script checks: for each @api-doc tag in source → matching file in docs/
  - Broken link = CI failure, not warning

古いドキュメントは、ドキュメントがないよりも悪いものです。エージェントは読んだ内容を信頼します。

1.4 タスクごとに独立した可観測性

各エージェントタスクには、共有の監視ストリームではなく、独自のログコンテキストを割り当てます。

PATTERN:
  - Assign task_id to each agent invocation
  - Route logs to task-specific output (file, log group, trace)
  - Post-task: review task log for failures, add to AGENTS.md if new pattern

監視を共有すると、個々のエージェントの失敗がノイズに埋もれます。

柱2：アーキテクチャ上の制約

目標： 決定論的な強制によって、違反を不可能にするか、即座に可視化します。

2.1 指導的なリンターエラー

エラーメッセージには、違反の指摘だけでなく、修正方法も含める必要があります。

# BAD linter output
ERROR: Import violation in src/api/handler.ts

# GOOD linter output
ERROR: Import violation in src/api/handler.ts
  ↳ Cannot import from 'packages/db' in 'src/api/'
  ↳ Use 'packages/db-client' instead (facade pattern)
  ↳ See: docs/architecture/data-access.md

エージェントはエラーメッセージを文字どおりに読みます。指導的なエラーメッセージがあれば、次の試行で同じ間違いを防げます。

2.2 構造テスト

アーキテクチャ上の境界はドキュメントではなく、CI で強制します。

# Pseudocode structural tests
test "no cross-boundary imports":
  For each FILE in src/api/**:
    IMPORTS = parse_imports(FILE)
    FORBIDDEN = ["packages/internal", "src/admin", "src/worker"]
    assert IMPORTS intersection FORBIDDEN == empty

test "dependency direction":
  LAYERS = [presentation, application, domain, infrastructure]
  For each LAYER in LAYERS:
    For each IMPORT in LAYER.imports:
      assert IMPORT.layer_index >= LAYER.index  # only import same or lower

test "API contract stability":
  CURRENT = parse_openapi("api/openapi.yml")
  PREVIOUS = parse_openapi("api/openapi.yml", ref="main")
  assert no_breaking_changes(CURRENT, PREVIOUS)

2.3 数値による CI ゲート

すべてのチェックは、合格か失敗かの二択である必要があります。助言的な警告は、エージェントには見えません。

チェックの種類	ゲートの実装
テストカバレッジ	coverage >= 80% でなければ失敗
バンドルサイズ	size <= 250KB でなければ失敗
リントエラー	errors == 0 でなければ失敗
型エラー	errors == 0 でなければ失敗
セキュリティ脆弱性	critical == 0 でなければ失敗

ルール： 重要ならゲートにします。警告であれば、エージェントは無視します。

2.4 依存関係の階層化

依存関係の方向を明示し、強制します。

# .dependency-layers.yml (or equivalent config)
layers:
  - name: presentation
    paths: ["src/ui/**", "src/api/routes/**"]
    can_import: [application, domain]

  - name: application
    paths: ["src/services/**", "src/use-cases/**"]
    can_import: [domain, infrastructure]

  - name: domain
    paths: ["src/models/**", "src/entities/**"]
    can_import: []  # domain has no dependencies

  - name: infrastructure
    paths: ["src/db/**", "src/external/**"]
    can_import: [domain]

明示的な階層がなければ、エージェントは循環依存を作ります。

柱3：ガベージコレクション

目標： 技術的負債を蓄積するのではなく、エントロピーに積極的に対処します。

3.1 バックグラウンド GC エージェント

小規模で自動マージ可能な PR を作成するスキャンを定期実行します。

GC_TASKS:
  - dead_code: find unused exports, unreachable functions → remove
  - stale_docs: find docs/ entries with no matching source → flag
  - unused_deps: find package.json/Gemfile entries with no imports → remove
  - orphan_tests: find test files with no matching source file → flag
  - config_drift: diff .env.example vs actual config usage → reconcile

FREQUENCY: weekly for active repos, monthly for stable repos
OUTPUT: one small PR per GC task (not one mega-PR)
MERGE: auto-merge if CI passes, otherwise flag for review

3.2 カスタム検証ツール

汎用リンターに頼るのではなく、リポジトリ固有の高速なフィードバックツールを構築します。

PRINCIPLE: fast feedback > comprehensive analysis

Examples:
  - bin/check-api-contracts → validates OpenAPI spec matches routes (5s)
  - bin/check-imports → validates dependency layers (2s)
  - bin/check-docs → validates doc cross-links (3s)

RULE: if a custom check takes > 30s, it's too slow for agent feedback loops

3.3 フィードバックループの規律

エージェントが質の悪い出力を生成した場合、次の診断順序に従います。

1. Check AGENTS.md — is the constraint documented?
   If NO → add it (Pillar 1 fix)
   If YES → is it enforced in CI?

2. Check CI — does a gate catch this failure?
   If NO → add structural test or linter rule (Pillar 2 fix)
   If YES → is the error message teaching?

3. Check error message — does it include remediation?
   If NO → improve the error message (Pillar 2.1 fix)
   If YES → the harness is correct, investigate agent-specific issue

NEVER: Skip to "the agent is broken" without completing steps 1-3

ハーネス評価チェックリスト

既存リポジトリのハーネス成熟度を評価します：

コンテキストエンジニアリング

• リポジトリのルートにAGENTS.mdが存在する
• AGENTS.mdの項目は一般的なアドバイスではなく、具体的な失敗事例を参照している
• 利用可能なツール／スクリプトが明示的に列挙されている
• 禁止されている操作が明示的に列挙されている
• docs/に、CIで強制されるソースへの相互リンクがある

アーキテクチャ上の制約

• リンターのエラーに修正方法の説明が含まれている
• 少なくとも1つの構造テストでモジュール境界を強制している
• すべてのCIチェックが合格／不合格の二択である（参考警告はない）
• 依存関係の方向が文書化され、強制されている

ガベージコレクション

• デッドコードの削除が随時ではなく、スケジュールに沿って行われている
• 古くなったドキュメントが自動的に検出される
• リポジトリ固有の不変条件を検証するカスタムツールがある
• 失敗後の診断は、まずハーネスを確認する順序に従っている（3.3）

採点： 各柱の合格項目数を数えます。いずれかの柱が3/5未満の場合は、ハーネスに不足があります。

相互参照

• hierarchical-agents — AGENTS.mdの構成、生成プロセス、JITインデックス作成
• tdd-workflow — レッド・グリーン・リファクタリングによる構造テストの実装
• structured-logging — タスク単位の分離に向けた可観測性のパターン
• quality-gateエージェント — CIゲートの実行メカニズム
• references/patterns-catalog.md — トポロジーテンプレート、AGENTS.mdのパターン、構造テストの例、GCエージェントのテンプレート