nestjs-code-audit

NestJS コード監査

現在のユーザーの NestJS プロジェクトを調査し、検証済みのコード上の問題と、根拠に基づくリスクをまとめた単一のレポートを返します。監査のみを行い、対象プロジェクトは変更しないでください。

実行前の競合ガード

ファイルを編集したり、状態を変更するコマンドを実行したりする前に、有効な指示を照合してください。読み取り専用の調査は続行できます。

前提条件

ルート、対象範囲、指示、Git の状態、インストール済みのバージョンと依存関係、安全に実行できるチェックを確認してください。ユーザーの変更を保持してください。要求されたセマンティックレーンについては、semantic-review.md を読み込んでください。兄弟スキルは、より詳細な指針として任意で利用できるものであり、インストールの前提条件ではありません。ほかの有効なスキルは、その判断が重なる場合にのみ読み込んでください。

主な担当範囲

このスキルは、読み取り専用の品質エビデンス、検出事項の重複排除、重大度、レポートの作成を担当します。インストール済みで関連性がある場合は、次のスキルと連携してください。

• nestjs-architecture-principles：モジュール、依存関係、データ、トランザクションの境界。
• nestjs-oop-design-patterns：オブジェクトの責務、不変条件、パターン。
• nestjs-features-performance：ライフサイクル、API／セキュリティ、テスト、ランタイム、パフォーマンス。
• nestjs-professional-software-engineering：実装と検証。
• nestjs-feature-audit：ブランチ固有のロードマップゲートと機能のレポート。
• nestjs-git-commit-pr-message：許可された Git への公開と CI のフォローアップ。

これらは判断の境界であり、必須の依存関係ではありません。作業を別のワークフローに引き継ぐ際も、ドメイン上の担当範囲を維持してください。

競合の判定

相容れない検出事項、安全でないチェック、または不足しているエビデンスについては、明示されたユーザーの意図、リポジトリの契約、検証済みのランタイム制約、最も限定的な担当範囲の順に解決してください。根本原因ごとに検出事項を一つにまとめてください。未解決の主張は 要検証 に記載してください。操作が監査の範囲を超える場合は、変更を加える前に停止してください。監査だけでは修正の許可は得られません。ユーザーが監査と修正の両方を明示的に依頼した場合は、まず読み取り専用の監査を完了し、同じ承認を再度求めずに、許可された実装フェーズへ進んでください。

呼び出し方法

推奨されるポータブルな呼び出し方法：

$nestjs-code-audit
$nestjs-code-audit full src/payments
$nestjs-code-audit static
$nestjs-code-audit security src/auth

Codex CLI／IDE のカスタムプロンプトエイリアスがインストールされている場合：

/prompts:nestjs-audit
/prompts:nestjs-audit full src/payments

Codex では、/Nestjs audit のような任意のユーザー定義コマンドはサポートされていません。サポートされているエイリアスを明示してください。

アクション

アクション	対象範囲
full（デフォルト）	安全な静的ゲートに加え、アーキテクチャ、オブジェクト設計、ランタイム、セキュリティ、テスト、デリバリーをレビューします
static	構文、TypeScript、リンター、設定、およびそれらに直接関係するツールチェーンの失敗を確認します
architecture	モジュール、依存関係、データ／書き込みの所有権、トランザクション、イベント、ポート、サービスの境界を確認します
design	責務、不変条件、結合、抽象化、パターン、リファクタリングのリスクを確認します
runtime	Nest のライフサイクル、API／エラー、信頼性、パフォーマンスのエビデンス、ヘルスチェック、シャットダウン、デリバリーを確認します
security	入力、ID／アクセス、テナント分離、シークレット、出力、不正利用対策、セキュリティテストを確認します
tests	テストレイヤーの選択、不足している境界カバレッジ、不安定になりやすいライフサイクルのリスク、安全に実行できるチェックを確認します

省略可能なリポジトリ相対の対象範囲を、アクションの後に指定できます。最初の引数が認識可能なアクションでない場合は、すべての引数を対象範囲／焦点として扱い、full を使用してください。対象を絞ったアクションでは、同梱のセマンティックリファレンスから関連するレーンのみを読み込み、レーンをまたぐ阻害要因に必要な場合は、利用可能な専門スキルも読み込んでください。要求された対象範囲のみを報告してください。

監査ワークフロー

1. 適用可否と対象範囲を確認する

1. リポジトリのルートから逸脱せず、現在の作業ディレクトリと任意のユーザースコープを解決します。
2. 対象範囲に影響する AGENTS.md とその他のリポジトリ指示、package.json、ロックファイル、nest-cli.json、TypeScript と lint の設定、ブートストラップファイル、モジュールファイル、テスト、デプロイマニフェストを読みます。
3. @nestjs/core が宣言されていること、またはリポジトリが明らかに NestJS ワークスペースであることを確認します。該当しない場合は中止し、この監査の対象外であることを報告します。
4. 現在のブランチと変更状態を記録します。既存の変更を変更または破棄してはいけません。
5. 観察されたアーキテクチャの概要を一文で示します。フォルダー名だけからクリーンアーキテクチャ、DDD、CQRS、マイクロサービスを推測してはいけません。

2. 決定的な証拠を収集する

このスキルのディレクトリに含まれるコレクターを使用します。

node scripts/collect-quality-evidence.mjs --root "$PWD" --run

