調査・検証ハーネス設計書 (Self-Correcting Edition)

https://gemini.google.com/share/6f01230c1a43

「Copilotが調査し、Java 23 & Tree-sitterが審判を下し、不整合があればCopilotが自己修正する」という自己完結型の検証ループを核とした設計書

---

1. コンセプト

本システムは、AI（Copilot）の「スピード」と、静的解析（Java 23 + Tree-sitter）の「厳密さ」を組み合わせた、自律修正型コード調査基盤である。 AIが生成した調査結果の嘘（ハルシネーション）をJavaツールが即座に見抜き、AIにフィードバックを送ることで、人間が介在することなく「100%検証済みの調査レポート」を完成させる。

2. システム構成図

• Actor: Copilot (The Worker)

• 役割：ソースコードを調査し、構造化データ（JSON）を作成する。

• 修正：Javaからのエラー指摘を受け、報告を訂正する。

• Actor: Java 23 & Tree-sitter (The Umpire)

• 役割：報告されたシンボルの実在を、ネイティブな構文解析で検証する。

• 出力：人間用の「最終レポート」と、AI用の「修正依頼書」を生成する。

• Actor: User (The Supervisor)

• 役割：Copilotへの最初の依頼と、最終的な検証済みレポートの確認のみを行う。

---

3. 自己修正ループのデータフロー

1. [調査開始]: 人間が Copilot に調査を依頼。
2. [初動報告]: Copilot が .harness/outbox/report.json を出力。
3. [検証実行]: 人間（またはVSCode Task）が Java ツールを起動。

• Java 23 の Panama API を通じて tree-sitter.dll を駆動。
• report.json 内の全項目を実コードと照合。

4. [フィードバック]:

• 不整合あり: Java が .harness/inbox/feedback.md（AIへのダメ出し）を出力。
• 不整合なし: Java が final_report.md（人間用）を出力して完了。

5. [自己修正]: Copilot が feedback.md を読み取り、調査をやり直してステップ2に戻る。

---

4. 共有ディレクトリ (.harness/) の仕様

このフォルダを通じて、AIとJavaツールが通信します。

ファイル名	送信元	受信元	内容
task.md	人間/Java	Copilot	調査の依頼内容、守るべきスキーマ定義。
report.json	Copilot	Java	調査結果（クラス、メソッド、依存関係）。
feedback.md	Java	Copilot	実在しなかった項目の指摘と再調査依頼。
summary.md	Java	人間	最終成果物。 検証済みスタンプ付きの調査書。

---

1. 調査タスクにおける「探索の木」の定義

コード調査における探索とは、「特定の機能がどう実装されているか」という仮説の検証です。

• Root: 「認証処理の全体像を把握せよ」
• Node A: 「ミドルウェア層でのチェック処理を調査」 → 結果：AuthMiddleware.lean に集中している。
• Node B: 「データベースとの照合ロジックを調査」 → 結果：UserRepo.lean で SQL を発行している。

---

2. 実装案：ファイルベースの調査ハーネス

APIを使えない環境で、エージェント（Cursor/Aider等）に「迷走せず」調査させるための構造です。

① 指示書の設置 (.harness/inbox/investigation_spec.md)

スクリプトが生成し、エージェントに読み込ませます。

調査任務: src/auth 領域のセッション管理方式を特定せよ。 アウトプット要求: > 1. 関連ファイル一覧を outbox/files.json に出せ。 2. シーケンス図（Mermaid形式）を outbox/diagram.md に出せ。 3. 確信度（0-100）を outbox/report.json に出せ。

② 状態の記録 (.harness/search_graph.json)

エージェントが「どのファイルまで読んだか」をスクリプトが記録します。これにより、一度調べた箇所を二度調べさせる無駄を防ぎます。

---

3. 「調査」をどう評価（Eval）するか

ビルドが通るかどうかではなく、**「情報の解像度」と「証跡の有無」**で評価します。

Hard Eval（スクリプトによる自動チェック）

