CommunityProgramación y desarrollogithub.com

backend-modular

Habilidad de codificación. Construir, extender, refactorizar o corregir backends modulares NestJS y Node.js con Fastify, AppBuilder, Helmet, errores localizados, almacenamiento Redis, limitación de tasa y paginación por cursor. Aplicar consultas eficientes, autenticación JWT y de dispositivo, guards de solicitud, trabajos programados, Docker y CI/CD a nuevos backends y sistemas existentes.

¿Qué es backend-modular?

Esta habilidad (skill) proporciona un conjunto completo de convenciones y reglas de arquitectura para desarrollar y mantener backends modulares construidos con NestJS y Node.js. Está diseñada para ser utilizada por agentes de IA como los que se encuentran en Claude Code, Cursor o Codex, para guiar la implementación de nuevas bases de código o la refactorización de proyectos existentes. La habilidad enfatiza un stack técnico específico que incluye Fastify, Helmet, AppBuilder, errores localizados vía i18n, almacenamiento en Redis, limitación de tasa y paginación por cursor. El valor principal radica en que establece un conjunto de decisiones de ingeniería de base que aseguran consistencia, rendimiento y mantenibilidad, evitando al mismo tiempo cambios especulativos o migraciones completas innecesarias. La habilidad cubre una amplia gama de preocupaciones, desde la estructura de módulos con DTOs, controladores, servicios y repositorios, hasta el manejo de errores tipificados, la gestión de transacciones, la justificación de índices, la configuración de Docker y la integración continua. Proporciona referencias detalladas para tareas específicas (arquitectura, errores, datos, identidad, límites de solicitud, operaciones, trabajo en segundo plano, Docker y CI/CD), y exige que el agente evalúe el alcance antes de editar, ya sea para un backend nuevo (aplicando las reglas directamente) o para uno existente (realizando una evaluación de arquitectura y proponiendo cambios). La habilidad también incluye pautas para verificar la implementación mediante pruebas de aceptación y pruebas de comportamiento.

Compatible con~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/yigitcicekci/modular-backend/tree/HEAD

Installed? Explore more Programación y desarrollo skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Backend Modular

Completa el comportamiento solicitado con el cambio legible más pequeño. Aplica estas convenciones a nuevos backends y al código afectado en proyectos existentes. No conviertas una corrección enfocada en una migración de todo el proyecto.

Carga las referencias relevantes

TareaLeer
Nuevo módulo, refactor estructural, DTOs, inyección de dependenciasArquitectura
Contratos de error, fallos de validación, filtros globales, i18nErrores e i18n
Consultas, índices, transacciones, Redis, comportamiento de caché/almacenamientoDatos y Redis
Paquetes de usuario, autenticación, sesiones, OAuth, dispositivos, huellas digitales, hashing de contraseñas/IPIdentidad
Guards de cabecera y JWT, middleware, decoradores de ruta y parámetrosLímite de solicitud
Bootstrap, configuración, límites de tasa, logs, salud, verificaciónOperaciones
Colas, trabajadores, programaciones, idempotencia de webhook, límites de recursosTrabajo en segundo plano
Dockerfile, Compose local, scripts Bash de inicio/parada, comandos de API/trabajadorDocker
Verificaciones de CI, contenedores, migraciones, lanzamientos, reversiónCI/CD

Para un nuevo backend, revisión de cimientos o solicitud de arreglar componentes base faltantes, lee Arquitectura, Operaciones, Errores e i18n, Límite de solicitud, Docker y Datos y Redis antes de editar. Lee otras referencias según las necesite la tarea. Adapta los ejemplos a las versiones instaladas y al dominio real. Usa Markdown portátil y herramientas de proyecto estándar. Sigue el modelo de permisos del agente anfitrión.

Establece el alcance antes de editar

Lee las instrucciones del repositorio, el manifiesto del paquete, el bootstrap, los módulos afectados y sus llamadores, los esquemas relevantes, el uso de Redis y las pruebas. Usa definiciones de configuración y nombres de variables de ejemplo para el descubrimiento.

Nuevo backend. Aplica las reglas de cimientos y arquitectura directamente. Implementa la base conectada y usa las referencias relevantes para los flujos de producto solicitados. Pregunta por decisiones de producto faltantes que afecten el comportamiento o la propiedad de los datos. La habilidad ya establece las elecciones de ingeniería base.

