silent-degradation-audit

サイレント劣化監査スキル

概要

コードベース全体のサイレント劣化を検出する、本番運用に対応したスキルです。6つの専門カテゴリ別エージェント、マルチエージェント検証パネル、収束検出を備えた複数ウェーブの監査システムを使用します。CyberGym コードベースで実戦検証済みで、約250件のバグを発見しました。

このスキルを使用するタイミング

次の場合に使用してください：

• コードに信頼性の問題があるものの、原因箇所が不明な場合
• システムが、オペレーターに通知されないままサイレントに障害を起こす場合
• エラー処理は実装されているものの、その有効性が不明な場合
• 複数の障害モードを網羅的に監査する必要がある場合
• 本番環境へのデプロイを準備する場合
• サイレント障害後に事後分析を行う場合

次の場合には使用しないでください：

• コードスタイルやフォーマットの問題（リンターを使用してください）
• パフォーマンスの最適化（プロファイラーを使用してください）
• セキュリティの脆弱性（セキュリティスキャナーを使用してください）
• 単発の簡単なコードレビュー（/analyze を使用してください）

主な機能

複数ウェーブによる段階的な監査

• ウェーブ 1：広範囲をスキャンし、明白な問題を検出します（全体の40～50％）
• ウェーブ 2～3：より深く分析し、隠れた問題を検出します（30～40％）
• ウェーブ 4～6：エッジケースや微妙な問題を検出します（10～20％）
• 収束：新しい検出結果が10件未満、またはウェーブ 1 の5％未満になった時点で停止します

6つのカテゴリ別エージェント

1. 依存関係の障害（カテゴリ A）：「X が停止したらどうなりますか？」
2. 設定エラー（カテゴリ B）：「設定が間違っていたらどうなりますか？」
3. バックグラウンド処理（カテゴリ C）：「バックグラウンド処理が失敗したらどうなりますか？」
4. テストの有効性（カテゴリ D）：「テストは実際に障害を検出できますか？」
5. オペレーターからの可視性（カテゴリ E）：「エラーはオペレーターに見えていますか？」
6. 機能スタブ（カテゴリ F）：「このコードは名前のとおりに実際に動作しますか？」

マルチエージェント検証パネル

• 3つのエージェントが検出結果をレビューします：セキュリティ、アーキテクト、ビルダー
• 検出結果の検証には、3者中2者の合意が必要です
• 誤検出や不要な変更を防ぎます
• 強い合意と弱い合意を追跡します

言語に依存しない設計

言語固有のパターンを使用し、9つの言語をサポートします：

• Python、JavaScript、TypeScript
• Rust、Go、Java、C#
• Ruby、PHP

統合モード

単独での呼び出し

対象を絞った監査を直接スキルから呼び出します：

/silent-degradation-audit path/to/codebase

品質監査ワークフロー内のサブループ

quality-audit-workflow のフェーズ 2 として統合します：

quality-audit-workflow calls silent-degradation-audit
→ Returns findings to quality workflow
→ Quality workflow applies fixes
→ Continues to next phase

使用方法

基本的な使い方

# Audit entire codebase
/silent-degradation-audit .

# Audit specific directory
/silent-degradation-audit ./src

# With custom exclusions
/silent-degradation-audit . --exclusions .my-exclusions.json

設定

コードベースのルートに .silent-degradation-config.json を作成します：

{
  "convergence": {
    "absolute_threshold": 10,
    "relative_threshold": 0.05
  },
  "max_waves": 6,
  "exclusions": {
    "patterns": ["*.test.js", "test_*.py", "**/__tests__/**"]
  },
  "categories": {
    "enabled": [
      "dependency-failures",
      "config-errors",
      "background-work",
      "test-effectiveness",
      "operator-visibility",
      "functional-stubs"
    ]
  }
}

除外リスト

グローバル除外

~/.amplihack/.claude/skills/silent-degradation-audit/exclusions-global.json を編集します：

[
  {
    "pattern": "*.test.*",
    "reason": "Test files excluded from production audits",
    "category": "*"
  },
  {
    "pattern": "**/vendor/**",
    "reason": "Third-party code",
    "category": "*"
  }
]

