nestjs-dev-guidelines

NestJS 開発ガイドライン

本番環境向けの NestJS および NestJS スタイルの Node.js バックエンド標準を網羅しています。モジュール、コントローラー、プロバイダー／サービス、DTO、パイプ、ガードなどの NestJS の概念をすでに使用しているコードベースで作業する場合や、これらのパターンの設計が明示的なタスクである場合は、常にこのルールを適用してください。シニアバックエンドエンジニアの視点で考えましょう。巧妙さより一貫性、暗黙より明示、近道より境界を重視してください。

このスキルの使い方

1. コードの作成やレビューの前に、references/00-execution-discipline.md と以下の 必須事項 を確認してください。
2. ファイルの配置、モジュールの境界、リファクタリングの判断には、判断ツリー を使用してください。
3. トピックの詳細を確認するには、対応する references/NN-<topic>.md ファイルを開いてください。各ファイルは単独で参照でき、要約、ルール、良い例／悪い例、アンチパターン、レビュー用チェックリストが含まれています。
4. PR をレビューする際は、references/29-code-review-checklist.md と、差分に関連するトピックのリファレンスを確認してください。

対象範囲と優先順位

リポジトリが「バックエンド TypeScript」ではあるものの、標準的な NestJS アプリかどうかが明確でない場合は、このセクションを使用してください。

1. NestJS を優先する対象範囲。 リポジトリが NestJS のプリミティブ（@Module、コントローラー、プロバイダー／サービス、ガード、パイプ、DTO）をすでに使用している場合、またはユーザーが NestJS ソリューションの設計を依頼している場合は、このスキルをそのまま適用してください。
2. プレーンな Node.js バックエンドには部分的にのみ適用。 リポジトリが NestJS のプリミティブを使わないプレーンな Express／Fastify／Hono／Koa の場合は、ここに記載された横断的なガイダンス（バリデーション、契約、認可、DB 設計、テスト、可観測性）のみを使用してください。NestJS 固有の API、デコレーター、フォルダー構成を、そのコードベースに無理に持ち込まないでください。
3. ツールより先に成果を守る。 以下の必須事項は、まず不変条件であり、実装上のデフォルトはその次です。入力バリデーションの一元化、安定したレスポンス契約、構造化され機密情報をマスキングしたログ、所有権チェック、テストカバレッジは、それを実現するために使用するライブラリよりも重要です。
4. 同等に安全なリポジトリの規約に従う。 リポジトリですでに、同じ安全性や境界の特性を維持する別の健全な仕組み（たとえば、class-validator の代わりに Zod を使う場合や、nestjs-pino の代わりにリポジトリ標準の構造化ロガーを使う場合）が採用されているなら、作業中に書き換えず、そのリポジトリの規約に従ってください。
5. 有害な競合はエスカレーションする。 既存のパターンがセキュリティ、正確性、データ整合性、または安定した契約を損なう場合は、その問題を明確に指摘し、パターンを標準化したり適用範囲を広げたりする前に確認してください。

実行規律

NestJS 固有の詳細に取り掛かる前に、以下のルールを適用してください。LLM によく見られる失敗パターン、つまり暗黙の決めつけ、過剰な実装、広範囲に及ぶリファクタリング、未検証の修正を減らすためのルールです。