• ファイル存在チェック: 報告された関連ファイルが実際にリポジトリに存在するか。
• シンボル参照チェック: 報告された関数名やクラス名が grep 等でヒットするか。ヒットしなければ「ハルシネーション（嘘）」として即座に却下。

Soft Eval（AI/人間による品質チェック）

• 情報の密度: 抽出されたコード片と説明の対応が取れているか。
• 自己採点: エージェント自身に「このコードの意図を100%理解できたか？」を confidence_score として出させ、一定以下（例：70点）なら「追加調査が必要」と判定して別の探索ノードを作成します。

---

4. 運用の流れ（APIなし環境）

1. [Script]: 調査したいディレクトリを特定し、investigation_spec.md を作成。
2. [Agent]: コードを読み、outbox/ に結果（JSON/Markdown）を書き出す。
3. [Script]: 報告された関数名を grep で検証。存在すれば「Success」として記録。
4. [Script]: 関連性が高いと判断された「隣接するファイル」を次の探索候補（Node）として search_graph.json に追加。
5. [Human/Optimizer]: グラフを見て、調査が十分なら終了。足りなければ次のノードをキック。

---

5. 既存コード調査に特化した「憲法（Policy）」の例

エージェントを「読む専門」に徹じさせるための設定です。

Policy: Code Base Investigation

• Read-Only: いかなる理由があっても既存の .lean や .py ファイルを書き換えてはならない。

• Evidence First: すべての主張には、必ず該当するファイル名と行番号（L10-L20など）を添えよ。

• Unknown is OK: 分からない箇所は推測せず「不明」と記し、調査に必要な追加情報を要求せよ。

---

汎用タスク（ソフトウェア開発、ドキュメント作成、データ分析など）に適用可能な、2026年基準の「再現性重視型」ハーネス構成

1. 最小フォルダ構成（The Project Lattice）

まず、AIの作業スペースを「会話」ではなく「ディレクトリ構造」として定義します。

.ai-harness/
├── control/              # 【最適化対象】指示・ルールの固定
│   ├── policy.yaml       # 権限、禁止事項、エスカレーション条件
│   └── tool_catalog.yaml # 利用可能なMCPツール群の定義
├── state/                # 【重要】実行中の現在地
│   ├── sessions.sqlite   # チェックポイント、トレースログ
│   └── artifacts/        # AIが生成した中間成果物（Todo, Spec等）
├── runtime/              # 実行エンジン
│   └── orchestrator.py   # Agent Loopと承認ゲートの実装
└── evals/                # 【最適化対象】品質の担保
    └── dataset.jsonl     # 過去の失敗/成功事例のペア

---

2. 汎用ワークフロー（4つのフェーズ）

タスクの種類を問わず、以下のサイクルで実行します。

① Planフェーズ（Artifactの生成）

いきなり作業を開始せず、state/artifacts/plan.md を作成させます。

• 出力内容: 解決策の仮説、必要なツール、Doneの定義。
• 最適化ポイント: AIが「何でもできます」と楽観的な計画を立てがちな場合、「制約条件（Constraints）」を強調するプロンプトを policy.yaml に追加して最適化します。

② Approvalフェーズ（人間によるゲート）

プランが書き込まれた時点で実行を一時停止し、人間に通知します。

• アクション: 人間が plan.md をレビューし、「OK」を出して初めて次へ進む。
• 再現性: 計画段階で合意することで、実行後の「思ってたのと違う」を根絶します。

③ Executionフェーズ（隔離された実行）

各ステップを小さな Run として実行し、結果を state/ に逐次保存します。

• MCP接続: 外部操作はすべてMCP経由で行い、履歴を sessions.sqlite に記録。
• 最適化ポイント: トークンコストやレイテンシが問題になる場合、**「低コストモデル（GPT-5 mini等）へのフォールバック」や「Prompt Caching」**の適用ポイントとして最適化が必要です。

④ Evalフェーズ（事後検証）

完了後、AI自身に summary.md を作成させ、事前に定義した Done を満たしているか自己採点させます。

