audit

コード監査スキル

目的

コードベースまたはファイルの一部を対象に、言語に依存しない徹底的な監査を実施し、重大度順にランク付けした指摘事項を含む構造化レポートを作成します。references/report-template.md のテンプレートに従い、レポートをプロジェクトのルートに Markdown ファイルとして保存します。

努力量

対象範囲内のコードを一行残らず読みます。流し読みしたり、抜き取り調査をしたり、ヒューリスティックに基づいてファイルを飛ばしたりしてはいけません。外部入力から処理レイヤーを経て出力やストレージに至るデータフローを追跡します。モジュールの境界を越えて呼び出しチェーンをたどり、コンポーネント間の相互作用によってのみ発生する問題を検出します。対象範囲が広すぎて一度に監査できない場合は、複数のサブエージェントに並行して作業を割り当てます（分割方法についてはステップ 4 を参照してください）。

ワークフロー

ステップ 1 — 対象範囲の確定

ユーザーのプロンプトから監査対象範囲を特定します。ユーザーが指定する対象には、次のようなものがあります。

• リポジトリ全体または作業ディレクトリ。
• 1 つ以上のディレクトリ（例：src/、lib/api/）。
• 特定のファイルのリスト。
• 自然言語で説明された機能領域（例：「認証フロー」）。
• ファイル内の特定の関数、クラス、またはコード領域。この場合、指定されたコードとその直接の依存先に分析を限定し、ファイル全体を監査しないでください。

ユーザーが指定したファイルまたはディレクトリが存在しない場合は、存在しないパスについて警告し、存在するファイルの監査を続けます。指定されたパスが一つも存在しない場合は、作業を中止して確認を求めます。

プロンプトに対象範囲を判断するための情報が不足している場合は、作業を開始する前に確認の質問を 1 つだけします。対象範囲を推測してはいけません。境界が曖昧な監査では、信頼できる結果を得られません。

ユーザーが再監査を依頼した場合は、プロジェクトのルートで AUDIT-REPORT-*.md に一致するファイルを検索します。レポートが複数ある場合は、日付が最も新しいものを使用します。デフォルトでは、元の監査と同じ対象範囲を使用します。ユーザーがより迅速な監査を希望する場合は、以前に指摘事項があったファイルのみに範囲を絞ることを提案できますが、黙って範囲を狭めてはいけません。以前問題がなかったファイルにも、新たな問題が生じている可能性があります。以前のレポートがある場合は、新しいレポートに、以前の指摘事項のうち解消されたものと、残っているものを記載し、差分を確認できるようにします。

対象範囲を確定したら、その範囲に含まれるすべてのファイルを列挙します。ユーザーが明示的に対象に含めない限り、生成ファイル（例：ロックファイル、コンパイル済み出力、ベンダー依存関係、圧縮済みバンドル）は除外します。ソースにコミットされている生成コード（protobuf スタブ、OpenAPI クライアント、ORM モデル）については、変更マーカーを確認します。手書きの追加コードが含まれている場合、または「DO NOT EDIT」ヘッダーが削除されている場合は、対象に含めます。ファイル単位の分析から生成コードやベンダーコードを除外する場合でも、フェーズ B のファイル横断分析では、想定される検証や安全性の保証が提供されているかを判断するため、除外対象コードへのデータフローを追跡します。指摘事項は除外対象コード内ではなく、その境界に対して報告します。

確定した対象範囲をユーザーに伝えます。対象範囲が明確な場合は、確認を待たずにすぐに作業を進めます。

ステップ 2 — カテゴリの選択と確認

ユーザーの依頼とコードベースを分析し、以下の全カテゴリから、監査に最も関連するものを選択します。

1. セキュリティ脆弱性
2. 競合状態と並行処理
3. デッドコード
4. アンチパターンとコードの問題点
5. パフォーマンス
6. 正確性
7. エラー処理の不足
8. テストの品質

ユーザーが明示的に依頼した内容と、コードから自然に必要とされる内容の両方を考慮します。たとえば、コードベースで非同期パターンが使われている場合、ユーザーが言及していなくても並行処理のカテゴリを含めます。

広範な依頼（「このコードベースを監査してください」など）の場合は、デフォルトですべてのカテゴリを対象とし、確認を求めずに進めます。選択が自明でない場合、つまりコード分析に基づいて一部のカテゴリを選んだ場合や、ユーザーの依頼から対象となるカテゴリが不明確な場合に限り、選択したカテゴリを提示して確認を求めます。