1. コーディングの前によく考えてください。 前提を明示してください。タスクが曖昧な場合は、質問するか、黙って一つに決めつけるのではなく、考えられる解釈を明示してください。
2. 変わりやすい情報を検証してください。 バージョン、パッケージ API、モデル ID、インストールコマンド、CLI フラグは変更されます。推奨する前に、公式ドキュメントとリポジトリで検証してください。記憶だけに頼らないでください。35-source-of-truth-freshness.md を参照してください。
3. 新しいコードを書く前に検索してください。 まず現在のモジュールを確認し、次に shared／common／core コードを調べて、再利用できる既存のユーティリティ、DTO、サービス、ガード、インターセプター、リポジトリ、パターンがないか確認してください。
4. きっかけとなった問題ではなく、根本原因を修正してください。 製品要件が文字どおり決定論的なルールベースのルーティングである場合を除き、一時しのぎの正規表現、ハードコードされたフレーズ、手動の if／then ルールで広範な動作を修正しないでください。
5. 正しく、最小限の変更を優先してください。 タスクまたはコードベースで明らかに必要とされていない限り、推測に基づくフラグ、抽象化、ヘルパー、設定、エッジケース処理を追加しないでください。
6. 必要箇所だけを編集してください。 依頼に必要な行だけを変更してください。近くにあるという理由だけで、無関係なコード、コメント、書式を整理しないでください。
7. 影響範囲全体を検索して更新してください。 共有関数、契約、DTO、型、動作を変更する場合は、呼び出し元、テスト、ドキュメント、サンプル、関連するフローを検索して更新し、変更全体に一貫性があることを確認してください。
8. 共有動作を変更する前に確認してください。 既存コードの再利用に共有セマンティクス、複数の呼び出し元、または再利用可能な契約の変更が必要な場合は、影響範囲を黙って拡大せず、作業を止めて確認してください。
9. 成功条件を定義してください。 曖昧な依頼を、回帰テスト、ユニットテスト、E2E テスト、型チェック、Lint、ビルド、具体的な手動確認など、検証可能なチェックに置き換えてください。
10. 迷ったら作業を止めてください。 不確かな点を早めに明示してください。間違ったコードを書き直すより、短く確認するほうが効率的です。

チェックリストと例の全文については、references/00-execution-discipline.md を開いてください。

必須事項（これらの成果を守るため、以下のパターンを優先してください）

各ルールには理由が記載されています。盲目的に適用するのではなく、エッジケースを考える際に役立ててください。

1. コントローラーにビジネスロジックを含めないでください。 コントローラーの役割は、入力を検証し、サービスに処理を委譲し、レスポンスを整えることです。それ以外は行いません。 理由： コントローラーは薄い HTTP アダプターです。コントローラー内のロジックは、フレームワークを起動しないとユニットテストできず、HTTP に関する関心事がドメインコードに入り込みます。04-code-quality.md を参照してください。
2. すべての外部入力は DTO を通してください。 ボディ、クエリ、パラメーターの DTO には class-validator を使用します。ValidationPipe は whitelist: true、forbidNonWhitelisted: true、transform: true を設定してグローバルに適用します。 理由： DTO は、未知のフィールド、不正な型、インジェクション用ペイロードを遮断する唯一の関門です。1 つでも省略すると、クライアントを信頼することになります。09-validation.md を参照してください。
3. クライアントを決して信頼しないでください。 URL から取得したすべての ID が、認証済みユーザー／組織の所有物であることを確認します。フィルターとソートのフィールドは許可リストで制限します。whitelist によってマスアサインメントを防ぎます。 理由： IDOR とマスアサインメントは、アプリケーションレベルで最もよくある 2 つの侵害です。「トークンが有効なら、ペイロードも問題ない」とコードが想定すると発生します。11、12 を参照してください。
4. 各モジュールは自身のテーブルを管理します。 モジュール間で生の DB 読み取りを行いません。モジュール B がモジュール A のデータを必要とする場合は、A のサービス（DI）を呼び出すか、A のイベントを購読します。 理由： テーブルへの共有アクセスがあると、スキーマを変更するたびにチーム間の調整が必要になります。モジュールが API ではなく DB を介して結合されます。03-module-design.md を参照してください。
5. データベースでは snake_case、コードでは camelCase を使用します。 テーブル名は複数形、カラム名は snake_case、主キーは id、外部キーは <entity>_id とします。 理由： 各エコシステムには規約があります。規約を混在させると、マッピングの不具合がいつまでも発生し、アドホックな SQL も扱いづらくなります。変更が最も難しい側（DB）の規約を選んでください。13-database-design.md を参照してください。
6. レスポンスは一貫した安定した契約に従います。 単一リソースの成功レスポンスはオブジェクトそのものを返し、リストの成功レスポンスは { data, meta } を返します。エラーは、適切な HTTP ステータスとともに { code, message, details?, traceId } を返します。 理由： 契約が一貫していれば、クライアントはあらゆる場面で使えるエラーハンドラーとページネーションハンドラーをそれぞれ 1 つ実装でき、サポート担当者も traceId で問題を切り分けられます。07、10 を参照してください。
7. すべてのリストエンドポイントでページネーションを必須にします。 変更される可能性がある大規模なデータを順に閲覧する場合はカーソル／キセット方式を選び、ページ番号による移動や正確な総件数が実際のプロダクト要件である場合はオフセット方式を選びます。どちらの方式もページネーション情報を含む meta を返します。 理由： ページネーションのないリストは、将来的な OOM や DB 障害の原因になります。適切なページネーション方式は、UX、一貫性の要件、規模によって異なります。08 を参照してください。
8. シークレットは環境変数からのみ取得し、起動時に Zod で検証します。 コードにもログにもシークレットを含めません。環境変数が無効な場合は、トラフィックの受け付けを開始する前にクラッシュさせます。 理由： 環境変数の欠落や形式不正を起動時に検知すれば軽微なインシデントで済みますが、ホットパスで実行時に検知すると顧客に影響する障害になります。20、11 を参照してください。
9. 構造化ログを使用し、機密情報をマスキングします。 本番環境では JSON 形式の nestjs-pino を使用し、authorization、cookie、set-cookie、password、token をマスキングします。すべてのログ行に相関 ID を含めます。 理由： プレーンテキストのログは大規模な環境でクエリできません。また、マスキングされていない Authorization ヘッダーが 1 つでもあれば、長期にわたる影響を伴う認証情報の漏えいにつながります。21 を参照してください。
10. 内部実装ではなく境界をテストします。 モックした依存関係を使ってサービスをユニットテストし、HTTP レイヤーを通じてコントローラーを E2E テストします。テスト対象のクラス自体をモックしてはいけません。 理由： テスト対象のコードをモックすると、モックの動作を再確認するだけになります。テストでは実装ではなく、契約（HTTP、DB、外部呼び出し）を検証してください。23 を参照してください。
11. テナント ID はサーバー側で導出し、多層で適用します。 マルチテナントアプリでは、テナント／組織 ID は認証済みセッション／JWT から取得し、リクエストボディから取得してはいけません。ガード、サービス、リポジトリーの各層でテナントによる絞り込みを行い、テナント A がテナント B のデータを参照できないことをテストで証明します。 理由： テナント間のデータ漏えいは、ほとんどの場合、WHERE tenant_id = ? が 1 か所欠けているか、クライアントから渡された ID を早い段階で信頼したことが原因です。多層で適用すれば、1 つの層にバグがあってもデータは漏えいしません。33 を参照してください。