リポジトリ固有の除外

リポジトリのルートに .silent-degradation-exclusions.json を作成します：

[
  {
    "pattern": "src/legacy/*.py",
    "reason": "Legacy code being replaced",
    "category": "*",
    "wave": 1
  },
  {
    "pattern": "api/endpoints.py:42",
    "reason": "Empty dict is valid API response",
    "category": "functional-stubs",
    "type": "exact"
  }
]

出力

レポート形式

.silent-degradation-report.md を生成します：

# Silent Degradation Audit Report

## Summary

- **Total Waves**: 4
- **Total Findings**: 137
- **Converged**: Yes
- **Convergence Ratio**: 4.2%

## Convergence Progress

Wave 1: ██████████████████████████████████████████████████ 120
Wave 2: ███████████████████████████ 65 (54.2% of Wave 1)
Wave 3: ████████ 18 (15.0% of Wave 1)
Wave 4: ██ 5 (4.2% of Wave 1)

Status: ✓ CONVERGED
Reason: Relative threshold met: 4.2% < 5.0%

## Findings by Category

### dependency-failures (42 findings)

- High: 15
- Medium: 20
- Low: 7

[... continues for all 6 categories ...]

検出結果の形式

.silent-degradation-findings.json を生成します：

[
  {
    "id": "dep-001",
    "category": "dependency-failures",
    "severity": "high",
    "file": "src/payments.py",
    "line": 89,
    "description": "Payment API failure silently falls back to mock",
    "impact": "Production system using mock payments, no real charges",
    "visibility": "None - no logs or metrics",
    "recommendation": "Add explicit failure logging and metric, or fail fast",
    "wave": 1,
    "validation": {
      "result": "VALIDATED",
      "consensus": "strong",
      "votes": {
        "security": "APPROVE",
        "architect": "APPROVE",
        "builder": "APPROVE"
      }
    }
  },
  ...
]

ワークフローの詳細

フェーズ 1：初期化

1. しきい値を設定して収束トラッカーを作成します
2. 除外マネージャーを初期化します
3. 監査の状態を設定します

フェーズ 2：言語の検出

1. コードベースをスキャンし、ファイル拡張子を調べます
2. 言語を特定します（5ファイル超、またはしきい値の5％超）
3. 言語固有のパターンを読み込みます

フェーズ 3：除外の読み込み

1. スキルディレクトリからグローバル除外を読み込みます
2. リポジトリ固有の除外を読み込みます
3. 1つの除外リストに統合します

フェーズ 4：ウェーブループ

収束するまで、各ウェーブで次を実行します。

1. カテゴリ分析（6 エージェントを並列実行）

   • 各エージェントがカテゴリ固有の問題をスキャンします
   • 言語固有のパターンを使用します
   • 以前の検出結果を除外します

2. 検証パネル（3 エージェントを並列実行）

   • セキュリティエージェントがセキュリティへの影響をレビューします
   • アーキテクトエージェントが設計への影響をレビューします
   • ビルダーエージェントが実装の実現可能性をレビューします

3. 投票集計

   • 2/3 の合意（APPROVE）を必要とします
   • 強い合意と弱い合意を追跡します
   • 結論が出ない場合は、人によるレビューのためにフラグを付けます

4. 除外フィルタリング

   • グローバルおよびリポジトリ固有の除外を適用します
   • 重複を除外します

5. 状態の更新

   • 新たな検出結果を合計に追加します
   • ウェーブのメトリクスを記録します

6. 収束チェック

   • 絶対値：新たな検出結果が 10 件未満
   • 相対値：Wave 1 の検出結果の 5% 未満
   • 収束した場合は終了します

フェーズ 5：レポートの生成

1. 収束プロットを生成します
2. メトリクスの概要を計算します
3. 検出結果を種類と重大度で分類します
4. Markdown レポートを作成します
5. JSON 形式の検出結果を書き出します

アーキテクチャ

ディレクトリ構造

