nestjs-health-audit

NestJS プロジェクト健全性監査 - モジュール型実行計画

この計画では、順次実行するモジュール型のルールを通じて NestJS プロジェクト健全性監査を実行します。各ステップでは、独立して実行できる特定のルールを使用し、その出力を最終レポートに反映します。

3 層サブエージェントアーキテクチャ

セッション内で実行する場合（Claude Code、Cursor、または Agent ツールをサポートする任意のエージェント）、このスキルは agents/orchestrator.md が調整する階層型のマルチサブエージェントトポロジーを通じて動作します。somnio run CLI の実行経路では、以下のルール実行順序（順次実行、1 回の実行につき単一モデル）を使用します。

エントリーポイント（セッション内）：agents/orchestrator.md（model: mid）

階層の割り当て：

階層	役割	エージェント
cheap	機械的なスキャナー — ファイルシステムのスキャン、キーの抽出、存在チェックリスト	env-setup-agent、repo-analyzer、config-analyzer、docs-analyzer
mid	推論を行うアナライザー — CI ゲートへの準拠、テスト品質の判断、コード品質の詳細分析、REST 規約への準拠、N+1 の検出、AI ハーネス品質の判断。また、オーケストレーターも含みます	orchestrator、cicd-analyzer、testing-analyzer、code-quality-analyzer、api-design-analyzer、data-layer-analyzer、harness-analyzer
frontier	レポートの統合 — セクション間のスコア調整、全体スコアの加重計算、説明文の一貫性、必須の 15 セクション構成	report-writer-agent

エージェントの役割とコンテキスト

役割：NestJS プロジェクト健全性監査担当

中核となる専門知識

あなたは、以下の分野に精通しています。

• 包括的なプロジェクト監査：技術スタック、アーキテクチャ、API 設計、テスト、CI/CD、ドキュメントなど、NestJS プロジェクトの健全性に関するあらゆる側面を評価します
• エビデンスに基づく分析：データを捏造したり推測したりせず、リポジトリ内の証拠を客観的に分析します
• モジュール化されたルールの実行：14 個の専門的な分析ルールを順次実行できるよう調整します
• スコアの算出：各セクションのスコア（0～100）と、重み付けされた総合スコアを正確に算出します
• 技術的リスク評価：技術的リスク、技術的負債、プロジェクトの成熟度を示す指標を特定します
• レポートの統合：複数の分析ルールから得られた結果を統合し、Markdown 形式のレポートにまとめます
• NestJS のベストプラクティス：NestJS のパターン、デコレーター、モジュール、プロバイダー、ガード、インターセプター、パイプに関する深い知識があります
• バックエンドアーキテクチャ：レイヤードアーキテクチャ、DDD、ヘキサゴナルアーキテクチャ、マイクロサービスのパターンを理解しています

責任：

• 計画の手順に沿って、技術監査を順番に実行します
• リポジトリ内で見つかった証拠に基づいて、客観的に調査結果を報告します
• 必須手順が失敗した場合は、直ちに実行を停止します
• 情報を決して捏造または推測せず、証拠がない場合は「不明」と報告します
• 技術面のみに焦点を当て、運用やガバナンスに関する推奨事項は除外します

期待される動作：

• プロフェッショナルでエビデンスに基づく対応：すべての調査結果は、リポジトリ内の実際の証拠によって裏付けられている必要があります
• 客観的な報告：重大な問題、推奨事項、中立的な項目を明確に区別します
• 明示的なドキュメント化：確認した内容、見つかった内容、不足している内容を記録します
• エラー処理：必須手順が失敗した場合は実行を停止し、重大でない問題については警告を記録して続行します
• 推測の禁止：リポジトリ内の証拠で立証できない場合は「不明」と記し、それを立証するには何が必要かを明示します

重要なルール：

• CODEOWNERS ファイルや SECURITY.md ファイルは決して推奨しないでください。これらは技術要件ではなく、ガバナンス上の判断事項です
• 運用ドキュメント（ランブック、デプロイ手順、監視など）は決して推奨しないでください。技術的なセットアップのみに焦点を当てます
• Node.js のバージョン管理には必ず nvm を使用してください。グローバル設定は必須です
• 依存関係の管理は必ず包括的に実施してください。ルート、パッケージ、アプリの依存関係をインストールする必要があります

実行規律（交渉不可）：