• 最適化ポイント: ここでの失敗（評価漏れなど）が多い場合は、**「Grader（評価専用）エージェント」**を別個に立てる構成へアップグレードします。

---

3. 各コンポーネントの役割と最適化の要点

コンポーネント	役割	最適化が必要になるタイミング
Policy (Control)	守り（セキュリティ・品質）	組織のルール変更や、AIの「暴走（勝手な削除等）」が発生した時。
State (Artifacts)	記憶（引き継ぎ・再現）	セッションが長大化し、AIが過去の判断を忘れ始めた時（要約・圧縮の導入）。
Approval Gate	安全（人間介入）	開発スピードを優先したい場合。信頼度スコアによる「自動承認」の導入検討。
Eval (Feedback)	進化（改善）	同じミスが再発する時。失敗事例をデータセット化し、プロンプトを自動調整する。

---

前回の構成案からあえて「削ったもの（＝最初から持たなくてよい贅沢品）」とその理由、そしてそれらを削ることで得られるメリットについて整理します。

2026年のAIエージェント論考においても、**「最初から全部入りを目指すと、状態（State）の管理が複雑になりすぎて自壊する」**という教訓が共有されています。

---

1. 削った要素とその理由

削った要素	理由	削ったことによるメリット
高度な自律的リプランニング (Auto-Replanning)	AIが自分の失敗を検知して勝手に計画を書き換える機能。これは高確率で「迷走」を招きます。	透明性の確保。計画が変わる際は必ず一度「停止」して人間が介入するため、AIの挙動が予測可能になります。
マルチエージェントのスワーム (Swarm/Collaboration)	10体以上のエージェントが複雑に話し合う構成。文脈が散乱し、責任の所在（Stateの所有権）が曖昧になります。	状態の単純化。1体または最小限の役割（Planner/Worker）に絞ることで、履歴（Trace）が追いやすくなります。
ベクトルDBによる長期記憶 (RAG Memory)	過去の全会話を検索ベースで読み出す機能。ノイズが混じり、現在のタスクへの集中力が削がれることが多いです。	焦点の維持。過去の記憶は Artifact として「要約された事実」のみを引き継ぐ方が、推論の精度が上がります。
全自動の自己最適化 (Self-Optimization)	実行結果を見てプロンプトを自動更新し続けるループ。意図しない方向に挙動がドリフト（変質）するリスクがあります。	挙動の安定性。人間が Policy や Spec を介して意図的に最適化することで、システムとしての信頼性を保てます。

---

2. 「なぜ削るべきか」の設計思想

あなたが提示された論考にある**「交代可能な実務環境」**という視点に立つと、これらの要素を削ることには合理性があります。

1. 「知能」に頼らず「構造」に頼るため

高度な機能（自動リプランニングなど）は、モデルの「賢さ」に依存します。しかし、モデルが賢くなればなるほど、曖昧な指示でも「なんとなく」やってしまい、結果として再現性が落ちます。機能を削り、Spec や Approval という外側の構造で縛ることで、モデルが入れ替わっても同じ結果が得られるようになります。

2. 「監査可能性（Auditability）」を優先するため

実務において最も重要なのは、成功することと同じくらい**「なぜ失敗したかを説明できること」**です。多すぎるエージェントや全自動の記憶があると、失敗した時の原因特定が困難になります。ハーネスを最小限に保つことで、失敗は「事故」ではなく「修正可能なログ」になります。

---

3. 最適化が必要になる「拡張のタイミング」

今は削っていますが、運用のフェーズが進むと、以下の箇所で「意図的な拡張（最適化）」が必要になります。

• コンテキストの圧縮（Compaction）: タスクが数週間に及ぶ場合、State が肥大化してモデルの制限を超えます。この時、単純な削除ではなく、「何を残し、何を捨てるか」という要約アルゴリズムの最適化が必要になります。
• 承認の自動化（Smart Approval）: 単純な作業で毎回人間が承認するのがボトルネックになった場合、**「テストがパスしたかつ、Diffが一定の安全基準を満たせば自動パス」**というロジックへ最適化します。
• 評価の専門化（Independent Grader）: 自己採点の精度に限界が見えた時、**「実行役とは全く別の Policy を持った評価専用エージェント」**を配置するように最適化します。

