claude-code-arcane 1.0.0 → 1.1.0

package/profiles/backend-nextjs.yaml

@@ -0,0 +1,56 @@
+name: backend-nextjs
+description: "Next.js full-stack — App Router, RSC, Server Actions, SEO, AI SDK, performance (64 reglas de Vercel). Front + back en un solo runtime."
+type: base
+
+skills:
+  # Next.js-specific (nuevas)
+  - nextjs-scaffold
+  - nextjs-best-practices
+  - seo-nextjs
+  - ai-sdk-setup
+  - pgvector-search
+  # Backend / API (Next es full-stack)
+  - api-design
+  - database
+  - caching-strategy
+  - rate-limiting
+  # Auth & security
+  - auth-strategy
+  - jwt-strategy
+  - oauth-setup
+  - web-security
+  - csp-headers
+  # Frontend quality
+  - accessibility
+  - performance
+  # Ops & quality
+  - testing
+  - deps-audit
+  - env-sync
+  - observability
+  - ci-cd-setup
+  - cdn-setup
+
+rules:
+  universal:
+    - nextjs-code
+    - react-perf
+    - frontend-code
+    - backend-code
+    - api-code
+  gamedev:
+    []
+
+agents:
+  - engineering
+
+permissions:
+  allow:
+    - "Bash(npm *)"
+    - "Bash(yarn *)"
+    - "Bash(pnpm *)"
+    - "Bash(npx *)"
+    - "Bash(docker ps*)"
+    - "Bash(docker images*)"
+  deny:
+    []

package/rules/nestjs-code.md

