nodejs

このスキルは、Node.js/Bun のリファレンス群を振り分けるシェルです。

必ず守るルール：

1. 最初に references/stack.md を読み、ランタイム（Node.js または Bun）、フレームワーク、固定された決定事項を確認してください。
2. 次に、実際のタスクに必要なリファレンスだけを読み込んでください。
3. TypeScript の strict モード — any、暗黙の戻り値、チェックされていないインデックスアクセスは禁止です。
4. すべての非同期関数でエラーを処理すること — 未処理のプロミス拒否は禁止です。各境界で try/catch または .catch() を使用してください。
5. システム境界で入力を検証すること — すべての外部入力（リクエストボディ、クエリパラメーター、環境変数、CLI 引数）に Zod スキーマを適用してください。req.body を決して信頼しないでください。
6. pino による構造化ログ — 本番コードでは console.log を使用しないでください。JSON を stdout に出力し、ログアグリゲーターで解析してください。
7. グレースフルシャットダウン — SIGTERM/SIGINT を処理し、接続をドレインし、処理中の作業を完了させ、DB プールを閉じてください。
8. コードやログにシークレットを含めないこと — 起動時に環境変数を検証し、ログにもエラーレスポンスにも決して含めないでください。

nodejs

入力

• $request：作業対象となるバックエンドのタスク、サブシステム、バグ、または機能

目標

プロジェクトの規約に従って Node.js/Bun のバックエンド作業を振り分け、サーバーアーキテクチャ、データアクセス、エラー処理、デプロイに関する既定のパターンに沿って実装できるようにします。

ステップ 0：スタックの契約を読む

必ず最初に次を読みます。

• references/stack.md

ここで、ランタイム（Node.js または Bun）、フレームワーク（Express/Fastify/Hono/なし）、ORM、テストランナー、パッケージマネージャー、固定された依存関係の選択が明らかになります。

bun.lockb または bunfig.toml が存在する場合、ランタイムは Bun です。ネイティブ API の違いについても references/bun-runtime.md を読み込んでください。

成功基準：実装を始める前に、プロジェクトのランタイム、フレームワーク、ツールチェーンの選択が明確になっていること。

ステップ 1：関連するリファレンスだけを読み込む

振り分け表を使ってリファレンスファイルを選択してください。リファレンス全体を一括で読み込まないでください。

タスク	読むファイル
ランタイム、TypeScript、パッケージマネージャー、固定された依存関係	references/stack.md
フォルダー規約、エントリーポイント、モノレポの構成	references/project-structure.md
Express/Fastify/Hono のパターン、ミドルウェア、ルーティング	references/http-server.md
REST の規約、バージョニング、ページネーション、エラーレスポンス	references/api-design.md
Zod/AJV による入力検証、DTO のパターン	references/validation.md
Prisma/Drizzle/Knex、マイグレーション、コネクションプーリング	references/database.md
JWT、セッション、OAuth2、RBAC、ミドルウェアガード	references/auth.md
エラークラス、非同期エラー境界、HTTP エラーレスポンス	references/error-handling.md
pino による構造化ログ、リクエストの相関、ログレベル	references/logging.md
vitest/jest/bun によるテスト、supertest、テストファクトリー、カバレッジ	references/testing.md
プロミス、ストリーム、ワーカースレッド、AbortController、シャットダウン	references/async-patterns.md
helmet、CORS、レート制限、入力のサニタイズ、依存関係の監査	references/security.md
Redis、インメモリーキャッシュ、キャッシュ無効化のパターン	references/caching.md
BullMQ、ジョブのパターン、再試行戦略、デッドレターキュー	references/queues-jobs.md
環境変数の検証、dotenv、設定モジュール、シークレット管理	references/config.md
OpenTelemetry、ヘルスチェック、メトリクス、分散トレーシング	references/observability.md
マルチステージ Dockerfile、.dockerignore、本番用と開発用のイメージ	references/docker.md
ws/Socket.io、接続ライフサイクル、スケーリング、ルーム	references/websockets.md
commander/yargs、引数の解析、終了コード、stdin/stdout	references/cli.md
Bun ネイティブ API、bun test、bun build、Bun.serve、Bun.$	references/bun-runtime.md

複数のタスクがある場合は、複数のファイルを読んでください。各リファレンスは単独で参照できます。

成功基準：タスクに関連するバックエンドの規約だけが適用されていること。

ステップ 2：コアバックエンドのガードレールに沿って実装する

以下のルールを常に適用してください。

• noUncheckedIndexedAccess を有効にした TypeScript の strict モード
• すべての外部入力を境界で検証する（Zod スキーマ）
• エラーは型付けし、捕捉して、構造化された HTTP レスポンスとして返す
• リクエスト相関 ID を含む pino 子ロガーでログを記録する
• データベースアクセスには、raw SQL 文字列ではなく、プロジェクトの ORM／クエリビルダーを使用する
• 原子性が重要な場合は、変更をトランザクションでラップする
• グレースフルシャットダウン：SIGTERM ハンドラーでサーバーをドレインし、プールを閉じて、正常に終了する
• 起動時に環境変数を検証する — 必須の設定がない場合は即座に失敗する
• any は使用しない。コメントで正当な理由を示さない限り、as による型アサーションも使用しない
• Bun ランタイムの場合：Node.js の同等機能より Bun.serve()、Bun.file()、bun test を優先する

成功基準：変更が一般的なデフォルトではなく、プロジェクトのバックエンドアーキテクチャに合致していること。

ステップ 3：影響範囲を検証する

関連する範囲に絞って検証してください。

• 単体テスト（vitest run、jest、または bun test）
• supertest または実際の HTTP 呼び出しによる統合テスト
• 型チェック（tsc --noEmit）
• リント（eslint .）
• Docker を使用している場合：イメージをビルドし、起動することを確認する

成功基準：変更したバックエンドの範囲が引き続きビルドでき、型チェックに合格し、テストを通過すること。

ガードレール

• Node.js ハンドブック全体を SKILL.md にそのまま埋め込まないでください。
• references/stack.md を省略しないでください。
• 本番コードで console.log を使用しないでください — pino を使用してください。
• API 境界での入力検証を回避しないでください。
• 未処理の Promise 拒否を残さないでください。
• シークレット、ポート、または環境固有の値をハードコードしないでください。
• disable-model-invocation を追加しないでください。これは通常のドメインスキルです。

参照資料を読み込むタイミング

• references/stack.md 常に読み込みます。

• references/bun-runtime.md プロジェクトで Bun を使用している場合に読み込みます（bun.lockb または bunfig.toml で検出）。

• その後は、タスクに関連する references/ 内のファイルのみを読み込みます。

出力要件

以下を報告してください。

1. 読み込んだ参照資料
2. 選択したアーキテクチャパターン
3. 実施した変更
4. 実行した検証