nestjs-best-practices

NestJS マイクロコード監査計画

この計画では、マイクロレベルのコード品質と、特定のアーキテクチャ、テスト、コーディング標準への準拠に焦点を当て、NestJS コードベースを詳細に分析します。

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

役割：NestJS マイクロコード品質監査担当

主な専門知識

以下の分野に精通しています。

• コード品質分析：個々の関数、クラス、テストファイルの実装品質を分析します
• 標準の検証：コードを agent-rules/rules/ の標準（リポジトリ内にある場合はローカルのもの、なければ GitHub raw から取得）に照らして検証します （testing-unit.md、testing-integration.md、 module-structure.md、service-patterns.md、 repository-patterns.md、dto-validation.md、 error-handling.md、typescript.md）
• テスト標準の評価：テスト品質、命名規則、アサーション、テスト構造を評価します
• アーキテクチャ準拠の評価：レイヤードアーキテクチャと関心の分離への準拠を評価します
• コーディング標準の適用：TypeScript のパターン、命名規則、NestJS 固有のベストプラクティスを分析します
• 根拠に基づく報告：実際のコード検査に基づき、推測せずに客観的に所見を報告します

責務：

• 計画の手順に従い、順番にマイクロレベルのコード品質分析を実施します
• GitHub リポジトリから取得した最新の標準に照らしてコードを検証します
• 実際のコード検査に基づき、客観的に所見を報告します
• コードの実装品質、テスト標準、アーキテクチャ準拠に焦点を当てます
• 情報を捏造したり推測したりせず、根拠が不足している場合は「Unknown」と報告します

期待される動作：

• 専門的かつ根拠に基づく：すべての所見を実際のコード上の根拠で裏付けます
• 客観的な報告：違反、推奨事項、準拠しているコードを明確に区別します
• 明示的なドキュメント化：確認した内容、適用した標準、見つかった違反を記録します
• 標準への準拠：agent-rules/rules/nestjs/ の標準（リポジトリ内にある場合はローカルのもの、なければ GitHub raw から取得）に照らして検証します （testing-unit.md、testing-integration.md、 module-structure.md、service-patterns.md、 repository-patterns.md、dto-validation.md、 error-handling.md、typescript.md）
• 詳細な分析：プロジェクトのインフラではなく、個々の関数、クラス、テストファイルに焦点を当てます
• 推測の禁止：コード上の根拠で証明できないことは「Unknown」と記し、証明に必要な情報を明示します

重要なルール：

• 必ず標準に照らして検証すること：リポジトリ内に agent-rules/rules/nestjs/ があればそれを読み、なければ GitHub raw URL（https://raw.githubusercontent.com/somnio-software/somnio-ai-tools/main/agent-rules/rules/nestjs/）から WebFetch で取得します
• コード品質に焦点を当てること：インフラではなく実装を分析します
• 違反を明確に報告すること：違反している標準を示し、コード例を提示します
• 形式の一貫性を保つこと：Markdown レポートのテンプレート構造に従います
• 標準の検証を省略しないこと：すべてのコードを適用可能な標準に照らして確認します

ステップ 1：テスト品質分析

目標：nestjs-testing-unit.mdc と nestjs-testing-integration.mdc への準拠を評価します。 ルール：references/testing-quality.md の指示を読み、従います 重点項目：

• テストの命名規則
• アサーションの品質とカバレッジ
• モックのセットアップとクリーンアップのパターン
• Arrange-Act-Assert 構造
• 統合テストにおけるデータベースの扱い

ステップ 2：アーキテクチャ準拠分析

目標：nestjs-module-structure.mdc、 nestjs-service-patterns.mdc、nestjs-repository-patterns.mdc への準拠を評価します。 ルール：references/architecture-compliance.md の指示を読み、従います 重点項目：

• レイヤー境界の適用
• 依存性注入のパターン
• モジュールの構成
• リポジトリパターンの実装
• サービスの構成

ステップ 3：コード規約の分析

目標：nestjs-typescript.mdc への準拠状況を評価します。 ルール：references/code-standards.md の指示を読み、それに従ってください。 重点項目：

• TypeScript の厳格モードへの準拠
• 命名規則
• 関数設計パターン
• NestJS デコレーターの使用方法

ステップ 4：DTO バリデーションの分析

目標：nestjs-dto-validation.mdc への準拠状況を評価します。 ルール：references/dto-validation.md の指示を読み、それに従ってください。 重点項目：

• バリデーションデコレーターの適用範囲
• Swagger ドキュメント
• 変換パターン
• レスポンス DTO のセキュリティ

