nestjs-architecture-principles

NestJS のアーキテクチャと原則

アーキテクチャの判断は、リポジトリの実際の制約に基づいて行います。必要な境界を守り、安全に進化できる最もシンプルな設計を優先します。

実行前の競合確認

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

前提条件

リポジトリの指示、インストール済みのバージョン、モジュールの接続、コントラクト、呼び出し元、テスト、および影響を受けるコマンドを調査してください。ユーザーによる変更を保持してください。判断が重なる場合に限り、ほかの有効なスキルを読み込んでください。

主な担当範囲

このスキルは、アーキテクチャレベル、機能／モジュール API、依存関係の方向、データ／書き込みとトランザクションの境界、ポート、およびサービスの抽出を担当します。関連するスキルがインストールされている場合は、以下と連携してください。

• nestjs-oop-design-patterns：オブジェクトの責務、不変条件、パターン。
• nestjs-features-performance：ライフサイクル、API／セキュリティ、テスト、ランタイム、パフォーマンス。
• nestjs-professional-software-engineering：実装と検証。
• nestjs-code-audit：読み取り専用の品質に関する根拠と、重複を排除した報告。
• nestjs-feature-audit：ブランチ固有のロードマップ上のゲートと機能の報告。
• nestjs-git-commit-pr-message：承認された Git への公開と CI のフォローアップ。

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

競合の確認

互換性のない編集／コントラクト、コマンドの順序や副作用、担当者の競合、バージョン、根拠、承認、またはリポジトリの前提条件の未充足を確認してください。明示的なユーザーの意図、リポジトリのコントラクト、検証済みのランタイム制約、そして最も限定的な担当範囲の順に解決してください。各判断の主担当は一つにし、互換性のない助言を満たすために並行して設計を作らないでください。重大な競合が残る場合は、変更を行う前に停止し、判断に必要な最小限の情報を確認してください。監査は読み取り専用で実施します。明示的な修正承認は、独立した実装フェーズで適用してください。

根拠から始める

アーキテクチャを推奨または変更する前に、次のことを行ってください。

1. package.json、nest-cli.json、TypeScript の設定、ブートストラップファイル、および関連モジュールを読みます。
2. モジュールのインポートグラフ、プロバイダーのエクスポート、エントリーポイント、永続化の担当範囲、トランスポート、および既存のテストを把握します。
3. ビジネス機能と、チームの所有権、独立したスケーリング、変化の多いインテグレーション、トランザクション境界、セキュリティ、またはデリバリー速度といった具体的な変更圧力を特定します。
4. 現在のアーキテクチャを一文で述べます。フォルダー名だけを根拠に、プロジェクトを「クリーンアーキテクチャ」や「DDD」と分類しないでください。
5. 健全なローカル規約を維持します。正確性、セキュリティ、運用性、または明示的なコントラクトを損なう場合に限り、規約の問題を指摘してください。

タスクがバージョンに依存する場合は、API やコマンドを使用する前に、インストール済みの NestJS バージョンと最新の公式ドキュメントを確認してください。

アーキテクチャのレベルを選ぶ

references/architecture-ladder.md のアーキテクチャラダーを使用してください。

基本方針：

• まずはビジネス機能ごとに整理したモジュラーモノリスから始めます。
• ドメインロジックやインフラストラクチャの変動性によって境界が有益になる場合は、内部レイヤーを追加します。
• 置き換え可能な外部関心事をアプリケーションから分離する必要がある場合は、ポートを追加します。
• コマンドとクエリの振る舞いが実際に異なる場合に限り、CQRS を追加します。
• 独立したデプロイ、所有権、スケーリング、データ、または障害の境界がある場合に限り、サービスを分割します。

フォルダーツリーを図に似せることだけを目的として、レイヤー、バス、リポジトリ、ファクトリー、またはサービスを導入しないでください。

これらの境界を守る

1. モジュールが公開する API は小さくします。 プロバイダーは、別のモジュールで実際に必要とされない限り、非公開にします。
2. ビジネス機能は、自らの不変条件と書き込みを管理します。 他のモジュールとは、エクスポートされたアプリケーションサービス、ポート、イベント、または意図的に設計された読み取りモデルを通じて連携します。
3. 依存関係はポリシーに向けます。 ドメインコードから NestJS、ORM、HTTP 型、キュージョブ、ベンダー SDK をインポートしません。
4. コントローラーとトランスポートハンドラーはアダプターです。 フレームワークの仕組みを通じて認証・認可を行い、トランスポート入力を検証し、アプリケーション操作を呼び出して結果をマッピングします。
5. アプリケーション操作は調整を担います。 永続化やトランスポートの詳細を取り込まずに、ユースケースの流れとトランザクションの意図を定義します。
6. インフラストラクチャは境界部分を実装します。 ORM、ブローカー、キャッシュ、ファイルシステム、外部 API は、その変化の大きさやテストコストに応じて、明示的な境界の内側に置きます。
7. 循環依存は設計上のフィードバックです。 forwardRef() は最後の手段として互換性を確保するために使い、デフォルトの解決策にはしません。
8. 構成ルートが配線を担います。 Nest モジュールとプロバイダーが実装を組み立てます。ビジネスオブジェクトが実行時に依存関係を探すことはありません。