@@ -0,0 +1,73 @@
+---
+paths:
+  - "src/**/*.ts"
+  - "**/*.module.ts"
+  - "**/*.controller.ts"
+  - "**/*.service.ts"
+  - "**/*.guard.ts"
+  - "**/*.pipe.ts"
+  - "**/*.interceptor.ts"
+  - "**/*.dto.ts"
+  - "apps/**"
+  - "libs/**"
+---
+
+# NestJS Code Rules
+
+Reglas production-ready para NestJS, ordenadas por impacto. Catálogo completo (40 reglas, 10 categorías) + ejemplos incorrecto/correcto: skill `nestjs-best-practices`.
+
+## CRITICAL — Arquitectura & DI
+
+- **Cero dependencias circulares entre módulos** — causa #1 de crashes en runtime. Si aparece `forwardRef()`, es señal de mal diseño: refactorizar.
+- **Organizar por feature modules**, no por capas técnicas (`users/`, no `controllers/` + `services/` globales).
+- **Exportar servicios desde módulos dedicados** para garantizar instancias singleton y evitar estado inconsistente.
+- **Single Responsibility por servicio** — un servicio = un concepto de dominio.
+- **Constructor injection siempre.** Nunca `ModuleRef.get()` en runtime (service locator anti-pattern). Dependencias explícitas, tipadas, testeables.
+- **Provider scopes**: `DEFAULT` (singleton) por defecto; `REQUEST` scope solo cuando se necesita contexto de request (tiene costo de performance).
+- **Injection tokens (símbolos o abstract classes) para interfaces** — las interfaces de TS no existen en runtime.
+
+## HIGH — Error handling & Security
+
+- **Servicios lanzan `HttpException` subclasses**, no retornan objetos de error.
+- **Manejar errores async explícitamente** — fire-and-forget y background tasks deben atrapar errores (no unhandled rejections).
+- **Exception filters** para formato de respuesta de error centralizado y consistente.
+- **`ValidationPipe` global + DTOs decorados** — rechazar input malformado antes de procesarlo. `whitelist: true`, `forbidNonWhitelisted: true`.
+- **Guards declarativos para auth/authz**, no chequeos manuales en cada handler.
+- **JWT seguro**: tokens de vida corta + refresh tokens, secretos en env/secret manager, nunca data sensible en el payload.
+- **Rate limiting con `@nestjs/throttler`**, límites por endpoint.
+- **Sanitizar output** (XSS) y setear `Content-Type` correcto.
+
+## HIGH — Performance & Data
+
+- **Evitar N+1**: eager loading con relations o joins de QueryBuilder.
+- **Optimizar queries**: seleccionar solo columnas necesarias, índices apropiados, no over-fetch de relaciones.
+- **Caching estratégico** con TTL apropiado e invalidación basada en eventos.
+- **Transacciones para operaciones multi-step** dependientes (consistencia ante fallos).
+- **Migraciones versionadas** — nunca `synchronize: true` en producción.
+- **Async lifecycle hooks** retornan promesas; constructores síncronos (no bloquear el arranque).
+
+## MEDIUM — API, Microservices, DevOps
+
+- **DTOs + serialización** (`ClassSerializerInterceptor`) para respuestas — controlar exposición, evitar referencias circulares.
+- **Interceptors para cross-cutting concerns** (logging, transformación, formato de respuesta).
+- **Pipes para transformación/validación** de input.
+- **API versioning** para cambios breaking.
+- **Health checks** (readiness/liveness) para orquestadores.
+- **Message queues para jobs largos** — no bloquear handlers de request.
+- **Graceful shutdown**: escuchar SIGTERM, drenar requests in-flight antes de salir.
+- **`ConfigModule` para configuración** por entorno — nada hardcodeado.
+- **Structured logging (JSON)** para parseo/filtrado en producción.
+
+## Anti-Patterns
+
+- `forwardRef()` para parchear dependencias circulares en vez de rediseñar
+- Lógica de negocio en controllers (solo parsean input, llaman service, dan shape a la respuesta)
+- `synchronize: true` contra una DB de producción
+- `ModuleRef.get()` / service locator en runtime
+- Validación manual de input en cada handler en vez de `ValidationPipe` + DTO
+- Devolver entidades de ORM crudas como respuesta HTTP
+- `REQUEST` scope sin necesidad real (penaliza performance)
+
+---
+
+_Derivado de [kadajett/agent-nestjs-skills](https://github.com/kadajett/agent-nestjs-skills) (nestjs-best-practices). Condensado al formato Arcane._

package/rules/nextjs-code.md

@@ -0,0 +1,60 @@
+---
+paths:
+  - "app/**"
+  - "src/app/**"
+  - "pages/**"
+  - "src/pages/**"
+  - "**/*.tsx"
+  - "**/route.ts"
+  - "next.config.*"
+---
+
+# Next.js Code Rules
+
+Reglas de performance y arquitectura para Next.js App Router (RSC, data fetching, caching). Ordenadas por impacto. Catálogo completo + ejemplos: skill `nextjs-best-practices`.
+
+## CRITICAL — Eliminar waterfalls
+
+- **Server Components por defecto.** `'use client'` solo cuando se necesita interactividad/estado/efectos/browser APIs. Empujar el boundary client lo más abajo posible en el árbol.
+- **Fetch paralelo, no secuencial.** Operaciones independientes con `Promise.all()`. Nunca `await` en serie cuando no hay dependencia entre llamadas.
+- **Iniciar promesas temprano, await tarde.** En route handlers y RSC, disparar el fetch independiente al inicio y await recién donde se usa el dato.
+- **Composición para fetch paralelo.** Reestructurar componentes para que fetches independientes corran simultáneamente; fetches dependientes se anidan dentro de la promesa de cada item, no en serie global.
+- **Suspense boundaries estratégicos.** Envolver subárboles con `<Suspense>` para mostrar shell rápido mientras streamea el contenido.
+
+## CRITICAL — Bundle size
+
+- **No barrel imports.** Importar directo del archivo fuente (`lodash/debounce`, no `lodash`); los barrels (`index.ts` que re-exportan todo) arrastran miles de módulos sin usar.
+- **`next/dynamic` para componentes pesados** no necesarios en el render inicial (charts, editores, modales).
+- **Diferir libs third-party no críticas** (analytics, logging, error tracking) a post-hydration; no bloquear el bundle inicial.
+- **Paths estáticamente analizables.** Imports con paths literales/mapas explícitos, no construidos dinámicamente.
+
+## HIGH — Server
+
+- **Autenticar cada Server Action como un API route.** Verificar auth/authz dentro de la action, no confiar solo en middleware.
+- **No module-level mutable state para datos de request.** Mantener datos de request locales al árbol de render; las variables a nivel módulo se comparten entre requests → data leaks.
+- **Minimizar serialización en boundaries RSC→Client.** Pasar solo los campos que el cliente realmente usa, no el objeto entero.
+- **`React.cache()` para dedupe por request**; LRU cache para datos compartidos entre requests dentro de una ventana de tiempo.
+- **`after()` para trabajo no bloqueante** (logging, analytics, cleanup) que corre después de enviar la respuesta.
+- **Hoist I/O estático a nivel módulo** para evitar lecturas redundantes en cada request.
+
+## HIGH — Rendering & data
+
+- **`generateMetadata` para todo el SEO** (title, description, OG, canonical). Nunca tags manuales en el body.
+- **`next/image` siempre** — width/height explícitos, `priority` para LCP, formatos modernos.
+- **Caching explícito.** Conocer y declarar `fetch` cache (`force-cache` / `no-store` / `revalidate`), `revalidatePath`/`revalidateTag` para invalidación.
+- **`content-visibility: auto`** para listas largas off-screen.
+- **Resource hints** (`preload`, `preconnect`) para recursos críticos.
+
+## Anti-Patterns
+
+- `'use client'` en la raíz del árbol (mata todo el beneficio de RSC)
+- `useEffect` + `fetch` en el cliente para datos que podían venir del server
+- Fetches en cascada (cada componente espera al padre sin necesidad)
+- `export *` barrel files en libs internas
+- Pasar objetos de DB crudos como props a Client Components
+- Hardcodear `revalidate`/cache sin entender la estrategia
+- Secrets o lógica sensible en código que cruza a `'use client'`
+
+---
+
+_Derivado de [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills) (react-best-practices, MIT). Condensado al formato Arcane._

package/rules/react-perf.md

@@ -0,0 +1,59 @@
+---
+paths:
+  - "**/*.tsx"
+  - "**/*.jsx"
+  - "src/components/**"
+  - "src/hooks/**"
+  - "components/**"
+  - "hooks/**"
+---
+
+# React Performance Rules
+
+Reglas de re-render, rendering y micro-optimización JS para React. Ordenadas por impacto. Catálogo completo (64 reglas) + ejemplos: skill `nextjs-best-practices`.
+
+## HIGH — Estructura de componentes
+
+- **No definir componentes dentro de componentes.** Definir a nivel módulo o extraer; definirlos inline los remonta en cada render (pierde estado, mata performance).
+- **`content-visibility: auto`** para listas largas — difiere render y paint de lo que está off-screen.
+- **`defer`/`async` en `<script>`** para no bloquear el render durante el parsing.
+- **Resource hints de React DOM** (`preload`, `preconnect`, `prefetchDNS`) para recursos críticos.
+
+## MEDIUM — Re-render optimization
+
+- **Calcular derived state durante el render**, no guardarlo en `useState` (se desincroniza y genera renders extra).
+- **Leer state dinámico en el callback**, no suscribirse en render time cuando solo se usa en un handler.
+- **Functional `setState`** (`setX(prev => ...)`) para operar sobre el último valor y crear callbacks estables.
+- **Lazy state init**: pasar función a `useState(() => expensive())` para no recomputar en cada render.
+- **`useTransition` para updates no urgentes**; `useDeferredValue` para mantener inputs responsivos durante cómputo pesado.
+- **`useRef` para valores transitorios** (no-UI) que cambian seguido y no deben disparar render.
+- **Extraer defaults no-primitivos** de componentes memoizados a constantes a nivel módulo (preserva la memoización).
+- **Side effects de interacción van en event handlers**, no en `useEffect`.
+- **Dependencias de effect primitivas y estrechas**, no objetos enteros.
+
+## LOW-MEDIUM — useMemo / JS
+
+- **No envolver expresiones simples en `useMemo`** — el overhead del hook supera el cómputo.
+- **Index maps (`Map`) para lookups repetidos** en vez de `.find()`/`.includes()` en loops → O(1).
+- **`.flatMap()`** en lugar de `.map().filter(Boolean)`; combinar iteraciones múltiples de array en un solo loop.
+- **Hoist de `RegExp`** a nivel módulo (no recrear en cada render).
+- **Early return** cuando el resultado ya está determinado; chequear `length` antes de operaciones caras (sort).
+- **`.toSorted()`** en vez de `.sort()` para inmutabilidad.
+
+## Hydration
+
+- Evitar mismatch sin flicker con scripts inline síncronos cuando se actualiza el DOM antes de hidratar.
+- `suppressHydrationWarning` solo para diferencias server/client intencionales (fechas, IDs).
+- Conditional rendering explícito con ternario, no `&&` (evita renderizar `0` u otros falsy).
+
+## Anti-Patterns
+
+- Componentes definidos dentro del render de otro componente
+- `useMemo`/`useCallback` por default "por las dudas" sin medir
+- `useEffect` para lógica que pertenece a un event handler
+- Guardar en state lo que se puede derivar de props/state existentes
+- `.find()` dentro de `.map()` (O(n²)) sobre listas grandes
+
+---
+
+_Derivado de [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills) (react-best-practices, MIT). Condensado al formato Arcane._

package/skills/ai-sdk-setup/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: ai-sdk-setup
+description: "Integrar features de IA en Next.js con el Vercel AI SDK: streaming de chat, tool calling, structured output, agents y RAG. Default a modelos Claude. Usar al agregar chat, generación o agentes a una app Next/Node."
+category: "ai"
+argument-hint: "[chat|stream|tools|structured|agent|rag]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit, Task
+---
+# ai-sdk-setup — Vercel AI SDK con Claude
+
+## MANDATORY WORKFLOW
+
+> **Antes de codear features LLM, leer la skill `claude-api`** para model IDs vigentes, params y pricing. No asumir de memoria.
+
+### Step 0: Gather Requirements
+1. **Caso:** chat / generación one-shot / extracción structured / agente con tools / RAG
+2. **Streaming** al cliente o respuesta completa
+3. **Modelo:** Opus 4.8 (`claude-opus-4-8`, razonamiento) / Sonnet 4.6 (`claude-sonnet-4-6`, balance) / Haiku 4.5 (`claude-haiku-4-5-20251001`, rápido/barato)
+4. ¿Necesita tool calling / structured output / RAG (ver skill `pgvector-search`)?
+
+### Step 1: Instalar
+```bash
+pnpm add ai @ai-sdk/anthropic zod
+# env: ANTHROPIC_API_KEY (validar con Zod en src/lib/env.ts, nunca hardcodear)
+```
+
+### Step 2: Chat con streaming (Route Handler)
+```ts
+// app/api/chat/route.ts
+import { anthropic } from '@ai-sdk/anthropic';
+import { streamText, convertToModelMessages } from 'ai';
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+  const result = streamText({
+    model: anthropic('claude-sonnet-4-6'),
+    messages: convertToModelMessages(messages),
+  });
+  return result.toUIMessageStreamResponse();
+}
+```
+Cliente: `useChat()` de `@ai-sdk/react`.
+
+### Step 3: Structured output (Zod)
+```ts
+const { object } = await generateObject({
+  model: anthropic('claude-sonnet-4-6'),
+  schema: z.object({ sentiment: z.enum(['pos','neg','neutral']), score: z.number() }),
+  prompt: text,
+});
+```
+
+### Step 4: Tool calling / agente
+```ts
+const result = await generateText({
+  model: anthropic('claude-opus-4-8'),
+  tools: {
+    search: tool({
+      description: 'Buscar docs', inputSchema: z.object({ q: z.string() }),
+      execute: async ({ q }) => searchDocs(q),
+    }),
+  },
+  stopWhen: stepCountIs(5),   // loop multi-step controlado
+  prompt,
+});
+```
+
+### Step 5: Buenas prácticas
+- **Server-only** la API key — nunca exponer al cliente
+- Auth en el route handler (como cualquier API route — ver rule `nextjs-code`)
+- Rate limiting en endpoints de IA (costo $)
+- Prompt caching para system prompts grandes (ver skill `claude-api`)
+- Manejar errores de stream y abort (`AbortController`)
+- Validar/parsear toda salida structured con Zod antes de usarla
+
+## Cierre
+
+Probar el endpoint con streaming real, verificar manejo de errores/abort y que la API key nunca llega al cliente. Endpoint funcionando + key server-only → integración **READY**. Confirmar el approach con el usuario antes de escribir código. Siguiente paso: skill `claude-api` para tuning de modelo/caching, o `pgvector-search` para RAG.
+
+---
+
+_Inspirado en las skills de AI SDK de [laguagu/claude-code-nextjs-skills](https://github.com/laguagu/claude-code-nextjs-skills). Adaptado al formato Arcane y a modelos Claude. Verificar API/SDK contra la skill `claude-api`._

package/skills/nestjs-best-practices/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: nestjs-best-practices
+description: "NestJS production best practices: 40 reglas en 10 categorías (arquitectura, DI, errores, seguridad, performance, testing, DB/ORM, API, microservicios, devops) priorizadas por impacto. Usar al escribir/revisar código NestJS."
+category: "backend"
+argument-hint: "[architecture|di|security|performance|testing|database|api|all]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit, Task
+---
+# nestjs-best-practices — Guía priorizada por impacto
+
+40 reglas para aplicaciones NestJS production-ready, organizadas en 10 categorías y priorizadas de **CRITICAL** a **LOW-MEDIUM**. Cada regla del catálogo (en `references/`) trae impacto, ejemplo incorrecto, ejemplo correcto y link a docs.
+
+## MANDATORY WORKFLOW
+
+**No aplicar las 40 reglas a ciegas. Diagnosticar primero, priorizar por impacto.**
+
+### Step 0: Determinar scope
+
+1. **¿Código nuevo o auditoría de existente?** Si es auditoría, leer primero el módulo/servicio objetivo.
+2. **¿Qué categoría aplica?** Mapear el área del problema (ver tabla) o usar `all` para review completa.
+3. **¿Hay síntomas concretos?** (crashes, lentitud, N+1, leaks) → ir directo a la categoría relevante.
+
+### Step 1: Priorizar por impacto
+
+Aplicar en este orden — no bajar de nivel hasta resolver el anterior:
+
+| Prioridad | Categoría | Impacto | Reference |
+|-----------|-----------|---------|-----------|
+| 1 | Architecture | CRITICAL | `references/architecture.md` |
+| 2 | Dependency Injection | CRITICAL | `references/dependency-injection.md` |
+| 3 | Error Handling | HIGH | `references/error-handling.md` |
+| 4 | Security | HIGH | `references/security.md` |
+| 5 | Performance | HIGH | `references/performance.md` |
+| 6 | Database & ORM | MEDIUM-HIGH | `references/database.md` |
+| 7 | Testing | MEDIUM-HIGH | `references/testing.md` |
+| 8 | API Design | MEDIUM | `references/api-design.md` |
+| 9 | Microservices | MEDIUM | `references/microservices-devops.md` |
+| 10 | DevOps & Deployment | LOW-MEDIUM | `references/microservices-devops.md` |
+
+### Step 2: Aplicar + verificar
+
+Para cada regla relevante: leer el ejemplo correcto en el reference, aplicarlo, y verificar contra el checklist de cierre.
+
+### Step 3: Checklist de cierre
+
+- [ ] Sin dependencias circulares (`madge --circular` o equivalente)
+- [ ] Constructor injection en todos los providers; cero `ModuleRef.get()` en runtime
+- [ ] `ValidationPipe` global + DTOs decorados en todos los endpoints
+- [ ] Guards declarativos para auth/authz (no checks manuales)
+- [ ] Sin N+1 (eager loading / joins donde corresponde)
+- [ ] Migraciones versionadas, `synchronize: false` en prod
+- [ ] Graceful shutdown (SIGTERM) + health checks
+- [ ] Structured logging (JSON)
+
+Si todo el checklist pasa → código **COMPLIANT**. Antes de escribir cambios significativos, confirmar el approach con el usuario (Question → Decision → Approval).
+
+## Tabla de mapeo síntoma → categoría
+
+| Síntoma | Categoría |
+|---------|-----------|
+| Crash al arrancar / módulos no resuelven | Architecture, DI |
+| Lentitud en endpoints, muchas queries | Performance, Database |
+| Errores 500 inconsistentes / leaks de stack traces | Error Handling |
+| Endpoints expuestos / brute force / data sensible | Security |
+| Tests frágiles o que llaman servicios reales | Testing |
+| Respuestas inconsistentes / circular refs | API Design |
+
+---
+
+_Adaptado de [kadajett/agent-nestjs-skills](https://github.com/kadajett/agent-nestjs-skills). El repo original compila reglas atómicas (`rules/*.md`) a un `AGENTS.md` vía build script; acá se reorganizó al formato skill+references de Arcane._

package/skills/nestjs-best-practices/references/api-design.md

@@ -0,0 +1,34 @@
+# 8. API Design (MEDIUM)
+
+## 8.1 Use DTOs and Serialization for Responses — MEDIUM
+
+Transformar entidades antes de retornar → controlar exposición, evitar referencias circulares, consistencia.
+```ts
+export class UserResponseDto {
+  @Expose() id: string;
+  @Expose() email: string;
+  @Exclude() password: string; // nunca sale
+}
+// @UseInterceptors(ClassSerializerInterceptor)
+```
+
+## 8.2 Use Interceptors for Cross-Cutting Concerns — MEDIUM
+
+Logging, transformación, formato de respuesta uniforme (`{ data, meta }`) vía interceptors, no repetido en cada handler.
+
+## 8.3 Use Pipes for Input Transformation — MEDIUM
+
+Pipes built-in (`ParseIntPipe`, `ParseUUIDPipe`) y custom para validar/transformar input.
+```ts
+@Get(':id') findOne(@Param('id', ParseUUIDPipe) id: string) {}
+```
+
+## 8.4 Use API Versioning for Breaking Changes — MEDIUM
+
+Versionar endpoints para mantener compatibilidad.
+```ts
+app.enableVersioning({ type: VersioningType.URI }); // /v1/users
+@Controller({ path: 'users', version: '1' })
+```
+
+_Ref: https://docs.nestjs.com/techniques/serialization · https://docs.nestjs.com/techniques/versioning_

package/skills/nestjs-best-practices/references/architecture.md

@@ -0,0 +1,53 @@
+# 1. Architecture (CRITICAL)
+
+## 1.1 Avoid Circular Dependencies — CRITICAL
+
+Causa #1 de crashes en runtime. `forwardRef()` es un parche, no una solución.
+
+**Incorrecto** — A importa B, B importa A:
+```ts
+// users.service.ts → inyecta OrdersService
+// orders.service.ts → inyecta UsersService  ⇒ ciclo
+```
+**Correcto** — extraer lo compartido a un tercer módulo o usar eventos:
+```ts
+// Mover la lógica común a SharedModule, o emitir un evento
+this.eventEmitter.emit('order.created', payload);
+```
+
+## 1.2 Organize by Feature Modules — CRITICAL
+
+Estructurar por feature, no por capa técnica → desarrollo 3-5x más rápido.
+
+```
+src/
+  users/   { users.module.ts, users.controller.ts, users.service.ts, dto/ }
+  orders/  { orders.module.ts, ... }
+```
+No: `controllers/`, `services/`, `repositories/` globales.
+
+## 1.3 Proper Module Sharing — CRITICAL
+
+Exportar servicios desde un módulo dedicado garantiza instancia singleton.
+
+**Correcto:**
+```ts
+@Module({ providers: [UsersService], exports: [UsersService] })
+export class UsersModule {}
+// Otro módulo: imports: [UsersModule] → reusa la MISMA instancia
+```
+Re-declarar el provider en otro módulo crea una instancia nueva → estado inconsistente.
+
+## 1.4 Single Responsibility for Services — CRITICAL
+
+Un servicio = un concepto de dominio. +40% testabilidad. Si un servicio hace auth + email + billing, separarlo.
+
+## 1.5 Event-Driven Architecture for Decoupling — MEDIUM-HIGH
+
+Emitir eventos de dominio (`@nestjs/event-emitter`) para desacoplar módulos y permitir procesamiento async sin dependencias directas.
+
+## 1.6 Repository Pattern for Data Access — HIGH
+
+Encapsular queries en repositorios; separar lógica de negocio de la persistencia. El servicio depende de una abstracción `UserRepository`, no del ORM directamente.
+
+_Ref: https://docs.nestjs.com/modules · https://docs.nestjs.com/fundamentals/circular-dependency_

package/skills/nestjs-best-practices/references/database.md

@@ -0,0 +1,37 @@
+# 7. Database & ORM (MEDIUM-HIGH)
+
+## 7.1 Avoid N+1 Query Problems — HIGH
+
+El asesino silencioso de performance. Eager loading con relations o joins.
+
+**Incorrecto** — 1 query + N queries en loop:
+```ts
+const orders = await this.orderRepo.find();
+for (const o of orders) o.user = await this.userRepo.findOne(o.userId); // N+1
+```
+**Correcto:**
+```ts
+// Prisma
+prisma.order.findMany({ include: { user: true } });
+// TypeORM
+this.orderRepo.find({ relations: ['user'] });
+```
+
+## 7.3 Use Transactions for Multi-Step Operations — MEDIUM-HIGH
+
+Operaciones dependientes en una transacción → consistencia ante fallos.
+```ts
+await this.prisma.$transaction(async (tx) => {
+  await tx.account.update({ where: { id: from }, data: { balance: { decrement: amt } } });
+  await tx.account.update({ where: { id: to },   data: { balance: { increment: amt } } });
+});
+```
+
+## 7.2 Use Database Migrations — MEDIUM-HIGH
+
+Versionar cambios de schema con migraciones. **Nunca `synchronize: true` en producción** (puede borrar datos).
+```ts
+TypeOrmModule.forRoot({ synchronize: false, migrationsRun: true });
+```
+
+_Ref: https://docs.nestjs.com/techniques/database · https://www.prisma.io/docs/orm/prisma-migrate_

package/skills/nestjs-best-practices/references/dependency-injection.md

@@ -0,0 +1,45 @@
+# 2. Dependency Injection (CRITICAL)
+
+## 2.4 Prefer Constructor Injection — CRITICAL
+
+Visibilidad, type safety y testabilidad. Siempre.
+```ts
+@Injectable()
+export class OrdersService {
+  constructor(private readonly users: UsersService) {}
+}
+```
+
+## 2.1 Avoid Service Locator Anti-Pattern — HIGH
+
+**Incorrecto:**
+```ts
+const svc = this.moduleRef.get(UsersService); // dependencia oculta, no testeable
+```
+**Correcto:** inyectar por constructor (2.4). `ModuleRef` solo para casos dinámicos justificados.
+
+## 2.5 Understand Provider Scopes — CRITICAL
+
+`DEFAULT` (singleton) por defecto. `REQUEST` scope tiene costo de performance (instancia por request) → usar solo cuando se necesita contexto de request real.
+```ts
+@Injectable({ scope: Scope.REQUEST }) // solo si es necesario
+```
+
+## 2.6 Use Injection Tokens for Interfaces — HIGH
+
+Las interfaces de TS no existen en runtime → no se pueden inyectar. Usar símbolo o abstract class como token.
+```ts
+export const USER_REPO = Symbol('USER_REPO');
+@Module({ providers: [{ provide: USER_REPO, useClass: PrismaUserRepository }] })
+// constructor(@Inject(USER_REPO) private repo: UserRepository) {}
+```
+
+## 2.2 Interface Segregation — HIGH
+
+Interfaces chicas y enfocadas, no "fat interfaces" que fuerzan dependencias sin usar.
+
+## 2.3 Liskov Substitution — HIGH
+
+Toda implementación de una interfaz honra el contrato idéntico → intercambiables sin romper consumidores.
+
+_Ref: https://docs.nestjs.com/fundamentals/custom-providers · https://docs.nestjs.com/fundamentals/injection-scopes_

package/skills/nestjs-best-practices/references/error-handling.md

@@ -0,0 +1,43 @@
+# 3. Error Handling (HIGH)
+
+## 3.2 Throw HTTP Exceptions from Services — HIGH
+
+Los servicios lanzan excepciones, no retornan objetos de error.
+
+**Incorrecto:**
+```ts
+return { error: 'not found' }; // el controller tiene que adivinar
+```
+**Correcto:**
+```ts
+throw new NotFoundException(`User ${id} not found`);
+```
+
+## 3.1 Handle Async Errors Properly — HIGH
+
+Fire-and-forget y background tasks deben atrapar errores → si no, unhandled rejection puede tumbar el proceso.
+
+**Incorrecto:**
+```ts
+this.mailer.send(email); // floating promise, error perdido
+```
+**Correcto:**
+```ts
+void this.mailer.send(email).catch(err => this.logger.error('mail failed', err));
+```
+
+## 3.3 Use Exception Filters — HIGH
+
+Filtro global para formato de respuesta de error consistente y centralizado.
+```ts
+@Catch()
+export class AllExceptionsFilter implements ExceptionFilter {
+  catch(exception: unknown, host: ArgumentsHost) {
+    // shape único: { statusCode, message, timestamp, path }
+  }
+}
+// app.useGlobalFilters(new AllExceptionsFilter());
+```
+Nunca filtrar stack traces crudos al cliente en producción.
+
+_Ref: https://docs.nestjs.com/exception-filters_

package/skills/nestjs-best-practices/references/microservices-devops.md

@@ -0,0 +1,41 @@
+# 9. Microservices (MEDIUM) & 10. DevOps (LOW-MEDIUM)
+
+## 9.1 Implement Health Checks — MEDIUM
+
+Endpoints readiness/liveness con `@nestjs/terminus` para que el orquestador maneje la salud del servicio.
+```ts
+@Get('health') @HealthCheck()
+check() { return this.health.check([() => this.db.pingCheck('db')]); }
+```
+
+## 9.2 Message and Event Patterns Correctly — MEDIUM
+
+Distinguir request-response (`@MessagePattern`) de event-based (`@EventPattern`). Usar el patrón correcto según si se espera respuesta.
+
+## 9.3 Use Message Queues for Background Jobs — MEDIUM
+
+Offload de tareas largas a colas (`@nestjs/bull` / BullMQ) → no bloquear handlers de request.
+```ts
+await this.reportQueue.add('generate', { userId }); // responde rápido, procesa async
+```
+
+## 10.1 Implement Graceful Shutdown — MEDIUM
+
+Escuchar SIGTERM, completar requests in-flight antes de salir.
+```ts
+app.enableShutdownHooks();
+// onModuleDestroy() { await this.drainConnections(); }
+```
+
+## 10.2 Use ConfigModule for Environment Config — MEDIUM
+
+Config por entorno vía `ConfigModule`, validada al boot. Nada hardcodeado.
+```ts
+ConfigModule.forRoot({ validationSchema: Joi.object({ DATABASE_URL: Joi.string().required() }) });
+```
+
+## 10.3 Use Structured Logging — LOW-MEDIUM
+
+Logging JSON consistente (pino/winston) con `request_id`, `trace_id` para parseo/filtrado en producción.
+
+_Ref: https://docs.nestjs.com/recipes/terminus · https://docs.nestjs.com/microservices/basics · https://docs.nestjs.com/techniques/configuration_