| 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
rg "completion|chat\.create|messages\.create|llm\.invoke"
rg "memory.*admit|long.*term.*update|persist.*memory" --type py --type ts
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 — エージェントハーネスをゼロから構築