.claude/skills/silent-degradation-audit/
├── SKILL.md                    # This file
├── reference.md                # Detailed patterns and examples
├── examples.md                 # Usage examples
├── patterns.md                 # Language-specific patterns
├── README.md                   # Quick start
├── category_agents/            # 6 category agent definitions
│   ├── dependency-failures.md
│   ├── config-errors.md
│   ├── background-work.md
│   ├── test-effectiveness.md
│   ├── operator-visibility.md
│   └── functional-stubs.md
├── validation_panel/           # Validation panel specs
│   ├── panel-spec.md
│   └── voting-rules.md
├── recipe/                     # Recipe-based workflow
│   └── audit-workflow.yaml
└── tools/                      # Python utilities
    ├── exclusion_manager.py
    ├── language_detector.py
    ├── convergence_tracker.py
    └── __init__.py

コンポーネントの役割

カテゴリエージェント：

• コードベースをスキャンし、カテゴリ固有の問題を検出します
• 言語固有のパターンを使用します
• 重大度、影響、推奨事項を含む検出結果を生成します

検証パネル：

• 複数の観点から検出結果をレビューします
• APPROVE／REJECT／ABSTAIN に投票します
• 2/3 の合意を必要とします

収束トラッカー：

• ウェーブごとの検出結果を追跡します
• 収束メトリクスを計算します
• 停止するタイミングを判断します

除外マネージャー：

• 除外リストを読み込み、統合します
• パターンに基づいて検出結果をフィルタリングします
• 新たな除外項目を追加します

言語検出器：

• コードベースで使用されている言語を特定します
• 言語固有のパターンを読み込みます
• 9 言語をサポートします

ベストプラクティス

初回監査の実施

1. 小さな範囲から始める：まず単一のサービス／モジュールを監査します
2. Wave 1 を慎重にレビューする：ベースラインを確立します
3. 除外を調整する：誤検出を除外リストに追加します
4. 修正を検証する：広範囲に適用する前に、修正をテストします

除外の管理

除外を追加する場合：

• 誤検出（実際には問題ではない検出結果）
• 意図的な設計（現状の動作が正しい）
• レガシーコード（今すぐ修正する価値がない）
• サードパーティコード（変更できない）

除外を追加しない場合：

• 修正したくない実際の問題
• 今すぐ修正する時間がない問題
• 難しそうな問題

より良い方法：実際の問題を修正し、重大度に応じて優先順位を付けます。

検証の調整

誤検出が多すぎる場合：

• 検証パネルのプロンプトを見直します
• 合意のしきい値を上げます（全員一致を必須にします）
• カテゴリ固有の検証ルールを追加します

実際の問題を見逃している場合：

• カテゴリエージェントのパターンを見直します
• 言語固有のパターンを追加します
• 合意のしきい値を下げます（1/3 の賛成で承認）

ウェーブの管理

一般的なウェーブの特徴：

• Wave 1：検出結果の 40～50%（明白な問題）
• Wave 2：25～30%（より深い問題）
• Wave 3：15～20%（見つけにくい問題）
• Wave 4 以降：各 10% 未満（境界ケース）

ウェーブが収束しない場合：

• 検出結果の重複を確認します（除外が機能していない可能性があります）
• カテゴリエージェント間の重複を見直します（同じ問題を検出している可能性があります）
• 収束のしきい値を下げることを検討します

メトリクスとモニタリング

成功のメトリクス

次の項目を継続的に追跡します。

Audit Success:
- Convergence reached: Yes/No
- Waves to convergence: 4 (target: 3-5)
- Total findings: 137 (varies by codebase)
- Validation rate: 75% (target: 60-80%)

Finding Distribution:
- High severity: 15% (target: < 20%)
- Medium severity: 45% (target: 40-60%)
- Low severity: 40% (target: 30-50%)

Panel Effectiveness:
- Strong consensus: 60% (target: > 50%)
- Weak consensus: 30% (target: 20-40%)
- Inconclusive: 10% (target: < 10%)
- Abstention rate: 5% (target: < 10%)

品質指標

健全な監査：