シニアエンジニアの考え方（判断ツリー）

判断ツリーの全文は references/05-thinking-decision-trees.md にあります。要約：

このファイルはどこに配置しますか？

• ビジネス機能 → modules/<feature>/
• アプリ全体のインフラ（認証、Redis、メール） → core/<name>/
• 汎用ユーティリティ（パイプ、デコレーター、型） → common/<kind>/
• 外部 API クライアント（Stripe、AWS） → integrations/<provider>/
• CLI／CRON ジョブ → commands/<name>.command.ts
• ドメインイベントの発行元／リスナー → events/<event-name>/

新しいモジュールを作成すべきですか？

• 独自の DB テーブルを所有しますか？ → はい、新しいモジュールを作成します。
• 独自のライフサイクル／ドメインロジックがありますか？ → はい、新しいモジュールを作成します。
• 1 つのモジュールだけで使用するヘルパーにすぎませんか？ → いいえ、そのモジュール内の utils/ に配置します。
• データは所有しないものの、2 つ以上のモジュールで使用されますか？ → common/ ユーティリティにします。

今すぐリファクタリングすべきですか？

• すでにこのコードを編集していますか？ → はい、作業しながら整理します。
• 現在の機能の妨げになっていますか？ → はい、最小限のリファクタリングを行います。
• 単に「見栄えが悪い」だけですか？ → いいえ、記録して先に進みます。

テストを省略すべきですか？

• コントローラーですか？ → いいえ。必ず E2E テストを行います。
• 分岐ロジックを含むサービスですか？ → いいえ。必ずユニットテストを行います。
• findById のようなロジックのない薄い処理の受け渡しですか？ → 省略してもかまいません。コントローラーの E2E テストでカバーされます。
• DTO／型ですか？ → テストは不要です。コンパイラーがテストになります。

