nodejs-core

使用時期

以下を含む Node.js の深い内部知識が必要な場合に、このスキルを使用します:

• C++ アドオン開発
• V8 エンジンのデバッグ
• libuv イベントループの問題
• ビルドシステムの問題
• コンパイルの失敗
• エンジンレベルでのパフォーマンス最適化
• Node.js コアアーキテクチャの理解

使用方法

詳細な説明とコード例については、個別のルールファイルを参照してください:

V8 エンジン

• rules/v8-garbage-collection.md - Scavenger、Mark-Sweep、Mark-Compact、世代別 GC
• rules/v8-hidden-classes.md - ヒドゥンクラス、インラインキャッシング、最適化
• rules/v8-jit-compilation.md - TurboFan、最適化/最適化解除パターン

libuv

• rules/libuv-event-loop.md - イベントループフェーズ、タイマー、I/O、アイドル、チェック、クローズ
• rules/libuv-thread-pool.md - スレッドプールサイズ、ブロッキング操作、UV_THREADPOOL_SIZE
• rules/libuv-async-io.md - 非同期 I/O パターン、ハンドル、リクエスト

ネイティブアドオン

• rules/napi.md - N-API 開発、ABI 安定性、非同期ワーカー
• rules/node-addon-api.md - C++ ラッパーパターン、ベストプラクティス
• rules/native-memory.md - バッファ処理、外部メモリ、メモリリーク防止

コアモジュール内部

• rules/streams-internals.md - Node.js ストリームが C++ レベルでどのように動作するか
• rules/net-internals.md - TCP/UDP 実装、ソケット処理
• rules/fs-internals.md - libuv fs 操作、同期と非同期
• rules/crypto-internals.md - OpenSSL 統合、パフォーマンス考慮事項
• rules/child-process-internals.md - IPC、spawn、fork 実装
• rules/worker-threads-internals.md - SharedArrayBuffer、Atomics、MessageChannel

JavaScript 内部

• rules/primordials.md - プロトタイプポルーション防止のための primordials の使用 (lib/internal/ で必須)

ビルドと貢献

• rules/build-and-test-workflow.md - 編集-ビルド-lint-テストサイクル (ここから始めてください)
• rules/configure.md - デバッグビルド、ASan、Ninja などの ./configure フラグ
• rules/build-system.md - gyp、ninja、make、クロスプラットフォームコンパイル
• rules/cli-options.md - CLI オプションの追加と実験的モジュールのゲート
• rules/contributing.md - Node.js コアへの貢献方法、プロセス
• rules/commit-messages.md - Node.js スタイルのコミットメッセージフォーマットと検証
• rules/reviewing-prs.md - PR レビュー、品質シグナル、低品質な AI 生成貢献の特定

ドキュメンテーション