• 3～5 ウェーブで収束します
• 検証率は 60～80% です
• 強い合意は 50% を超えます
• 棄権率は 10% 未満です

警告サイン：

• 6 ウェーブを過ぎても収束しない（エージェントが同じ問題を検出している）
• 検証率が 95% を超える（形式的な追認）
• 検証率が 40% 未満（厳しすぎる）
• 結論が出ない割合が 20% を超える（コンテキストが不十分）

トラブルシューティング

「監査が収束しない」

症状：収束せずに最大ウェーブ数に達する

原因：

• カテゴリエージェントが重複する問題を検出している
• 除外フィルタリングが機能していない
• 収束のしきい値が厳しすぎる

解決策：

1. 検出結果の重複を確認します
2. 除外パターンが一致していることを確認します
3. 相対しきい値を 10% に上げます
4. 最大ウェーブ数を 5 に減らします

「誤検出が多すぎる」

症状：検証率が 95% を超えているが、問題ではないものが多い

原因：

• カテゴリエージェントが過剰に反応している
• 検証パネルの基準が緩すぎる
• パターンがコードベースに合わせて調整されていない

解決策：

1. カテゴリエージェントのパターンを見直す
2. 誤検出パターンを除外する設定を追加する
3. 全員一致の検証を必須にする（3/3）
4. 言語固有のパターンを調整する

「実際の問題を見逃す」

症状：既知の問題が検出結果に含まれていない

原因：

• カテゴリエージェントに不足がある
• 除外範囲が広すぎる
• 検証パネルの基準が厳しすぎる

解決策：

1. 問題がいずれかのカテゴリに該当するか確認する
2. 除外リストに範囲が広すぎるパターンがないか見直す
3. 合意のしきい値を 1/3 に下げる
4. 見逃した問題に対する具体的なパターンを追加する

「検証パネルが判断を保留する」

症状：保留率が高い（20% 超）

原因：

• 検出結果のコンテキストが不十分
• エージェントのプロンプトが不明確
• 検出結果がエージェントの専門外である

解決策：

1. 検出結果にコードのコンテキストを追加する
2. エージェントのプロンプトを見直し、改善する
3. 4 つ目の「ジェネラリスト」エージェントを追加する
4. 検出結果の説明を改善する

高度な設定

カスタムカテゴリエージェント

category_agents/custom.md にカスタムカテゴリエージェントを作成します：

# Category Custom: My Special Cases

## Core Question

"What happens when [specific scenario]?"

## Detection Focus

[Patterns to detect...]

## Language-Specific Patterns

[Language examples...]

次に、設定で有効にします：

{
  "categories": {
    "enabled": [
      "dependency-failures",
      "config-errors",
      "background-work",
      "test-effectiveness",
      "operator-visibility",
      "functional-stubs",
      "custom"
    ]
  }
}

カスタム検証パネル

異なるエージェントを使用して検証パネルを上書きします：

# In recipe/audit-workflow.yaml
validation_panel:
  agents:
    - security
    - architect
    - builder
    - domain-expert # Add domain-specific agent

  consensus:
    required: 0.75 # Require 3/4 approval

段階的な展開

コードベースを段階的に監査します：

# Phase 1: Critical services only
/silent-degradation-audit ./services/payments ./services/auth

# Phase 2: All services
/silent-degradation-audit ./services

# Phase 3: Full codebase
/silent-degradation-audit .

関連項目

• reference.md - 詳細な技術リファレンス
• examples.md - 実際の使用例
• patterns.md - 言語固有の劣化パターン
• README.md - クイックスタートガイド
• category_agents/ - 各カテゴリエージェントのドキュメント
• validation_panel/ - 検証パネルの仕様

変更履歴

バージョン 1.0.0（2025-02-24）

• 初回リリース
• 6 つのカテゴリエージェント（A～F）
• マルチエージェント検証パネル（2/3 の合意）
• 収束検出（2 つのしきい値）
• 言語非依存（9 言語）
• CyberGym（約 250 件のバグ）で実環境テスト済み
• 統合モード：スタンドアロン＋サブループ