ルール一覧（参照ファイルごとに 1 行）

詳細が必要な場合は、参照ファイルの全文を読んでください。番号の接頭辞は順序を固定するためのものです。

#	File	Rule in one line
00	00-execution-discipline.md	まず考え、変わりやすい事実（バージョン／API／モデル ID）はドキュメントで検証し、変更を小さく保ち、必要な箇所だけを編集し、成功基準を定め、完了を宣言する前に検証します
01	01-folder-structure.md	src/{core,common,integrations,modules,events,commands} — コードの種類ごとに置き場所を一つにします
02	02-naming-conventions.md	変数はcamelCase、クラスはPascalCase、DB はsnake_case、ファイルはkebab-case.ts、環境変数はSCREAMING_SNAKE
03	03-module-design.md	境界づけられたコンテキストごとにモジュールを一つ設けます。@Global()はアプリ全体で使う基盤に限ります
04	04-code-quality.md	SOLID、コンストラクター DI、純粋なユーティリティ、小さな関数、理由のないanyは禁止
05	05-thinking-decision-trees.md	判断方法：コードの配置場所、リファクタリングのタイミング、テストを省略するタイミング
06	06-api-design.md	REST、複数形の名詞、意味に合った動詞、URI バージョニング/v1/...、冪等性キー
07	07-standard-responses.md	単一の成功レスポンスはプレーンオブジェクト、リストは{ data, meta }、エラーは{ code, message, details?, traceId }を返します
08	08-pagination-filters-sorting.md	順次閲覧にはカーソル／キ​​ーセット方式、ページ番号や正確な総数が実際に必要な場合はオフセット方式を使います。filter[field]=、sort=-createdAtを使用し、フィールドをホワイトリスト化します
09	09-validation.md	class-validator DTO とグローバル ValidationPipe を使用します。環境変数と実行時の JSON 解析には Zod を使用します
10	10-error-handling.md	ハイブリッド分類：HTTP ステータス＋名前空間付きコード＋traceId。ドメインエラーは意味に即した Nest 例外を継承します。host.getType()とheadersSentのガードを備えたグローバルフィルターを一つ設け、PinoLoggerでログを記録します
11	11-security.md	セキュリティレビューの手順：OWASP Top 10、トランスポート／CORS、インジェクション／SSRF、パスワードのハッシュ化、レート制限、PII／監査、認証／ウェブフック／アップロードへのリンク
12	12-authentication-patterns.md	セッション Cookie（ブラウザー）または Bearer JWT（モバイル／サーバー）を使用します。セッション／リフレッシュトークンは保存時にハッシュ化し、リフレッシュトークンをローテーションし、revoked_beforeを使用します。Cookie を優先し、無効な Cookie があれば安全側に倒して認証を拒否します。認証エラーは{ code, message }を使用します
13	13-database-design.md	snake_case、複数形のテーブル名、FK は<entity>_id、FK とクエリパスにインデックスを設定し、deleted_atを使用します。UUIDv7 または bigint を使用します
14	14-database-orm-patterns.md	raw pg／TypeORM／Prisma／Drizzle — パターンを並べて比較します
15	15-migrations.md	本番環境では常に前方のみのマイグレーションにします。2 段階のロールアウトなしに破壊的な変更を行いません
16	16-cascade-rules.md	所有データにはON DELETE CASCADE、共有参照にはRESTRICT、任意の参照にはSET NULLを使用します
17	17-pipelines-interceptors-guards.md	順序：Guard → Interceptor（前処理）→ Pipe → Handler → Interceptor（後処理）→ Filter
18	18-events.md	プロセス内では EventEmitter2 を使用します。サービス間またはキューをまたぐ場合は outbox パターンを使用します
19	19-background-jobs.md	デフォルトは BullMQ です。ハンドラーは冪等にし、バックオフ付きで再試行し、処理不能なメッセージには DLQ を使用します
20	20-configuration.md	ConfigModuleをグローバルにします。Zod スキーマを使用し、環境変数が無効な場合は起動時に速やかに失敗させます
21	21-logging.md	nestjs-pino、本番環境では JSON、シークレットを秘匿し、リクエストごとに相関 ID を付与します
22	22-observability.md	トレースとメトリクスには OpenTelemetry を使用し、LLM トレースには Langfuse／Helicone を使用します
23	23-testing.md	単体テストは実装の隣に配置（*.spec.ts）、e2e テストはtest/に配置します。境界でモックし、統合テストには実 DB を使用します
24	24-performance.md	N+1 を避け、コネクションプールのサイズを適切に設定し、必要な箇所だけをキャッシュし、大きなペイロードはストリーミングします
24a	24a-caching-patterns.md	キャッシュは意図的に使用します。安定した名前空間付きキー、TTL＋無効化、スタンピード対策を採用します。認証／クォータ／課金の唯一の正としないでください
25	25-documentation-swagger.md	@ApiTags／@ApiOperation／@ApiResponseを使用します。@ApiPropertyにより DTO のスキーマを自動生成します
26	26-ai-product-patterns.md	プロバイダー抽象化、再試行、フォールバック、タイムアウトを備えた LLM ゲートウェイ
27	27-ai-streaming-sse.md	SSE エンドポイントを使用します。キャンセルを認識して上流を中断し、ハートビートを送り、イベント語彙を型付けします。再接続時に再開できる設計にはしません
28	28-ai-usage-metering-cost.md	呼び出しごとにトークン数とコストを記録し、ユーザー／組織／モデルごとに集計して、クォータを適用します
29	29-code-review-checklist.md	上記すべてのルールにわたる PR レビューチェックリスト
30	30-code-review-anti-patterns.md	アンチパターンと、良い例／悪い例のスニペットをまとめています
31	31-rules-rationale-examples.md	ルール、根拠、良い例／悪い例を横断的にまとめたクイックリファレンス
32	32-modern-nestjs-stack.md	NestJS サービスのモダナイズ／新規構築のための判断チェックリスト。ブートストラップの順序、モジュールシステムの確認を含み、固定されたバージョン一覧は設けません
33	33-multi-tenancy-patterns.md	テナント ID はサーバー側で取得し、認証、ガード、サービス、リポジトリーの各レイヤーで適用します。テストで分離を証明します
34	34-health-shutdown.md	ライブネスとレディネスを区別します。シャットダウンコーディネーターは一つにし、終了前に処理をドレインします。ワーカープロセスは個別にドレインします
35	35-source-of-truth-freshness.md	永続的な不変条件はローカルに保持します。変わりやすい API／バージョン／モデルは公式ドキュメントとリポジトリーで検証します
36	36-webhooks.md	生バイト列で署名を検証し（raw-body 設定＋timingSafeEqual）、(provider, event_id)で重複排除し、キューへの登録後に2xxで応答します（未処理のタイプも含む）。重要度の高いイベントでは信頼できる状態を再取得し、検証済みペイロードからテナントを特定します
37	37-file-uploads.md	署名付き URL を使ったバケットへの直接アップロードを優先します（クライアントにはPUT、ブラウザーにはPOSTポリシー）。境界でサイズ／MIME タイプを制限し、マジックバイトを確認します。不透明でテナント接頭辞付きのストレージキーを使い、ハッシュ／サイズ／MIME タイプをサーバー側で計算し、公開前に AV スキャンを実施し、アップロードエンドポイントにレート制限を設定します
38	38-decorators-scopes-dynamic-modules.md	パラメーターデコレーターはリクエストからの値の抽出に限ります。スコープはデフォルトでシングルトンにします。設定可能な基盤には動的モジュールを使用します。forwardRefは要注意の兆候です
39	39-exception-filters.md	グローバルフィルターは一つにし、すべてのエラーを{ code, message, details?, traceId }に整形します。型付きのHttpExceptionサブクラスをスローし、内部情報を漏らさないでください
40	40-ddd-layered-architecture.md	任意の DDD レイヤリングを 3 段階で示します（従来のレイヤー → レイヤー化された機能モジュール → ヘキサゴナルアーキテクチャのポート／アダプター）。依存関係は内向きにし、ドメインからフレームワークを排除します。CRUD ではデフォルトの 6 分類レイアウトが引き続き有効です
41	41-n-plus-one-elimination.md	N+1 は推測ではなくクエリ数で証明します。明らかなループ以外の 6 つのパターン、JOIN と 2 クエリの一括ロードとリクエスト単位の DataLoader を比較し、結合したコレクションに対する SQL のLIMITは決して使いません。クエリ数テストで修正を固定します

