quality-audit

品質監査ワークフロー

目的

コードベース全体を対象に、体系的かつ並列で品質監査を実施し、PR の作成による自動修正と、PM が優先順位を付けた推奨事項を提供します。

起動する条件

次のような語句に言及すると、自動的に読み込まれます。

• 「品質監査」または「コード監査」
• 「コードベースのレビュー」または「コード全体のレビュー」
• 「リファクタリングの機会」または「技術的負債の監査」
• 「モジュールの品質チェック」または「アーキテクチャレビュー」
• 複数のエージェントによる「並列分析」

実行内容

次の 7 フェーズのワークフローを実行します。

1. プロジェクトを把握します（調査フェーズ）
2. コードベースを分割し、複数のエージェントで並列に監査します
3. 発見した問題ごとに GitHub issue を作成します 3.5. 最近の PR と照合して検証します（誤検出を防止）
4. 残った issue ごとに、並列のワークツリーで PR を生成します
5. PM アーキテクトとともに PR をレビューし、優先順位を付けます
6. 統合した推奨事項をマスター issue で報告します

クイックスタート

User: "Run a quality audit on this codebase"
Skill: *activates automatically*
       "Beginning quality audit workflow..."

7 つのフェーズ

フェーズ 1：プロジェクトの把握

• プロジェクトの構成を調査するワークフローを実行します
• モジュール、依存関係、エントリーポイントを整理します
• 既存のパターンとアーキテクチャを把握します

フェーズ 2：並列品質監査

• コードベースを論理的なセクションに分割します
• セクションごとに複数の種類のエージェント（アナライザー、レビュアー、セキュリティ、オプティマイザー）を配置します
• PHILOSOPHY.md の基準を徹底して適用します
• モジュールのサイズ、複雑さ、単一責任を確認します

フェーズ 3：issue の作成

• 発見事項ごとに GitHub issue を作成します
• 重要度、場所、推奨事項を記載します
• 適切なラベルを付けます
• 一意の ID、キーワード、ファイルのメタデータを追加します

フェーズ 3.5：監査後の検証 [NEW]

• 過去 30 日間（設定可能）にマージされた PR をスキャンします
• PR と issue の一致度を表す信頼度スコアを計算します
• 信頼度の高い一致（≥90%）を自動的にクローズします
• 信頼度が中程度の一致（70-89%）に検証用のタグを付けます
• issue と PR の相互参照を追加します
• 目標：誤検出率を 5% 未満に抑えます

フェーズ 4：並列 PR 生成

• 未解決の issue ごとにワークツリーを作成します（worktrees/fix-issue-XXX）
• 各ワークツリーで DEFAULT_WORKFLOW.md を実行します
• 未解決であることが確認された issue ごとに修正 PR を生成します

フェーズ 5：PM レビュー

• pm-architect スキルを呼び出します
• PR をカテゴリと優先度でグループ化します
• 修正間の依存関係を特定します

フェーズ 6：マスターレポート

• マスター GitHub issue を作成します
• 関連するすべての issue と PR にリンクします
• 推奨事項を含む、優先順位付きのアクションプランを作成します

哲学の適用

このワークフローでは、次の原則を徹底して適用します。

