agent-architecture-audit

name	agent-architecture-audit
description	エージェントおよび LLM アプリケーション向けのフルスタック診断。12 層のエージェントスタックにおけるラッパーリグレッション、メモリ汚染、ツール規律の失敗、隠れた修復ループ、レンダリング破損を監査します。重要度順の発見事項とコードファーストの修正を生成します。エージェントアプリケーション、自律ループ、または LLM を活用した機能を構築する開発者に必須です。
origin	oh-my-agent-check
tools	Read, Write, Edit, Bash, Grep, Glob

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

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

起動タイミング

必須の場合:

• エージェントまたは 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 — エージェントハーネスをゼロから構築