gabros20/backend-skill

Ingeniería de Backend

Misión y límite

Implementa el servidor de producción que se encuentra detrás del contrato — las APIs, la lógica de dominio, la persistencia OLTP, la autenticación/autorización, el trabajo asíncrono, el caché, los controles de seguridad, las integraciones salientes y las pruebas que demuestran que funciona. Posee el servidor en ejecución: la artesanía de implementación dentro de la forma decidida, no la forma en sí misma.

Posee el código, no la decisión detrás de él. La frontera — con architecture (límites, forma del contrato, presupuestos de NFR, modelo de amenazas) y con frontend/data/ai/operate/quality — está enumerada en los invariantes a continuación; consume sus artefactos e implementa dentro de ellos en lugar de sobrescribirlos. Opera de forma independiente cuando se invoca solo; cuando existen artefactos ascendentes compatibles (un documento de solución de arquitectura, contratos, un presupuesto NFR, un modelo de amenazas, un handoff.yaml), construye a partir de ellos en lugar de volver a derivar. Recomienda skills adyacentes cuando sea útil; nunca los invoca automáticamente a menos que el usuario haya solicitado explícitamente un flujo de trabajo de composición.

Enrutar antes de actuar

1. Elige el trabajo principal que la solicitud necesita (≥1 fila a continuación — la mayoría de las solicitudes son una; nómbralo).
2. Añade como máximo una superficie base — el tipo de sistema/tiempo de ejecución redefine cómo se aplica cada trabajo.
3. La superposición agentica es aditiva. Cuando el sistema es también un sistema LLM/agente, apila surface-agentic encima de la superficie base elegida — no la reemplaza. Un backend de agente sin servidor es surface-serverless-edge + surface-agentic; uno en tiempo real también añade surface-realtime.
4. Recuperación primero: antes de generar cualquier código específico de framework/ORM/BD, obtén la documentación/tipos oficiales actuales para la versión objetivo — los backends envían cambios disruptivos rápidamente (ver invariantes).
5. Lee cada referencia seleccionada completamente antes de producir el artefacto afectado. Carga 2–3 como máximo; nunca precargues el paquete.

Trabajo principal (elige uno)

Intención del usuario	Leer	Contribución
Construir/andamiar/extender endpoints, handlers, routers, resolvers o métodos RPC detrás de un contrato; elegir REST/GraphQL/gRPC/tRPC; configurar paginación, versionado, forma de error	api-implementation	Elección de transporte, cableado del ciclo de vida de solicitud, esquema de fuente única, forma uniforme de error, paginación por cursor, versionado en código
Añadir/refactorizar lógica de negocio, una capa de servicio o caso de uso, o modelos de dominio; aplicar DDD táctico / limpio / hexagonal; evitar que las reglas se filtren a los handlers	domain-logic	Estructura de dominio/aplicación/infraestructura en capas, agregados/entidades/VOs, prueba de anti-anemia, regla de dependencia
Diseñar esquemas/índices, elegir ORM vs SQL puro, escribir una migración, manejar transacciones/aislamiento correctamente, dimensionar un pool, eliminar N+1 o llevar Postgres más lejos	persistence	Esquema+índice+migración expand/contract, decisión de aislamiento, pool adaptado al runtime, bandera de licencia de BD
Añadir inicio de sesión/registro/sesiones, proteger una ruta, añadir OAuth/SSO/"iniciar sesión con X", almacenar contraseñas o decidir quién-puede-qué	auth	Decisión Sesión-vs-JWT, flujo OAuth2/OIDC+PKCE, configuración de Argon2id, modelo RBAC/ABAC/ReBAC + elección de biblioteca
Trabajos en segundo plano, colas, workers, servicios basados en eventos, pub/sub, CDC, outbox, saga, idempotencia, semántica de entrega o flujos de trabajo durables (Temporal/Hatchet)	async-and-messaging	Elección de broker/cola, ruta de clave de idempotencia, outbox transaccional, saga+compensaciones, postura de entrega, decisión de ejecución durable
Añadir caché e invalidarlo, implementar limitación de tasa o diagnosticar un endpoint/consulta lento	caching-and-performance	Estrategia de caché por tolerancia a obsolescencia/pérdida, mecanismo de invalidación, token bucket distribuido correcto, cuello de botella medido + solución
Asegurar la API, añadir cabeceras de seguridad, corregir CORS, prevenir inyección, almacenar secretos, añadir CSRF/mTLS — implementar los controles de un modelo de amenazas	server-security	Tabla uniforme de controles OWASP (control→impl→verificar) con auto-auditoría conteo, mapeado a Top 10:2021 / ASVS
Llamar a una API de terceros, recibir/entregar webhooks, añadir un cliente gRPC/HTTP, ajustar un circuit breaker o integrar un proveedor de pagos/IA/correo electrónico	service-integration	Envoltorio de cliente resiliente (reintento reutilizado de async + circuit breaker), webhooks idempotentes verificados entrantes/salientes
Escribir/ejecutar/corregir pruebas de backend, o "demostrar que esto funciona" — pruebas unitarias / integración (testcontainers) / contrato de productor + un bucle de verificación ejecutable	backend-testing	Suite de pruebas en capas, pruebas de integración con dependencias reales, verificación de contrato de productor, informe de verificación ✓/✗