• 手順を決して省略、統合、短縮しないでください — この計画の各手順は、個別に、かつ完全に実行する必要があります
• 参照ファイルを実行する代わりに要約しないでください — 各参照ファイルを読み、その指示にすべて従う必要があります
• 近道を決して選ばないでください — 答えをすでに知っていると思っても、分析コマンドを実行し、実際の証拠を収集する必要があります
• 手順を実行する前に、必ず参照ファイルを読んでください — 参照先の .md ファイルをすべて読み、その指示に従ってから、各手順を実行してください
• 手順の完了を必ず記録してください — 各手順の完了後、次に進む前に「STEP N COMPLETED: [結果の簡潔な要約]」と出力してください
• 現在の手順が完了する前に、次の手順に決して進まないでください — 手順の一部だけを実行することは認められません
• 手順が失敗した場合：失敗を記録し、復旧を試みてください。復旧が不可能な場合に限り、その理由と省略した内容を明記してスキップしてください

要件 - NODE.JS バージョンの整合

必須ステップ 0: NestJS プロジェクトの分析を実行する前に、必ず nvm を使用して Node.js のバージョンを確認し、プロジェクトが要求するバージョンに合わせてください。

実行するルール: references/version-alignment.md の指示を読み、従ってください。

重要な要件: このステップでは、nvm がプロジェクトの Node.js バージョンを使用するように設定しなければなりません。これは必須であり、分析を開始する前に必ず正常に実行してください。

この要件は、検出されたバージョンにかかわらず、すべての NestJS プロジェクトに適用されます。バージョンに起因するビルド失敗を防ぎ、正確に分析するためのものです。

ステップ 0. Node.js 環境のセットアップとテストカバレッジの確認

目的: 必須の nvm 設定を行って Node.js 環境を構成し、テストとカバレッジの確認を含む包括的な依存関係管理を実行します。

重要: このステップでは、nvm がプロジェクトの Node.js バージョンを使用するように設定し、すべての依存関係（ルート、パッケージ、アプリ）をインストールしなければなりません。nvm の設定に失敗した場合、実行を停止します。

実行するルール:

1. references/tool-installer.md の指示を読み、従ってください（必須: Node.js、nvm、必要な CLI ツールをインストールします）。
2. references/version-alignment.md の指示を読み、従ってください（必須。失敗した場合は停止します）。
3. references/version-validator.md の指示を読み、従ってください。
4. references/test-coverage.md の指示を読み、従ってください（カバレッジを生成します）。

実行順序:

1. 最初に references/tool-installer.md のルールを実行します（必須。失敗した場合は停止します）。
2. references/version-alignment.md のルールを実行します（必須。失敗した場合は停止します）。
3. references/version-validator.md のルールを実行して、nvm の設定と包括的な依存関係管理を確認します。
4. references/test-coverage.md のルールを実行して、カバレッジを生成します。

包括的な依存関係管理:

• ルートプロジェクト: npm install または yarn install または pnpm install
• すべてのパッケージ: find packages/ -name "package.json" -execdir npm install \;
• すべてのアプリ: find apps/ -name "package.json" -execdir npm install \;
• 確認: npm list または yarn list または pnpm list
• ビルドステップがある場合は、ビルド成果物を生成します:
  • ルート: npm run build または yarn build または pnpm build
  • アプリ: find apps/ -name "package.json" -execdir npm run build \;

統合: これらのルールからのすべての出力を保存し、最終監査レポートに統合してください。

失敗時の対応: nvm の設定に失敗した場合は、実行を停止して解決手順を提示してください。

並列実行戦略

ステップ 1〜9 は、Agent ツールを使用して複数の分析エージェントを同時に起動することで、一部を並列化できます。以下のウェーブ構成を使用してください。

ウェーブ 0（逐次 — 必須）：ステップ 0 — 環境のセットアップ 分析を開始する前に、必ず完全に完了させてください。

ウェーブ 1（並列）：ステップ 1 + 2 — リポジトリの調査 + 設定の分析 両方を並列エージェントとして起動します。両エージェントはそれぞれ独立してファイルシステムを読み取ります。

ウェーブ 2（並列）：ステップ 3 + 4 + 5 + 9 — CI/CD + テスト + コード品質 + AI ハーネスと導入状況 4 つすべてを並列エージェントとして起動します。読み取り専用の独立した分析です。ハーネス分析は先行する成果物に依存しないため、このウェーブに含めます。

ウェーブ 3（並列）：ステップ 6 + 7 — API 設計 + データレイヤー 両方を並列エージェントとして起動します。フレームワーク固有の独立した分析です。

ウェーブ 4（逐次）：ステップ 8 — ドキュメント分析 すべての分析ウェーブの完了後に実行できます。

ウェーブ 5（逐次）：ステップ 10 + 11 — レポートの生成 + エクスポート すべての前の結果が必要なため、最後に実行してください。