体系的な分析の基礎として、references/categories.md のチェックリストを使用します。コードベースに存在する言語、フレームワーク、パラダイムに該当しない個々のチェック項目は省略します。コードベースにテストファイルがない場合は、テストが存在しないことを示す指摘を 1 件だけ報告し、テストの品質に関する個々のチェック項目の評価は行いません。

ステップ 3 — 意図の把握

分析を始める前に、コードベースを調査して、文書化された意図（設計上の決定、トレードオフ、規約、既知の制約）を確認します。これにより、意図的な選択と実際の問題を区別するための背景情報が得られ、誤検出を減らせます。

3 つのサブエージェントを並行して実行します。

• ドキュメントスキャナー — 監査範囲にかかわらず、プロジェクト全体のすべてのドキュメントファイルを読み、明示された決定、トレードオフ、制約、規約を抽出します。
• コード意図スキャナー — 対象範囲内のソースファイルを検索し、コードの選択における「理由」を示す根拠コメント、抑制ディレクティブ、説明的なブロックコメントを抽出します。
• 履歴スキャナー — 対象範囲内のファイルについて、変更理由を説明しているコミットメッセージに注目し、Git のコミット履歴から意図を示す情報を抽出します。

このステップは、コードベースの規模にかかわらず常に実行します。ステップ 4 で分割方式を使用する大規模なコードベースでは、同じ Intent Brief をすべての分割担当サブエージェントと共有します。

出力は、情報源ごとではなくテーマごとに整理した構造化された Intent Brief です（「アーキテクチャ上の決定」「意図的なトレードオフ」「規約と標準」「既知の制約と技術的負債」「抑制された警告と意図的な逸脱」）。項目数は 100 件以下を目安とし、確認済みの監査カテゴリとの関連性が高いものを優先します。

意図の調査で項目が見つからなかった場合、Intent Brief は空になります。その場合は相互参照を行わずに通常どおり分析を進め、レポートの「背景と意図」セクションに、文書化された意図を示す情報が見つからなかったことを記載します。

サブエージェントへの詳細なプロンプト、抽出ルール、Intent Brief のテンプレートについては、references/intent-discovery.md を参照してください。

ステップ 4 — 体系的な分析

大規模コードベースの分割

対象範囲が50ファイルまたはコード10,000行を超える場合（どちらか一方のしきい値を超えれば該当します）、表面的な分析を避けるため、並列サブエージェントを使用します。これらのしきい値は意図的に選言的に設定されています。小さなファイルが多数あるプロジェクトも、大きなファイルが少数あるプロジェクトと同様に、並列化のメリットがあります。

• 対象範囲を論理的なモジュールまたはディレクトリツリーに分割します。各分割の規模がほぼ等しくなるようにします。複数の独立したサービスを含むモノレポでは、まずサービスごとに分割します。サービス境界はレイヤー境界より優先されます。単一のサービス内では、ファイル数を任意に分けるのではなく、アーキテクチャレイヤー（例：データアクセス、ビジネスロジック、API ハンドラー）に沿った境界を優先します。
• 分割ごとにサブエージェントを1つ割り当てます。各サブエージェントは、同じチェックリストと記録形式に従い、担当する分割についてフェーズ A（ファイルレベル分析）を独立して実施します。各サブエージェントには、コードベース全体のアーキテクチャの簡単な説明、ステップ3の意図の概要、および該当するチェックリストを提供します。
• すべてのサブエージェントが完了したら、統合した調査結果を対象にフェーズ B（ファイル横断分析）を実施し、分割間の相互作用に焦点を当てます。特に信頼境界に注意してください。ある分割から別の分割へ流れるデータは、検証漏れやインジェクション脆弱性が見落とされる一般的な原因です。
• 共有または重複するコードを調査した複数のサブエージェントが個別に発見した問題は、重複を排除します。最も重大度の高い内容に統合し、影響を受ける場所をすべて記載します。

サブエージェントを利用できない場合、または対象範囲が十分に小さい場合は、単一のエージェントとしてすべてのフェーズを順番に実施します。分割してもすべての行を分析できない場合は、セキュリティ上または正確性上、重要な経路を優先して詳細に調査します。対象は、エントリーポイント、認証・認可フロー、データ永続化、外部 API 境界です。