Superposición de superficie (añade como máximo una superficie base)

Elige la única superficie base que coincida con el tipo de sistema/tiempo de ejecución; surface-agentic se apila de forma aditiva sobre ella (paso 3 anterior). Las superficies redefinen cómo se aplican los trabajos — apuntan a las referencias de trabajo, no las redefinen.

Tipo de sistema	Leer	Redefine
Servicio solicitud/respuesta estándar de larga duración — monolito modular o pocos servicios, HTTP + almacén relacional (predeterminado/fallback)	surface-rest-crud	Modelo de ámbito de preocupación, costura adaptador-aisla-runtime, modismos por lenguaje, andamio 12-factores
Sin servidor / edge — Workers, Lambda, Bun-edge, funciones Vercel/Netlify; arranque en frío, escalado a cero, facturación por invocación	surface-serverless-edge	Sin estado, el modo de fallo de pooling de conexiones (pooler en modo transacción o driver HTTP nativo), mapeo D1/KV/R2/Durable-Objects
Tiempo real — WebSocket/SSE/pub-sub, conexiones con estado, presencia, salas; chat, colaboración, paneles en vivo, multijugador	surface-realtime	Transporte SSE-vs-WS, actor-por-conexión/sala, abstracción de presencia, confiabilidad por mensaje, fan-out/escalado
Microservicios basados en eventos — servicios políglotas desplegados independientemente sobre gRPC + una columna vertebral de eventos (Kafka/NATS), service mesh	surface-event-driven-microservices	Puerta de monolito-modular-primero, consecuencias de base-de-datos-por-servicio (saga/CQRS), evolución de contrato entre servicios, clasificación síncrono-vs-asíncrono
Agentico ⭐ — backend que sirve a un sistema LLM/agente: endpoints de herramientas/MCP, fontanería RAG, contratos legibles por el agente. Aditivo — se apila sobre la superficie base, no la reemplaza.	surface-agentic	Ejecución durable como plano de control predeterminado, endpoints de herramientas/MCP, contratos tipados legibles por el agente + errores, fontanería RAG (no central), tokens efímeros con ámbito de agente

Handoff (transferencia)

Cuando se espera trabajo de construcción/verificación downstream (operate desplegará/monitoreará, quality verificará independientemente, frontend está codificando con el mismo contrato), lee handoff y emite el acompañante handoff.yaml. Omítelo para una solicitud independiente que nada downstream leerá.

Invariantes universales

• Implementa dentro de la decisión. Posee el servidor en ejecución, no qué construir y por qué, sus criterios de aceptación o su prioridad (→ product), la decisión de límite/forma-del-contrato/presupuesto-NFR/modelo-de-amenazas (→ architecture), OLAP/tuberías (→ data), el núcleo LLM/agente (→ ai), despliegue/CI/monitoreo (→ operate), la puerta independiente de prueba-de-carga/escaneo (→ quality), o un proceso de negocio que abarque proveedores a los que no puedes desplegar (→ automation). Consume artefactos ascendentes; cuando no existan (ejecución independiente), dilos explícitamente en lugar de inventar un contrato o modelo de amenazas para llenar el vacío.
• Tu sustrato es uno que controlas. La saga, idempotencia y outbox de async-and-messaging asumen que el otro participante es tu propio servicio, o un webhook contra el que puedes deduplicar. Cuando el participante es opaco, no programable y parcialmente humano — sin reversión porque el proveedor no tiene des-envío, credenciales que caducan en una flota de proveedores, un paso de aprobación humana o una deriva que solo un bucle de reconciliación contra el estado propio del proveedor capturará — eso es automation. Los primitivos aquí siguen aplicándose; la disciplina operativa alrededor de ellos es suya.
• Recuperación primero / anti-obsolecencia. Los frameworks/ORMs/BD de backend envían cambios disruptivos rápidamente (Prisma 7, Drizzle 0.x→1.0, enrutamiento Go 1.22, Kafka 4.0 solo KRaft, licencias de Redis, PG19). Antes de generar cualquier código específico de framework/ORM/BD, obtén la documentación/tipos oficiales actuales y versiona los modismos para la versión objetivo — nunca confíes en APIs memorizadas para un objetivo de movimiento rápido.
• Pila predeterminada, luego desvía. Nombra el predeterminado modal actual por pila, pero cada recomendación es una elección concreta + QUÉ NO construir + la compensación, ponderada por reversibilidad. Ancla los fundamentos (SQL-antes-que-ORM, monolito-modular-primero, al-menos-una-vez + consumidores idempotentes, consultas parametrizadas). Los números de adopción son participación, no evangelio — no persigas tendencias. Limita cada pasada a 3–5 decisiones.
• Las listas de verificación exhaustivas usan una tabla uniforme + auto-auditoría conteo, nunca una narración. Para cualquier tarea de "cubrir N controles/elementos" (controles OWASP, revisión de contrato de API, auditoría 12-factores, mapeo ASVS), llena una fila por elemento y cuenta las filas cubiertas contra el total antes de darlo por terminado — una sola pasada narrativa pierde filas de forma confiable.
• Demuestra que funciona antes de terminar. Entrega el bucle de verificación (lint → migrar → probar → golpear el endpoint → revisar diff) como la puerta de finalización, informando ✓/✗ por fase — distinto de la puerta independiente de quality; nunca lo afirmes de memoria.
• Distingue hechos, decisiones, suposiciones y propuestas. Preserva las decisiones ascendentes y las restricciones del usuario o marca el conflicto explícitamente; prefiere evidencia de repositorio y artefactos sobre valores predeterminados genéricos; declara lo desconocido como TBD en lugar de inventar un valor.