エージェントの起動パターン：並列ウェーブごとに、Agent ツールを使用してステップごとに 1 つのエージェントを起動します。各エージェントは必ず次の作業を行います。

1. 参照先の .md ファイルをすべて読む
2. そのファイルのすべての指示を実行する
3. 分析結果を完全な形で返す
4. 省略や要約をせず、証拠をすべて返す

ウェーブ 1 の例：

• エージェント 1：「references/repository-inventory.md を読み、指示をすべて実行してください。調査結果を完全な形で返してください。」
• エージェント 2：「references/config-analysis.md を読み、指示をすべて実行してください。調査結果を完全な形で返してください。」

ステップ 1. リポジトリの調査

目標：リポジトリの構造、モノレポのパッケージ、モジュール構成、機能構成を検出します。

実行するルール：references/repository-inventory.md の指示を読み、それに従ってください。

統合：リポジトリ構造の調査結果を、アーキテクチャと技術スタックの各セクション用に保存します。

ステップ 2. コア設定ファイル

目標：NestJS/Node.js の設定ファイルを読み取り、バージョン情報、依存関係、TypeScript のセットアップ、環境設定を分析します。

実行するルール：references/config-analysis.md の指示を読み、それに従ってください。

統合：設定の調査結果を、技術スタックとコード品質の各セクション用に保存します。

ステップ 3. CI/CD ワークフロー分析

目標：Docker のセットアップを含め、すべての GitHub Actions ワークフローと関連する CI/CD 設定ファイルを読み取ります。

実行するルール：references/cicd-analysis.md の指示を読み、それに従ってください。

統合：CI/CD の調査結果を、CI/CD セクションのスコアリング用に保存します。

ステップ 4. テストインフラストラクチャ

目標：すべてのテストファイルを見つけて分類し、カバレッジ設定とテストの種類（単体、統合、E2E）を特定します。

実行するルール：references/testing-analysis.md の指示を読み、それに従ってください。

統合：テストの調査結果をテストセクション用に保存し、ステップ 0 のカバレッジ結果と統合します。

ステップ 5. コード品質とリンター

目標：ESLint の設定、Prettier の構成、TypeScript の strict モード、コード品質の強制方法を分析します。

実行するルール：references/code-quality.md の指示を読み、それに従ってください。

統合：コード品質の調査結果を、コード品質セクションのスコアリング用に保存します。

ステップ 6. API 設計分析

目標：REST/GraphQL API の設計、DTO、バリデーションのパターン、OpenAPI/Swagger ドキュメント、API バージョニングを分析します。

実行するルール：references/api-design-analysis.md の指示を読み、それに従ってください。

統合：API 設計の調査結果を、API 設計セクションのスコアリング用に保存します。

ステップ 7. データレイヤー分析

目標：ORM/データベース連携、リポジトリパターン、マイグレーション、データアクセスレイヤーの構成を分析します。

実行するルール：references/data-layer-analysis.md の指示を読み、それに従ってください。

統合：データレイヤーの調査結果を、データレイヤーセクションのスコアリング用に保存します。

ステップ 8. ドキュメントと運用

目標：技術ドキュメント、API ドキュメント、ビルド手順、環境設定を確認します。

実行するルール：references/documentation-analysis.md の指示を読み、従ってください。

統合：ドキュメントと運用セクションのスコアリング用に、ドキュメントの調査結果を保存します。

ステップ 9. AI ハーネスと導入状況の分析

目標：プロジェクトの AI ハーネス（CLAUDE.md、.claude/rules/、settings.json の権限とフック、.claude/agents/、コマンド／スキル、pre-push git フック）を、存在するかどうかだけでなく品質に基づいて、10 項目・100 点満点の評価基準で採点します。

実行するルール：references/harness-analysis.md の指示を読み、従ってください。

統合：「AI ハーネスと導入状況」レポートセクション用に、AI ハーネスと導入状況の調査結果、スコア、優先順位付きアクションリストを保存します。

ステップ 10. 最終レポートの作成

目標：すべての分析結果を統合して、最終的な NestJS プロジェクト健全性監査レポートを作成します。

実行するルール：references/report-generator.md の指示を読み、従ってください。

統合：このルールでは、これまでのすべての分析結果を統合して、最終レポートを作成します。

レポートのセクション：

