Claude Code do zero ao deploy — guia completo e real

Todo tutorial de "crie um site com IA em 10 minutos" mostra a parte que funciona. Ninguém mostra o contexto que precisou dar antes, os erros que quebraram o build no meio do caminho, ou as decisões de arquitetura que a IA tomou errado e precisaram ser corrigidas.

Esse guia é diferente. Você vai ver o processo completo — do diretório vazio ao site no ar — com as partes que os tutoriais cortam.

O que você vai construir

Um site em Next.js com as seguintes páginas: home, blog com lista de artigos, e uma página de contato. Deploy na Vercel. Tecnologias: Next.js 14, Tailwind CSS, conteúdo em Markdown.

Tempo real de trabalho: entre 3 e 5 horas na primeira vez. Depois que você entende o padrão, cai para menos de 2.

Antes de começar: o contexto que a IA precisa

O erro número um de quem usa Claude Code pela primeira vez é abrir o terminal e sair pedindo componentes sem dar contexto.

O Claude Code lê o diretório atual. Se o diretório está vazio, ele não sabe nada sobre o que você quer construir — vai inventar decisões de arquitetura, escolher bibliotecas que você não quer, estruturar pastas de um jeito que vai te dar trabalho depois.

O que funciona é dar o contexto antes de pedir qualquer coisa:

Vou construir um site pessoal com Next.js 14, App Router, e Tailwind CSS.
O site tem três páginas: home (com apresentação e links), blog (lista de artigos em MDX),
e contato (formulário simples). Deploy vai ser na Vercel.
Quero que o código seja limpo, sem dependências desnecessárias. 
Não use bibliotecas de UI externas — vamos fazer os componentes do zero com Tailwind.
Antes de criar qualquer arquivo, me mostre a estrutura de pastas que você vai usar.

Essa última instrução — "me mostre a estrutura antes de criar" — é crucial. A IA vai fazer escolhas. Você precisa validar essas escolhas antes de ter 30 arquivos criados numa estrutura errada.

Passo 1: Iniciar o projeto

npx create-next-app@latest meu-site
cd meu-site
claude

Quando o create-next-app perguntar sobre as opções, escolha:

TypeScript: Sim
ESLint: Sim
Tailwind CSS: Sim
src/ directory: Não (simplifica a estrutura)
App Router: Sim
Import alias: Não por enquanto

Com o projeto criado e o Claude Code aberto, envie o contexto que você escreveu antes de abrir a sessão. Não comece pedindo coisas — comece contextualizando.

Passo 2: Revisar o plano antes de executar

Depois de receber o contexto, o Claude vai propor uma estrutura. Algo parecido com:

app/
  page.tsx          (home)
  blog/
    page.tsx        (lista de posts)
    [slug]/
      page.tsx      (post individual)
  contato/
    page.tsx        (formulário)
components/
  Header.tsx
  Footer.tsx
  PostCard.tsx
content/
  posts/            (arquivos .mdx)
lib/
  posts.ts          (helpers para ler MDX)

Leia com atenção. Se alguma coisa não faz sentido para o seu projeto — uma pasta que você não vai usar, uma rota que não planejou — corrija aqui. É muito mais fácil ajustar o plano do que refatorar arquivos já criados.

Só depois de validar a estrutura, diga: "Ok, pode criar a estrutura de pastas e os arquivos base."

Passo 3: Criar os componentes principais

Com a estrutura pronta, a ordem que funciona melhor:

Header e Footer primeiro — são usados em todas as páginas, e erros aqui aparecem cedo
Layout global — o app/layout.tsx que envolve tudo
Página home — começo da experiência do usuário
Sistema de posts — helpers de leitura + listagem + post individual
Formulário de contato — costuma ser mais simples

Para cada componente, seja específico no pedido:

Ruim:

Cria o Header do site

Bom:

Cria o componente Header em components/Header.tsx.
Deve ter: logo com o nome do site à esquerda, links de navegação à direita
(Home, Blog, Contato). Em mobile, os links viram um menu hambúrguer simples.
Usa os tokens de cor do Tailwind — sem cores hardcoded. Fundo branco com borda inferior cinza claro.

A diferença de resultado entre as duas instruções é enorme.

Passo 4: Os erros que vão aparecer (e como resolver)

Não existe sessão de vibe coding sem erro. A questão não é se vai dar erro — é como você responde quando dá.

Erro mais comum 1: import não encontrado

Module not found: Can't resolve '@/lib/posts'

O Claude criou o arquivo em um caminho diferente do que importou, ou esqueceu de criar o arquivo de helpers. Mande o erro de volta:

Tá dando esse erro de import: [cole o erro completo aqui]
O arquivo lib/posts.ts foi criado? Se não, cria ele com as funções getPostBySlug e getAllPosts.

Erro mais comum 2: tipos TypeScript

Property 'x' does not exist on type 'y'

