affaan-m/agent-architecture-audit

エージェントアーキテクチャ監査

ラッパー層、古いメモリ、リトライループ、トランスポート・レンダリングの変異の背後に失敗を隠すエージェントシステムのための診断ワークフロー。

起動タイミング

必須の場合:

• エージェントまたは LLM を活用したアプリケーションを本番リリースする前
• ツール呼び出し、メモリ、または多段階ワークフローを含む機能をリリースする前
• ラッパー層を追加した後にエージェントの動作が低下する場合
• ユーザーが「エージェントが悪化している」または「ツールが不安定」と報告する場合
• 同じモデルがプレイグラウンドでは動作するがラッパー内で壊れる場合
• 根本原因を見つけることなく 15 分以上エージェントの動作をデバッグしている場合

特に重要な場合:

• 新しいプロンプト層、ツール定義、またはメモリシステムを追加した場合
• システム内の異なるエージェントが一貫性なく動作する場合
• 昨日は正常だったモデルが今日ハルシネーションを起こしている場合
• 応答をサイレントに変異させる隠れた修復・リトライループが疑われる場合

使用しない場合:

• 一般的なコードデバッグ — agent-introspection-debugging を使用
• コードレビュー — 言語固有のレビューエージェントを使用
• セキュリティスキャン — security-review または security-review/scan を使用
• エージェントパフォーマンスのベンチマーク — agent-eval を使用
• 新機能の作成 — 適切なワークフロースキルを使用

12 層スタック

すべてのエージェントシステムはこれらの層を持ちます。いずれも回答を破壊する可能性があります：

| # | 層 | 問題の内容 | |---|-------|----------------| | 1 | システムプロンプト | 矛盾する指示、指示の肥大化 | | 2 | セッション履歴 | 前のターンからの古いコンテキスト注入 | | 3 | 長期メモリ | セッション間の汚染、新しい会話に古いトピックが混入 | | 4 | 蒸留 | 圧縮されたアーティファクトが疑似事実として再投入 | | 5 | アクティブリコール | コンテキストを無駄にする冗長な再要約層 | | 6 | ツール選択 | 誤ったツールルーティング、モデルが必要なツールをスキップ | | 7 | ツール実行 | ハルシネーションによる実行 — 呼び出したと主張するが実際には呼び出していない | | 8 | ツール解釈 | ツール出力の誤読または無視 | | 9 | 回答整形 | 最終応答でのフォーマット破損 | | 10 | プラットフォームレンダリング | トランスポート層の変異（UI、API、CLI が有効な回答を変異させる） | | 11 | 隠れた修復ループ | サイレントなフォールバック・リトライエージェントが 2 回目の LLM パスを実行 | | 12 | 永続化 | 期限切れの状態またはキャッシュされたアーティファクトがライブエビデンスとして再利用 |

一般的な障害パターン

1. ラッパーリグレッション

ベースモデルは正しい回答を生成するが、ラッパー層がそれを悪化させる。

症状:

• プレイグラウンドや直接 API 呼び出しでは正常に動作するが、エージェント内で壊れる
• 新しいプロンプト層を追加したら既存の動作が低下した
• エージェントは自信を持っているが、自信を持って間違っている
• 「最後のアップデート前は動作していた」

2. メモリ汚染

履歴、メモリ検索、または蒸留を通じて古いトピックが新しい会話に漏れる。

症状:

• エージェントが無関係な過去のトピックを持ち出す
• ユーザーの修正が定着しない（古いメモリが新しいものを上書きする）
• 同一セッション内のアーティファクトが疑似事実として再投入される
• メモリが際限なく増加し、時間とともに応答品質が低下する

3. ツール規律の失敗

ツールはプロンプトで宣言されているがコードでは強制されていない。モデルがそれをスキップするか実行をハルシネーションする。

症状:

• プロンプトに「ツール X を必ず使用する」とあるが、モデルはそれを呼び出さずに回答する
• ツール結果は正しく見えるが実際には実行されていない
• 異なるツールが同じ責任をめぐって競合する
• モデルが使うべきでない時にツールを使う、または使うべき時にスキップする

4. レンダリング・トランスポート破損

エージェントの内部回答は正しいが、プラットフォーム層が配信中にそれを変異させる。

症状:

• ログは正しい回答を示すが、ユーザーには壊れた出力が表示される
• Markdown レンダリング、JSON パース、またはストリーミングフラグメントが有効な応答を破損する
• 隠れたフォールバックエージェントが配信前に回答をサイレントに置き換える
• 出力がターミナルと UI で異なる

5. 隠れたエージェント層

明示的なコントラクトなしにサイレントな修復、リトライ、要約、またはリコールエージェントが実行される。

症状:

• 内部生成とユーザー配信の間で出力が変化する
• 「自動修正」ループがユーザーの知らない 2 回目の LLM パスを実行する
• 複数のエージェントが調整なしに同じ出力を修正する
• 回答が不可視の層によって「滑らか」または「修正」される

監査ワークフロー

フェーズ 1: スコープ

監査対象を定義する：

• 対象システム — どのエージェントアプリケーションか？
• エントリポイント — ユーザーはどのように操作するか？
• モデルスタック — どの LLM とプロバイダーか？
• 症状 — ユーザーは何を報告しているか？
• 時間ウィンドウ — いつ始まったか？
• 監査する層 — 12 層のうちどれが該当するか？

フェーズ 2: エビデンス収集

コードベースからエビデンスを収集する：

