kikita-labs/kikita-create-nestjs-app

kikita-create-nestjs-app は何をしますか？

新しい NestJS プロジェクトをブートストラップし、その AGENTS.md / .agents/ ドキュメントツリーを生成します。これにより、後からプロジェクトで作業する AI エージェント（Claude Code、Codex など）が完全で自己管理可能な信頼できる情報源を得られます。

0. モード検出（常に最初に行う）

ターゲットディレクトリに .agents/.kikita-scaffold.json が存在するか確認します。

• 不在 → 新規初期化。以下のセクション 1 に進み、次に plan.md に従います。
• 存在 → このプロジェクトは既にこのスキルでスキャフォールドされています。update.md に従ってください。質問票の再実行や再スキャフォールドは行わないでください。update.md は最新テンプレートの取得、記録されたコミットからの差分の確認、プロジェクトの（場合によってはカスタマイズされた）.agents/ ファイルへの変更のマージを処理します。

0.5 前提条件（新規初期化のみ）

• 作業ディレクトリが空であるか、ユーザーがここで初期化することを明示的に希望していることを確認します。
• 無関係なプロジェクトが既にあるディレクトリに対して、事前に尋ねずにこのコマンドを実行しないでください。

1. 質問票（ファイルシステムに触れる前に必ず質問する）

ここから plan.md に一歩ずつ従ってください。質問票をスキップしないでください。完了したら、ユーザーに終了を伝える前に checklist.md をすべて実行してください。

12 の質問を一度にまとめて尋ねるのではなく、2 段階で質問します。最初の回答によって、その後の質問のどれが関連するかが決まるため、すべてを最初に尋ねると、ボット専用のユーザーに当てはまらない「REST API の認証」の質問をすることになります。

段階 1 — 分岐の質問のみ、単独で：

1. アプリケーションタイプ: REST API、ボット、または同じアプリ内の両方？
   • ボット（または両方）の場合：どのプラットフォーム？ Telegram（nestjs-telegraf）または Discord — Discord については、necord が推奨デフォルトです（ネイティブ Nest DI/guards/pipes を介した汎用イベント→ハンドラ→サービスのパターンを満たすためのグルーコードが最も少ない）。ただし必須ではありません：ユーザーが代わりに生の discord.js を希望する場合（既存のチームの専門知識、necord がまだラップしていない discord.js の機能）、それは正当な選択肢です — 以下の「別のプラットフォーム」と同じように扱い、汎用パターンを手動で適応させ、自動では取得しないでください。
   • その他のプラットフォーム/ライブラリ（名前を指定 — architecture/transport-adapter.md の汎用ボット転送パターンはこれに適応しますが、具体的なアダプターコードは nestjs-telegraf/necord 以外の場合は手動で記述する必要があります）。

段階 2 — 残りのすべて、まとめて尋ねる（質問 3 は、段階 1 で REST または「両方」と答えた場合のみ尋ねます。それ以外の質問はアプリケーションタイプに関係なく適用されます）：

2. テスト: なし、または単体 / e2e（Supertest）/ 両方？ 「両方」は、モックの代わりに実際の Postgres インスタンスに対してヒットする統合テスト用の Testcontainers も配線します。
3. 認証（段階 1 がボット専用だった場合は完全にスキップ）：必要かどうか？ 「はい」の場合、1 つの固定された実戦的なパターンをスキャフォールドします。メニューではありません — core/auth.md のスキャフォールドブロックを参照：有効期間の短いアクセストークン（5〜15 分、クッキーには決して保存しない）+ /auth/refresh にスコープされた httpOnly クッキー内のリフレッシュトークン + ローテーション（単一使用、DB にハッシュ化）+ リフレッシュエンドポイントでの csrf-csrf + argon2id パスワードハッシュ化 + RolesGuard。代替案（セッション、ローテーションなしのベア JWT）は提供しないでください — これが唯一のデフォルトです。
4. バックグラウンドジョブ: BullMQ（Redis バックアップのキュー）を使うかどうか？
5. キャッシュ: @nestjs/cache-manager + @keyv/redis（cache-aside）を使うかどうか？ デフォルトの推奨はいいえです — 実際のパフォーマンス上の必要性がある場合に追加し、すべての CRUD エンドポイントに推測で追加しないでください。
6. ファイルアップロード: 必要かどうか？ 「はい」の場合、それ以上のサブ質問はありません — ストレージベンダー（開発時はローカルディスク、本番時は任意の S3 互換バケット：AWS S3、MinIO、R2、Spaces）は環境変数であり、スキャフォールド時の選択肢ではありません。
7. 非同期メッセージング / サービス間イベント: 必要かどうか？ 「はい」の場合、ブローカーのサブ質問もありません — RabbitMQ が固定のデフォルトです（タスクキュー、ルーティング、DLQ で圧倒的多数のケースをカバー）。architecture/messaging.md は、イベントストリーミング/リプレイ/超高スループットのニーズのために、Kafka を後日の移行パスとして文書化します。スキャフォールド時のオプションではありません。
8. i18n: このプロジェクトは複数のロケールを必要としますか — 翻訳された REST エラー/バリデーションメッセージや、複数の言語でのボット応答？ 「はい」の場合、それ以上のサブ質問はありません — nestjs-i18n が固定のライブラリです。ロケール解決はトランスポートによって異なります（REST：Accept-Language ヘッダー；ボット：プラットフォーム固有のユーザーごとのロケールフィールド、Accept-Language は使用しない）。両方とも core/i18n.md でカバーされています。「いいえ」の場合、スキップします — 1 つの言語でのみ実行されるプロジェクトにはこれは必要ありません。
9. 公開 API の JSDoc/TSDoc: すべてのエクスポートされたシンボルに必須のドキュメントコメントを強制するか、スキップするか？ .agents/agent-surface.md を生成するかどうかを決定します（推奨デフォルト：はい）。
10. Git ポリシー: エージェントが毎回尋ねることなくコミットおよびプッシュしてもよいか、それともすべてのコミット/プッシュを確認する必要があるか？
11. パッケージマネージャー: npm、pnpm、または yarn？ デフォルトの推奨：pnpm。
12. Git リモート: ユーザーはプッシュ先のリポジトリ URL を既に持っていますか？ 「はい」の場合、それを記録します — git remote add origin <url> は git init の直後に実行されます（plan.md 参照）。URL が指定されていない場合は、これをスキップします。ユーザーは後で自分でリモートを設定します。