• 全体スコアを含むエグゼクティブサマリー
• 9 セクションすべてのスコアに加え、> Test Coverage: の行、スコアリングの凡例、全体スコアの解釈文を含む一目でわかるスコアカード
• 9 つの詳細セクションすべて（技術スタック、アーキテクチャ、API 設計、データレイヤー、テスト、コード品質、ドキュメントと運用、CI/CD、AI ハーネスと導入状況）—テストには正式なコードカバレッジ／カバレッジ内訳の各項目を記載
• 追加指標（カバレッジ率は含めません。カバレッジ率はスコアカードの行とテストセクションのみに記載します）
• リスクと機会（箇条書き 5～8 項目）
• 推奨事項（優先順位付きアクション 6～10 項目）
• 付録：エビデンスインデックス
• 付録：スコアリング方法（番号なし。重みを記載する唯一の箇所）

ステップ 11. 最終レポートのエクスポート

目標：共有可能な最終 Markdown レポートを reports ディレクトリに保存します。

アクション：reports ディレクトリが存在しない場合は作成し、最終的な NestJS プロジェクト健全性監査レポートを次の場所に保存します。 ./reports/<YYYY-MM-DD>-<project>-nestjs-health-audit.md

形式：Markdown 形式のレポート（適切な Markdown 構文を使用し、# 見出し、太字のマーカー、バッククォートによるコード参照を含めます）。

コマンド：

mkdir -p reports
# Save report content to ./reports/<YYYY-MM-DD>-<project>-nestjs-health-audit.md

注：セキュリティ分析には、単独のセキュリティ監査（/somnio:security-audit）を実行してください。

実行概要

ルールの合計：14 件

ルールの実行順序：

1. references/tool-installer.md {model: cheap}
2. references/version-alignment.md（必須 — nvm が失敗した場合は停止します）{model: cheap}
3. references/version-validator.md（nvm のセットアップを検証します）{model: cheap}
4. references/test-coverage.md（カバレッジを生成します）{model: cheap}
5. references/repository-inventory.md {model: cheap}
6. references/config-analysis.md {model: cheap}
7. references/cicd-analysis.md {model: mid}
8. references/testing-analysis.md {model: mid}
9. references/code-quality.md {model: mid}
10. references/api-design-analysis.md {model: mid}
11. references/data-layer-analysis.md {model: mid}
12. references/documentation-analysis.md {model: cheap}
13. references/harness-analysis.md の指示を読み、それに従います {model: mid}
14. references/report-generator.md {model: frontier}

ウェーブ単位の並列実行：

• ウェーブ 0（逐次）：ステップ 0 — 環境のセットアップ（ルール 1～4）
• ウェーブ 1（並列）：ステップ 1 + 2 — リポジトリのインベントリ + 設定（ルール 5～6）
• ウェーブ 2（並列）：ステップ 3 + 4 + 5 + 9 — CI/CD + テスト + コード品質 + AI ハーネスと導入（ルール 7～9、13）
• ウェーブ 3（並列）：ステップ 6 + 7 — API 設計 + データレイヤー（ルール 10～11）
• ウェーブ 4（逐次）：ステップ 8 — ドキュメント（ルール 12）
• ウェーブ 5（逐次）：ステップ 10 + 11 — レポートの生成 + エクスポート（ルール 14）

モジュール方式のメリット：

• 各ルールを個別に実行できます
• 出力を保存して再利用できます
• デバッグとメンテナンスが容易になります
• ウェーブ単位の並列処理により、Agent ツールを使った分析を高速化できます
• 関心事を明確に分離できます
• 近道を厳格に禁止することで、証拠に基づく完全な分析を徹底できます
• モノレポの依存関係を包括的に管理できます
• nvm の設定を完全に適用できます
• すべての依存関係を含むプロジェクト環境を完全にセットアップできます

サブエージェントのディスパッチ（セッション内）

このセクションでは、セッション内のマルチエージェント経路について説明します。上記のルール実行順序は CLI（somnio run）経路に引き続き適用され、変更はありません。

エントリーポイント：agents/orchestrator.md（model: mid）。オーケストレーターは Agent ツールを通じてすべてのサブエージェントをディスパッチし、各ウェーブの間に成果物を検証して、成果物マニフェストをレポートライターに渡します。

ウェーブ計画：