• 徹底したシンプルさ：過剰に設計されたモジュールを指摘します
• モジュールサイズの上限：モジュールあたり 300 LOC 未満を目標とします
• 単一責任：1 つの部品につき目的は 1 つにします
• ゼロ BS：スタブ、TODO、デッドコードを認めません
• フォールバックの禁止 (#2805, #2810)：サイレントな劣化やエラーを握りつぶすパターンを検出します
• 構造分析 (#2809)：サイズの大きすぎるファイル、深くネストされたコード、複雑に絡み合った依存関係を指摘します

検出カテゴリ

標準カテゴリ

カテゴリ	検出する内容
セキュリティ	ハードコードされたシークレット、入力検証の欠如、クエリ内での文字列補間
信頼性	タイムアウトの欠如、bare except 句、未処理の非同期処理
デッドコード	未使用のインポート、到達不能な分岐、古い TODO
テスト不足	テストのないファイル、アサーションのないテスト
ドキュメント不足	docstring のない公開関数、古いドキュメント

拡張カテゴリ

| カテゴリ | 検出する内容 | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | -------------------------- | | サイレントフォールバック | except: pass、デフォルト値をサイレントに返す広範な例外処理、失敗を隠すフォールバックチェーン、設定の欠落を隠す ?? defaultValue、必須値に対する dict.get(key, default)、シェルスクリプト内の | | fallback | | エラーの握りつぶし | 再送出・再スローしない catch ブロック、エラーを None/null に変換する処理、例外を破棄する包括的な例外処理、ログ出力だけを行う catch ブロック、空の catch ブロック、false／デフォルト値／空のコレクションを返す catch (Exception) | | 結果の破棄 | ファイア・アンド・フォーゲットの非同期処理（_ = Task()、エラー処理のない asyncio.create_task()）、確認されない HTTP レスポンスステータス、破棄される戻り値、個別の失敗を確認しない Task.WhenAll／Promise.all／asyncio.gather、確認されない subprocess.run() | | シェルのアンチパターン | \|\| true、>/dev/null 2>&1、2>/dev/null、set +e、\|\| fallback_command、set -euo pipefail の欠落 | | サイレントな切り詰め | ログ出力のない Take(N)／[:N]／.slice(0,N)、処理すべき項目をサイレントに除外する .Where()／リスト内包表記、範囲外のログ出力を伴わない文字列の部分切り出し | | 非同期処理のアンチパターン | async void（C#）、.Result／.Wait() による同期的な非同期処理、await されないコルーチン／Promise、同期なしの共有可変状態、伝播されない CancellationToken、破棄されない Timer／CancellationTokenSource | | 設定の不整合 | デプロイ設定で定義されている環境変数を、コード内でサイレントなフォールバックを使って読み込む処理、ステージング環境や本番環境に漏れる可能性のある IsDevelopment() ガード、インフラが提供しない設定を想定するサービス | | 検証の不足 | 入力検証のない API エンドポイント、SQL／GraphQL／Cypher での文字列補間、ページネーション上限の欠落、リクエストサイズ上限の欠落、検証なしのユーザー入力による列挙型の解析、null チェックなしで外部データのデシリアライズ結果を信頼する処理 | | ヘルス状態と可観測性 | Unhealthy が適切な場合に Degraded と報告する処理、バックグラウンドワーカーの失敗が /health に反映されないこと、メトリクスのないログのみのエラー処理、恒久的なエラーを一時的なエラーとして扱う処理（デッドレターにせず再試行する）、部分的な成功を完全な成功として扱う処理 | | 再試行のアンチパターン | 再試行上限に達した後、サイレントに終了する再試行ループ、アラートを出さずに開くサーキットブレーカー、最後のエラーを送出せずに最終的に諦める再試行ロジック | | 構造上の問題 | 500 LOC を超えるファイル、50 行を超える関数、4 レベルを超えるネスト、5 個を超えるパラメーター、循環インポート | | ドキュメント | 特定時点の内容、プロらしくない文体（海賊風の言い回し、チャットボットの痕跡）、品質や正確性の不足 | | ハードコードされた上限 | 設定できない数値上限（[:N]、max_X = N）、ログ出力のないサイレントな切り詰め、処理上限によるデータ損失 |

マルチエージェント検証（v3.0）

すべての指摘事項は、3つの独立したエージェント（アナライザー、レビュアー、アーキテクト）によって検証されます。2つ以上のエージェントが一致した場合にのみ、指摘事項が確認済みとなります。これにより、修正を試みる前に誤検出を排除できます。

深度を段階的に高める反復ループ（v3.0）

Cycle 1: SEEK → VALIDATE (3 agents) → FIX → decision
Cycle 2: SEEK (deeper) → VALIDATE → FIX → decision
Cycle 3: SEEK (deepest) → VALIDATE → FIX → decision
...continues if thresholds not met

ループのルール：

• 最低でも必ず3サイクル実行します
• 以下の場合は3サイクルを超えて続行します：重大度が高い、またはクリティカルな新しい指摘事項が見つかった場合、あるいは新しい中程度の指摘事項が3件を超える場合
• 最大6サイクル（安全弁）
• 各サイクルでは、新たな視点でより深く調査し、以前の指摘事項に異議を唱えます
• 修正には、完全なDEFAULT_WORKFLOWの手法（理解 → テスト → 実装 → 検証）を使用します
• サイクルごとの全件修正ルール（#2842）： サイクル内で確認された指摘事項は、サイクル完了前にすべて修正する必要があります。一部だけのサイクルは認められません。指摘事項を「フォローアップの課題」や「次のサイクル」に持ち越すことはできません。SEEKで問題が見つかった場合、FIXはそのすべてに対処する必要があります。
• 新しい指摘事項に基づくループ判定（#2842）： 続行するかどうかは、過去の指摘事項が未修正のまま残っているかどうかではなく、現在のサイクルで新しい問題が見つかったかどうかに基づいて判定します（全件修正ルールにより、過去の指摘事項が未修正のまま残ることはありません）。
• 修正の検証ステップ： 修正後、確認済みの指摘事項と修正結果を照合し、対応漏れがないことを確認します。

レシピを使って実行：

amplihack recipe execute quality-audit-cycle.yaml --context '{"target_path": "src/amplihack", "min_cycles": "3", "max_cycles": "6"}'

設定

レシピのコンテキストまたは環境変数でデフォルト値を上書きできます。

構造化入力（#2843に基づくレシピのコンテキスト）：

入力	デフォルト値	説明
target_path	src/amplihack	監査対象のディレクトリ
min_cycles	3	監査サイクルの最小回数
max_cycles	6	サイクルの最大回数（安全弁）
validation_threshold	2	一致が必要な検証者の最小数（3人中）
severity_threshold	medium	報告する最低重大度
module_loc_limit	300	この行数を超えるモジュールにフラグを立てます
fix_all_per_cycle	true	次のサイクルに進む前にすべての指摘事項を修正します（#2842）
categories	（すべて）	チェックするカテゴリのカンマ区切りリスト

利用可能なカテゴリ：security、reliability、dead_code、silent_fallbacks、 error_swallowing、result_dropping、shell_anti_patterns、silent_truncation、 async_anti_patterns、config_divergence、validation_gaps、health_observability、 retry_anti_patterns、structural、hardcoded_limits、test_gaps、doc_gaps、documentation

実行例：

amplihack recipe execute quality-audit-cycle.yaml --context '{
  "target_path": "src/amplihack/fleet",
  "min_cycles": "3",
  "max_cycles": "6",
  "severity_threshold": "medium",
  "module_loc_limit": "300",
  "fix_all_per_cycle": "true",
  "categories": "security,reliability,dead_code,silent_fallbacks,error_swallowing"
}'

コア設定（環境変数）：

• AUDIT_PARALLEL_LIMIT：同時に処理できるワークツリーの最大数（デフォルト：8）

フェーズ3.5の検証設定：

• AUDIT_PR_SCAN_DAYS：最近のPRを検索する日数（デフォルト：30）
• AUDIT_AUTO_CLOSE_THRESHOLD：自動クローズに必要な信頼度（%）（デフォルト：90）
• AUDIT_TAG_THRESHOLD：タグ付けに必要な信頼度（%）（デフォルト：70）
• AUDIT_ENABLE_VALIDATION：フェーズ3.5を有効にします（デフォルト：true）