TL;DR

Implantamos 30+ projetos headless em 18 meses na Social Animal. Aproximadamente um terço da nossa entrada recente é trabalho de resgate de builds liderados por designers que enviaram demos mas quebraram em produção. O guia "Claude Code for Designers" de Michael Nervegna no Substack é legitimamente bom para prototipagem -- mas para antes de Row Level Security, atualização de token de autenticação, escolhas de abstração de banco de dados, rollback de deploy, Content Security Policy e autenticação de admin. Este artigo cobre essas lacunas. Se você está enviando para produção, você precisa delas.

Índice

O Que É Claude Code e Por Que Os Designers Estão Usando?

Claude Code é a ferramenta de codificação baseada em terminal do Anthropic que foi lançada no início de 2025. Ela é executada como @anthropic-ai/claude-code e requer Claude Pro ($20/mês) ou Team ($30/assento/mês) com acesso à API. Você escreve, edita e depura código através de linguagem natural no seu terminal.

Designers estão usando porque fecha a lacuna entre "Eu projetei isso no Figma" e "isso é um aplicativo Next.js funcionando." Diferentemente de v0 ou Bolt, Claude Code opera no seu sistema de arquivos real. Ele lê a estrutura do seu projeto, modifica arquivos, executa seu servidor dev e itera sobre a saída de erro. Para alguém que entende hierarquia de componentes mas não quer memorizar genéricos de TypeScript, isso é genuinamente útil.

Nervegna a posiciona como uma ferramenta que permite aos designers "pensar em sistemas" ao invés de sintaxe. Concordamos. Onde nos divergimos é no que acontece após o primeiro npm run dev ter sucesso.

O Que O Guia De Nervegna Acerta?

Nervegna acerta em três coisas que a maioria dos tutoriais de IA de codificação erra.

Primeiro: contexto do projeto. Ele recomenda alimentar Claude Code com um arquivo CLAUDE.md com suas convenções de projeto, stack de tecnologia e design tokens. Vimos Claude Code gerar utilitários Tailwind contra um projeto usando CSS Modules porque ninguém disse as convenções. Estabelecer contexto antes de escrever código é a abordagem certa.

Segundo: o loop iterativo. Prompt, revisão de saída, correção de rumo, repetição. Ele não trata Claude Code como um botão "descrever e enviar". Ele o trata como um parceiro de pareamento que precisa de supervisão. Esse é o modelo mental correto.

Terceiro: começar pequeno. Construir um único componente ou página antes de tentar scaffold completo da aplicação. Vimos designers fazer prompt "construa-me um dashboard SaaS completo com auth, billing e admin" em uma mensagem. O resultado é sempre uma bagunça. A abordagem incremental de Nervegna evita isso.

Onde o guia de Nervegna serve bem aos designers é na fase 0-para-protótipo. O problema é que protótipos se tornam código de produção, e é aí que as lacunas importam.

Onde O Guia Para?

A peça de Nervegna funciona para a fase de prototipagem. Ela não aborda preocupações que se tornam urgentes quando você conecta um banco de dados real, usuários reais e infraestrutura de deploy real.

O que está faltando:

  1. Row Level Security (RLS) -- Projetos Supabase gerados por Claude Code quase nunca têm políticas RLS corretas
  2. Handoff de autenticação -- a lacuna entre Supabase Auth em desenvolvimento e fluxos de produção com atualização de token, gerenciamento de sessão e manipulação de redirecionamento
  3. Decisões de abstração de banco de dados -- quando usar cliente Supabase diretamente vs. Prisma ou Drizzle ORM
  4. Estratégia de rollback de deploy -- o que acontece quando um commit de Claude Code quebra produção
  5. Content Security Policy -- especialmente para Next.js Image com ativos proxificados/externos
  6. Autenticação de admin -- quando você precisa de acesso baseado em função além de autenticação de usuário simples

Vamos abordar cada um.

Armadilhas De Row Level Security Que Claude Não Vai Detectar

Row Level Security é o mecanismo do Supabase para garantir que queries de banco de dados retornem apenas linhas que o usuário solicitante está autorizado a ver. Quando você cria uma tabela no Supabase, RLS está desabilitada por padrão. Qualquer usuário autenticado -- ou em algumas configurações, qualquer requisição anônima -- pode ler cada linha.

