codebase-audit

コードベース監査 — 適応型の詳細分析

プロジェクトの技術スタックに合わせてエージェント構成を調整し、構造化された検出事項を必須とし、レポートに含める前にCritical／Highの検出事項を敵対的に検証します。前回の監査台帳との差分（解決済み／未解決／新規）を取り、重大度順のレポートと段階的な修正ロードマップを出力する、包括的なコードベース監査です。

基本原則

1. 読み取り専用 — 監査エージェントは、対象内のファイルを作成、変更、削除してはなりません。すべてのエージェントプロンプトは、references/agent-prompts.md の読み取り専用の前置きから始めます。
2. セッションのモデルを継承 — すべてのエージェントで model パラメーターを省略し、セッションのモデル（通常は利用可能な中で最も高性能なモデル）を継承させます。セッションのモデルがファイル横断の推論に明らかに不十分な場合に限り、上位のモデルに変更します。このスキル内で特定のモデル名をハードコードしてはなりません。
3. 広さより深さ — 範囲を広く統合した少数のエージェントの方が、浅く調査する多数のエージェントより優れています。各エージェントは、ファイル境界をまたいで問題を追跡します。
4. 適応型 — エージェントの数と調査項目は、技術スタックとモードに応じて変わります。
5. 検証済みの検出事項 — Critical／Highの検出事項は、敵対的な検証を通過する必要があります。Mediumの検出事項は検証を経ずに進み、レポートでは unverified とラベル付けされます。

運用上の取り決め

• 直接実行できる作業：読み取り専用の調査、ローカルの依存関係監査、対象配下でのレポート作成、およびユーザーがこのスキルを呼び出した後の <target>/.audit/ 配下での台帳更新です。
• 事前に確認する必要がある作業：監査対象のプロジェクトソースファイル、依存関係マニフェスト、.gitignore、CI 設定、リモートの Issue、PR の状態、または依頼された監査／レポートの範囲外にあるものを編集することです。
• 機密情報の証拠：ファイル名、行番号、周辺のコードを保持しますが、検出事項、レポート、台帳のエントリーでは認証情報の値を [REDACTED] に置き換え、実際の値は決して再掲しません。この伏字化されたスニペットは、コードによる証拠の要件を満たします。
• 証拠に基づく異議申し立て：「問題なし」や「解決済み」という判断への異議申し立ては、ファイルの証拠、依存関係監査の出力、検証結果、または台帳の抜き打ち確認がある場合に限ります。
• フィードバックループ：繰り返し見落とされる問題は、セッション中だけのメモにとどめず、プロンプトの更新、台帳の照合ルール、またはフィクスチャ評価ケースに反映します。

注意点

• 依存関係監査コマンドは、アシスタントがたまたま使用している作業ディレクトリではなく、{TARGET_DIR} から実行する必要があります。
• Finder エージェントは、埋め込みバグのあるフィクスチャを監査する際、evals/expected-findings.json や評価用 README ファイルを読んではなりません。
• 前回の台帳で見落とされていたことは、検出事項が解決済みである証拠にはなりません。古い検出事項を resolved とマークする前に、ファイルを抜き打ち確認してください。

モード

モード	トリガー	エージェント	検証	台帳
full（デフォルト）	指定なしでの呼び出し、「全面审查」	技術スタックに応じて3～5個（＋任意の調査項目）	あり	あり
quick	引数に「quick」を指定、「快速体检」	2個（サイレントな機能低下とセキュリティ、データ整合性とレジストリ）	なし — すべての検出事項に unverified のラベルを付ける	あり

任意の調査項目（full モードのみ。ユーザーが求めた場合、またはリポジトリに明らかに必要な場合に有効化します）：

• tests — テストの品質：アサーションの強度、スキップマーカー、重要なパスのカバレッジ（エージェント6）
• concurrency — 競合、非同期処理内のブロッキング呼び出し、タスク／goroutine のリーク（エージェント7）

ワークフロー

フェーズ 0：検出と準備