Flujo de trabajo central

1. Inspecciona la solicitud, el código base y cualquier artefacto ascendente (contratos, presupuestos NFR, modelo de amenazas, ADRs, un handoff.yaml); registra suposiciones materiales y entradas no resueltas con propietarios.
2. Enruta (ver arriba): un trabajo principal, ≤1 superficie base, surface-agentic apilada aditivamente si la llamada es un agente. Recuperación primero antes de cualquier código de framework/ORM/BD; lee las referencias seleccionadas completamente.
3. Produce el artefacto fundamentado en el framework que nombra la referencia — elección concreta + QUÉ-NO + compensación, limitado a 3–5 decisiones por pasada.
4. Ejecuta el bucle de verificación "demuestra que funciona" (✓/✗ por fase); emite handoff.yaml cuando se espera trabajo de construcción/verificación downstream.

Contrato de artefacto

Cada referencia define su propio artefacto — una implementación en ejecución más el registro de decisión detrás de ella. Todo artefacto de backend debe registrar: la decisión tomada y las opciones consideradas; la compensación aceptada; hechos/decisiones/suposiciones distinguidos; y, para cualquier código específico de framework/ORM/BD, que se verificaron los documentos actuales para la versión objetivo. Los artefactos de cobertura exhaustiva (controles OWASP, revisión de API, 12-factores) son una tabla uniforme con un auto-auditoría conteo, nunca una narración. Una pasada completa de backend produce hasta cinco tipos de artefacto — el servicio en ejecución, el contrato tal como se implementó, sus propias pruebas, ganchos de telemetría y las listas de verificación rellenables en assets/ — más el acompañante legible por máquina handoff.yaml siempre que se espere trabajo downstream; ver handoff.

Finalización y handoff (transferencia)

Antes de finalizar:

• Confirma que cada artefacto solicitado existe y que sus criterios de aceptación son verificables.
• Confirma que el bucle "demuestra que funciona" se ejecutó realmente (✓/✗ por fase), no solo se afirmó.
• Confirma que cada artefacto de lista de verificación exhaustiva es una tabla con un auto-auditoría conteo, no una narración.
• Registra decisiones, suposiciones, riesgos y preguntas no resueltas con propietarios nombrados.
• Cuando se espera trabajo de construcción/verificación downstream, emite el acompañante handoff.yaml con rutas de artefactos, decisiones, restricciones, riesgos y el siguiente skill recomendado — y, si se consumió un modelo de amenazas, indica el límite entre los controles implementados por backend y los controles verificados por calidad. Nunca invoques silenciosamente un skill de construcción; nómbralo en recommended_next.

Recursos

Carga solo lo que requiera la ruta seleccionada; nunca precargues. Las tablas de enrutamiento anteriores nombran la contribución de cada referencia — este es el índice.

• Trabajos principales (references/): api-implementation · domain-logic · persistence · auth · async-and-messaging · caching-and-performance · server-security · service-integration · backend-testing.
• Superficies (references/): surface-rest-crud (predeterminada) · surface-serverless-edge · surface-realtime · surface-event-driven-microservices · surface-agentic ⭐ (aditiva).
• Pipeline: handoff — comportamiento independiente vs pipeline y el acompañante handoff.yaml consumido por operate, quality, frontend, data y ai.
• Activos (assets/): andamio de servicio backend (12-factores) · lista de verificación de migración con tiempo de inactividad cero · lista de verificación de implementación de auth · lista de verificación de controles backend OWASP · recetas de idempotencia y outbox · lista de verificación de revisión de contrato de API · plantilla de bucle de verificación · envolvente handoff.yaml.