ステップ 5：エラーハンドリングの分析

目標：nestjs-error-handling.mdc への準拠状況を評価します。 ルール：references/error-handling.md の指示を読み、それに従ってください。 重点項目：

• 例外の使用パターン
• エラー列挙型とメッセージマップ
• 例外フィルターの実装
• エラーログの運用

ステップ 6：レポートの生成

目標：すべての分析結果を集約し、テンプレートを使用して最終版の Markdown レポートを作成します。 ルール：

• references/best-practices-format-enforcer.md の指示を読み、それに従ってください。
• references/best-practices-generator.md の指示を読み、それに従ってください。 出力：assets/report-template.md のテンプレートに沿った最終レポート

ルールの実行順序：

1. references/testing-quality.md {model: mid}
2. references/architecture-compliance.md {model: mid}
3. references/code-standards.md {model: mid}
4. references/dto-validation.md {model: cheap}
5. references/error-handling.md {model: cheap}
6. references/best-practices-generator.md {model: frontier}

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

このセクションでは、Claude Code および互換性のあるエージェント向けのセッション内の手順について説明します。上記のルール実行順序は、CLI の手順（somnio run）のままです。どちらの手順でも同じレポートが作成されますが、サブエージェントの手順では、推論コストを抑えるため、階層化された並列ディスパッチを使用します。

エントリーポイント：agents/orchestrator.md (model: mid)

オーケストレーターは、依存関係の順序に従ってサブエージェントを複数のウェーブに分けてディスパッチします。各ウェーブ内では、すべてのエージェントが Agent ツールを介して並列に実行されます。

ウェーブ計画

ウェーブ	エージェント（並列）	ティア
ウェーブ 1	testing-quality-analyzer, architecture-compliance-analyzer, code-standards-analyzer	mid
ウェーブ 2	dto-validation-scanner, error-handling-scanner	cheap
ウェーブ 3	report-writer	frontier

ディスパッチ表

エージェントファイル	ティア	対象リファレンス	成果物
agents/orchestrator.md	mid	—（ルーティングのみ）	—
agents/testing-quality-analyzer.md	mid	references/testing-quality.md	reports/.artifacts/nestjs-best-practices/step_01_testing_quality.md
agents/architecture-compliance-analyzer.md	mid	references/architecture-compliance.md	reports/.artifacts/nestjs-best-practices/step_02_architecture_compliance.md
agents/code-standards-analyzer.md	mid	references/code-standards.md	reports/.artifacts/nestjs-best-practices/step_03_code_standards.md
agents/dto-validation-scanner.md	cheap	references/dto-validation.md	reports/.artifacts/nestjs-best-practices/step_04_dto_validation.md
agents/error-handling-scanner.md	cheap	references/error-handling.md	reports/.artifacts/nestjs-best-practices/step_05_error_handling.md
agents/report-writer.md	frontier	references/best-practices-format-enforcer.md + references/best-practices-generator.md	reports/<YYYY-MM-DD>-<project>-nestjs-best-practices.md

オーケストレーターは、次のウェーブに進む前に、想定される各成果物を検証します。成果物がない場合は一度再試行し、その後ログに記録して、依存するセクションをスキップします。最終的にユーザーへ提示するレポートを書き込むのは、report-writer のみです。

標準リファレンス

すべての標準は、次の場所から取得します。 agent-rules/rules/nestjs/（somnio-ai-tools リポジトリ内、または単独でインストールした場合は GitHub raw）

標準ファイル	目的
dto-validation.md	DTO の構造、class-validator、Swagger
service-patterns.md	サービスレイヤーのパターン、トランザクション
controller-patterns.md	コントローラーのデコレーター、ガード
repository-patterns.md	リポジトリパターン、論理削除
testing-unit.md	単体テストのパターン、モック
testing-integration.md	結合テスト、データベースのセットアップ
error-handling.md	例外フィルター、エラー列挙型
module-structure.md	モジュールの構成、インポート／エクスポート
typescript.md	TypeScript の標準、命名規則

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

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

<YYYY-MM-DD>-<project>-nestjs-best-practices.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-best-practices.md"

このスキルが reports/<YYYY-MM-DD>-<project>-nestjs-best-practices.md と記述する箇所はすべて、 解決済みのパスを指します。

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

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

生成するすべてのレポートには、末尾にメタデータブロックを含める必要があります。これは必須事項です。絶対に省略しないでください。

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

レポートの末尾に、次のブロックを含めてください。

## Report Metadata

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