1. スタックの検出：package.json／tsconfig.json → TS／JS、pyproject.toml／requirements.txt → Python、Cargo.toml → Rust、go.mod → Go、複数に該当 → フルスタック。
2. 規模の推定：tokei <target>（利用できない場合：find <target> -name '*.<ext>' | xargs wc -l）を実行します。ベンダーコードと生成コードは除外します。有効な規模が 400K LOC 以上の場合は、各エージェントの担当範囲をトップレベルディレクトリごとに分割し、レポートに分割した旨を記載します。
3. 除外対象（すべてのエージェントプロンプトに毎回含めます）：node_modules/、vendor/、target/、dist/、build/、.git/、ロックファイル、生成コード。
4. 台帳：<target>/.audit/findings.json が存在する場合は読み込みます。これは前回の監査結果を示すベースラインです（形式：references/ledger-format.md）。
5. 決定論的な依存関係の監査：{TARGET_DIR} から（アシスタントがたまたま使用している現在の作業ディレクトリではなく）、該当するツールをそれぞれ実行し、生の出力を「エラー処理とセキュリティ」プロンプトに渡します。
   • Rust：cargo audit
   • Node：npm audit
   • Python メタデータ（pyproject.toml／setup.py）：pip-audit .
   • Python の requirements（requirements.txt）：pip-audit -r requirements.txt
   • プロジェクトファイルがない場合の Python フォールバック：pip-audit .
   • Go：govulncheck ./... 必須ツールを利用できない場合、レポートに 依存审计降级跳过: <tool> と記載する必要があります。利用できない旨を黙って省略してはいけません。

フェーズ 1：評価軸の構成

検出したスタックに応じて構成を選びます。プロンプトの完全なテンプレートは references/agent-prompts.md にあります。読み取り専用の前置き文を追加し、各テンプレートに {TARGET_DIR}／{STACK_INFO} を挿入します。

フルスタック（5 エージェント） — フロントエンドとバックエンドの両方が存在する場合：

#	評価軸	対象範囲（統合後）
1	フロントエンドとバックエンドの契約	型の一貫性、レンダリングパイプライン、シリアライズの境界。両方を読み取ります。
2	データの整合性とフロー	エンドツーエンドのパイプライン追跡、フィールドの欠落、宣言と実行の不整合、レジストリ網羅範囲の整合性。
3	エラー処理とセキュリティ	暗黙の縮退、例外パターン、シークレット、インジェクション、安全でないデシリアライズ。
4	アーキテクチャとコード品質	レイヤー違反、肥大化したオブジェクト、重複／乖離、拡張コスト、レジストリとの相互参照。
5	設定と永続化	設定の完全性、キャッシュキー／整合性、DB スキーマ、一時ファイル、状態の永続化。

バックエンドのみ（4 エージェント）：#1 を「API 契約とデータ整合性」に置き換えます（#2 のデータフロー／レジストリ範囲を統合します。#2 も別途割り当ててはいけません）。#3～#5 はそのまま維持します。 フロントエンドのみ（3 エージェント）：コンポーネントアーキテクチャとレンダリング、エラー処理とコード品質、設定とビルド。 クイックモード（2 エージェント）：暗黙の縮退とセキュリティ（＝#3）、データ整合性とレジストリ（＝#2 の主要範囲）。

フォールバック時のエージェントタイプ（Workflow の代わりに Agent ツールを使用する場合）：エージェントの利用可否は環境によって異なります。現在のセッションで参照できるサブエージェントレジストリを確認し、そこにあるタイプ名だけを使用してください。別名を作ってはいけません（汎用の reviewer タイプはありません）。該当する専門タイプがない場合は、すべての評価軸で general-purpose（または環境のデフォルトの汎用タイプ）を使用します。プロンプトは自己完結しています。references/agent-prompts.md のマッピング例を参照してください。

フェーズ 2：オーケストレーション

推奨 — Workflow ツール（スキルの呼び出しはユーザーが明示的に選択した場合のみ）：references/workflow-template.md のスクリプトを使用します。このスクリプトは、各ファインダーの出力をスキーマに基づいて構造化された検出結果に変換し、各評価軸の Critical／High の検出結果を敵対的検証エージェントに直接渡します（待ち合わせは不要です。ほかの評価軸のスキャン中に検証を開始します）。

