TL;DR

Hemos desplegado 30+ proyectos headless en 18 meses en Social Animal. Aproximadamente un tercio de nuestras incorporaciones recientes es trabajo de rescate de compilaciones dirigidas por diseñadores que enviaron demostraciones pero se rompieron en producción. La guía "Claude Code for Designers" de Michael Nervegna en Substack es genuinamente buena para prototipos -- pero se detiene antes de Row Level Security, actualización de tokens de autenticación, decisiones de abstracción de bases de datos, reversión de despliegue, Política de Seguridad de Contenidos y autenticación de administrador. Este artículo cubre esas brechas. Si estás enviando a producción, las necesitas.

Tabla de Contenidos

¿Qué es Claude Code y por qué los diseñadores lo están usando?

Claude Code es la herramienta de codificación basada en terminal de Anthropic que se lanzó a principios de 2025. Se ejecuta como @anthropic-ai/claude-code y requiere Claude Pro ($20/mes) o Team ($30/asiento/mes) con acceso a API. Escribes, editas y depuras código a través del lenguaje natural en tu terminal.

Los diseñadores lo están usando porque cierra la brecha entre "diseñé esto en Figma" y "esta es una aplicación Next.js funcional". A diferencia de v0 o Bolt, Claude Code opera en tu sistema de archivos real. Lee tu estructura de proyecto, modifica archivos, ejecuta tu servidor de desarrollo e itera sobre la salida de errores. Para alguien que entiende la jerarquía de componentes pero no quiere memorizar genéricos de TypeScript, eso es genuinamente útil.

Nervegna lo posiciona como una herramienta que permite a los diseñadores "pensar en sistemas" en lugar de sintaxis. Estamos de acuerdo. Donde divergimos es en lo que sucede después de que el primer npm run dev tiene éxito.

¿Qué consigue bien la guía de Nervegna?

Nervegna acierta en tres cosas que la mayoría de tutoriales de codificación de IA pierden.

Primero: contexto del proyecto. Recomienda alimentar a Claude Code con un archivo CLAUDE.md que contenga tus convenciones de proyecto, stack de tecnología y tokens de diseño. Hemos visto a Claude Code generar utilidades de Tailwind contra un proyecto que usa CSS Modules porque nadie le contó las convenciones. Establecer contexto antes de escribir código es el enfoque correcto.

Segundo: el bucle iterativo. Indicación, revisar salida, corregir el rumbo, repetir. No trata a Claude Code como un botón "describir y enviar". Lo trata como un socio de emparejamiento que necesita supervisión. Ese es el modelo mental correcto.

Tercero: empezar en pequeño. Construye un único componente o página antes de intentar un andamiaje completo de la aplicación. Hemos visto a diseñadores pedir "construye un panel de control SaaS completo con autenticación, facturación y administrador" en un mensaje. El resultado siempre es un desastre. El enfoque incremental de Nervegna evita esto.

Donde la guía de Nervegna sirve bien a los diseñadores es en la fase 0-a-prototipo. El problema es que los prototipos se convierten en código de producción, y es ahí donde importan las brechas.

¿Dónde se queda corta la guía?

La pieza de Nervegna se entrega para la fase de prototipado. No aborda preocupaciones que se vuelven urgentes cuando conectas una base de datos real, usuarios reales e infraestructura de despliegue real.

Lo que falta:

  1. Row Level Security (RLS) -- Los proyectos de Supabase generados por Claude Code casi nunca tienen políticas RLS correctas
  2. Transferencia de autenticación -- la brecha entre Supabase Auth en desarrollo y flujos de producción con actualización de tokens, gestión de sesiones y manejo de redirecciones
  3. Decisiones de abstracción de base de datos -- cuándo usar el cliente de Supabase directamente vs. Prisma u ORM Drizzle
  4. Estrategia de reversión de despliegue -- qué sucede cuando una confirmación de Claude Code rompe la producción
  5. Política de Seguridad de Contenidos -- especialmente para Next.js Image con activos proxificados/externos
  6. Autenticación de administrador -- cuándo necesitas acceso basado en roles más allá de autenticación de usuario simple

Tomemos cada uno.

Problemas de Row Level Security que Claude no detectará

Row Level Security es el mecanismo de Supabase para garantizar que las consultas de base de datos solo devuelvan filas que el usuario solicitante está autorizado a ver. Cuando creas una tabla en Supabase, RLS está deshabilitado de forma predeterminada. Cualquier usuario autenticado -- o en algunas configuraciones, cualquier solicitud anónima -- puede leer cada fila.

