code-audit

コード監査スキル

目的

コードベースまたは対象ファイル群を、言語に依存しない方法で徹底的に監査し、重大度順にランク付けした指摘事項を含む構造化レポートを作成します。レポートは、ユーザーが選択した形式（下記「レポート形式」を参照）で、プロジェクトのルートに自己完結型のファイルとして出力します。形式は、references/report-template-html.md に従う HTML、または references/report-template.md に従う Markdown です。

作業量

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

レポート形式

監査では、プロジェクトのルートに自己完結型のファイルを作成します。形式によって、ファイル拡張子とステップ 5 で使用するテンプレートが決まります。既定の形式は HTML です。インライン SVG データフロー図、重大度バッジ、折りたたみ可能な Intent Brief テーマ、指摘事項間の相互参照アンカーを利用できるためです。これらの機能は長い監査レポートを大幅に改善しますが、Markdown では表現できません。

**対象範囲を確定する前に、形式を決定してください。** これは必須のゲートです。この実行で形式が確定するまで、対象範囲の確定、意図の把握、分析、その他いかなる作業も開始してはいけません。

まず、ユーザーが起動時に送信したメッセージに、明示的な形式の指定がないか確認します。次のいずれかがあれば、それに従ってください。

• HTML の指定：HTML、html、「Web ページとして」、「ブラウザーで閲覧可能」、「レンダリングされたレポート」。
• Markdown の指定：MD、md、Markdown、markdown、「プレーンテキストのレポート」、「Markdown 形式で」。

起動時のメッセージに明確な形式の指定が含まれている場合は、それをゲートの回答として受け入れて先に進みます。形式を確定した対象範囲を伝える際に、選択した形式を簡潔に示してください。形式の確認だけを目的とした質問を改めて行ってはいけません。

起動時のメッセージに形式の指定がない場合は、次の質問（または同等の質問）を正確に行い、ユーザーが回答するまで待ってください。

希望するレポート形式をお知らせください。HTML（既定、インライン図と重大度バッジを含む自己完結型ファイル）または MD（プレーンな Markdown）をお選びください。

この質問に他の内容を含めてはいけません。確認せずに既定の形式を選んではいけません。このゲートは、このスキルを実行するたびに適用されます。

形式を選択した後は、実行の残りの間、その形式を一貫して使用してください。

形式	テンプレート	ファイル名
HTML	references/report-template-html.md	AUDIT-REPORT-YYYY-MM-DD.html
MD	references/report-template.md	AUDIT-REPORT-YYYY-MM-DD.md

HTML レポートを生成する場合は、references/report-template-html.md に記載された HTML 固有の機能を、情報を追加できるときに活用するツールとして扱い、装飾として扱ってはいけません。これらの機能を使わずに Markdown の内容を HTML タグで囲むだけでは、HTML を選んだ意味がありません。

ワークフロー

ステップ 1 — スコープの確定

ユーザーのプロンプトから監査スコープを判断します。ユーザーが指定する対象は、次のいずれかです。

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

ユーザーが存在しないファイルやディレクトリを指定した場合は、不足しているパスについて警告し、存在するファイルの処理を続けます。指定されたパスが 1 つも存在しない場合は、停止して確認を求めてください。

プロンプトにスコープを判断するための十分な情報が含まれていない場合は、作業を開始する前に確認の質問を 1 つだけ行ってください。スコープを推測しないでください。境界が不明確な監査では、信頼できる結果が得られません。

ユーザーが再監査を依頼した場合は、プロジェクトのルートで AUDIT-REPORT-*.md と AUDIT-REPORT-*.html に一致するファイルを検索します。レポートが複数ある場合は、形式にかかわらず、ファイルの更新日時が最も新しいものを使用します。デフォルトでは、元の監査と同じスコープを使用します。ユーザーがより迅速な監査を望む場合は、以前に指摘事項があったファイルだけに絞ることを提案してもかまいません。ただし、黙って範囲を狭めないでください。以前問題がなかったファイルにも、新しい問題が発生している可能性があります。以前のレポートがある場合は、解消された以前の指摘事項と、引き続き残っている指摘事項を新しいレポートに記載し、差分を確認できるようにします。新しいレポートの形式は今回の実行におけるゲートの判定に従います。以前のレポートと同じ形式である必要はありません。

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

確定したスコープをユーザーに伝えます。スコープが明確な場合は、確認を待たずにすぐ作業を進めてください。

ステップ 2 — カテゴリを選択して確認する

