Melhores Práticas de Habilidades de Agente
Um resumo condensado das 25 práticas mais importantes de Habilidades de Agente para equipes de SME Node.js - extraído de todas as páginas desta seção.
//
Busque em todas as páginas da documentação
Um resumo condensado das 25 práticas mais importantes de Habilidades de Agente para equipes de SME Node.js - extraído de todas as páginas desta seção.
Habilidades são playbooks, não tutoriais: SKILL.md diz aos agentes como executar - Noções Básicas de Habilidades de Agente define a estrutura; Noções Básicas de Fastify ensina conceitos.
Fixe a stack em cada habilidade: Node.js 24.18.0, TypeScript 5.6+, Fastify 5 / Nest 11 - habilidades não fixadas alucinam APIs depreciadas.
Uma habilidade por domínio de decisão: Scaffold, fila, upgrade, incidente - nunca uma mega-habilidade.
Declare inputs antes de agir: Framework ADR, nome do serviço, URL do Redis, versão atual do Node - agentes adivinham sem eles.
Outputs devem ser verificáveis: npm ci, npm run typecheck, npm test, curl /health - rejeite apenas texto "feito.".
Guardrails são a seção de maior valor: Sem segredos no git, workers separados de HTTP, retentativas idempotentes - veja Habilidade de Worker de Fila.
Invoque habilidades em pontos de decisão: Novo serviço, upgrade LTS, incidente às 3 da manhã - não para ler documentação introdutória.
Documentação humana permanece fonte da verdade: Habilidades linkam para cookbooks; não duplique guias completos de framework.
Execute npm audit --audit-level=high na verificação de habilidade: Obrigatório para outputs de scaffold e upgrade.
ESM padrão para novos scaffolds: "type": "module" a menos que ADR diga CommonJS.
Scaffold de API inclui health + graceful shutdown: Antes de qualquer rota de domínio - Habilidade de Scaffold de API.
Habilidades de fila impõem Zod em payloads: Mensagens "poison" atingem DLQ com jobId logado, não corrupção silenciosa.
Workers como deployables separados: Nunca bloqueie o event loop com BullMQ no processo HTTP.
Habilidades de upgrade de Node usam trens de PR ordenados: Plataforma CI/Docker antes de correções por serviço - Habilidade de Upgrade de Node.
Reconstrua addons nativos no bump de LTS: Erros de ABI de bcrypt, sharp significam npm ci no novo Node, não hacks de código.
Habilidades de incidente: contenha antes de diagnosticar: Rollback, scale, desative - depois snapshot de heap ou análise de consulta.
Atribua IC e scribe em execuções de habilidade de incidente: Linha do tempo em thread do Slack com timestamps UTC.
Esgotamento de pool: corrija vazamentos de app antes de reiniciar Postgres: Habilidade de Triagem de Incidente.
Atualize habilidades após postmortems: Cada guardrail perdido se torna um novo item com data.
Versionar habilidades quando guardrails mudam: Semver ou changelog em docs/skills/.
Política de invocação de equipe em CONTRIBUTING.md: Nomeie a habilidade no prompt; humano revisa todo o output.
Sem any em TypeScript gerado sem ticket TODO: Modo estrito é o padrão.
Dockerfile fixa o mesmo patch do Node que .nvmrc: 24.18.0, não 24-alpine flutuante.
Scripts de CI em habilidades correspondem ao package.json local: Mesma superfície de comando que Integração com GitHub Actions.
Revisão trimestral de habilidades após anúncios de LTS: Deprecie exemplos Node N-2 de todos os arquivos SKILL.md.
.cursor/skills/ no repositório de serviço para convenções específicas do projeto; repositório git da organização para playbooks compartilhados de upgrade e incidente.
Sim para a estrutura, mas SEV1/2 requer um engenheiro staff na thread. A habilidade não substitui a política de escalonamento.
Geradores de CLI (npm run create:service) codificam um caminho; habilidades guiam agentes quando os requisitos variam. Prefira CLI quando 90% idêntico a cada vez.
Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (LTS Ativo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, e NestJS 11.
Revisado por Chris St. John·Última atualização: 16 de jul. de 2026