Cuando Claude Code estructura un proyecto de Supabase, crea tablas y escribe consultas del lado del cliente. A veces agregará políticas de RLS si las solicitas. Pero las políticas que genera a menudo son sutilmente incorrectas.

Errores comunes de RLS en código generado por IA

Error Qué sucede Cómo arreglarlo
RLS no está habilitado en absoluto Cualquier usuario autenticado lee todos los datos ALTER TABLE tu_tabla ENABLE ROW LEVEL SECURITY;
La política usa auth.uid() pero la tabla no tiene columna user_id La política se compila pero coincide con cero filas, bloqueando todo acceso Agrega user_id UUID REFERENCES auth.users(id) y rellénalo
La política SELECT existe pero sin políticas INSERT/UPDATE/DELETE Los usuarios pueden leer pero no escribir sus propios datos Crea políticas para cada operación por separado
La política usa auth.role() = 'authenticated' solo Cualquier usuario conectado puede ver todas las filas, no solo las suyas Agrega condición auth.uid() = user_id
Clave de rol de servicio usada en código del lado del cliente RLS se omite completamente Nunca expongas SUPABASE_SERVICE_ROLE_KEY en paquetes del cliente

Hemos visto ese último -- clave de rol de servicio en código del cliente -- en tres proyectos separados construidos por diseñadores este año. Claude Code a veces usará la clave de rol de servicio porque "funciona" y no lanza errores de permiso. Esa clave omite toda RLS. Pertenece únicamente a código del lado del servidor (rutas API, acciones de servidor, funciones edge). Nunca en un componente use client.

Nervegna no cubre RLS en su guía, lo cual es comprensible. Pero si estás siguiendo su flujo de trabajo y conectándote a Supabase, verifica manualmente cada tabla. Ejecuta esto en el editor SQL de Supabase:

SELECT schemaname, tablename, rowsecurity
FROM pg_tables
WHERE schemaname = 'public';

Si rowsecurity es false para cualquier tabla que contenga datos de usuario, detente y corrígelo antes de desplegar.

Transferencia de Autenticación: La brecha entre prototipo y producción

La autenticación es el punto de falla más común en compilaciones dirigidas por diseñadores. No porque la configuración inicial sea incorrecta -- Supabase Auth es fácil de estructurar -- sino porque la autenticación de producción implica casos extremos que no aparecen durante el desarrollo local.

La guía de Nervegna se enfoca en que las cosas funcionen localmente. Aquí está lo que se rompe cuando despliegas:

Fallos de actualización de tokens

Los tokens de autenticación de Supabase expiran después de 3600 segundos (1 hora) de forma predeterminada. El cliente de Supabase maneja la actualización automáticamente -- en teoría. En la práctica, si tu middleware de Next.js o componentes de servidor crean un nuevo cliente de Supabase en cada solicitud sin pasar la sesión existente, obtendrás errores 401 intermitentes después de la primera hora.

Con Next.js App Router, necesitas @supabase/ssr (versión 0.5.x a partir de febrero de 2025) y manejo adecuado de cookies en middleware. Claude Code a menudo genera el paquete anterior @supabase/auth-helpers-nextjs, que está deprecado. Verifica tu package.json.

Desajustes de URI de redirección

Los proveedores de OAuth (Google, GitHub) requieren URIs de redirección exactos. Claude Code los configura para localhost:3000. Cuando despliegas en Vercel o Netlify, necesitas agregar tu URL de producción y cualquier URL de despliegue de vista previa tanto a la consola del proveedor de OAuth como a la configuración Auth de Supabase bajo "Redirect URLs". Toma 5 minutos pero bloquea 100% de los inicios de sesión de OAuth si lo pierdes.

El problema de la sincronización de sesiones

En Next.js 14+, tienes componentes de servidor, componentes de cliente, middleware, rutas API y acciones de servidor -- potencialmente todos necesitando la sesión del usuario actual. El cliente de Supabase debe crearse de manera diferente en cada contexto. Claude Code a menudo crea una única utilidad createClient() y la usa en todos lados, lo que causa desajustes de hidratación y sesiones obsoletas.

Necesitas un mínimo de tres funciones de creación de cliente:

  • createBrowserClient() para componentes cliente
  • createServerClient() para componentes de servidor y acciones de servidor
  • createMiddlewareClient() para middleware

Esto está documentado en la guía SSR de Supabase pero Claude Code no lo genera consistentemente correctamente.

Supabase vs Prisma: ¿Cuál debería generar Claude Code?

Nervegna no aborda esta decisión, y importa más de lo que la mayoría de diseñadores se dan cuenta.

