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: 修正戦略 デフォルトの修正順序（コードファースト、プロンプトファーストではない）： ツール要件のコードゲート化 — プロンプトテキストだけでなくコードで強制する 隠れた修復エージェントの削除または縮小 — フォールバックをコントラクトで明示的にする コンテキストの重複を削減 — プロンプト・履歴・メモリ・蒸留を通じた同一情報 メモリ受付の厳格化 — ユーザーの修正 > エージェントのアサーション 蒸留トリガーの厳格化 — 圧縮すべきでないものは圧縮しない レンダリング変異の削減 — パススルー、変換しない 型付き JSON エンベロープへの変換 — 構造化された内部フロー、自由形式の散文ではない 重要度モデル レベル 意味 アクション critical エージェントが自信を持って誤った操作動作を生成できる 次のリリース前に修正 high エージェントが頻繁に正確性や安定性を低下させる このスプリントで修正 medium 正確性は通常維持されるが出力が脆弱または無駄 次のサイクルで計画 low 主に見た目または保守性の問題 バックログ 出力フォーマット 発見事項をユーザーにこの順序で提示する： 重要度順の発見事項 （最も重要なものから） アーキテクチャ診断 （どの層が何を破損させ、なぜか） 優先度付き修正計画 （コードファースト、プロンプトファーストではない） お世辞や要約から始めないこと。システムが壊れている場合は直接そう述べる。 クイック診断質問 エージェントシステムを監査する際、以下に答える： # 質問 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 — エージェントハーネスをゼロから構築