claude-code-arcane 1.0.1 → 1.1.0

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_

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

@@ -0,0 +1,32 @@
+# 5. Performance (HIGH)
+
+## 5.3 Optimize Database Queries — HIGH
+
+Seleccionar solo columnas necesarias, índices apropiados, no over-fetch de relaciones.
+```ts
+// Prisma: select explícito en vez de traer la fila entera + relaciones
+prisma.user.findMany({ select: { id: true, email: true } });
+```
+
+## 5.4 Use Caching Strategically — HIGH
+
+Cachear operaciones caras con TTL apropiado e invalidación basada en eventos.
+```ts
+@UseInterceptors(CacheInterceptor)
+@CacheTTL(30)
+@Get('stats') getStats() { /* ... */ }
+```
+
+## 5.1 Async Lifecycle Hooks Correctly — HIGH
+
+Retornar promesas de hooks async; constructores síncronos (no bloquear el arranque).
+```ts
+async onModuleInit() { await this.warmupCache(); } // ✓
+// constructor(){ await ... }  ✗ no se puede / bloquea
+```
+
+## 5.2 Lazy Loading for Large Modules — MEDIUM
+
+Diferir inicialización de módulos poco usados con `LazyModuleLoader` → menor tiempo de arranque y memoria.
+
+_Ref: https://docs.nestjs.com/techniques/caching · https://docs.nestjs.com/fundamentals/lazy-loading-modules_

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

@@ -0,0 +1,50 @@
+# 4. Security (HIGH)
+
+## 4.1 Secure JWT Authentication — CRITICAL
+
+Tokens de vida corta (15m) + refresh tokens. Secreto en env/secret manager. Nunca data sensible en el payload.
+```ts
+JwtModule.register({
+  secret: process.env.JWT_SECRET,        // nunca hardcodeado
+  signOptions: { expiresIn: '15m' },
+});
+// payload: { sub: userId, role }  ← nada de passwords, emails completos, PII
+```
+
+## 4.5 Validate All Input with DTOs and Pipes — HIGH
+
+`ValidationPipe` global + DTOs decorados. Rechazar input malformado antes de procesarlo.
+```ts
+app.useGlobalPipes(new ValidationPipe({
+  whitelist: true,            // descarta props no declaradas
+  forbidNonWhitelisted: true, // 400 si vienen props extra
+  transform: true,
+}));
+
+export class CreateUserDto {
+  @IsEmail() email: string;
+  @MinLength(8) password: string;
+}
+```
+
+## 4.4 Use Guards for AuthN/AuthZ — HIGH
+
+Guards declarativos, no checks manuales en cada handler.
+```ts
+@UseGuards(JwtAuthGuard, RolesGuard)
+@Roles('admin')
+@Get('users') findAll() { /* ... */ }
+```
+
+## 4.2 Rate Limiting — HIGH
+
+`@nestjs/throttler`, límites por endpoint (login más estricto que lecturas).
+```ts
+@Throttle({ default: { limit: 5, ttl: 60000 } }) // 5/min en /login
+```
+
+## 4.3 Sanitize Output to Prevent XSS — HIGH
+
+Sanitizar contenido generado por usuario antes de almacenar; `Content-Type` correcto en respuestas.
+
+_Ref: https://docs.nestjs.com/security/authentication · https://docs.nestjs.com/security/rate-limiting_

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