フェーズ A — ファイルレベル分析

対象範囲内のすべてのファイルを順に確認します。各ファイルについて、次の作業を行います。

• ファイル全体を読みます。ざっと読んだり、一部を抜き出して確認したりしてはいけません。
• 確認済みのカテゴリーに関する各チェックリスト項目に沿って、調査対象のコードに説明された問題が見られるかどうかを評価します。
• 問題を記録する前に、意図の概要と照合します。概要で該当箇所の該当パターンが直接かつ明示的に扱われている場合は、記録を省略します。概要に一般的な背景情報はあるものの、個々の箇所について認識が示されていない場合は、重大度を下げ（意図の出典を注記して）報告します。
• 問題を見つけたら、そのファイルパス、行番号、カテゴリー、暫定的な重大度（references/severity-guide.md に従う）、問題の説明、影響、および具体的な推奨事項をただちに記録します。
• データフローまたは呼び出しチェーンが現在のファイルの外に及ぶ問題は、フェーズ B でファイル横断の追加調査が必要であることを明記します。

共通のパターン（例：あらゆる場所で使われるユーティリティ関数）が複数のファイルに現れる場合、同じ論理的な問題を何度も記録しないでください。代わりに1回だけ記録し、影響を受ける場所をすべて記載します。

フェーズ B — ファイル横断分析

ファイル単位の確認を完了したら、ファイル横断の追加調査が必要とされた指摘を再確認します。

• エントリーポイント（HTTP ハンドラー、CLI パーサー、メッセージコンシューマー、公開 API サーフェス）から、中間レイヤーを経て最終的な処理（データベースへの書き込み、ファイル I/O、外部 API 呼び出し、ユーザーへの応答）に至るまで、データの流れを追跡します。
• 個々のファイルを単独で見ると問題がないように見える場合でも、追跡した経路のどこかで入力検証、認可、エラー処理、リソースのクリーンアップが欠けていないか評価します。
• アーキテクチャ上の問題を確認します。モジュール間の循環依存、レイヤー間で一貫性のないエラー処理方針、微妙なバグを招くパラダイムの混在、複数のモジュールからアクセスされる共有可変状態などが該当します。
• フェーズ A と同じ除外・格下げルールを使い、新たに見つかったファイル横断の指摘を Intent Brief と照合します。

新たな指摘を記録し、ファイル横断の広い文脈で深刻度が高く、または低くなると判明したファイル単位の指摘については、深刻度の評価を更新します。

重複排除

レポートの作成に進む前に、指摘の重複を排除します。

• 複数箇所に現れる同じ根本原因を説明する指摘は統合し、影響を受けるすべての箇所をその指摘に記載します。
• ファイル横断分析で誤検知と判明した指摘を削除します（例：あるファイルでは未検証に見えた入力が、後から判明したミドルウェアレイヤーで検証されている場合）。
• Intent Brief に記載された同じトレードオフに起因する指摘は、Intent Brief の該当項目を参照し、影響を受けるすべての箇所を列挙した単一の指摘にまとめます。
• 想定される最悪の影響を考慮し、相反する深刻度の評価を調整します。

ステップ 5 — レポートの作成

references/report-template.md で定義された構成と書式ルールに従い、最終レポートを作成します。具体的には、以下を行います。

• レポートの日付を現在の日付に設定します。
• 解決済みのスコープ、確認されたカテゴリ、深刻度ごとの指摘件数をサマリーテーブルに記入します。
• サマリーテーブルと深刻度「Critical」のセクションの間に、「Context & Intent」セクションを追加します。このセクションでは Intent Brief を要約し、監査に影響した主要な文書化済みの決定を列挙します。
• AUDIT-001 から始まる連番の AUDIT-NNN 識別子を指摘に割り当てます。深刻度（Critical を先頭）、次にカテゴリ、同じ深刻度とカテゴリ内ではファイルパスの順に指摘を並べます。
• 各指摘に必須フィールドをすべて記載します。識別子、短いタイトル、カテゴリ、場所（file:line）、深刻度、説明、影響、推奨事項です。
• テンプレートに記載されたファイル名規則（AUDIT-REPORT-YYYY-MM-DD.md）に従ってレポートをプロジェクトルートに保存します。同名のファイルがすでに存在する場合は、末尾の番号を増やします。

レポートを保存したら、ファイルパスと結果の簡単な概要をユーザーに伝えます。