詳しく読むタイミング

作業内容	開くファイル
実装やバグ修正を始める	00, 05
新しい機能モジュールを始める	01, 03, 04
DDD レイヤー／ヘキサゴナルアーキテクチャ／ポートとアダプターで構成する	40, 01, 03
サービスを開始または近代化する	32, 34, 20
新しいエンドポイントを設計する	06, 07, 08, 09
エラーを一貫して返す	10
DB テーブルを設計する	13, 14, 15, 16
エンドポイントに認証を追加する	11, 12, 17
マルチテナントの分離を追加する	33, 11, 12, 14
一覧エンドポイントを追加する	07, 08, 41
キャッシュを追加する	24, 24a
遅いエンドポイント、N+1、またはクエリ数の多さを修正する	41, 24, 14, 13
バックグラウンドタスクを追加する	19, 34
テストを書く	23
可観測性を追加する	21, 22
ヘルスチェック／レディネス／シャットダウンを追加する	34, 32
LLM 機能を構築する	26, 27, 28, 22
サードパーティからの Webhook を処理する	36, 11, 19, 21, 33
ファイルアップロードを受け付ける	37, 11, 24
カスタムデコレーター／スコープ付きプロバイダー／動的モジュールを設計する	38, 03, 17
グローバル例外フィルター／エラーワイヤ形式を設計する	39, 07, 10
バージョン／コマンド／モデルに関するアドバイスをする	35
PR をレビューする	29, 30、および差分に関連するトピック