Quando Claude Code faz scaffold de um projeto Supabase, ele cria tabelas e escreve queries do lado do cliente. Às vezes adicionará políticas RLS se você pedir. Mas as políticas que gera frequentemente estão erradas de maneiras sutis.

Erros Comuns De RLS Em Código Gerado Por IA

Erro O Que Acontece Como Corrigir
Nenhum RLS habilitado Qualquer usuário autenticado lê todos os dados ALTER TABLE sua_tabela ENABLE ROW LEVEL SECURITY;
Política usa auth.uid() mas tabela não tem coluna user_id Política compila mas não corresponde a nenhuma linha, bloqueando todo acesso Adicione user_id UUID REFERENCES auth.users(id) e populate-a
Política SELECT existe mas sem políticas INSERT/UPDATE/DELETE Usuários podem ler mas não escrever seus próprios dados Crie políticas para cada operação separadamente
Política usa auth.role() = 'authenticated' apenas Qualquer usuário logado pode ver todas as linhas, não apenas as suas Adicione condição auth.uid() = user_id
Chave de role de serviço usada em código do lado do cliente RLS é completamente contornada Nunca exponha SUPABASE_SERVICE_ROLE_KEY em bundles do cliente

Vimos aquela última -- chave de role de serviço em código do cliente -- em três projetos construídos por designers separados este ano. Claude Code às vezes usará a chave de role de serviço porque "funciona" e não lança erros de permissão. Essa chave contorna todas as RLS. Ela pertence apenas a código do lado do servidor (rotas de API, ações de servidor, funções edge). Nunca em um componente use client.

Nervegna não cobre RLS em seu guia, o que é compreensível. Mas se você estiver seguindo seu workflow e conectando ao Supabase, verifique cada tabela manualmente. Execute isto no editor SQL do Supabase:

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

Se rowsecurity for false para qualquer tabela que contenha dados de usuário, pare e corrija antes de fazer deploy.

Handoff De Autenticação: A Lacuna Entre Protótipo E Produção

Auth é o ponto de falha mais comum em builds liderados por designers. Não porque a configuração inicial está errada -- Supabase Auth é fácil de fazer scaffold -- mas porque auth de produção envolve casos extremos que não aparecem durante desenvolvimento local.

O guia de Nervegna se concentra em fazer as coisas funcionarem localmente. Aqui está o que quebra quando você faz deploy:

Falhas De Atualização De Token

Tokens de autenticação do Supabase expiram após 3600 segundos (1 hora) por padrão. O cliente Supabase trata atualização automaticamente -- em teoria. Na prática, se seu middleware Next.js ou componentes de servidor criarem um novo cliente Supabase em cada requisição sem passar a sessão existente, você terá erros intermitentes 401 após a primeira hora.

Com Next.js App Router, você precisa de @supabase/ssr (versão 0.5.x em fevereiro de 2025) e manipulação de cookie apropriada em middleware. Claude Code frequentemente gera o pacote antigo e descontinuado @supabase/auth-helpers-nextjs. Verifique seu package.json.

Incompatibilidades De Redirect URI

Provedores de OAuth (Google, GitHub) requerem URIs de redirecionamento exatos. Claude Code configura estes para localhost:3000. Quando você faz deploy para Vercel ou Netlify, você precisa adicionar sua URL de produção e qualquer URL de deployment de preview tanto ao console do provedor de OAuth quanto às configurações de Auth do Supabase sob "Redirect URLs." Isso leva 5 minutos mas bloqueia 100% dos logins OAuth se você perder.

O Problema De Sincronização De Sessão

Em Next.js 14+, você tem componentes de servidor, componentes de cliente, middleware, rotas de API e ações de servidor -- potencialmente todos precisando da sessão de usuário atual. O cliente Supabase deve ser criado diferentemente em cada contexto. Claude Code frequentemente cria uma única utilidade createClient() e a usa em todo lugar, o que causa incompatibilidades de hidratação e sessões obsoletas.

Você precisa no mínimo de três funções de criação de cliente:

  • createBrowserClient() para componentes de cliente
  • createServerClient() para componentes de servidor e ações de servidor
  • createMiddlewareClient() para middleware

Isto está documentado no guia SSR do Supabase mas Claude Code não gera consistentemente corretamente.

Supabase vs Prisma: Qual Claude Code Deveria Gerar?

Nervegna não aborda esta decisão, e ela importa mais do que a maioria dos designers percebe.