Cliente de Supabase (@supabase/supabase-js) consulta la base de datos a través de la API PostgREST de Supabase. Es conveniente, no requiere archivos de definición de esquema, y funciona directamente con RLS. Pero no te da seguridad de tipos más allá de lo que Supabase genera, y acopla fuertemente tu aplicación a la infraestructura de Supabase.

Prisma ORM (actualmente v6.x) se conecta directamente a PostgreSQL. Te da un archivo de esquema (schema.prisma), tipos de TypeScript generados, migraciones y consultas agnósticas de base de datos. Pero no respeta políticas RLS (se conecta como usuario privilegiado), y requiere un paso de construcción para generar el cliente.

Drizzle ORM (v0.36.x) es una alternativa más ligera con sintaxis similar a SQL y mejor soporte de tiempo de ejecución edge.

Matriz de decisión

Factor Cliente de Supabase Prisma Drizzle
Soporte RLS Nativo Debe implementarse en capa de aplicación Debe implementarse en capa de aplicación
Seguridad de tipos Generado vía CLI Generado desde esquema Esquema como código
Compatible con tiempo de ejecución edge Sí Limitado (Prisma Accelerate requerido) Sí
Curva de aprendizaje para diseñadores Baja Media Media
Bloqueo de proveedor Alto (Supabase) Bajo Bajo
Calidad de generación de Claude Code Buena Buena Inconsistente

Nuestra recomendación: si estás construyendo un prototipo o siempre ejecutarás en Supabase, usa el cliente de Supabase. Si necesitas salirte de Supabase o quieres desarrollo basado en esquema estricto, usa Drizzle. Nos hemos alejado de Prisma para nuevos proyectos debido a limitaciones de tiempo de ejecución edge, aunque Prisma Accelerate ($0 para 60K consultas/mes, luego $49/mes) ha mejorado esto.

Cuéntale a Claude Code tu decisión explícitamente en tu archivo CLAUDE.md. Si no lo haces, mezclará enfoques -- a veces consultando vía cliente de Supabase, a veces vía un ORM -- y terminarás con dos patrones de acceso a datos diferentes en el mismo proyecto.

Reversión de despliegue: Qué sucede cuando tu código generado por IA se rompe

La guía de Nervegna recorre la construcción de características iterativamente. No aborda qué sucede cuando una sesión de Claude Code genera una confirmación que pasa en desarrollo local pero se rompe en producción.

Esto sucede más a menudo de lo que esperarías. Claude Code puede modificar 15 archivos en una sola respuesta de indicación. Si confirmas eso como una unidad e implementas, revertir significa revertir los 15 cambios -- incluso si 13 estaban bien.

Una estrategia práctica de reversión

1. Confirma después de cada cambio lógico, no después de cada sesión de Claude Code. Si Claude modifica autenticación, UI y esquema de base de datos en una sesión, haz tres confirmaciones separadas.

2. Usa la reversión instantánea de Vercel. Si estás implementando en Vercel, cada despliegue es inmutable. Puedes revertir a cualquier despliegue anterior en menos de 10 segundos desde el panel. Netlify ofrece lo mismo.

3. Nunca ejecutes migraciones de base de datos desde Claude Code directamente. Si Claude genera un archivo de migración, revísalo manualmente antes de ejecutar npx supabase db push o npx prisma migrate deploy. Una columna eliminada no es algo que puedas revertir con un git revert.

4. Etiqueta estados conocidos-buenos. Antes de comenzar una sesión de Claude Code que toque rutas críticas (autenticación, pagos, modelos de datos), crea una etiqueta git: git tag pre-auth-refactor. Si las cosas van mal, git reset --hard pre-auth-refactor te devuelve.

5. Los despliegues de vista previa son obligatorios, no opcionales. Vercel y Netlify ambos crean despliegues de vista previa para cada PR. No fusiones a main sin hacer clic en la vista previa. Claude Code puede generar código que funciona localmente pero falla en producción debido a variables de entorno faltantes, incompatibilidades de tiempo de ejecución edge o violaciones de CSP.

Política de Seguridad de Contenidos para activos proxificados

Esto es especializado pero muerde duro cuando despliegas un sitio construido por diseñadores.

El componente <Image> de Next.js proxifica imágenes externas a través de /_next/image de forma predeterminada. Esto es excelente para optimización. Pero si tienes un encabezado de Política de Seguridad de Contenidos (y deberías), necesitas permitir explícitamente los dominios de los que tus imágenes provienen.

Claude Code configurará next.config.js con remotePatterns para optimización de imagen pero no agregará encabezados CSP. Cuando despliegas detrás de los encabezados de seguridad de Vercel o agregas los tuyos vía middleware, las imágenes externas se rompen silenciosamente -- se cargan localmente (donde CSP es a menudo lax) pero fallan en producción.