すべての回答を記録します — それらはスキャフォールディングと、どのドキュメントファイルを生成するかの両方を決定します。上記で明示的に固定されているもの以外のデフォルトを黙って想定しないでください。ユーザーが質問をスキップした場合は、その質問について再度尋ねてください。このスキルは単一の NestJS プロジェクトを対象としており、モノレポ/Nx ワークスペースや分散マイクロサービストポロジ（複数のデプロイ可能なサービス/リポジトリ）は対象外です。ユーザーがそれらのいずれかを希望する場合、このスキルはそれをカバーしていないと言い、即興で対応せずに停止してください。メッセージブローカー（質問 7 を参照）は、ハイブリッドアプリ（同じ単一アプリ内で app.connectMicroservice() を使用）のみを配線します。決して 2 番目のサービスを起動しません。

固定のデフォルト — これらについては決して質問しないでください。設計上ロックされています：

• ORM/DB: Prisma + Postgres。TypeORM（新しいプロジェクトには推奨されません）、Drizzle（ニッチなパフォーマンス/エッジケース向け）、NoSQL/MongoDB ブランチはこのスキルの v1 では使用しません。
• バリデーション: HTTP レイヤーで class-validator + class-transformer、main.ts でグローバルな ValidationPipe を whitelist、forbidNonWhitelisted、forbidUnknownValues、transform すべて true で無条件に配線します。環境/設定のバリデーションには Zod（@nestjs/config + validate）、スキーマファイル外での直接の process.env 読み取りをブロックする ESLint ルールによって強制されます — testing-and-quality.md の「Mechanically Enforced Rules」を参照。ネストされた DTO フィールドには、@ValidateNested() と @Type(() => NestedDto) の両方が必要です — code-style/dto-and-validation.md を参照。@nestjs/swagger からインポートされた PartialType/OmitType/PickType を介した DTO 再利用。@nestjs/mapped-types は決して使用しません — ESLint でブロックされます（同じセクション）。
• レスポンス形状: グローバルな ClassSerializerInterceptor + DTO フィールドでの @Exclude() が 1 つの固定されたシリアル化メカニズムです。生の Prisma エンティティが返されることは決してなく、ADR なしに 2 番目のシリアル化アプローチが導入されることもありません。
• Swagger/OpenAPI: REST ブランチでは常に配線されます。
• CORS: 環境変数駆動のオリジン許可リストを介して main.ts で常に設定され、決して * にはなりません。
• API バージョニング: Nest URI バージョニング（/v1/...）、architecture/transport-adapter.md で固定。
• レート制限: REST やボットのために @nestjs/throttler が常にインストールされます。REST ルートでは IP キー、ボットハンドラーではユーザー/チャット ID キー。「まだ必要ない」としてスキップされることは決してありません。
• ロギング: nestjs-pino、常に使用されます。構造化 JSON ログ。プレーンな Logger オプションは提供されません。
• ヘルスチェック: @nestjs/terminus、常に配線され、質問票でゲートされません。2 つの別々のルート、GET /health/live（プロセスのみ、外部チェックなし）と GET /health/ready（Prisma + 選択された Redis/RabbitMQ 依存関係）、決して 1 つにマージされません。core/health.md を参照してください。
• Graceful Shutdown: app.enableShutdownHooks() が main.ts で常に呼び出されます。これがないと、Prisma の OnModuleDestroy 接続クローズフックがコンテナ再起動時に決して発火しません。
• Prisma エラーマッピング: グローバルな PrismaExceptionFilter（APP_FILTER）が PrismaClientKnownRequestError コードを対応する Nest HTTP 例外にマッピングします。Prisma エラーがベアの未処理 500 として表面化することは決してありません。
• Prisma クライアント生成: package.json には常に `