ahmad-00/claude-skills

Ingeniero Senior Next.js / React / TypeScript

Next.js cambia rápidamente y la memoria del modelo suele estar desactualizada. Antes de usar cualquier API que dependa de una versión, consulta references/versions.md. Si el next instalado tiene documentación empaquetada (node_modules/next/dist/docs/) o un AGENTS.md generado por Next.js, prefiere esos sobre la memoria.

Paso 0: detectar versiones y convenciones (siempre)

Ejecuta bash scripts/detect_versions.sh (solo lectura), luego confirma:

• package.json + archivo de bloqueo (pnpm/npm/yarn/bun) → next, react, typescript, tailwindcss, herramientas de prueba; usa el gestor de paquetes del archivo de bloqueo
• next.config.* → cacheComponents, partialPrefetching, reactCompiler, experimental.*
• Router: app/ vs src/app/, cualquier pages/ (routers mixtos), proxy.ts vs middleware.ts legado
• Capa de datos: ORM/SDK, módulos lib/dal.ts existentes o server-only, librería de autenticación
• Estilizado y kit de UI (versión de Tailwind, CSS Modules, shadcn/ui, tokens de diseño), lint/format (ESLint flat config vs Biome)
• Pruebas: Vitest/Jest, Testing Library, Playwright; scripts CI existentes

Coincide con las convenciones existentes. Si el proyecto está en una versión mayor anterior, escribe código que funcione en esa versión.

Valores predeterminados (uno por decisión, con vía de escape)

Decisión	Valor predeterminado	Usa la alternativa cuando
Tipo de componente	Server Component	Necesita estado, efectos, APIs del navegador o manejadores de eventos → "use client" en la hoja más pequeña
Modelo de caching (16.x)	Cache Components (cacheComponents: true, 'use cache' + cacheLife/cacheTag)	Aplicación existente con el modelo anterior sin migración planificada. No migres a medias
Mutaciones	Server Actions + revalidateTag/updateTag/refresh	API pública consumida por otros clientes → route handler
Acceso a datos	Una capa de acceso a datos (DAL) solo para servidor que autentica y autoriza cada lectura/escritura	—
Intercepción de solicitudes	proxy.ts solo para redirecciones/reescrituras/headers	Nunca para autorización como única comprobación
Runtime	Node.js (predeterminado)	Ninguno en 16.3+: runtime = 'edge' está obsoleto/sin soporte
Formularios	<form action={serverAction}> + useActionState + validación de esquema (zod o del proyecto) en el servidor	Asistentes complejos solo para cliente → librería de formularios cliente ya en el proyecto
Estilizado	Sistema del proyecto; para proyectos nuevos Tailwind CSS v4 con configuración CSS-first	—
Estado del cliente	Parámetros de búsqueda URL → estado del servidor → estado de React; store global solo si se demuestra necesario	—
Memoización	React Compiler si está habilitado; de lo contrario, memoiza solo los puntos calientes medidos	—
Pruebas	Vitest + Testing Library para unidades; Playwright para flujos críticos E2E	Jest ya configurado

Flujo de trabajo A: construir una ruta o funcionalidad

- [ ] Paso 0 completado
- [ ] Segmento de ruta: page.tsx, layout.tsx, loading.tsx/límites de Suspense, error.tsx, not-found.tsx según sea necesario
- [ ] Datos a través de la DAL (solo servidor), esperados en Server Components; params/searchParams son Promesas: `const { id } = await params`
- [ ] Decide qué se almacena en caché ('use cache' + cacheLife/cacheTag) vs tiempo de solicitud (dentro de Suspense)
- [ ] Mutaciones a través de Server Actions: valida la entrada, vuelve a verificar la autorización en la acción, revalida las etiquetas
- [ ] Componentes de cliente mínimos; props serializables; sin secretos en los bundles del cliente (solo NEXT_PUBLIC_* llegan al navegador)
- [ ] Accesibilidad: elementos semánticos, etiquetas, gestión de enfoque, recorridos de teclado, contraste de color
- [ ] Pruebas para la lógica + una E2E para el camino crítico
- [ ] El bucle de validación pasa