Mande o erro e o contexto do componente onde aconteceu. O Claude corrige. Não tente corrigir manualmente se você não domina TypeScript — é mais rápido deixar a IA consertar.

Erro mais comum 3: Tailwind não aplicando estilos

Geralmente é problema no tailwind.config.ts — o caminho para os arquivos não está coberto pelo content. Mande o arquivo de configuração e o Claude identifica.

O padrão que funciona para qualquer erro:

Estou com esse erro: [cole a mensagem de erro completa]
Acontece em: [nome do arquivo ou rota]
O que o arquivo relevante tem agora: [cole o código]

Contexto completo = solução mais rápida. Nunca mande só a mensagem de erro sem contexto — a IA vai tentar adivinhar e pode errar.

Passo 5: O sistema de posts em MDX

Esse é o ponto onde a maioria trava. Ler arquivos .mdx em Next.js tem mais peças do que parece.

Peça assim:

Preciso de um sistema para ler posts em MDX do diretório content/posts/.
Cada post tem frontmatter com: title, date, slug, excerpt.
Preciso de duas funções em lib/posts.ts:
1. getAllPosts() — retorna lista de posts ordenada por data (mais recente primeiro)
2. getPostBySlug(slug) — retorna o conteúdo completo de um post

Para renderizar MDX, usa o pacote next-mdx-remote.
Me mostra o package.json atualizado com as dependências necessárias.

Ao pedir as dependências antes, você evita o ciclo de instalar, ver erro, instalar outra coisa, ver outro erro.

Crie um post de teste antes de avançar:

---
title: "Post de teste"
slug: "post-teste"
date: "2026-07-08"
excerpt: "Primeiro post para testar o sistema"
---

Esse é o conteúdo do post.

Se a listagem funciona e o post renderiza, o sistema está correto. Só aí siga para os outros componentes.

Passo 6: Preparar para o deploy

Antes de subir para a Vercel, algumas verificações:

Build local primeiro:

npm run build

Se der erro no build local, vai dar erro no deploy também. É muito mais fácil debugar localmente do que no painel da Vercel.

Erros comuns de build:

Componente que usa window ou localStorage sem verificar se está no browser
Imagem importada sem o alt correto
Rota dinâmica sem o generateStaticParams quando necessário

Para cada um, cole o erro no Claude Code e ele resolve.

Variáveis de ambiente: Se o projeto usa alguma chave de API (no formulário de contato, por exemplo), crie o arquivo .env.local agora e certifique de que ele está no .gitignore. Nunca suba chaves para o repositório.

Passo 7: Deploy na Vercel

Com o build passando localmente:

Faça o push do projeto para um repositório no GitHub
Acesse vercel.com e conecte o repositório
A Vercel detecta Next.js automaticamente — não precisa configurar nada
Clique em Deploy

Em 2 a 3 minutos o site está no ar.

Se você tem variáveis de ambiente, adicione-as no painel da Vercel antes do primeiro deploy: Settings > Environment Variables.

Para deploys futuros: Qualquer push para a branch main dispara um build automático na Vercel. Você não precisa fazer nada manualmente — o Claude Code faz o commit, você faz o push, a Vercel cuida do resto.

O que ninguém te conta sobre vibe coding na prática

A IA não tem memória entre sessões por padrão. Se você fechar o Claude Code e abrir de novo, ele leu o código mas não sabe o que foi decidido na sessão anterior. O arquivo CLAUDE.md na raiz do projeto resolve isso — coloque lá as decisões de arquitetura, padrões que quer manter, e coisas que a IA não deve alterar.

Sessões longas pioram. Depois de muitas trocas, o contexto acumula e a qualidade das respostas cai. Use /compact para comprimir o histórico ou abra uma sessão nova quando mudar de tarefa.

Revisar é parte do trabalho. O vibe coding não elimina a necessidade de ler o que foi criado. Você não precisa entender cada linha de código, mas precisa entender o que cada componente faz e por que está ali. Componente que você não entende é componente que você não sabe manter.

Erros são o progresso. Um erro de build não significa que a abordagem está errada. Significa que tem um detalhe para corrigir. Cole o erro, explique o contexto, deixe a IA resolver. Na maioria dos casos, o problema está resolvido em menos de 5 minutos.

Resultado: o que você tem ao final

Site Next.js funcionando com roteamento por arquivo
Blog com sistema de posts em MDX, fácil de adicionar novos artigos
Formulário de contato funcional
Deploy automático na Vercel a cada push
Base de código que você entende o suficiente para manter

O tempo total depende da sua familiaridade com a ferramenta. Na primeira vez, espere 3 a 5 horas de trabalho real. Da segunda vez em diante, você vai mais rápido — porque já sabe como dar o contexto certo, como ler os erros, e o que pedir antes de o problema aparecer.

Isso é vibe coding na prática: não é 10 minutos, mas também não é 3 semanas. É um meio-termo produtivo que coloca sites reais no ar sem exigir anos de experiência técnica.

Claude Code na prática: criando um site completo do zero ao deploy