nodejs-core

nodejs-core skill の概要

nodejs-core は何のためのスキルか

nodejs-core skill は、Node.js の内部レイヤーでのデバッグや実装に向いています。たとえば、native addon、C++ bindings、V8 の挙動、libuv のスケジューリング、ビルド失敗、パフォーマンス問題など、通常の JavaScript のプロンプトでは見落としやすい領域です。JS/C++ の境界をまたぐ Backend Development や、Node のランタイム動作そのものに依存する作業では、nodejs-core が特に役立ちます。

どんな人・どんな作業に向いているか

nodejs-core skill は、次のようなケースで使うのが適しています。

• binding.gyp や node-gyp のビルドエラーを直す
• crash、segfault、メモリリーク、断続的に失敗する native test を調べる
• N-API、node-addon-api、NAN ベースのコードを書く・レビューする
• event loop、worker thread、thread pool の挙動を調整する
• V8 の deopt、GC 圧、hidden-class の回帰を診断する

何が違うのか

この skill は、一般的な概要ではなく、実行可能な Node core のルールを軸に整理されています。価値の中心は rules/ 以下の補助ファイルにあります。build workflow、V8、libuv、native memory、CLI options、debugging path が分かれているため、エージェントが適切な subsystem を素早く選べます。

nodejs-core skill の使い方

正しくインストールし、適切な範囲で使う

リポジトリの skill command で nodejs-core をインストールし、runtime internals や native build の推論が必要なときだけ使ってください。問題が標準的な Express、API 設計、素の TypeScript ロジックで済むなら、この skill はたいてい低レベルすぎます。

最初に開くべきファイル

nodejs-core のインストール後の初回確認では、まず次を開きます。

• 範囲と入口を確認する SKILL.md
• 必須の edit-build-test ループを示す rules/build-and-test-workflow.md
• コンパイルと binding.gyp の文脈を確認する rules/build-system.md
• 問題に合う subsystem のルール。たとえば rules/napi.md、rules/libuv-event-loop.md、rules/v8-jit-compilation.md、rules/debugging-native.md

あいまいな依頼を使えるプロンプトにする

「Node addon が crash するのを助けて」は広すぎます。より良い nodejs-core の依頼には、次の情報を含めてください。

• platform: Linux/macOS/Windows
• Node version と build type
• 具体的な失敗モード: compile error、abort、hang、deopt、leak、wrong output
• subsystem の手がかり: N-API、libuv、V8、child process、streams、memory
• 直近で何を変えたか
• 再現に使える command または test

例:
Use nodejs-core to diagnose a native addon crash on Node 22. The addon uses N-API, fails only in release builds, and crashes after a GC cycle. Focus on likely root causes, what to inspect in rules/napi.md and rules/memory-debugging.md, and the fastest repro steps.

より良い結果につながる進め方

まず該当する rule file を開き、症状を最小の subsystem に切り分けます。build 問題なら build workflow を先に読み、runtime bug なら subsystem ルールを読みつつ、再現結果が Node の期待動作とどう違うかを比べます。src/ や lib/ を編集する作業なら、テスト前に必ず再ビルドしてください。古いビルド成果物を追いかけてしまうのを防げます。

nodejs-core skill の FAQ

nodejs-core は Node core のコントリビューター専用ですか？

いいえ。addon 作者、platform engineer、そして JavaScript レイヤーより下で起きる production 問題を調べる backend チームにも有用です。Node core に実際に貢献していなくても、nodejs-core skill は使えます。

通常のプロンプトと何が違うのですか？

通常のプロンプトは、JavaScript レベルの修正を推測しがちです。nodejs-core は、答えが build flags、binary embedding、C++ bindings、V8 の最適化挙動、libuv の内部動作に左右されるときに強みを発揮します。適切な subsystem ルールへ誘導することで、推測を減らせます。

初心者にも向いていますか？

はい、質問が具体的であれば向いています。ただし、「なぜ Node が遅いのか」のようなあいまいな依頼には向きません。初心者ほど、repro command、stack trace、関連する subsystem を添えると成果が出やすくなります。そうすることで nodejs-core の使い方がかなり正確になります。

使わないほうがいいのはどんなときですか？

framework の不具合、アプリの設計、日常的な API 利用には使わないでください。また、再現手順や少なくとも明確な failure category を示せない場合も避けたほうがよいです。この skill が最も強いのは、問題がすでに runtime、build、native integration のどれかに見えているときです。

nodejs-core skill を改善する方法

skill に正しい証拠を渡す

最も有用な入力は、stack trace、build logs、node -p process.versions、compile flags、そして最小限の reproduction です。nodejs-core を Backend Development に使うなら、サービスが CPU-bound か memory-bound か、あるいは I/O 待ちで詰まっているかも含めてください。どのルールが最重要かが、V8、libuv、native memory のどれに寄るかで変わるからです。

最初に subsystem を示す

リポジトリ全体を頭の中で探させないでください。問題が次のどれに近いかを最初に伝えます。

• rules/napi.md または rules/node-addon-api.md
• rules/v8-garbage-collection.md または rules/profiling-v8.md
• rules/libuv-event-loop.md または rules/libuv-thread-pool.md
• rules/debugging-native.md または rules/native-memory.md

よくある失敗パターンに注意する

最も多い見落としは、build 問題を runtime bug として扱うこと、または JS 側の修正で C++/binding の問題が解決すると決めつけることです。もう一つよくあるのは、src/ や lib/ を編集したのに再ビルドを忘れることです。最初の回答が広すぎるなら、再現条件を 1 つ絞り、コードサンプルを 1 つ小さくし、さらに「build か runtime かに焦点を当てて」と明示してやり取りを進めてください。

最初の回答は絞り込みの起点として使う

最初の出力は triage と考えてください。次に疑うべき subsystem、次に打つ診断 command、あるいは次に確認すべき正確な file を聞き出す段階です。nodejs-core の結果は、失敗している command、platform、そして一般的な説明ではなく具体的な症状を 1 つ足すだけで、たいてい 1 回の refinement で大きく改善します。