Aquí está el mínimo que necesitas en tu middleware o encabezados de next.config.js:

// middleware.ts
const cspHeader = `
  default-src 'self';
  script-src 'self' 'unsafe-eval' 'unsafe-inline';
  style-src 'self' 'unsafe-inline';
  img-src 'self' blob: data: https://tu-proyecto-supabase.supabase.co https://tu-cdn.com;
  font-src 'self';
  connect-src 'self' https://tu-proyecto-supabase.supabase.co;
  frame-ancestors 'none';
`;

Reemplaza 'unsafe-eval' y 'unsafe-inline' con nonces para endurecimiento de producción. El punto es: si Claude Code trae imágenes de Unsplash, Supabase Storage o cualquier CDN externo, y no agregas esos dominios a tu directiva CSP img-src, obtendrás imágenes rotas en producción sin errores de consola en desarrollo.

¿Cuándo realmente necesitas autenticación de administrador?

La guía de Nervegna cubre autenticación básica de usuario. Muchos proyectos construidos por diseñadores necesitan una interfaz de administrador -- una manera para el propietario del sitio o equipo de contenido de gestionar datos sin tocar la base de datos directamente.

La pregunta es: ¿cuándo necesitas autenticación de administrador como preocupación separada vs. simplemente usar el panel de Supabase?

NO necesitas autenticación de administrador personalizada cuando:

  • Eres la única persona que gestiona contenido
  • Tu cliente se siente cómodo usando el Editor de tabla de Supabase
  • El proyecto tiene menos de 3 tipos de contenido
  • Las actualizaciones suceden menos de una vez por semana

SÍ necesitas autenticación de administrador personalizada cuando:

  • Miembros del equipo no técnicos necesitan gestionar contenido
  • Necesitas flujos de trabajo de aprobación o estados de borrador/publicado
  • El proyecto tiene acceso basado en roles (editor vs. administrador vs. visualizador)
  • Estás gestionando contenido generado por el usuario que requiere moderación

Si necesitas autenticación de administrador, el enfoque más simple es una columna role en tu tabla profiles (que refleja auth.users) con un enum: 'user' | 'editor' | 'admin'. Luego agrega políticas RLS que verifiquen este rol:

CREATE POLICY "Los administradores pueden hacer cualquier cosa"
ON public.posts
FOR ALL
USING (
  EXISTS (
    SELECT 1 FROM public.profiles
    WHERE profiles.id = auth.uid()
    AND profiles.role = 'admin'
  )
);

Claude Code puede generar esto si lo solicitas específicamente. Sin la solicitud, usará como predeterminado políticas simples de auth.uid() = user_id que no tienen en cuenta el acceso de administrador. Terminarás con un administrador que no puede ver el contenido de otros usuarios.

El flujo de trabajo de Nervegna de definir requisitos en un archivo CLAUDE.md atrapería esto -- si piensas en incluir acceso basado en roles en tus requisitos. Agrega eso al archivo antes de empezar a construir.

Antes de hacer push a producción: la lista de verificación

Esto es lo que usamos en Social Animal antes de desplegar cualquier proyecto construido o significativamente asistido por herramientas de codificación de IA.

Base de datos y seguridad

  • RLS está habilitado en cada tabla en esquema public
  • Políticas RLS existen para SELECT, INSERT, UPDATE y DELETE en cada tabla
  • SUPABASE_SERVICE_ROLE_KEY solo se usa en código del lado del servidor (grep tu base de código: grep -r "SERVICE_ROLE" --include="*.ts" --include="*.tsx")
  • No hay cliente de Supabase creado con la clave de rol de servicio en ningún archivo que contenga 'use client'
  • Las migraciones de base de datos han sido revisadas manualmente
  • Las restricciones de clave foránea existen donde se espera
  • Los índices existen en columnas utilizadas en cláusulas WHERE y políticas RLS

Autenticación

  • @supabase/ssr se usa (no @supabase/auth-helpers-nextjs deprecado)
  • Funciones de creación de cliente separadas existen para contextos de navegador, servidor y middleware
  • Los URI de redirección de OAuth están configurados para dominio de producción Y dominios de despliegue de vista previa
  • La actualización de tokens se prueba (establece una expiración corta temporalmente y verifica que las sesiones sobrevivan)
  • Las rutas protegidas redirigen al inicio de sesión cuando la sesión está ausente
  • El cierre de sesión borra todas las cookies y el estado de sesión del lado del servidor

