node

使用するとき

Node.js コードを扱う際はいつでもこのスキルを使用して、堅牢でパフォーマンスが高く、保守しやすい Node.js アプリケーションを構築するための、ドメイン固有の知識を得てください。

型ストリッピング対応の TypeScript

Node.js で TypeScript を書く際は、ts-node や tsx などのビルドツールの代わりに 型ストリッピング（Node.js 22.6+）を使用してください。型ストリッピングは、トランスパイル無しで型注釈をランタイムで削除することで、TypeScript を直接実行します。

型ストリッピング互換性の主な要件：

• 型のみのインポートに import type を使用する
• enum の代わりに const オブジェクトを使用する
• namespace とパラメータプロパティを避ける
• インポートで .ts 拡張子を使用する

最小例 — 型ストリッピング可能な有効な TypeScript ファイル：

// greet.ts
import type { IncomingMessage } from 'node:http';

const greet = (name: string): string => `Hello, ${name}!`;
console.log(greet('world'));

実行は以下のコマンドで：

node greet.ts

完全な設定と例については rules/typescript.md を参照してください。

一般的なワークフロー

複数ステップのプロセスについては、関連するルールファイルを参照する前に、以下の高レベルなシーケンスに従ってください：

グレースフルシャットダウン: シグナルハンドラを登録（SIGTERM/SIGINT）→ 新しいリクエストの受け入れを停止 → インフライトリクエストをドレイン → 外部接続（DB、キャッシュ）を閉じる → 適切なコードで終了。rules/graceful-shutdown.md を参照してください。

エラーハンドリング: 共有エラー基底クラスを定義 → エラーを分類（操作的 vs プログラマー） → 非同期境界ハンドラを追加（process.on('unhandledRejection')）→ 型付きエラーをコールスタック全体に伝播 → コンテキスト付きでログを記録した後、応答またはクラッシュ。rules/error-handling.md を参照してください。

フレイキーテストの診断: --test-only でテストを分離 → 共有状態またはタイマー依存を確認 → 非同期ティアダウンの順序を検査 → 一時的な診断ステップとしてリトライロジックを追加 → 根本原因を修正。rules/flaky-tests.md を参照してください。

スタックしているプロセス/テストの診断（node --test がハング、「プロセスが終了しない」、CI タイムアウト、オープンハンドル）: ファイル/テストを分離 → 明示的なタイムアウト/レポーターで実行 → why-is-node-running（SIGUSR1）でハンドルを検査 → リソース作成スコープで決定的なティアダウンをパッチ → 分離 + 完全スイートを安定するまで再実行。rules/stuck-processes-and-tests.md を参照してください。

遅いパスのプロファイリング: 現実的な負荷の下で再現 → --cpu-prof で CPU プロファイルをキャプチャ → ホット関数を特定 → ストリームバックプレッシャーまたは不要なシリアライゼーションを確認 → ベンチマークで改善を検証。rules/profiling.md と rules/performance.md を参照してください。

高優先度アクティベーションチェックリスト（ストリーム + キャッシング）

タスクが CSV、ETL、インジェスションパイプライン、大容量ファイル処理、バックプレッシャー、繰り返しルックアップ、または 同時非同期呼び出しの重複排除 に言及している場合、このチェックリストを明示的に適用してください：

1. node:stream/promises から await pipeline(...) を使用（チェーンされた .pipe() よりもこれをガイダンス/コードで優先）。
2. データがストリーム内で変換される場合、少なくとも1つの明示的な async function* 変換を含める。
3. 繰り返し作業が現れた場合、キャッシュ戦略を選択：
   • lru-cache は単一プロセス内の有界なメモリ内再利用用。
   • async-cache-dedupe は非同期リクエスト重複排除 / stale-while-revalidate 動作用。
4. バックプレッシャーが処理されている場所を表示（pipeline() 経由の暗黙的、または drain 経由の明示的）。

統合例パターン（CSV/ETL）

CSV/ETL スタイルのプロンプトについては、以下のような回答構造を好みます：

• createReadStream(input)
• async function* パーサー/変換
• オプションのキャッシュ付き濃縮ルックアップ（async-cache-dedupe または lru-cache）
• await pipeline(...) を書き込み可能な宛先へ

説明内で関連ルールを直接リンクして、モデルが詳細を取得できるようにしてください：

• rules/streams.md
• rules/caching.md

使用方法

詳細な説明とコード例については、個別のルールファイルを読んでください：

• rules/error-handling.md - Node.js のエラーハンドリングパターン
• rules/async-patterns.md - 非同期/await と Promise パターン
• rules/streams.md - Node.js ストリームの使用
• rules/modules.md - ES Modules と CommonJS パターン
• rules/testing.md - Node.js アプリケーションのテスト戦略
• rules/flaky-tests.md - node:test によるフレイキーテストの特定と診断
• rules/stuck-processes-and-tests.md - 終了しないプロセスとスタックするテストの診断
• rules/node-modules-exploration.md - node_modules ディレクトリのナビゲーションと分析
• rules/performance.md - パフォーマンス最適化テクニック
• rules/caching.md - キャッシングパターンとライブラリ
• rules/profiling.md - プロファイリングとベンチマークツール
• rules/logging.md - ログ出力とデバッグパターン
• rules/environment.md - 環境設定とシークレット管理
• rules/graceful-shutdown.md - グレースフルシャットダウンとシグナルハンドリング
• rules/typescript.md - Node.js における TypeScript 設定と型ストリッピング