• ソースコード — エージェントループ、ツールルーター、メモリ受付、プロンプトアセンブリ
• ログ — 過去のセッショントレース、ツール呼び出し記録
• 設定 — プロンプトテンプレート、ツールスキーマ、プロバイダー設定
• メモリファイル — SOP、ナレッジベース、セッションアーカイブ

rg を使用してアンチパターンを検索する：

# プロンプトテキストのみで表現されたツール要件（コードでなく）
rg "must.*tool|必须.*工具|required.*call" --type md

# バリデーションなしのツール実行
rg "tool_call|toolCall|tool_use" --type py --type ts

# メインエージェントループ外の隠れた LLM 呼び出し
rg "completion|chat\.create|messages\.create|llm\.invoke"

# ユーザー修正優先度なしのメモリ受付
rg "memory.*admit|long.*term.*update|persist.*memory" --type py --type ts

# 追加の LLM 呼び出しを実行するフォールバックループ
rg "fallback|retry.*llm|repair.*prompt|re-?prompt" --type py --type ts

# サイレントな出力変異
rg "mutate|rewrite.*response|transform.*output|shap" --type py --type ts

フェーズ 3: 障害マッピング

各発見事項について文書化する：

• 症状 — ユーザーが見るもの
• メカニズム — ラッパーがそれを引き起こす方法
• ソース層 — 12 層のうちどれか
• 根本原因 — 最も深い原因
• エビデンス — ファイル:行 またはログ:行の参照
• 信頼度 — 0.0 から 1.0

フェーズ 4: 修正戦略

デフォルトの修正順序（コードファースト、プロンプトファーストではない）：

1. ツール要件のコードゲート化 — プロンプトテキストだけでなくコードで強制する
2. 隠れた修復エージェントの削除または縮小 — フォールバックをコントラクトで明示的にする
3. コンテキストの重複を削減 — プロンプト・履歴・メモリ・蒸留を通じた同一情報
4. メモリ受付の厳格化 — ユーザーの修正 > エージェントのアサーション
5. 蒸留トリガーの厳格化 — 圧縮すべきでないものは圧縮しない
6. レンダリング変異の削減 — パススルー、変換しない
7. 型付き JSON エンベロープへの変換 — 構造化された内部フロー、自由形式の散文ではない

重要度モデル

| レベル | 意味 | アクション | |-------|---------|--------| | critical | エージェントが自信を持って誤った操作動作を生成できる | 次のリリース前に修正 | | high | エージェントが頻繁に正確性や安定性を低下させる | このスプリントで修正 | | medium | 正確性は通常維持されるが出力が脆弱または無駄 | 次のサイクルで計画 | | low | 主に見た目または保守性の問題 | バックログ |

出力フォーマット

発見事項をユーザーにこの順序で提示する：

1. 重要度順の発見事項（最も重要なものから）
2. アーキテクチャ診断（どの層が何を破損させ、なぜか）
3. 優先度付き修正計画（コードファースト、プロンプトファーストではない）

お世辞や要約から始めないこと。システムが壊れている場合は直接そう述べる。

クイック診断質問

エージェントシステムを監査する際、以下に答える：

| # | 質問 | Yes の場合 → | |---|----------|----------| | 1 | モデルが必要なツールをスキップして回答できるか？ | ツールがコードゲートされていない | | 2 | 古い会話コンテンツが新しいターンに現れるか？ | メモリ汚染 | | 3 | 同じ情報がシステムプロンプトとメモリと履歴にあるか？ | コンテキストの重複 | | 4 | プラットフォームが配信前に 2 回目の LLM パスを実行するか？ | 隠れた修復ループ | | 5 | 内部生成とユーザー配信で出力が異なるか？ | レンダリング破損 | | 6 | 「ツール X を必ず使用する」ルールがプロンプトテキストのみか？ | ツール規律の失敗 | | 7 | エージェント自身のモノローグが永続メモリになり得るか？ | メモリポイズニング |

避けるべきアンチパターン

• ラッパー層のリグレッションを否定する前にモデルを責めることを避ける。
• 汚染パスを示さずにメモリを責めることを避ける。
• 現在のクリーンな状態が汚れた過去の出来事を消すことを許可しない。
• Markdown の散文を信頼できる内部プロトコルとして扱わない。
• コードがそれを強制しないのにプロンプトテキストの「ツールを必ず使用する」を受け入れない。
• 発見事項を直接的に、エビデンスに基づいて、重要度順に維持する。

レポートスキーマ

監査はこの形状に従った構造化されたレポートを生成すべきです：

{
  "schema_version": "ecc.agent-architecture-audit.report.v1",
  "executive_verdict": {
    "overall_health": "high_risk",
    "primary_failure_mode": "string",
    "most_urgent_fix": "string"
  },
  "scope": {
    "target_name": "string",
    "model_stack": ["string"],
    "layers_to_audit": ["string"]
  },
  "findings": [
    {
      "severity": "critical|high|medium|low",
      "title": "string",
      "mechanism": "string",
      "source_layer": "string",
      "root_cause": "string",
      "evidence_refs": ["file:line"],
      "confidence": 0.0,
      "recommended_fix": "string"
    }
  ],
  "ordered_fix_plan": [
    { "order": 1, "goal": "string", "why_now": "string", "expected_effect": "string" }
  ]
}

関連スキル

• agent-introspection-debugging — エージェントランタイムの失敗（ループ、タイムアウト、状態エラー）のデバッグ
• agent-eval — エージェントパフォーマンスの対決ベンチマーク
• security-review — コードと設定のセキュリティ監査
• autonomous-agent-harness — 自律エージェント操作のセットアップ
• agent-harness-construction — エージェントハーネスをゼロから構築