Mejores prácticas para las habilidades del agente
Un resumen condensado de las 25 prácticas más importantes de las habilidades del agente para equipos de expertos en Node.js, extraídas de cada página de esta sección.
//
Busca en todas las páginas de la documentación
Un resumen condensado de las 25 prácticas más importantes de las habilidades del agente para equipos de expertos en Node.js, extraídas de cada página de esta sección.
Las habilidades son manuales, no tutoriales: SKILL.md le dice a los agentes cómo ejecutar - Conceptos básicos de las habilidades del agente define la estructura; Conceptos básicos de Fastify enseña los conceptos.
Fija la pila en cada habilidad: Node.js 24.18.0, TypeScript 5.6+, Fastify 5 / Nest 11 - las habilidades no fijadas alucinan APIs deprecadas.
Una habilidad por dominio de decisión: Andamiaje, cola, actualización, incidente - nunca una mega-habilidad.
Declara las entradas antes de actuar: ADR del framework, nombre del servicio, URL de Redis, versión actual de Node - los agentes adivinan sin ellas.
Las salidas deben ser verificables: npm ci, npm run typecheck, npm test, curl /health - rechaza "hecho" solo en prosa.
Las barreras de seguridad son la sección de mayor valor: Sin secretos en git, trabajadores separados de HTTP, reintentos idempotentes - ver Habilidad de trabajador de cola.
Invoca habilidades en los puntos de decisión: Nuevo servicio, actualización LTS, incidente a las 3 am - no para leer documentación introductoria.
La documentación humana sigue siendo la fuente de verdad: Las habilidades enlazan a recetarios; no dupliques guías completas del framework.
Ejecuta npm audit --audit-level=high en la verificación de habilidades: Obligatorio para las salidas de andamiaje y actualización.
ESM por defecto para nuevos andamiajes: "type": "module" a menos que el ADR diga CommonJS.
El andamiaje de la API incluye salud + apagado elegante: Antes de cualquier ruta de dominio - Habilidad de andamiaje de API.
Las habilidades de cola aplican Zod en las cargas útiles: Los mensajes venenosos llegan a la DLQ con jobId registrado, no corrupción silenciosa.
Trabajadores como desplegables separados: Nunca bloquees el bucle de eventos con BullMQ en el proceso HTTP.
Las habilidades de actualización de Node usan trenes de PR ordenados: CI de plataforma/Docker antes de las correcciones por servicio - Habilidad de actualización de Node.
Reconstruye los complementos nativos en el salto LTS: Los errores de ABI de bcrypt, sharp significan npm ci en el nuevo Node, no trucos de código.
Habilidades de incidente: contener antes de diagnosticar: Revertir, escalar, deshabilitar - luego instantánea de montón o análisis de consulta.
Asigna IC y escriba en las ejecuciones de habilidades de incidente: Línea de tiempo en el hilo de Slack con marcas de tiempo UTC.
Agotamiento del pool: corrige las fugas de la aplicación antes de reiniciar Postgres: Habilidad de triaje de incidentes.
Actualiza las habilidades después de los postmortems: Cada barrera de seguridad omitida se convierte en una nueva viñeta con fecha.
Versiona las habilidades cuando cambien las barreras de seguridad: Semver o changelog en docs/skills/.
Política de invocación del equipo en CONTRIBUTING.md: Nombra la habilidad en el prompt; un humano revisa toda la salida.
No any en TypeScript generado sin un ticket TODO: El modo estricto es el predeterminado.
Dockerfile fija el mismo parche de Node que .nvmrc: 24.18.0, no 24-alpine flotante.
Los scripts de CI en las habilidades coinciden con el package.json local: Misma superficie de comando que Integración de GitHub Actions.
Revisión trimestral de habilidades después de los anuncios LTS: Depreca los ejemplos de Node N-2 de todos los archivos SKILL.md.
.cursor/skills/ en el repositorio del servicio para convenciones específicas del proyecto; repositorio git de la organización para manuales compartidos de actualización e incidentes.
Sí para la estructura, pero SEV1/2 requiere un ingeniero senior en el hilo. La habilidad no reemplaza la política de escalada.
Los generadores CLI (npm run create:service) codifican una ruta; las habilidades guían a los agentes cuando los requisitos varían. Prefiere CLI cuando el 90% es idéntico cada vez.
Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.
Revisado por Chris St. John·Última actualización: 16 jul 2026