everything-claude-code/docs/ja-JP/skills/agent-architecture-audit/SKILL.md

---
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` を使用してアンチパターンを検索する：

```bash
# プロンプトテキストのみで表現されたツール要件（コードでなく）
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 の散文を信頼できる内部プロトコルとして扱わない。
- コードがそれを強制しないのにプロンプトテキストの「ツールを必ず使用する」を受け入れない。
- 発見事項を直接的に、エビデンスに基づいて、重要度順に維持する。

## レポートスキーマ

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

```json
{
  "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` — エージェントハーネスをゼロから構築