nodejs-core

Visão geral do skill nodejs-core

Para que serve o nodejs-core

O skill nodejs-core serve para depurar e construir na camada interna do Node.js: addons nativos, bindings em C++, comportamento do V8, agendamento do libuv, falhas de build e problemas de performance que prompts comuns de JavaScript normalmente não capturam. Ele é mais útil quando você precisa de nodejs-core para trabalho de Backend Development que cruza a fronteira entre JS/C++ ou depende da mecânica de runtime do Node.

Para quem ele é mais indicado

Use o skill nodejs-core se você está:

• corrigindo erros de build em binding.gyp ou node-gyp
• investigando crashes, segfaults, leaks ou testes nativos intermitentes
• escrevendo ou revisando código baseado em N-API, node-addon-api ou NAN
• ajustando o comportamento do event loop, de worker threads ou do thread pool
• diagnosticando deopts do V8, pressão de GC ou regressões de hidden class

O que o torna diferente

Este skill é organizado em torno de regras acionáveis do core do Node, não de uma visão geral genérica. O valor está nos arquivos de suporte em rules/: eles separam fluxo de build, V8, libuv, memória nativa, opções de CLI e caminhos de depuração para que um agente consiga escolher rapidamente o subsistema certo.

Como usar o skill nodejs-core

Instale e delimite o escopo corretamente

Instale nodejs-core com o comando de skill do repositório e use-o apenas quando sua tarefa exigir entendimento de internals de runtime ou raciocínio sobre build nativo. Se o seu problema for Express tradicional, design de API ou lógica pura de TypeScript, este skill provavelmente está em um nível baixo demais.

Comece pelos arquivos certos

Para a instalação do nodejs-core e a leitura inicial, abra:

• SKILL.md para escopo e pontos de entrada
• rules/build-and-test-workflow.md para o ciclo obrigatório de editar-construir-testar
• rules/build-system.md para contexto de compilação e binding.gyp
• a regra do subsistema que corresponde ao seu problema, como rules/napi.md, rules/libuv-event-loop.md, rules/v8-jit-compilation.md ou rules/debugging-native.md

Transforme uma tarefa vaga em um prompt útil

Um pedido fraco como “me ajuda com um crash num addon do Node” é amplo demais. Um prompt mais forte para usar nodejs-core inclui:

• plataforma: Linux/macOS/Windows
• versão do Node e tipo de build
• modo exato da falha: erro de compilação, abort, hang, deopt, leak, saída incorreta
• pista de subsistema: N-API, libuv, V8, child process, streams ou memória
• o que mudou recentemente
• o comando ou teste que reproduz o problema

Formato de exemplo:
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.

Fluxo de trabalho que gera resultados melhores

Comece pelo arquivo de regra correspondente e depois mapeie o sintoma para o menor subsistema possível. Para problemas de build, leia primeiro o fluxo de build; para bugs em runtime, leia a regra do subsistema e compare a reprodução com o comportamento esperado do Node. Se a tarefa envolver alterações em src/ ou lib/, refaça o build antes de testar para não perseguir saída desatualizada.

FAQ do skill nodejs-core

O nodejs-core é só para contribuidores do core do Node?

Não. Ele também é útil para autores de addons, engenheiros de plataforma e times de backend que estão depurando problemas de produção abaixo da camada JavaScript. Você não precisa contribuir para o core do Node para usar o skill nodejs-core.

Em que ele é diferente de um prompt normal?

Um prompt comum pode chutar soluções no nível de JavaScript. nodejs-core é melhor quando a resposta depende de flags de build, embedding binário, comportamento de otimização de bindings C++ ou internals do libuv. Ele reduz o chute ao conduzir o fluxo de trabalho para as regras corretas do subsistema.

É amigável para iniciantes?

Sim, se a pergunta for concreta. Ele é menos amigável para pedidos vagos como “por que o Node está lento?”. Iniciantes conseguem resultados melhores quando informam um comando de reprodução, um stack trace e o subsistema relevante. Isso torna o uso do nodejs-core muito mais preciso.

Quando eu não devo usar?

Evite para bugs de framework, arquitetura de aplicativo ou uso rotineiro de APIs. Também não use se você não conseguir fornecer uma reprodução ou, no mínimo, uma categoria clara da falha; o skill é mais forte quando o problema já parece ser de runtime, build ou integração nativa.

Como melhorar o skill nodejs-core

Dê ao skill as evidências certas

As entradas mais úteis são exatas: stack traces, logs de build, node -p process.versions, flags de compilação e a menor reprodução possível. Para nodejs-core em Backend Development, inclua também se o serviço é limitado por CPU, memória ou I/O, porque isso muda se as regras de V8, libuv ou memória nativa são as mais relevantes.

Aponte o subsistema cedo

Não peça para o modelo “procurar no repositório inteiro” mentalmente. Diga se o problema está mais perto de:

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

Fique atento aos modos de falha mais comuns

O erro mais comum é tratar um problema de build como bug de runtime, ou assumir que uma correção em JS vai resolver um problema de C++/binding. Outro erro frequente é esquecer de rebuildar depois de editar src/ ou lib/. Se a primeira resposta vier ampla demais, refine com uma reprodução mais precisa, um trecho de código menor e uma instrução explícita de “focar em build vs runtime”.

Use a primeira resposta como uma etapa de afunilamento

Trate a primeira saída como uma triagem: peça o subsistema mais provável, o próximo comando de diagnóstico ou o arquivo exato para inspecionar em seguida. Bons resultados com nodejs-core normalmente melhoram depois de um ciclo de refinamento, especialmente quando você adiciona o comando que falha, a plataforma e um sintoma concreto em vez de uma descrição genérica.