フォールバック — Agent ツール（Workflow を利用できない場合）：すべてのファインダーエージェントを 1 つのメッセージで起動します。プロンプトでは同じ JSON 出力を求めています。エージェントの応答後、Critical／High の検出結果ごとに検証エージェントを 1 つ起動します（こちらも 1 つのメッセージにまとめます）。検証には references/workflow-template.md のプロンプトを使用します。

フェーズ 3：重複排除と台帳の差分

重複排除：

• 同じファイルの同じ行にある場合 → 統合します。
• 複数のエージェントが同じ根本原因を見つけた場合 → 最も詳細なものを残し、エージェント間で確認済みであることを記載します（確信度が上がります）。
• 重大度が食い違う場合 → 最も高い重大度を使用します。

検証結果：

• confirmed=false の指摘はメインレポートに含めず、反証理由とともに付録「検証により反証」に記載します（作業の監査可能性を保つため）。
• 検証に失敗した場合、または検証者がいない場合 → 指摘を残し、unverified とラベル付けします。

台帳の差分（以前の台帳がない場合はスキップし、すべて new とします）：

• 以前の指摘と現在の指摘を (category, file, root-cause summary) で照合します。行番号では照合しません（行番号は変動するため）。
• 現在の指摘と一致しない以前の指摘 → ファイルを開いて抜き取り確認してから resolved とします。まだ存在しているのに見落としていた場合は、still-open として再追加します。
• 現在の指摘をすべて new / still-open に分類します。
• 更新した台帳を <target>/.audit/findings.json に書き込みます。リポジトリが追跡対象であり、.audit/ が無視されていない場合は、.gitignore への追加を提案します（自分で .gitignore を編集しないでください）。

フェーズ 4：レポート

レポート全文を <target>/audit-report-YYYY-MM-DD.md に書き込み、その後、重大度ごとの件数、主な Critical、台帳の差分（N resolved / N still-open / N new）、依存関係監査の状況、ロードマップをチャットで要約して投稿します。

レポート本文の要件：

• 問題の説明、影響分析、修正案には日本語を使用します。コード識別子、パス、エラーメッセージは元の形式のままにします。
• 各指摘を事実／推論／推奨に分けます。指摘そのものは file:line を含む事実とし、影響は確信度を伴う推論、修正案は前提を明記した推奨とします。
• 推論のみの指摘は、検証者がユーザーに見える影響またはセキュリティへの影響を確認していない限り、重大度を Medium より高くできません。

レポートの構成：

# [Project] Codebase Audit Report
> Date / Target / Stack / Mode / Agents / Dependency audit / Previous audit: date or "none"

## Summary
| Level | Count | Verified | Key Areas |

## Delta vs Previous Audit   (omit if first audit)
Resolved: N (list) | Still-open: N | New: N

## Critical (Fix Immediately)
Per finding: file:line, code snippet, risk, fix suggestion, verify status.

## High / P1 (Fix This Week)     — grouped by category
## Medium / P2 (Plan to Fix)     — labeled unverified where applicable

## Refuted by Verification       — appendix: finding + refutation reason

## Repair Roadmap
| Phase | Scope | Est. Files |

重大度の分類

レベル	基準
Critical	データ損失、レンダリングの失敗、セキュリティ脆弱性、または現在ユーザーに影響している機能の完全な破損
High/P1	気付かれない劣化（ユーザーに誤った、または不完全な出力が表示される）、データ切り捨てを引き起こす型の不一致、出力が空になる設定の欠落、開発を阻むアーキテクチャ違反
Medium/P2	コードの重複、一貫性のないパターン、最適でないエラー処理、機能を損なわないものの開発を遅らせる技術的負債

参照資料

• references/agent-prompts.md — 読み取り専用の前置きとプロンプトテンプレート（エージェント 1–7）
• references/stack-patterns.md — スタックごとの検索パターン
• references/workflow-template.md — ワークフロースクリプト、指摘／判定スキーマ、検証プロンプト
• references/ledger-format.md — 台帳の JSON スキーマと照合ルール
• evals/ — バグを仕込んだフィクスチャ。評価では evals/expected-findings.json に対する再現率を測定します