ユーザーのリクエストとコードベースを分析し、次の全カテゴリの中から、監査に最も関連するカテゴリを選択します。

1. 競合状態と並行処理
2. デッドコード
3. アンチパターンとコードの不自然な点
4. パフォーマンス
5. 正確性
6. エラー処理の不備
7. テスト品質

セキュリティ分析は、このスキルの対象外です。ユーザーのリクエストにセキュリティ上の懸念（脆弱性、インジェクション、認証、認可、シークレット、暗号化、依存関係の CVE、OWASP の問題、IaC、CI/CD のレビュー）が含まれている場合は、この監査と併せて、またはこの監査に代えて security-audit スキルを実行するよう推奨します。この監査中に偶発的にセキュリティ上の問題を見つけた場合は、その問題を記載した単一の指摘として記録し、追加で security-audit を実行するよう推奨してください。ここでは詳しく分析しないでください。

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

「このコードベースを監査して」のような広範なリクエストでは、既定で全カテゴリを対象とし、確認を求めずに進めてください。選択が自明でない場合、つまりエージェントがコード分析に基づいて一部のカテゴリを選んだ場合、またはユーザーのリクエストから適用するカテゴリが明確でない場合に限り、選択したカテゴリを提示して確認を求めます。

references/categories.md のチェックリストを体系的な分析の基礎として使用してください。コードベースに含まれる言語、フレームワーク、パラダイムに該当しない個別のチェックリスト項目は省略します。コードベースにテストファイルがない場合は、テストが存在しないことを記した単一の指摘を報告し、テスト品質の個別項目は評価しないでください。

ステップ 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 の呼び出し、ユーザーへの応答）に至るまで、データの流れを追跡します。
• 追跡した経路のどこかで、型や形状の検証、事前条件の確認、エラー処理、リソースのクリーンアップが欠けていないかを評価します。個々のファイルを単独で見ると正しく見える場合でも同様です。（認可チェックとセキュリティに関わる入力検証は、security-audit スキルで評価します。）
• アーキテクチャ上の問題を確認します。モジュール間の循環依存、レイヤー間で一貫性のないエラー処理方針、微妙なバグを引き起こす異なるパラダイムの混在、複数のモジュールからアクセスされる共有の可変状態などです。
• フェーズ A と同じスキップ／重要度引き下げのルールを使い、新たなファイル横断の指摘を Intent Brief と照合します。

新たな指摘を記録し、より広い文脈で見ると重要度が上がる、または下がることが判明したファイル単位の指摘については、重要度の評価を更新します。

重複排除

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

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

ステップ 5 — レポート生成

Format Gate で選択した形式に対応するテンプレートに従って、最終レポートを生成します。HTML 出力には references/report-template-html.md、Markdown 出力には references/report-template.md を使用します。以下の内容に関するルールはどちらの形式にも適用され、構造上の表現は各テンプレートで定義されています。

• レポートの日付を現在の日付に設定します。
• サマリーテーブルに、確定した対象範囲、確認済みのカテゴリ、重要度別の指摘件数を記入します。
• Summary テーブルと Critical 重要度セクションの間に「コンテキストと意図」セクションを設けます。このセクションでは Intent Brief の要約と、監査に影響した主要な文書化済みの決定事項を記載します。
• AUDIT-001 から始まる連番の AUDIT-NNN 識別子を指摘に割り当てます。指摘は重要度（Critical が最初）、次にカテゴリ、同じ重要度とカテゴリ内ではファイルパスの順に並べます。
• 識別子、短いタイトル、カテゴリ、場所（file:line）、重要度、説明、影響、推奨事項など、必須のフィールドをすべて各指摘に記載します。
• 選択したテンプレートのファイル名規則（HTML の場合は AUDIT-REPORT-YYYY-MM-DD.html、Markdown の場合は AUDIT-REPORT-YYYY-MM-DD.md）に従って、プロジェクトのルートにレポートを保存します。同じ名前のファイルがすでに存在する場合は、サフィックスを増やします。

選択した形式が HTML の場合は、さらに以下を適用します。

• references/report-template-html.md の構造上の契約に厳密に従います。必須の ID、クラス、data-* 属性は省略できません。このひな形によってレポートの解析と再監査の差分確認が可能になります。
• 情報の追加に役立つ場合は、HTML 固有の機能（インライン SVG データフロー図、折りたたみ可能な Intent Brief のテーマ、指摘間のアンカー参照）を使用します。同じ内容が文章で十分に伝わる場合は使用しません。目標は装飾ではなく、情報密度です。

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