コードレビュー モード

ユーザーから PR、変更、または差分のレビューを依頼された場合：

1. まず差分を上から下まで読み、批評する前に意図を理解します。
2. 29-code-review-checklist.md を確認し、各項目を合格／不合格／該当なしで判定します。
3. 不合格の項目ごとに、該当するリファレンスファイルの具体的なセクションを示します（例： 「コントローラー内のビジネスロジック — 04-code-quality.md → レイヤリング／アンチパターンを参照」）。
4. ブロッカー（セキュリティ、データ損失のリスク、必須ルール違反）と 提案（スタイル、軽微な命名、任意のリファクタリング）を区別します。提案を理由にブロックしてはいけません。
5. アンチパターンに気づいた場合は、30-code-review-anti-patterns.md へのリンクを示し、 推奨されるコードを引用します。
6. レビューの最後に、（a）ブロッカー（番号付き）、（b）提案（箇条書き）、（c）ブロッカーの解消を条件とする承認を記載します。

AI 製品向け付録

プロジェクトが AI 製品のバックエンド（LLM、エージェント、RAG、ベクトルストア、ストリーミング、利用量ベースの課金）である場合は、次も読みます：

• 26-ai-product-patterns.md — プロバイダーに依存しない LLM ゲートウェイ、リトライ／フォールバック
• 27-ai-streaming-sse.md — SSE エンドポイントのパターン、キャンセル、ハートビート
• 28-ai-usage-metering-cost.md — トークンとコストの計測、クォータの適用
• 22-observability.md — LLM トレーシングのための Langfuse／Helicone

それ以外のすべて（認証、DB、エラー処理、テスト）は、AI 製品にも同様に適用されます。AI はモジュールであり、フレームワークではありません。

補足

• フレームワークの詳細より、実行規律を優先します。 小さく、明示的で、検証済みの変更は、素早く、広範で、巧妙な変更に勝ります。
• スタイルの好みより、ルールを優先します。 これらがルールであるのは、実際のバグを防ぎ、保守性の向上につながるからです。スタイルに関する議論は対象外です。
• 巧妙さより、一貫性を優先します。 リポジトリに、このスキルとは異なるものの、確立された同等に安全なパターンがある場合は、そのパターンに明らかな害がない限り、リポジトリの慣例に従います。
• 迷ったら、無難な方法を選びます。 無難なコードはレビューしやすく、オンボーディングしやすく、置き換えも容易です。それが目的です。