@@ -0,0 +1,32 @@
+# 6. Testing (MEDIUM-HIGH)
+
+## 6.3 Use Testing Module for Unit Tests — HIGH
+
+Entorno aislado con `Test.createTestingModule` y dependencias mockeadas.
+```ts
+const moduleRef = await Test.createTestingModule({
+  providers: [
+    OrdersService,
+    { provide: UserRepository, useValue: mockUserRepo },
+  ],
+}).compile();
+const service = moduleRef.get(OrdersService);
+```
+
+## 6.2 Mock External Services in Tests — HIGH
+
+Nunca llamar APIs o DBs reales en tests. Mockear todas las dependencias externas con escenarios realistas (éxito, error, timeout).
+
+## 6.1 Use Supertest for E2E Testing — HIGH
+
+Probar el ciclo completo request/response incluyendo middleware, guards y pipes. Setup/teardown apropiados.
+```ts
+const app = moduleRef.createNestApplication();
+await app.init();
+await request(app.getHttpServer())
+  .post('/users').send({ email: 'a@b.com', password: 'secret123' })
+  .expect(201);
+await app.close();
+```
+
+_Ref: https://docs.nestjs.com/fundamentals/testing_

package/skills/nestjs-scaffold/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: nestjs-scaffold
+description: "Scaffold de API NestJS production-ready con módulos por feature, DI, ValidationPipe global, Prisma/Drizzle, guards de auth y testing. Usar para iniciar un backend NestJS nuevo."
+category: "backend"
+argument-hint: "[project-name]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit, Task
+---
+# nestjs-scaffold — NestJS API Scaffolder
+
+## MANDATORY WORKFLOW
+
+**Antes de generar cualquier código, completar estos pasos en orden.**
+
+### Step 0: Gather Requirements
+1. **Nombre del servicio** (kebab-case)
+2. **Transport:** REST (default) / GraphQL / microservicio
+3. **ORM:** Prisma (default) / Drizzle / TypeORM
+4. **DB:** PostgreSQL (default) / MySQL
+5. **Auth:** JWT + refresh (default) / OAuth / ninguna
+6. **Deploy:** Docker (default) / Railway / AWS ECS
+
+### Step 1: Crear base
+```bash
+npm i -g @nestjs/cli
+nest new <name> --package-manager pnpm
+cd <name>
+nest g module users && nest g controller users && nest g service users
+```
+
+### Step 2: Estructura (feature modules — NO por capa)
+```
+src/
+  users/   { users.module.ts, users.controller.ts, users.service.ts, dto/, entities/ }
+  auth/    { auth.module.ts, jwt.strategy.ts, guards/, decorators/ }
+  common/  { filters/, interceptors/, pipes/ }
+  config/  { config.module.ts, env.validation.ts }
+  main.ts
+```
+
+### Step 3: Bootstrap no negociable (`main.ts`)
+```ts
+app.useGlobalPipes(new ValidationPipe({ whitelist: true, forbidNonWhitelisted: true, transform: true }));
+app.useGlobalFilters(new AllExceptionsFilter());
+app.enableShutdownHooks();           // graceful shutdown
+app.enableVersioning({ type: VersioningType.URI });
+```
+
+### Step 4: Defaults
+- Constructor injection siempre; cero `ModuleRef.get()` en runtime
+- DTOs decorados (`class-validator`) en todos los endpoints
+- Guards declarativos para auth/authz
+- `ConfigModule` con validación de env (Joi/Zod) al boot
+- Migraciones versionadas, `synchronize: false`
+- Health check (`@nestjs/terminus`) + structured logging (pino)
+- Tests: `Test.createTestingModule` (unit) + supertest (e2e)
+
+### Step 5: Verificar
+`npm run build` + `npm run test`. Revisar contra la rule `nestjs-code` y el skill `nestjs-best-practices`. Build + tests verdes → scaffold **READY**.
+
+## Stack Defaults
+
+| Componente | Default |
+|------------|---------|
+| Framework | NestJS 10+ |
+| ORM | Prisma |
+| DB | PostgreSQL |
+| Auth | JWT + refresh tokens |
+| Validación | class-validator + ValidationPipe |
+| Testing | Jest + supertest |
+| Deploy | Docker |
+
+---
+
+_Inspirado en las skills NestJS de [kadajett/agent-nestjs-skills](https://github.com/kadajett/agent-nestjs-skills) y [giuseppe-trisciuoglio/developer-kit](https://github.com/giuseppe-trisciuoglio/developer-kit). Adaptado al formato Arcane._

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

@@ -0,0 +1,64 @@
+---
+name: nextjs-best-practices
+description: "React + Next.js performance: 64 reglas en 8 categorías (waterfalls, bundle, server, client fetching, re-render, rendering, JS, advanced) priorizadas por impacto, de Vercel Engineering. Usar al escribir/optimizar React o Next.js."
+category: "frontend"
+argument-hint: "[waterfalls|bundle|server|rerender|rendering|js|all]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit, Task
+---
+# nextjs-best-practices — Performance priorizada por impacto
+
+64 reglas de optimización de performance para React y Next.js, de Vercel Engineering, organizadas en 8 categorías priorizadas de **CRITICAL** a **LOW**. Detalle por categoría en `references/`.
+
+## MANDATORY WORKFLOW
+
+**Diagnóstico dirigido por métricas, no aplicar las 64 reglas a ciegas** (este es el enfoque `vercel-optimize`: medir primero, optimizar solo lo que las métricas señalan).
+
+### Step 0: Medir / localizar
+
+1. **¿Hay métricas?** Lighthouse, Web Vitals (LCP/INP/CLS), bundle analyzer, traces de Vercel.
+2. **¿Cuál es el síntoma dominante?** TTFB alto → waterfalls/server. Bundle grande / TBT → bundle size. Jank en interacción → re-render. Layout shift → rendering.
+3. Identificar las rutas/componentes concretos que las métricas apuntan. Optimizar **esos**, no todo.
+
+### Step 1: Priorizar por impacto
+
+| Prioridad | Categoría | Impacto | Reference |
+|-----------|-----------|---------|-----------|
+| 1 | Eliminating Waterfalls | CRITICAL | `references/waterfalls.md` |
+| 2 | Bundle Size Optimization | CRITICAL | `references/bundle-size.md` |
+| 3 | Server-Side Performance | HIGH | `references/server.md` |
+| 4 | Client-Side Data Fetching | MEDIUM-HIGH | `references/client-fetching.md` |
+| 5 | Re-render Optimization | MEDIUM | `references/rerender.md` |
+| 6 | Rendering Performance | MEDIUM | `references/rendering.md` |
+| 7 | JavaScript Performance | LOW-MEDIUM | `references/javascript.md` |
+| 8 | Advanced Patterns | LOW | `references/advanced.md` |
+
+### Step 2: Aplicar + medir de nuevo
+
+Aplicar la regla, re-medir. Si la métrica no mejoró, revertir y subir de categoría — no acumular micro-optimizaciones sin impacto medible.
+
+### Step 3: Checklist de cierre
+
+- [ ] Fetches independientes en paralelo (`Promise.all`), no en cascada
+- [ ] Server Components por defecto; `'use client'` empujado abajo en el árbol
+- [ ] Sin barrel imports en el critical path; componentes pesados con `next/dynamic`
+- [ ] Server Actions autenticadas individualmente
+- [ ] Sin componentes definidos dentro de componentes
+- [ ] `next/image` + `generateMetadata` + resource hints donde corresponde
+- [ ] Re-medir Web Vitals post-cambios
+
+Si todo el checklist pasa → optimización **COMPLETE**. Antes de escribir cambios significativos, confirmar el approach con el usuario (Question → Decision → Approval).
+
+## Tabla síntoma → categoría
+
+| Métrica mala | Categoría |
+|--------------|-----------|
+| TTFB / tiempo de respuesta del server | Waterfalls, Server |
+| First Load JS / TBT alto | Bundle Size |
+| INP / jank en interacción | Re-render, JS |
+| LCP | Rendering, Bundle, Server |
+| CLS / flicker en hydration | Rendering |
+
+---
+
+_Adaptado de [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills) (react-best-practices, MIT, © Vercel). 64 reglas priorizadas por impacto, reorganizadas al formato skill+references de Arcane._

package/skills/nextjs-best-practices/references/advanced.md

@@ -0,0 +1,21 @@
+# 8. Advanced Patterns (LOW)
+
+Patrones de borde con `useEffectEvent` y setup de app. Impacto bajo pero evitan bugs sutiles.
+
+## 8.4 useEffectEvent for Stable Callback Refs — LOW
+Referencias de callback estables para componentes memoizados sin re-disparar effects.
+```tsx
+const onTick = useEffectEvent(() => doSomething(latestProp));
+useEffect(() => { const id = setInterval(onTick, 1000); return () => clearInterval(id); }, []);
+```
+
+## 8.1 Do Not Put Effect Events in Dependency Arrays — LOW
+Los Effect Events no van en el array de dependencias; se llaman desde el effect, no lo re-disparan.
+
+## 8.2 Initialize App Once, Not Per Mount — LOW
+Setup de app a nivel module-load, no en effects/mounts de componente.
+
+## 8.3 Store Event Handlers in Refs — LOW
+Handlers que cambian seguido en refs → no causan re-render.
+
+_Ref: https://react.dev/reference/react/experimental_useEffectEvent_

package/skills/nextjs-best-practices/references/bundle-size.md

@@ -0,0 +1,32 @@
+# 2. Bundle Size Optimization (CRITICAL)
+
+## 2.1 Avoid Barrel File Imports — CRITICAL
+Los barrels (`index.ts` que re-exportan todo) arrastran miles de módulos sin usar.
+```ts
+// ✗ import { debounce } from 'lodash';   (todo lodash)
+// ✓ import debounce from 'lodash/debounce';
+```
+Configurar `optimizePackageImports` en `next.config.js` para libs grandes.
+
+## 2.4 Dynamic Imports for Heavy Components — CRITICAL
+```tsx
+const Chart = dynamic(() => import('./Chart'), { ssr: false, loading: () => <Skeleton/> });
+```
+Para charts, editores de texto rico, modales, mapas — todo lo no necesario en el primer render.
+
+## 2.5 Prefer Statically Analyzable Paths — HIGH
+Imports con paths literales/mapas explícitos, no construidos en runtime → permite tree-shaking.
+
+## 2.2 Conditional Module Loading — HIGH
+Cargar data/módulos grandes solo cuando la feature se activa.
+
+## 2.6 Preload Based on User Intent — MEDIUM
+Precargar el bundle pesado en hover/focus, antes de que se necesite.
+```tsx
+<button onMouseEnter={() => import('./HeavyModal')}>Abrir</button>
+```
+
+## 2.3 Defer Non-Critical Third-Party Libraries — MEDIUM
+Analytics, logging, error tracking → cargar después de hydration, no bloquear el bundle inicial (`next/script` con `strategy="afterInteractive"` o `lazyOnload`).
+
+_Ref: https://nextjs.org/docs/app/api-reference/components/script · https://nextjs.org/docs/app/api-reference/config/next-config-js/optimizePackageImports_

package/skills/nextjs-best-practices/references/client-fetching.md

@@ -0,0 +1,20 @@
+# 4. Client-Side Data Fetching (MEDIUM-HIGH)
+
+## 4.3 Use SWR for Automatic Deduplication — MEDIUM-HIGH
+Dedup de requests, caching y revalidación entre instancias de componente.
+```ts
+const { data } = useSWR(`/api/user/${id}`, fetcher); // mismo key = 1 request
+```
+
+## 4.2 Use Passive Event Listeners for Scrolling — MEDIUM
+```ts
+el.addEventListener('touchstart', handler, { passive: true }); // scroll inmediato
+```
+
+## 4.4 Version and Minimize localStorage Data — MEDIUM
+Prefijo de versión en las keys (`app:v2:prefs`) y guardar solo campos necesarios → evita conflictos y reduce tamaño.
+
+## 4.1 Deduplicate Global Event Listeners — LOW
+Compartir listeners globales entre instancias con un `Map` + `useSWRSubscription()` en vez de uno por componente.
+
+_Ref: https://swr.vercel.app_