Administrador y roles

  • Si existen características de administrador, las verificaciones de rol suceden a nivel RLS (no solo ocultamiento de nivel UI)
  • Las rutas de administrador están protegidas por middleware, no solo renderizado condicional
  • El rol predeterminado para nuevos usuarios es el rol menos privilegiado

Despliegue y reversión

  • Las variables de entorno se establecen en la plataforma de despliegue
  • Existe una etiqueta git conocida-buena de antes de los últimos cambios asistidos por IA importante
  • El despliegue de vista previa ha sido probado haciendo clic a través de flujos principales
  • La reversión instantánea de Vercel/Netlify es entendida y documentada para el equipo
  • Las copias de seguridad de base de datos están habilitadas (el plan Supabase Pro incluye copias de seguridad diarias por $25/mes)

Seguridad de contenido y activos

  • Los encabezados CSP incluyen todos los dominios de imagen externa en img-src
  • Los encabezados CSP incluyen URL de proyecto Supabase en connect-src
  • next.config.js remotePatterns coincide con dominios CSP img-src
  • Las fuentes se alojan por cuenta propia o su CDN está en font-src
  • Sin contenido mixto (recursos HTTP en páginas HTTPS)

Calidad de código

  • El modo estricto de TypeScript está habilitado ("strict": true en tsconfig.json)
  • Sin @ts-ignore o tipos any que Claude Code agregó para suprimir errores
  • npm run build pasa sin advertencias (no solo npm run dev)
  • Los límites de error existen para componentes cliente que obtienen datos
  • Los estados de carga y error existen para operaciones asincrónicas

Desempeño

  • Las imágenes usan el componente Next.js <Image> con width y height o fill
  • Sin obtención de datos del lado del cliente para datos que podrían obtenerse en componentes de servidor
  • El tamaño del paquete ha sido verificado (npx next@latest build muestra tamaños de ruta)
  • La puntuación de Lighthouse está por encima de 90 para Desempeño (ejecuta en el despliegue de vista previa, no localhost)

Esta lista de verificación no es exhaustiva. Es el mínimo para un proyecto que toca Supabase, Next.js y código generado por IA.

FAQ

¿Claude Code es lo suficientemente bueno para que los diseñadores construyan aplicaciones de producción?

Claude Code es excelente para generar código funcional a partir de intención de diseño. Pero la preparación de producción requiere conocimiento de seguridad, autenticación e infraestructura que la herramienta no proporciona sin solicitud. Emparéjalo con una lista de verificación y revisión de código de alguien con experiencia en backend.

¿La guía de Nervegna funciona para proyectos más allá de prototipos?

El flujo de trabajo de Nervegna -- indicación centrada en contexto, construcción incremental, revisión iterativa -- escala bien. La brecha está en preocupaciones de producción como RLS, casos extremos de autenticación y estrategia de despliegue. Su enfoque es sólido; necesita suplementación para cualquier cosa orientada al usuario.

¿Debo usar Supabase o Prisma con Claude Code?

Usa la biblioteca cliente de Supabase si quieres cumplimiento de RLS a nivel de base de datos y estás comprometido con la plataforma Supabase. Usa Drizzle ORM si quieres portabilidad de base de datos y compatibilidad de tiempo de ejecución edge. Nos hemos alejado de Prisma para nuevos proyectos debido a limitaciones de edge.

¿Cómo prevengo que Claude Code use la clave de rol de servicio de Supabase en código cliente?

Agrega una regla explícita a tu archivo CLAUDE.md: "Nunca uses SUPABASE_SERVICE_ROLE_KEY en componentes cliente. Úsalo solo en acciones de servidor, rutas API o middleware." Claude Code respeta instrucciones a nivel de proyecto cuando se declaran claramente.

¿Cuál es la forma más barata de desplegar una aplicación Next.js generada por Claude Code?

El plan Hobby gratuito de Vercel soporta un despliegue de producción por proyecto. El nivel gratuito de Supabase incluye 2 proyectos con 500MB de base de datos y 1GB de almacenamiento de archivo. Costo total: $0/mes para sitios de bajo tráfico. Espera pasar a Vercel Pro ($20/mes) y Supabase Pro ($25/mes) una vez que tengas usuarios reales.

¿Con qué frecuencia Claude Code genera código con problemas de seguridad?

En nuestra experiencia, aproximadamente el 40% de las sesiones de Claude Code que involucran operaciones de base de datos producen código con al menos una brecha de RLS. No es malicioso -- la herramienta optimiza para código "funcional" y las violaciones de RLS no producen errores. Solo exponen datos silenciosamente. Siempre audita manualmente.