Cliente Supabase (@supabase/supabase-js) queries o banco de dados através da API PostgREST do Supabase. É conveniente, não requer arquivos de definição de schema, e funciona diretamente com RLS. Mas oferece nenhuma type safety além do que Supabase gera, e acopla fortemente sua aplicação à infraestrutura do Supabase.

Prisma ORM (atualmente v6.x) conecta diretamente a PostgreSQL. Oferece um arquivo de schema (schema.prisma), tipos TypeScript gerados, migrations, e queries agnósticas de banco de dados. Mas não respeita políticas RLS (conecta como usuário privilegiado), e requer um passo de build para gerar o cliente.

Drizzle ORM (v0.36.x) é uma alternativa mais leve com sintaxe parecida com SQL e melhor suporte a edge runtime.

Matriz De Decisão

Fator Cliente Supabase Prisma Drizzle
Suporte a RLS Nativo Deve implementar em camada de app Deve implementar em camada de app
Type safety Gerado via CLI Gerado de schema Schema-como-código
Compatível com edge runtime Sim Limitado (Prisma Accelerate requerido) Sim
Curva de aprendizado para designers Baixa Média Média
Vendor lock-in Alto (Supabase) Baixo Baixo
Qualidade de geração de Claude Code Boa Boa Inconsistente

Nossa recomendação: se você está construindo um protótipo ou sempre executará no Supabase, use o cliente Supabase. Se você precisar sair do Supabase ou quer desenvolvimento orientado por schema estrito, use Drizzle. Nos afastamos de Prisma para novos projetos devido a limitações de edge runtime, embora Prisma Accelerate ($0 para 60K queries/mês, depois $49/mês) tenha melhorado isto.

Diga a Claude Code sua decisão explicitamente em seu arquivo CLAUDE.md. Se você não disser, ele misturará abordagens -- às vezes queryando via cliente Supabase, às vezes via ORM -- e você acabará com dois padrões diferentes de acesso a dados no mesmo projeto.

Deploy Rollback: O Que Acontece Quando Seu Código Gerado Por IA Quebra

O guia de Nervegna o orienta através da construção de features iterativamente. Ele não aborda o que acontece quando uma sessão de Claude Code gera um commit que passa em dev local mas quebra em produção.

Isto acontece mais frequentemente do que você esperaria. Claude Code pode modificar 15 arquivos em uma única resposta de prompt. Se você commitar isso como uma unidade e fazer deploy, rollback significa reverter todas as 15 mudanças -- mesmo se 13 estivessem bem.

Uma Estratégia Prática De Rollback

1. Commit após cada mudança lógica, não cada sessão de Claude Code. Se Claude modificar auth, UI, e schema de banco de dados em uma sessão, faça três commits separados.

2. Use rollback instantâneo do Vercel. Se você estiver fazendo deploy no Vercel, cada deployment é imutável. Você pode fazer rollback para qualquer deployment anterior em menos de 10 segundos a partir do dashboard. Netlify oferece o mesmo.

3. Nunca execute migrações de banco de dados do Claude Code diretamente. Se Claude gerar um arquivo de migration, revise-o manualmente antes de executar npx supabase db push ou npx prisma migrate deploy. Uma coluna descartada não é algo que você possa fazer rollback com um git revert.

4. Marque estados conhecidos-bons. Antes de iniciar uma sessão de Claude Code que toca caminhos críticos (auth, pagamentos, modelos de dados), crie uma git tag: git tag pre-auth-refactor. Se as coisas derem errado, git reset --hard pre-auth-refactor o leva de volta.

5. Preview deployments são obrigatórios, não opcionais. Vercel e Netlify ambos criam preview deployments para cada PR. Não faça merge para main sem clicar no preview. Claude Code pode gerar código que funciona localmente mas falha em produção devido a variáveis de ambiente ausentes, incompatibilidades de edge runtime, ou violações de CSP.

Content Security Policy Para Ativos Proxificados

Isto é nicho mas morde duro quando você faz deploy de um site construído por designer.

O componente <Image> do Next.js proxifica imagens externas através de /_next/image por padrão. Isso é ótimo para otimização. Mas se você tem um cabeçalho Content Security Policy (e você deveria ter), você precisa explicitamente permitir os domínios de onde suas imagens vêm.