Backend existente. Comienza con una evaluación de arquitectura de solo lectura. Presenta la arquitectura actual, el objetivo propuesto y qué componentes mantener, cambiar, agregar o aplazar. "Revisa este backend según modular-backend" cubre todo el backend. Cuando una solicitud especifique el estándar sin seleccionar cambios específicos, pregunta en una pregunta concisa qué propuestas aplicar y espera la decisión. Si el usuario ya solicitó explícitamente un cambio específico, primero analiza y comparte la arquitectura relevante, procede con ese cambio y pregunta antes de asumir más cambios arquitectónicos. Una solicitud de solo análisis termina con la evaluación. Después de que el usuario seleccione el alcance, impleméntalo y ejecuta las comprobaciones de aceptación aplicables.

Para una solicitud que nombre una característica, endpoint o error, limita la evaluación a esa ruta y sus llamadores afectados. Usa el módulo existente más cercano que siga estas reglas como modelo para nombres, ubicación de archivos, DTOs, errores y estilo de transacción.

Nuevo backend, revisión de cimientos o remediación de base

  • AppBuilder y Helmet son obligatorios para HTTP. Mantén src/main.ts delgado y coloca la construcción de HTTP en src/builder/app.builder.ts. Usa un FastifyAdapter explícito de Nest o fastify directo para HTTP Node.js sin Nest. Registra @fastify/helmet compatible antes de la inicialización o escucha. Vincula el builder real en pruebas de integración HTTP. Los trabajadores sin HTTP usan su propio punto de entrada.
  • Localiza los errores HTTP en un filtro global o manejador de Fastify. Usa definiciones de error de módulo con code, status y messageKey, un registro tipificado y una excepción compartida. Devuelve { status, code, message } para nuevos contratos HTTP. status coincide con el estado HTTP, code permanece estable entre idiomas y message proviene de i18n. Para APIs existentes, conserva los campos publicados hasta que se acuerde una migración compatible.
  • La infraestructura de Redis y una ruta de datos real de Redis son obligatorias. Agrega configuración de conexión validada, archivos centralizados de claves Redis y TTL, un proveedor Redis compartido y una sonda de readiness. Asigna a Redis al menos una familia de datos útil para la cual sea la fuente de verdad. Implementa sus lecturas y escrituras reales a través de un repositorio de dominio. Una conexión, sonda de salud o caché de respuesta SQL por sí sola no satisface esta regla. Usa un flujo de producto existente adecuado, como configuración de cliente publicada, clasificación/estado en vivo o limitación compartida. Cuando el producto tenga configuración de cliente o política de versión, almacena y sirve su documento publicado desde Redis. Identifica una decisión de producto faltante si no se puede elegir ninguna familia de datos legítima del alcance.
  • Genera claves de Redis a partir de plantillas compartidas. Mantén las plantillas [placeholder] en redis-keys.config.ts, los TTL en redis-ttl.config.ts y generateRedisKey/generateRedisKeys en src/utils/redis-key.util.ts. Haz que el proveedor compartido aplique el namespace configurado una vez. Usa esta ruta en lectores, escritores y trabajos reales. Conserva el formato de clave existente durante las revisiones a menos que el usuario seleccione una migración planificada. Consulta ejemplos de claves Redis.
  • Las lecturas propiedad de Redis y preparadas permanecen en Redis. Establece el comportamiento de población, actualización, falta de clave, caducidad, interrupción y recuperación por familia de clave. Usa ausencia tipificada para una entidad genuinamente faltante y no disponible tipificado para una interrupción o una proyección requerida que no está lista. Una solicitud nunca consulta SQL como respaldo para estos roles. Usa una excepción explícita de caché-aside solo para una caché desechable acordada. Conserva un contrato de lectura existente en revisiones no relacionadas.
  • Conecta la limitación de tasa compartida para HTTP. Registra el guard o hook de cumplimiento y configura un presupuesto predeterminado para rutas externas. Agrega presupuestos más estrictos respaldados por Redis para autenticación, recuperación y acciones costosas que existan. Usa contadores separados de IP y cuenta normalizada para el inicio de sesión con contraseña. Incrementa y expira atómicamente, responde con 429 y Retry-After, y devuelve 503 tipificado cuando el cumplimiento requerido no esté disponible. Usa una política explícita para exenciones de rutas del sistema.
  • Pagina cada colección en crecimiento expuesta por HTTP. Usa un DTO de consulta validado, límite acotado y un cursor de keyset estable que contenga cada valor de ordenación más un desempate único. Consulta limit + 1 con el alcance y filtros del llamador en el repositorio. Devuelve { items, nextCursor } para nuevas listas. Calcula totales exactos y usa desplazamiento de número de página solo cuando el contrato de la API lo necesite.
  • Conecta los guards y decoradores que usa la API. Usa un guard de cabecera tipificado para un contrato móvil/dispositivo, un guard JWT para rutas JWT protegidas y guards de rol, invitado o proveedor específico donde la política los necesite. Registra los guards y consume su contexto validado usando decoradores de parámetros. Usa hooks de solicitud de Fastify o middleware existente para preocupaciones de transporte transversales.
  • Entrega un flujo de trabajo Docker ejecutable. Proporciona o reutiliza un Dockerfile, Compose para dependencias locales y comandos Bash de inicio/parada con alcance de proyecto. Espera la preparación y usa volúmenes duraderos para datos autoritativos. Conserva un flujo de trabajo equivalente establecido en las revisiones. Ejecuta programaciones de trabajos y consumidores solo cuando la carga de trabajo lo justifique.
  • Implementa solo los módulos/características requeridos. Los flujos de trabajo de autenticación/usuario/dispositivo son orientación reutilizable, no permiso para agregar funciones de cuenta a un servicio que no las necesita.
  • Usa primero los módulos integrados de Node.js y los módulos oficiales de NestJS. La base aprobada incluye @fastify/helmet compatible, un único cliente Redis y nestjs-i18n para errores HTTP de Nest si no hay una integración de i18n adecuada instalada. Un nuevo flujo de autenticación por contraseña puede usar argon2 compatible para Argon2id; usa node:crypto para resúmenes de tokens y huellas digitales con clave. Mantén el cliente Redis existente funcional o usa redis por defecto para un nuevo proyecto. Usa fastify directamente donde se importe. Otros nuevos paquetes de terceros, pares opcionales y plugins de Fastify requieren aprobación explícita. Consulta Operaciones.
  • Entrega bootstrap conectado, configuración validada, proveedores, migraciones requeridas, configuración local y las APIs solicitadas. No te detengas en archivos de andamio desconectados.