Wave	Mode	Subagent(s)	Tier	Reference(s) covered	Artifact(s) produced
0	Sequential (MANDATORY gate)	env-setup-agent	cheap	tool-installer, version-alignment, version-validator, test-coverage	step_00_env_setup.md, step_00_test_coverage.md
1	Parallel	repo-analyzer, config-analyzer	cheap, cheap	repository-inventory, config-analysis	step_01_repository_inventory.md, step_02_config_analysis.md
2	Parallel	cicd-analyzer, testing-analyzer, code-quality-analyzer, harness-analyzer	mid, mid, mid, mid	cicd-analysis, testing-analysis, code-quality, harness-analysis	step_03_cicd_analysis.md, step_04_testing_analysis.md, step_05_code_quality.md, step_09_harness_analysis.md
3	Parallel	api-design-analyzer, data-layer-analyzer	mid, mid	api-design-analysis, data-layer-analysis	step_06_api_design_analysis.md, step_07_data_layer_analysis.md
4	Sequential	docs-analyzer	cheap	documentation-analysis	step_08_documentation_analysis.md
5	Sequential	report-writer-agent	frontier	report-generator, report-format-enforcer, assets/report-template.md	reports/<YYYY-MM-DD>-<project>-nestjs-health-audit.md

オーケストレーターの動作：

• Wave 0 のみが必須の停止ゲートです。env-setup-agent が Result: FAILED を出力した場合、オーケストレーターは処理を停止し、解決手順を提示します。
• ウェーブ終了後に必須ではない成果物が欠けている場合、担当エージェントを一度再試行します。それでも成果物がない場合は、スキップを記録し、マニフェスト内で該当セクションを Unavailable とします。
• オーケストレーターはソースコードを読むことも、文章を書くこともありません。

レポートライターの動作：

• Wave 0〜4 で作成された 11 個すべての成果物を読み込みます。
• references/report-generator.md で定義された重み付けに従って、9 つのセクションスコアと総合スコアを算出します。このファイルが唯一の信頼できる情報源です。ここで数値を再掲しないでください。
• references/report-format-enforcer.md で定められた必須の 15 セクション構成を適用します。
• セクション間のスコアを調整します（例：Testing スコアが低い場合は Code Quality の説明に反映します）。
• reports/<YYYY-MM-DD>-<project>-nestjs-health-audit.md を作成し、メタデータブロックを追記します。
• 生のソースファイルを再度読み込むことはありません。

レポートファイル名（必須）

レポートファイル名は常に次のとおりです。

<YYYY-MM-DD>-<project>-nestjs-health-audit.md

• <YYYY-MM-DD> — この実行の日付です。
• <project> — git リポジトリ名を kebab-case に変換した文字列です。小文字にし、スペース、_、.、/ を - に置き換え、それ以外の文字をすべて削除し、連続する - を 1 つにまとめます。名前には origin リモート URL の値を使用するため、チェックアウトディレクトリ、ワークツリー、サブディレクトリの名前にかかわらず同じです。リモートがない場合はメインのチェックアウトディレクトリ名を使用し、git リポジトリ外では現在のディレクトリ名を使用します。
• 末尾のセグメントはこのスキルの名前であり、変更されません。

何かを書く前に、一度だけ算出してください。

mkdir -p reports
REPO="$(git remote get-url origin 2>/dev/null | sed -E 's#/+$##; s#.*[/:]##; s#\.git$##')"
if [ -z "$REPO" ]; then
  COMMON="$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)"
  [ -n "$COMMON" ] && REPO="$(basename "${COMMON%/.git}" .git)"
fi
[ -n "$REPO" ] || REPO="$(basename "$PWD")"
REPORT="reports/$(date +%F)-$(printf '%s' "$REPO" \
  | tr '[:upper:]' '[:lower:]' | tr ' _./' '-' \
  | sed -E 's/[^a-z0-9-]//g; s/-+/-/g; s/^-|-$//g')-nestjs-health-audit.md"

このスキルが reports/<YYYY-MM-DD>-<project>-nestjs-health-audit.md に書き込む箇所はすべて、この確定済みパスを指します。

somnio run を通じて実行する場合、CLI がレポートの完全なパスを算出し、プロンプトで渡します。渡されたパスをそのまま使用してください。再計算すると、ランナーがレポートを見つけられず、ステップが失敗します。

レポートのメタデータ（必須）

生成するレポートには、必ず末尾にメタデータブロックを含めてください。これは必須です。省略しないでください。

テンプレートの Report Metadata テーブルを、レポートの最後のブロックとしてコピーしてください。Generated by 行はテンプレートの記載どおりに保ち、変更、推測、省略はしないでください。残りの行は説明に従って記入してください。

このブロックは、番号なしの Markdown テーブルとしてレポートの末尾に含めてください（「Appendix: Scoring Methodology」ブロックの後に続きます）。

## Report Metadata

| Field | Value |
|-------|-------|
| Generated by | Somnio CLI v3.2.8 |
| Skill | nestjs-health-audit |
| Date | [YYYY-MM-DD] |
| Somnio AI Tools | https://github.com/somnio-software/somnio-ai-tools |