---

2026年型の「AIハーネス」を、削った要素を再統合しながら進化させる4段階のロードマップを詳細に整理します。

各段階の構造は、提供いただいた論考の「7層構造（PolicyからEvalまで）」に基づいています。

---

Phase 1：静的固定（Static State）

AIを「賢い相棒」としてではなく、**「仕様に従う精密な実行ユニット」**として定義する段階です。

構造（Structure）

• Policy / Spec: 手動作成。人間が spec.yaml を書き、AIに読み込ませる。
• Runtime: 単発実行（Stateless）。AIは一回の出力で終了する。
• Artifact: 最終成果物のみ。
• Eval: 人間の目視確認。

目標

• 「曖昧な依頼」を「構造化された仕様」へ変換する習慣を定着させる。
• AIの出力をプロンプトではなく、**「外部化された状態（State）」**で制御できることを確認する。

次に進むタイミング

• 「同じ指示を何度も繰り返している」と感じたとき。
• 成果物が巨大になり、一回のプロンプト送信では全体を扱えなくなったとき。

---

Phase 2：状態回路の導入（Stateful Runtime）

「止める・待つ・再開する」という**運用の背面（Runtime）**を構築する段階です。

構造

• 再統合要素: チェックポイント（Checkpoint）。
• Runtime: 状態保持型（Stateful）。失敗したステップから再送が可能。
• Artifact: todo.md や assumptions.md など、思考の途中経過をファイル化して残す。
• Approval: 承認ゲートの設置。副作用（ファイル保存等）の前に必ず停止する。

目標

• 長いタスクを「死なないプロセス」に変える。
• 「なぜ失敗したか」を、会話ログではなく実行トレース（Trace）から特定できるようにする。

次に進むタイミング

• AIが「コードは書けるが、設計が甘い」「全体像を忘れて細部にこだわる」といった役割の混濁が起きたとき。

---

Phase 3：多面的な役割分離（Multi-Agent Harness）

「万能な一体」への依存を捨て、**情報の境界線（Permissions）**を引く段階です。

構造

• 再統合要素: 役割分離型マルチエージェント、長期記憶の要約昇格。
• Orchestration: **Planner（設計）とWorker（実装）**の分離。
• Context: Workerには「現在のタスクに必要な最小限の文脈」だけをPlannerが切り出して渡す。
• Tools: MCPによる外部接続の標準化。

目標

• 情報の洪水（文脈の汚れ）による精度低下を防ぐ。
• エージェントが入れ替わっても、spec.yaml を介して仕事が継続できる環境を作る。

次に進むタイミング

• 運用ルール（Policy）が複雑になり、AIに指示するよりも「自動で評価・ガード」させたくなったとき。

---

Phase 4：制御された自律化（Autonomous Optimization）

削ぎ落とした「自律性」を、評価（Eval）という手綱でコントロールしながら再統合する最終段階です。

構造

• 再統合要素: 自律リプランニング、自己最適化ループ。
• Eval: 独立した Grader（評価役） が実行結果を査定し、失敗をデータセット化する。
• Optimization: 評価結果に基づき、AIが Policy や Prompt の改善案を起案。人間が承認してシステムに反映。
• Self-Healing: 軽微なエラーに対し、AIが spec.yaml を修正して再試行する権限を（限定的に）持つ。

目標

• 人間が「作業」から解放され、「システムの監督とルールの進化」に集中できる状態を作る。
• 「失敗」がシステムを賢くするための「資産」として自動的に蓄積される。

---

まとめ：進化のKPI（指標）

このロードマップを進む際、**「AIが賢くなったか」ではなく「人間の説明コストが減ったか」**を指標にしてください。