Claude Code fará setup de next.config.js com remotePatterns para otimização de imagem mas não adicionará cabeçalhos CSP. Quando você faz deploy atrás de cabeçalhos de segurança do Vercel ou adiciona os seus próprios via middleware, imagens externas quebram silenciosamente -- elas carregam localmente (onde CSP é frequentemente relaxado) mas falham em produção.

Aqui está o mínimo que você precisa em seu middleware ou cabeçalhos 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://seu-projeto-supabase.supabase.co https://seu-cdn.com;
  font-src 'self';
  connect-src 'self' https://seu-projeto-supabase.supabase.co;
  frame-ancestors 'none';
`;

Substitua 'unsafe-eval' e 'unsafe-inline' com nonces para hardening de produção. O ponto é: se Claude Code puxa imagens de Unsplash, Supabase Storage, ou qualquer CDN externo, e você não adiciona esses domínios à sua diretiva img-src de CSP, você terá imagens quebradas em produção com zero erros de console em desenvolvimento.

Quando Você Realmente Precisa De Admin Auth?

O guia de Nervegna cobre autenticação básica de usuário. Muitos projetos construídos por designers precisam de uma interface de admin -- uma forma para o proprietário do site ou equipe de conteúdo gerenciar dados sem tocar o banco de dados diretamente.

A questão é: quando você precisa de auth de admin como preocupação separada versus apenas usar o dashboard do Supabase?

Você NÃO Precisa De Admin Auth Customizado Quando:

  • Você é a única pessoa gerenciando conteúdo
  • Seu cliente está confortável usando o Table Editor do Supabase
  • O projeto tem menos de 3 tipos de conteúdo
  • Atualizações acontecem menos de uma vez por semana

Você PRECISA De Admin Auth Customizado Quando:

  • Membros não-técnicos da equipe precisam gerenciar conteúdo
  • Você precisa de fluxos de aprovação ou estados draft/publish
  • O projeto tem acesso baseado em função (editor vs. admin vs. viewer)
  • Você está gerenciando conteúdo gerado pelo usuário que requer moderação

Se você precisar de admin auth, a abordagem mais simples é uma coluna role em sua tabela profiles (que espelha auth.users) com um enum: 'user' | 'editor' | 'admin'. Depois adicione políticas RLS que verificam este role:

CREATE POLICY "Admins podem fazer qualquer coisa"
ON public.posts
FOR ALL
USING (
  EXISTS (
    SELECT 1 FROM public.profiles
    WHERE profiles.id = auth.uid()
    AND profiles.role = 'admin'
  )
);

Claude Code pode gerar isto se você fazer prompt especificamente. Sem o prompt, ele usará como padrão políticas simples auth.uid() = user_id que não contabilizam acesso de admin. Você acabará com um admin que não pode ver o conteúdo de outros usuários.

O workflow de Nervegna de definir requisitos em um arquivo CLAUDE.md pegaria isto -- se você pensar em incluir acesso baseado em função em seus requisitos. Adicione ao arquivo antes de começar a construir.

Antes De Fazer Push Para Prod: O Checklist

Isto é o que usamos na Social Animal antes de fazer deploy de qualquer projeto construído ou significativamente assistido por ferramentas de codificação por IA.

Banco De Dados & Segurança

  • RLS está habilitado em cada tabela no schema public
  • Políticas RLS existem para SELECT, INSERT, UPDATE e DELETE em cada tabela
  • SUPABASE_SERVICE_ROLE_KEY é usado apenas em código do lado do servidor (grep seu codebase: grep -r "SERVICE_ROLE" --include="*.ts" --include="*.tsx")
  • Nenhum cliente Supabase é criado com a chave de role de serviço em qualquer arquivo contendo 'use client'
  • Migrações de banco de dados foram revisadas manualmente
  • Restrições de chave estrangeira existem onde esperado
  • Índices existem em colunas usadas em cláusulas WHERE e políticas RLS

Autenticação

  • @supabase/ssr é usado (não descontinuado @supabase/auth-helpers-nextjs)
  • Funções de criação de cliente separadas existem para contextos de navegador, servidor e middleware
  • URIs de redirecionamento de OAuth estão configuradas para domínio de produção E domínios de deployment de preview
  • Atualização de token é testada (defina uma expiração curta temporariamente e verifique se as sessões sobrevivem)
  • Rotas protegidas redirecionam para login quando a sessão está ausente
  • Logout limpa todos os cookies e estado de sessão do lado do servidor

Admin & Funções

  • Se features de admin existem, verificações de função acontecem no nível de RLS (não apenas ocultação em nível de UI)
  • Rotas de admin são protegidas por middleware, não apenas renderização condicional
  • Role padrão para novos usuários é o role menos privilegiado

Deployment & Rollback

  • Variáveis de ambiente estão definidas na plataforma de deployment
  • Uma git tag conhecida-boa existe antes das últimas mudanças principais assistidas por IA
  • Deployment de preview foi testado clicando através de fluxos principais
  • Rollback instantâneo do Vercel/Netlify é compreendido e documentado para a equipe
  • Backups de banco de dados estão habilitados (plano Supabase Pro inclui backups diários por $25/mês)

Segurança E Ativos De Conteúdo

  • Cabeçalhos CSP incluem todos os domínios de imagem externa em img-src
  • Cabeçalhos CSP incluem URL do projeto Supabase em connect-src
  • next.config.js remotePatterns corresponde aos domínios img-src de CSP
  • Fonts são auto-hospedadas ou seu CDN está em font-src
  • Nenhum conteúdo misto (recursos HTTP em páginas HTTPS)

Qualidade Do Código

  • Modo strict do TypeScript está habilitado ("strict": true em tsconfig.json)
  • Nenhum @ts-ignore ou tipos any que Claude Code adicionou para suprimir erros
  • npm run build passa sem warnings (não apenas npm run dev)
  • Limites de erro existem para componentes de cliente que buscam dados
  • Estados de carregamento e erro existem para operações assincronas

Performance

  • Imagens usam o componente <Image> do Next.js com width e height ou fill
  • Nenhuma busca de dados do lado do cliente para dados que poderiam ser buscados em componentes de servidor
  • Tamanho de bundle foi verificado (npx next@latest build mostra tamanhos de rota)
  • Score Lighthouse está acima de 90 para Performance (execute no deployment de preview, não localhost)

Este checklist não é exaustivo. É o mínimo para um projeto que toca Supabase, Next.js e código gerado por IA.

FAQ

Claude Code é bom o suficiente para designers construírem aplicativos de produção?

Claude Code é excelente para gerar código funcionando a partir de intenção de design. Mas prontidão de produção requer conhecimento de segurança, auth e infraestrutura que a ferramenta não fornece sem prompt. Combine com um checklist e revisão de código de alguém com experiência de backend.

O guia de Nervegna funciona para projetos além de protótipos?

O workflow de Nervegna -- prompting com foco em contexto, construção incremental, revisão iterativa -- escala bem. A lacuna está em preocupações de produção como RLS, casos extremos de auth e estratégia de deployment. Sua abordagem é sólida; ela precisa de suplementação para qualquer coisa voltada para o usuário.

Devo usar Supabase ou Prisma com Claude Code?

Use biblioteca de cliente do Supabase se quiser cumprimento de RLS no nível de banco de dados e você está comprometido com a plataforma Supabase. Use Drizzle ORM se quiser portabilidade de banco de dados e compatibilidade de edge runtime. Nos afastamos de Prisma para novos projetos devido a limitações de edge.

Como faço para impedir que Claude Code use a chave de role de serviço Supabase em código de cliente?

Adicione uma regra explícita ao seu arquivo CLAUDE.md: "Nunca use SUPABASE_SERVICE_ROLE_KEY em componentes de cliente. Use-o apenas em ações de servidor, rotas de API ou middleware." Claude Code respeita instruções em nível de projeto quando estão claramente declaradas.

Qual é a forma mais barata de fazer deploy de um aplicativo Next.js gerado por Claude Code?

Plano Hobby gratuito do Vercel suporta um deployment de produção por projeto. Tier gratuito do Supabase inclui 2 projetos com 500MB de banco de dados e 1GB de armazenamento de arquivo. Custo total: $0/mês para sites com pouco tráfego. Espere se mover para Vercel Pro ($20/mês) e Supabase Pro ($25/mês) uma vez que você tem usuários reais.

Quantas vezes Claude Code gera código com problemas de segurança?

Na nossa experiência, aproximadamente 40% das sessões de Claude Code envolvendo operações de banco de dados produzem código com pelo menos uma lacuna de RLS. Não é malicioso -- a ferramenta otimiza para código "funcionando", e violações de RLS não produzem erros. Elas apenas expõem dados silenciosamente. Sempre audite manualmente.