Validar → corregir → repetir:

pnpm exec tsc --noEmit            # o equivalentes de npm/yarn/bun
pnpm lint                          # ESLint o Biome según el proyecto (next lint fue eliminado en 16)
pnpm test -- --run                 # Vitest
pnpm build                         # Detecta errores de Cache Components / prerenderizado
pnpm exec playwright test          # cuando existan E2E

Los errores de next build sobre datos no almacenados en caché fuera de <Suspense> son señales, no ruido. Corrige añadiendo 'use cache', moviendo el acceso a un límite de Suspense, o marcándolo como tiempo de solicitud.

Flujo de trabajo B: actualizar Next.js (baja libertad)

- [ ] Lee "Patrones antiguos" y pisos de seguridad en references/versions.md
- [ ] Confirma un árbol limpio; crea una rama
- [ ] Ejecuta la herramienta de actualización oficial: `npx next@canary upgrade --agent=latest`
      (o `npx @next/codemod@canary upgrade latest` si el flujo del agente no está disponible)
- [ ] Actualiza react, react-dom y @types/react junto con next
- [ ] Elimina las exportaciones de `runtime = 'edge'`; renombra middleware.ts → proxy.ts (runtime Node)
- [ ] Bucle de validación; luego prueba manualmente autenticación, redirecciones, caching y revalidación

Seguridad primero: si la versión instalada está por debajo de un piso parcheado en versions.md, actualiza el propio next (parchear solo los paquetes de React no es suficiente).

Flujo de trabajo C: adoptar Cache Components en una aplicación existente

Migra ruta por ruta. Habilita cacheComponents (+ partialPrefetching en 16.4+) en una rama, ejecuta next build y corrige cada límite reportado. Consulta references/caching.md. Si está instalado, el skill next-cache-components-adoption de Next.js cubre la mecánica en profundidad; úsalo junto con este.

Reglas de autenticación y seguridad

• Autoriza en la DAL y en cada Server Action y route handler. Las comprobaciones de proxy/middleware son solo una redirección optimista. CVE-2025-29927 demostró que son posibles las evasiones basadas en headers del middleware.
• Las Server Actions son endpoints HTTP públicos: valida la entrada, verifica la sesión, verifica la propiedad.
• Importa server-only en módulos con secretos o acceso a BD; devuelve DTOs (solo campos necesarios) a los Client Components.
• Detalles: references/data-and-auth.md.

Implementar a partir de un diseño o mockup

1. Inventaria el diseño: tokens (color, escala tipográfica, espaciado, radio), componentes, estados (hover, focus, disabled, loading, empty, error) y puntos de ruptura.
2. Mapea primero a los tokens y componentes existentes del proyecto; añade nuevos tokens al tema, no como valores únicos.
3. Construye primero el marcado estático del Server Component, luego añade interactividad en las hojas.
4. Verifica a 320px, tablet y escritorio. Verifica etiquetas de teclado y lector de pantalla. Respeta prefers-reduced-motion.
5. Si hay una herramienta de navegador o Playwright disponible, toma una captura de pantalla y compara con el mockup; itera hasta que el espaciado y la tipografía coincidan.

Modo de revisión

Usa references/review-checklist.md. Reporta cada hallazgo como bloqueante / debería corregirse / detalle menor, con archivo:línea, el problema y una corrección de código concreta. Ordena los hallazgos por severidad. Los bloqueantes incluyen: autenticación solo en proxy, secretos que llegan a los bundles del cliente, entrada de Server Action no validada, una versión vulnerable de next y datos específicos de usuario dentro de un ámbito compartido de 'use cache'.

Mapa de referencias

• references/versions.md: versiones, pisos de seguridad, patrones antiguos, notas de verificación
• references/data-and-auth.md: patrón DAL, plantilla de Server Action, manejo de sesiones
• references/caching.md: reglas de Cache Components, ensureStatic, navigation()/prefetch()
• references/review-checklist.md: reglas clasificadas por impacto