Backend existente / revisión

  • Encuentra todos los llamadores antes de cambiar una función compartida o mover archivos: servicios, controladores, trabajos, guards, exportaciones, mocks, fixtures y consumidores de respuesta.
  • Conserva cambios no relacionados, contratos públicos, comportamiento de token/almacenamiento, validación, filtros de propiedad y nombres establecidos. Restringe la limpieza a la ruta de la tarea.
  • Cuando la tarea configure, reemplace o repare la base HTTP, trae Fastify, AppBuilder y Helmet juntos al alcance. Conserva el adaptador y el bootstrap durante cambios de características no relacionados. Al migrar a Fastify, verifica los códigos de estado, middleware, cookies, cargas y cuerpos de webhook firmados donde sea relevante.
  • Extrae consultas a repositorios concretos al cambiar el servicio relevante. Conserva el contexto de transacción, bloqueos, manejo de errores, forma de retorno, ámbito de soft-delete y tenant.
  • Al cambiar una lista o limitador, conserva el cursor público existente y el contrato de respuesta y ajusta la validación dentro del alcance. Rastrea los metadatos de límite de tasa hasta un guard o hook en ejecución. Mantén el ámbito de actor y tenant en la consulta de datos. Planifica explícitamente los cambios incompatibles de cursor o clave de limitador.
  • Para una configuración o refactor de infraestructura, aplica la misma política de paquetes. Conserva las integraciones existentes a menos que la tarea las cambie. Resuelve las dependencias requeridas para la infraestructura solicitada antes de agregar paquetes.
  • No elimines silenciosamente el respaldo, cambies el almacenamiento de sesión, modifiques los tiempos de vida de los tokens o invalides todas las sesiones como limpieza. Planifica la compatibilidad y las migraciones de datos/claves para las transiciones solicitadas.
  • Produce las migraciones necesarias; no elimines datos en vivo ni ejecutes migraciones de producción incidentalmente.