統合されたルールセットについては、references/architecture-rules.md を読み込んでください。NestJS の境界の詳細については、references/module-boundaries.md と references/dependency-injection.md を読み込んでください。

原則を実務に即して適用する

references/engineering-principles.md は、標語ではなく判断基準として使用してください。

原則が相反する場合は、次の優先順位に従ってください。

1. 正確性、セキュリティ、データの整合性
2. 明示的な外部契約と後方互換性
3. 運用性と障害の封じ込め
4. リポジトリで確立された慣習
5. 設計の純粋性と局所的な洗練性

KISS は、障害ケースを隠すことではありません。DRY は、たまたま似ているものを抽象化することではありません。SOLID は、動詞ごとにクラスを 1 つ作ることを求めていません。YAGNI は、既知の要件によってすでに求められている境界を設けない理由にはなりません。

ワークフロー

新しい設計の場合

1. 目標、制約、対象外の事項、重要な品質属性、想定される変更軸を定義します。
2. それらを満たす、最も低いアーキテクチャレベルを選びます。
3. 技術レイヤーの名前を決める前に、機能と所有権に名前を付けます。
4. 依存関係とデータの所有権を図示します。書き込みの所有権が曖昧な場合は採用しません。
5. 同期呼び出し、イベント、トランザクション、障害時の動作を明確にします。
6. 推奨する設計を 1 つ提示し、意図的に最適化していない点を説明します。
7. その判断を守るアーキテクチャテスト、統合テスト、運用チェックを定義します。

実装またはリファクタリングの場合

1. 関連するリクエスト、メッセージ、ジョブをエンドツーエンドで追跡します。
2. 問題の原因となっている、最小の境界違反を特定します。
3. 抽象化を追加する前に、振る舞いをその所有者へ移します。
4. 複数の実装がある場合、変化しやすい境界がある場合、または価値のあるテストの接点になる場合に限り、ポートを導入します。
5. 変更は段階的に行い、ユーザーが移行を求めていない限り公開契約を維持します。
6. 影響を受けるテスト、モジュールの配線、ドキュメント、呼び出し元を更新します。

レビューの場合

references/architecture-review.md を使用してください。重要度、影響、最小限の修正案、検証手順を添えて、根拠に基づく指摘を報告します。境界の修正で十分な場合に、全面的な書き直しを提案しないでください。

参照先

利用者に対する保証と、実行可能な配線や動作の制御については、module-contracts.md を参照してください。

タスク	参照先
統合されたアーキテクチャルールを適用またはレビューする	architecture-rules.md
モジュラーモノリス、レイヤー、ヘキサゴナル、CQRS、またはサービスを選択する	architecture-ladder.md
機能モジュール、エクスポート、所有権を設計する、または循環依存を解消する	module-boundaries.md
プロバイダートークン、ポート、スコープ、ファクトリー、または動的モジュールを定義する	dependency-injection.md
データベースの所有権、リポジトリ、マイグレーション、トランザクション、または ORM の境界を定義する	database-orm.md
サービスの分離、分散データの所有権、コントラクト、またはメッセージングのセマンティクスを判断する	microservices.md
KISS、YAGNI、DRY、凝集度、結合度、依存関係のルールを適用する	engineering-principles.md
リポジトリを監査する、または段階的な移行を計画する	architecture-review.md

期待される回答

アーキテクチャに関する作業では、結果を評価しやすい形にしてください。

• ベースライン： 現在のアーキテクチャと根拠。
• 決定： 推奨する方向性を1つ。
• 理由： 判断の根拠となる制約とトレードオフ。
• 境界： モジュールの所有権、依存関係の方向、データの所有権、統合方式。
• 移行： 変更が必要な場合は、最も安全で小規模な手順。
• 検証： テスト、グラフチェック、ランタイムチェック、運用シグナル。

アーキテクチャの変更が正当化されない場合は、その旨を明確に伝えてください。