• rules/documentation.md - doc/api/*.md ファイルの更新: 構造、リンク順序、エラードキュメント、コード例の制約

デバッグとプロファイリング

• rules/debugging-native.md - gdb、lldb、C++ アドオンのデバッグ
• rules/profiling-v8.md - --prof、--trace-opt、--trace-deopt、フレームグラフ
• rules/memory-debugging.md - ヒープスナップショット、メモリリーク検出

指示

必須: テスト前のリビルド

Node.js は js2c を通じて lib/ JavaScript ファイルをバイナリにコンパイル時に埋め込みます。src/ または lib/ に対する ANY 変更後、テストを実行する前に必ずリビルドする必要があります。 リビルドなしでテストを実行すると、古いコードに対してテストが実行され、結果は意味がありません。

src/ または lib/ を編集  →  make -j$(nproc)  →  make lint  →  その後テスト

リビルドステップをスキップしないでください。編集後にリビルドせずに ./node test/... を実行しないでください。

作業を開始する前に、ユーザーに確認してください。ビルド設定について (Make vs Ninja、デバッグ vs リリース、どの configure フラグを使用するか)。特定のセットアップを仮定しないでください。ほとんどの場合、./configure は既に実行されており、リビルドには make -j$(nproc) のみが必要です。

configure フラグ、lint ターゲット、テストコマンドを含む完全なワークフローについては、rules/build-and-test-workflow.md を参照してください。

コア知識領域

Node.js 内部にわたる深い知識を以下の領域に適用します:

• コアアーキテクチャ: Node.js コアモジュールと C++ 実装、V8 GC と JIT、libuv イベントループメカニクス、スレッドプール動作、スタートアップ/モジュールロード ライフサイクル
• ネイティブ開発: N-API、node-addon-api、および NAN アドオン開発、V8 C++ API ハンドル管理、メモリ安全性、gdb/lldb によるネイティブデバッグ
• ビルドシステム: node-gyp、gyp、ninja、make、クロスプラットフォームコンパイル、リンカーエラー、依存関係の問題、プラットフォーム固有の考慮事項 (Windows、macOS、Linux、組み込み)
• パフォーマンスとデバッグ: イベントループプロファイリング、JS とネイティブコード内のメモリリーク検出、CPU フレームグラフ、V8 最適化/最適化解除トレース

クイックリファレンスデバッグコマンド

V8 最適化トレース:

node --trace-opt --trace-deopt script.js
# チェックポイント: プロファイリングに進む前に、予期しない最適化解除警告がないことを確認します
node --prof script.js && node --prof-process isolate-*.log > processed.txt

イベントループラグ検出:

node --trace-event-categories v8,node,node.async_hooks script.js

ネイティブアドオンデバッグ (gdb):

gdb --args node --napi-modules ./build/Release/addon.node
# gdb 内部:
run
bt        # クラッシュ時のバックトレース
# チェックポイント: 修正を適用する前に、バックトレースが予想される呼び出しサイトを示していることを確認します

メモリリーク用ヒープスナップショット:

node --inspect script.js   # その後 chrome://inspect を開き、ヒープスナップショットを取得
# チェックポイント: 2 つの連続したヒープスナップショットを比較して、修正前後のリーク増加を確認します。修正後にネイティブリークが残っていないことを確認するために valgrind --leak-check=full node addon_test.js を実行します

Node.js 固有の診断デシジョンツリー

ネイティブアドオン内のセグメンテーションフォルト/クラッシュ:

1. node --napi-modules でクラッシュが再現可能か? → gdb を実行し、bt をキャプチャ
2. bt が V8 ハンドルスコープの問題を指しているか? → アドオン内の HandleScope / EscapableHandleScope 使用をチェック
3. libuv コールバックを指しているか? → 非同期ハンドルの有効期間と uv_close() シーケンスを検査
4. 明確な C++ フレームがないか? → ネイティブバインディングに渡される JS 側の型ミスマッチをチェック

V8 最適化解除 / パフォーマンス低下:

1. --trace-opt --trace-deopt を実行 → 最適化解除された関数と理由を特定 (例えば、"not a Smi"、"wrong map")
2. チェックポイント: 複数の実行にわたって同じ関数が一貫して最適化解除されることを確認
3. ヒドゥンクラス遷移を検査 (--trace-ic) して、プロパティ追加順序または型の不一致を修正
4. --trace-opt を再実行して、関数が現在最適化されていることを確認

ビルド失敗 (node-gyp / binding.gyp):

1. ヘッダーが見つからないか? → binding.gyp の include_dirs と Node.js ヘッダーインストールを検証
2. リンカーエラーか? → libraries と link_settings エントリをチェック、ABI 互換性を確認
3. プラットフォーム固有か? → Windows/macOS/Linux 差異については rules/build-system.md を参照

常に JavaScript レベルとネイティブレベル両方の原因を検討し、パフォーマンスの意味とトレードオフを説明し、議論される実験的機能の安定性ステータスを指定してください。コード例は Node.js 内部パターンをデモンストレートし、エッジケースを説明して、一般的な開発者が見落とす可能性がある本番環境対応にしてください。