Reglas de arquitectura

  1. Usa el diseño completo para cada característica bajo src/modules/. Cada módulo de característica incluye dto/, un controlador, un servicio, un repositorio y <feature>.module.ts. Mantén un solo controlador, servicio o repositorio en la raíz del módulo. Cuando una capa tenga múltiples archivos, agrúpala en controllers/, services/ o repositories/. Usa errors/ para errores específicos del módulo cuando sea necesario. Coloca los proveedores de soporte bajo infraestructura o trabajos bajo workers cuando no tengan API de característica o acceso a datos. En una revisión con alcance, conserva las rutas existentes a menos que un cambio en el diseño del módulo sea parte de la tarea.
  2. El controlador maneja HTTP; el servicio decide; el repositorio accede a los datos. Sin lógica de negocio, consultas ORM o comandos Redis en los controladores. Los servicios poseen reglas y orquestación. Los repositorios poseen consultas y operaciones Redis, incluyendo escrituras condicionales que imponen invariantes atómicas.
  3. Componer de manera práctica. Las acciones de negocio entre módulos llaman al servicio propietario. El uso directo de un repositorio exportado está permitido para trabajo solo de datos o transacciones compartidas. No crees métodos de servicio de paso directo por apariencia.
  4. Mantén la propiedad de la transacción cerca del trabajo. El servicio puede abarcar varios repositorios con un cliente de transacción pasado; el repositorio puede poseer una operación atómica autónoma. Cada participante usa ese cliente. Sin Unidad de Trabajo genérica o marco de transacciones.
  5. Escribe código pequeño y legible. Reutiliza ayudantes, APIs estándar y dependencias instaladas. Evita opciones especulativas, envoltorios, clases base, repositorios genéricos y abstracciones de un solo uso. Elimina validación redundante y captura-y-relanza; conserva la validación de límites, autorización, concurrencia y protección contra pérdida de datos.
  6. Reduce el trabajo real. Minimiza consultas, viajes redondos, campos, filas y asignaciones intermedias. Las consultas paralelas por elemento siguen siendo N+1. Equilibra tiempo y espacio para la carga de trabajo; no prometas ambos mínimos absolutos ni debilites el hashing de contraseñas por velocidad.
  7. Justifica los índices. Vincula cada índice a una consulta real o restricción de integridad. Inspecciona los índices primarios/únicos/compuestos antes de agregar más. No agregues duplicados especulativos ni elimines índices basándote solo en la apariencia del esquema.
  8. Asigna a Redis un rol. Distingue datos primarios, modelos de lectura preparados y cachés desechables. Define propiedad, población/actualización, TTL, fallo (miss), interrupción (outage) y recuperación. Sin respaldo automático a DB. Los fallos de caché y las fallas de conexión son separados; elige la política de la referencia de datos.
  9. Comparte solo código compartido. Los ayudantes comunes pertenecen a utils/common, la infraestructura a libs, las configuraciones compartidas a config. Mantén los ayudantes solo de módulo locales. Centraliza las claves Redis y los TTL.
  10. Posee y tipifica los errores. Define errores de dominio bajo el directorio errors/ del módulo. Lanza el ErrorCode registrado a través de AppException y traduce su messageKey en el límite HTTP. Mantén las consultas internas, trazas de pila, secretos y detalles del proveedor fuera de las respuestas.

Completa y verifica

Actualiza los llamadores necesarios, DTOs, definiciones de error, proveedores/exportaciones, configuración, esquemas/migraciones y pruebas. Implementa fallos importantes así como éxitos.

Para trabajo de cimientos, sigue las comprobaciones de aceptación. Traza el punto de entrada de producción a través del builder y una característica real a través de su repositorio Redis. Verifica Helmet, el contrato de error HTTP localizado, la inicialización y cierre de Redis, y fallo versus interrupción. Verifica 429 y 503 en rutas limitadas reales, y prueba la paginación estable en cada nuevo contrato de lista. Informa cualquier elemento de base que falte o no esté verificado.

La nueva lógica no trivial necesita una pequeña prueba de comportamiento o verificación basada en aserciones. Verifica los invariantes afectados: propiedad, recuento de consultas, reversión, caducidad/reutilización/concurrencia de tokens, fallo versus interrupción de Redis o actualizaciones atómicas. Los movimientos triviales no necesitan una prueba.

Habilidades relacionadas

  • tecnología-específica – Habilidades que proporcionan documentación de referencia para pilas concretas como PostgreSQL, RabbitMQ, Prisma, etc.
  • componente-específico – Habilidades que proporcionan documentación de componentes desplegables como sistemas de archivos, pruebas, etc.

Skills relacionados