NestJS GraphQL 構造
NestJS GraphQL（コードファースト）アプリケーションにおける各ファイルの所属場所とその動作を定義します。このスキルは配置と構造のガイドです。「このファイルはどのフォルダに属するのか？」「このファイルの責務は何か？」「モジュールはどのように接続してフィールドやリレーションを解決するのか？」に答えます。ベース構造マップに加え、モジュール、サービス、リゾルバ（クエリ、ミューテーション、サブスクリプション、フィールド）、入力型と引数、ページネーション、エンティティ（共有型のMongooseスキーマベストプラクティス）、リポジトリ専用モデルインジェクション、モデル/マッパー、リポジトリ、Mongoose判別器、導出フィールド、プロバイダ、ローダー、イベント、バックグラウンドジョブ、認証、例外、カスタムスカラー、設定、共通ビルディングブロック、インフラセットアップ、命名/テスト/リント規則に至るまでのファイル別ルールを網羅します。
このスキルは意図的に nestjs-best-practices スキルとは分離されています。後者のスキルはフレームワークの振る舞い（依存性注入の深さ、セキュリティ、パフォーマンス、エラーハンドリング、マイクロサービス、DevOps）を扱い、本スキルは構造とモジュール構成を扱います。重複する部分（機能モジュール、循環依存関係）については、本スキルは配置の観点から見て、行動の深さについては他方のスキルを相互参照します。
このスキルは構造ルール（ファイルの配置場所） とモジュール解決ルール（実行時のモジュール接続方法、循環依存関係の解決など） の両方をカバーします。モジュール解決ルールはセクション2と3にあります。
適用タイミング
以下の場合にこれらのガイドラインを参照してください：
- NestJS GraphQLコードベースに新しいファイルを配置する場所を決めるとき
- 機能優先のディレクトリレイアウトを設計またはレビューするとき
- 新しい機能モジュールとそのファイルをスキャフォールディングするとき
- ポリモーフィックドキュメント（Mongoose判別器）をモデル化し、そのGraphQL型を自動公開する方法を決めるとき
- Mongooseモデルを注入できる場所、およびデータベースアクセスをリポジトリの背後に保つ方法を決めるとき
- ある値がデータベースに保存されるべきか、読み取り時に導出されるべきかを決めるとき
- 別のモジュールに存在するフィールドやリレーションをモジュールが解決する方法を検討するとき
- モジュール間の接続問題（循環依存関係、エクスポート漏れ）を解決するとき
優先度別ルールカテゴリ
| 優先度 | カテゴリ | 影響度 | 接頭辞 |
|---|---|---|---|
| 1 | アプリケーション構造 | クリティカル | struct- |
| 2 | モジュールとブートストラップ | クリティカル | module- |
| 3 | リレーションとクロスモジュール | クリティカル | relations- |
| 4 | サービス | 高 | service- |
| 5 | GraphQLリゾルバ | 高 | resolver- |
| 6 | GraphQLタイプと入力 | 高 | type- |
| 7 | データアクセス | 中高 | data- |
| 8 | 設定、共通、インフラ | 中 | infra- |
| 9 | 規則とテスト | 中 | conventions- |
クイックリファレンス
1. アプリケーション構造（クリティカル）
struct-auth-feature- 認証を独自の機能モジュールに保持するstruct-canonical-layout- 標準的なアプリケーション構造struct-feature-decomposition- 機能が大きくなったらサブモジュールに分割するstruct-file-placement-table- ファイル配置テーブルstruct-module-kinds- ドメイン機能とアプリレベルモジュールを区別するstruct-schema-artifact- 生成されたスキーマ成果物の場所とポリシー
2. モジュールとブートストラップ（クリティカル）
module-bootstrap- main.ts と app.module.ts は薄く保つmodule-export-policy- 機能の公開API（サービス）のみをエクスポートするmodule-feature-module- 機能モジュールファイル
3. リレーションとクロスモジュール（クリティカル）
relations-avoid-circular- 循環モジュール依存関係を解決するrelations-dataloader- リクエストごとのDataLoaderでリレーションをバッチ処理するrelations-events- イベントでモジュールを疎結合にするrelations-field-resolvers- @ResolveField でリレーションを解決するrelations-owning-module- リレーションフィールドをデータを所有するモジュールに配置する
4. サービス（高）
service-background-jobs- キュープロセッサとスケジュールジョブを機能と共に保持するservice-external-providers- サードパーティクライアントを providers/ に保持するservice-interfaces-tokens- サービス契約とインジェクショントークンを interfaces/ で宣言するservice-single-responsibility- モジュールごとに複数の焦点を絞ったサービスservice-small-focused-methods- サービスのメソッドを小さく焦点を絞って保つ
5. GraphQLリゾルバ（高）
resolver-computed-fields- フィールドは型で宣言し、計算フィールドはリゾルバで解決するresolver-organization- 役割に応じてリゾルバを resolvers/ に分割するresolver-per-type- フィールドリゾルバを持つ型ごとに1つのリゾルバファイルresolver-subscriptions- サブスクリプションリゾルバを resolvers/ に、PubSubを infra/ に配置する
6. GraphQLタイプと入力（高）
type-args- @Args クラスを dto/ に定義するtype-inputs- GraphQL入力を dto/ に定義するtype-pagination- リストクエリを共有のページタイプでページネーションするtype-polymorphic-discriminators- 判別されたドキュメントをインターフェースまたはユニオンとして公開するtype-unions-interfaces- ユニオン型とインターフェース型をモジュールの型と共に配置する
7. データアクセス（中高）
data-derived-fields- 導出フィールドは計算する；保存しないdata-discriminators- ポリモーフィックサブタイプを判別器でモデル化するdata-entity-mongodb- MongoDBエンティティを entities/ に配置するdata-model-injection- モデルはリポジトリでのみ注入するdata-models-mappers- APIがストレージと異なる場合、 models/ と mappers/ を分割するdata-mongoose-schema- 共有型のMongooseスキーマベストプラクティスdata-repository- データアクセスを repositories/ に保持する
8. 設定、共通、インフラ（中）
infra-common-types- 共有型を common/types/ に配置するinfra-common- 共有ビルディングブロックを common/ に配置するinfra-config- 型付き設定を config/ に配置するinfra-custom-scalars- カスタムスカラーを common/scalars/ に実装するinfra-database- データベース設定とマイグレーションを infra/database/ に配置するinfra-directives- スキーマディレクティブを common/directives/ に配置するinfra-exceptions- 例外を exceptions/ に配置するinfra-graphql- GraphQL設定を infra/graphql/ に配置するinfra-seeds- シードスクリプトを infra/database/seeds/ に配置するinfra-shared-module- 横断的サービスには SharedModule を使用する
9. 規則とテスト（中）
conventions-barrels-aliases- バレルとパスエイリアスを意図的に使用するconventions-cli-generator- Nest CLIジェネレータを使用し、その後調整するconventions-constants-enums- 定数と列挙型をクラスファイルの外に保持するconventions-module-boundaries- リントでモジュール境界を強制するconventions-naming- ファイルとクラスの命名規則conventions-test-fixtures- テストフィクスチャ、ファクトリ、ヘルパーを test/ に配置するconventions-testing- テストファイルの配置
使い方
ベース構造ルールから始め、作業中の特定のファイル種別のルールを読んでください。ルールファイルは rules/ の下にあります：
rules/struct-canonical-layout.md
rules/_sections.md
各ルールファイルには以下が含まれています：
- 目的と配置（ファイルがどこに存在し、どのように命名されるか）
- 責務と非責務
- 説明付きの誤った例
- 説明付きの正しい例
完全なコンパイルドキュメント
すべてのルールを1つのドキュメントに展開した完全版ガイドは AGENTS.md を参照してください。