ユーザーがより狭い範囲の監査を依頼した場合は、--scope <relative-path> を追加します。コレクターは次の処理を行います。

• マニフェストとソースファイルを変更せずに読み取ります。
• パッケージマネージャーと利用可能な品質チェック用スクリプトを特定します。
• --run が指定された場合に限り、許可リストにある修正を行わない ESLint コマンドと tsc --noEmit コマンドだけを実行します。
• 依存関係のインストール、ビルド、スナップショットの更新、カバレッジの書き込み、任意のパッケージスクリプトの実行は行いません。
• コマンドの結果とヒューリスティックによるレビュー候補を含む JSON を返します。

依存関係が不足している場合や、コマンドが安全でない、利用できない、タイムアウトする、または対象範囲外の場合は、未実行として記録します。チェックが未実行であることを合格と解釈してはいけません。この監査中は、lint --fix、フォーマットや書き込みを行うコマンド、マイグレーション、デプロイコマンド、ライブ統合テスト、共有インフラにアクセスする可能性のあるテストを実行してはいけません。

3. 4 つの証拠レーンをレビューする

ツールチェーンの正確性

• パーサー、TypeScript、lint の診断を、問題の特定に十分な精度で報告します。
• 同じ根本原因から発生した連鎖的なコンパイラーエラーは重複を取り除きます。
• 依存関係の不足や設定の破損など、コマンドの失敗とコード上の問題を区別します。

アーキテクチャ

ブートストラップのエントリーポイント、モジュールのインポート／エクスポート、プロバイダーの可視性、リクエスト／メッセージの経路、永続化の責任範囲、トランザクション、イベント、外部アダプターを追跡します。循環依存や境界の漏えいは、実際のインポートと呼び出し経路から確認します。アーキテクチャ上の好みを欠陥として報告してはいけません。

オブジェクト設計と保守性

責務、依存関係の集中、インバリアントの配置、繰り返される条件分岐による変化、フレームワーク／ベンダー依存の漏えい、隠れたサービス検索、先走った抽象化、リスクの高いリファクタリング箇所を調べます。ファイルの長さや正規表現による兆候だけで問題を指摘してはいけません。

ランタイム、セキュリティ、検証

ライフサイクル上の配置、検証、認証／認可、テナント／リソースの所有権、公開するエラーとレスポンスの契約、シークレット／ログ、クエリとリソースの上限、タイムアウト／再試行／冪等性、ヘルスチェック／シャットダウン、テストの境界、存在する場合はデプロイの証拠を調べます。測定せずにパフォーマンスの問題を主張してはいけません。

4. 問題を検証し、重複を除く

確認済みの問題には、次の項目が必要です。

• 安定した ID：TOOL、ARCH、OOP、RUN、SEC、TEST のいずれかに番号を付けたもの。
• 深刻度：critical、high、medium、low。
• 主な担当スキル。
• ファイルと行の根拠に加え、関連するインポート、呼び出し経路、診断、または設定。
• ルール名だけでなく、具体的な影響。
• 最小限で安全な修正方法。
• 修正を証明できる検証手順。

critical は、現存するセキュリティ、データ損失、テナント分離、または深刻な可用性のリスクに限ります。high は、誤った動作が起こりそうな場合、または既知の変更を妨げる境界上の欠陥がある場合に限ります。medium は、信頼できる保守性、正確性、または運用性のコストがある場合に限ります。low は、リスクが限定的な局所的改善に限ります。

未検証の正規表現による兆候、デッドコードの疑い、パフォーマンスの懸念、依存関係不足で妨げられているチェックは 要検証 に移します。スタイル上の好みを持ち出したり、1 つの根本原因から複数の問題を報告したりして、報告を水増ししてはいけません。

必須レポート

以下の順序で Markdown を返してください。

1. 監査判定： pass、pass with risks、または fail。監査対象の範囲と、ベースラインを一文で記載してください。
2. 品質ゲート： 構文／TypeScript、lint、安全に実行できる場合はテスト、監査の網羅性。それぞれについて、正確なコマンドまたは実行しなかった理由とともに、pass、fail、または not run を記載してください。
3. 指摘の概要： 重要度および担当領域ごとの件数。
4. 確認済みの指摘： 上記のエビデンス／対処法／検証の形式に従い、重要度と影響度の高い順に記載してください。
5. 要確認事項： 候補、エビデンスの不足内容、次に行う最小限の確認。
6. 健全なパターン： リポジトリ内で実際に確認できた、特筆すべき制御のみを記載してください。
7. 推奨する順序： 依存関係を考慮した簡潔な修正手順。ユーザーが修正を明示的に許可した場合に限り、別フェーズで実施してください。

確認済みの問題がない場合は、その旨を明記し、実行しなかったチェックを列挙してください。lint が問題なく完了しても、アーキテクチャ、セキュリティ、実行時の動作、テストカバレッジが健全である証明にはなりません。

参照先の選択

必要な内容	読み込むファイル
関連スキルを併用せずに、アーキテクチャ、オブジェクト、実行時の動作、健全な制御をレビューする	semantic-review.md
プロジェクトを変更せずに実行できるチェックを判断する	check-policy.md
3 つのドメインスキル間で指摘の担当を割り当て、重複を除外する	finding-ownership.md
最終監査レポートの形式を統一する	report-template.md