HUB TECNOLOGIA
MANUAL TÉCNICO COMPLETO • CONTEÚDO INTEGRAL DA MASTERCLASS (NÃO É RESUMO)

Claude Code: Guia Completo do Zero ao Deploy em Produção

Manual prático e definitivo da metodologia ensinada por Renato Asse: aprenda a construir uma aplicação web profissional com Next.js, Supabase, consumo de APIs em tempo real e publicação na Vercel através de comandos no terminal com a CLI do Claude Code.

Duração da Masterclass: 3h 15min (195 min)
Stack Arquitetural: Next.js + Supabase
Infraestrutura: Vercel (CI/CD)
Nível & Metodologia: Vibe Coding & Specs
Módulo 01 • Fundamentos

1. O Conceito de Vibe Coding & A Diferença entre Chat e CLI

A maioria dos desenvolvedores usa inteligência artificial colando blocos de código em janelas de chat como ChatGPT ou Claude Web. O Renato Asse demonstra logo no início da aula por que esse método tradicional é ineficiente e propenso a erros:

O Chat Tradicional (Gargalo)

  • • Você é o operador manual de "copiar e colar".
  • • O chat não tem acesso ao sistema de arquivos local.
  • • Não consegue rodar comandos, testes nem checar erros no terminal.
  • • O contexto se perde rapidamente em conversas longas.

A CLI do Claude Code (Autônomo)

  • • Opera direto no terminal da sua máquina.
  • • Lê, cria, edita e deleta arquivos com autonomia controlada.
  • • Executa comandos (npm install, builds, git, migrações).
  • • Lê a saída de erro do terminal e se auto-corrige sozinho.

O termo Vibe Coding (popularizado por Andrej Karpathy e destrinchado pelo Renato) não significa programar sem rigor. Pelo contrário: significa que o desenvolvedor assume o papel de Arquiteto de Software e Curador, focando na especificação funcional dos requisitos, enquanto a IA assume a digitação braçal da sintaxe.

Módulo 02 • Ambiente

2. Setup do Ambiente & Instalação Passo a Passo

Para rodar o Claude Code na sua máquina, são necessários três pré-requisitos essenciais: Node.js (versão 20 ou superior), Git instalado e uma chave de API da Anthropic (ou login corporativo).

Passo 2.1: Instalação Global da CLI

Abra seu terminal (PowerShell, Bash ou Zsh) e execute o comando oficial de instalação:

npm install -g @anthropic-ai/claude-code

Passo 2.2: Autenticação & Inicialização

Navegue até a pasta onde deseja criar o projeto e inicialize o agente:

claude

Na primeira execução, o Claude Code solicitará a autorização via navegador ou a inserção da sua chave ANTHROPIC_API_KEY. Concluído o login, o terminal assume a interface interativa do agente.

Módulo 03 • Engenharia de Contexto

3. O Arquivo Mestre: CLAUDE.md (A Chave de Ouro)

Este é o momento mais importante de toda a masterclass. O Renato Asse enfatiza: "Se você abrir o Claude Code e começar a pedir código sem criar o CLAUDE.md, você vai gastar tokens, ter alucinações e o código vai quebrar."

O Claude Code lê automaticamente qualquer arquivo chamado CLAUDE.md na raiz do projeto antes de cada ação. É nesse arquivo que você declara as regras invioláveis de arquitetura:

Arquivo: /CLAUDE.md Regras de Contexto
# DIRETRIZES TÉCNICAS DO PROJETO (CATÁLOGO DE FILMES)

## 1. STACK ARQUITETURAL
- Framework: Next.js 15 (App Router com TypeScript)
- Estilização: Tailwind CSS + Lucide Icons
- Banco de Dados & Auth: Supabase (PostgreSQL)
- API Externa: The Movie Database (TMDb API v3)
- Deploy: Vercel

## 2. REGRAS INVIOLÁVEIS DE CÓDIGO
- Sempre utilize Server Components para listagens e SEO.
- Utilize Client Components ('use client') apenas quando houver interatividade (modais, busca, estado).
- Nunca exponha chaves secretas (Service Role) no frontend. Utilize apenas variáveis NEXT_PUBLIC_ anonimizadas.
- Todas as chamadas para a TMDb API devem ser tratadas em rotas seguras (/api/movies) ou Server Actions.

## 3. PADRÕES DE DESIGN
- Interface moderna em Dark Mode nativo (fundo escuro #0B0F17, cards #0F172A).
- Efeitos suaves de hover e transições em cards de filmes.
- Skeleton loading durante o carregamento de imagens e listas.
                    
Módulo 04 • Arquitetura

4. Arquitetura da Solução & Catálogo em Tempo Real

O aplicativo desenvolvido ao longo do treinamento é um portal completo de catálogo audiovisual com dados vivos. A arquitetura conecta 4 elementos essenciais:

[CLAUDE CODE CLI] (Terminal do Desenvolvedor)
       │
       ▼
[NEXT.JS 15 - APP ROUTER] (Frontend + Rotas de API)
       │
       ├──> [TMDb API] ────> Puxa filmes em cartaz, trailers oficiais e capas em HD
       │
       ├──> [SUPABASE] ────> PostgreSQL salva perfis, lista "Quero Assistir" e favoritos
       │
       └──> [VERCEL] ──────> Hospedagem com CDN global e HTTPS automático
                    
Por que essa arquitetura é poderosa? Você não gasta tempo criando painel de administração nem populando banco manualmente. A TMDb API fornece milhares de títulos atualizados diariamente de graça, enquanto o Supabase cuida da identidade do seu usuário.
Módulo 05 • Integração de APIs

5. Conexão com API Externa (The Movie Database - TMDb)

O Renato demonstra como cadastrar uma conta gratuita no themoviedb.org e gerar o API Read Access Token (v4 auth).

Em seguida, as credenciais são organizadas no arquivo .env.local:

# Credenciais da TMDb API
TMDB_API_KEY="seu_api_key_aqui"
TMDB_READ_TOKEN="seu_bearer_token_longo_aqui"

# Configuração de Imagens da TMDb
NEXT_PUBLIC_TMDB_IMAGE_BASE_URL="https://image.tmdb.org/t/p/w500"
                    

Os Endpoints Consumidos na Aplicação:

  • /movie/now_playing — Filmes atualmente em cartaz nos cinemas.
  • /trending/movie/week — Tendências e mais assistidos da semana.
  • /search/movie?query=... — Busca em tempo real com barra de pesquisa.
  • /movie/{id}/videos — Busca o trailer oficial no YouTube para o modal de exibição.
  • /movie/{id}/watch/providers — Mostra onde o filme está disponível (Netflix, Prime, Max, etc.).
Módulo 06 • Banco de Dados & Autenticação

6. Banco Relacional & Autenticação no Supabase (PostgreSQL)

Para que a aplicação não seja apenas uma vitrine estática, ela precisa de persistência: o usuário deve conseguir se cadastrar, fazer login e salvar seus filmes favoritos.

O Supabase foi escolhido por fornecer **PostgreSQL real**, autenticação nativa sem fricção e integração pronta via biblioteca oficial.

Script SQL das Tabelas (Executado no SQL Editor do Supabase):

-- 1. Criação da tabela de Favoritos
CREATE TABLE public.favorites (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE NOT NULL,
    movie_id INTEGER NOT NULL,
    title TEXT NOT NULL,
    poster_path TEXT,
    vote_average NUMERIC(3,1),
    created_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc'::text, now()) NOT NULL,
    UNIQUE(user_id, movie_id)
);

-- 2. Habilitação de Segurança em Nível de Linha (RLS)
ALTER TABLE public.favorites ENABLE ROW LEVEL SECURITY;

-- 3. Políticas de Acesso: Cada usuário só vê e altera seus próprios favoritos
CREATE POLICY "Usuários podem ver seus favoritos" 
ON public.favorites FOR SELECT 
USING (auth.uid() = user_id);

CREATE POLICY "Usuários podem adicionar favoritos" 
ON public.favorites FOR INSERT 
WITH CHECK (auth.uid() = user_id);

CREATE POLICY "Usuários podem remover favoritos" 
ON public.favorites FOR DELETE 
USING (auth.uid() = user_id);
                    

Essa política de Row Level Security (RLS) garante soberania e segurança total: mesmo que um usuário mal-intencionado tente alterar o `movie_id` de outro usuário pelo navegador, o PostgreSQL rejeita a operação a nível de banco.

Módulo 07 • Operação Prática

7. O Ciclo de Desenvolvimento Guiado por Terminal

Com as regras no `CLAUDE.md`, as chaves configuradas e o banco criado, o Renato mostra a dinâmica do **ciclo atômico de prompts**. Em vez de pedir: "Crie o site inteiro para mim", o segredo é fatiar em comandos específicos:

Etapa 1: Estrutura Base "Inicialize a home page consumindo os filmes em cartaz da TMDb API e exiba um grid de cards responsivo em Tailwind."
Etapa 2: Interatividade "Adicione uma barra de pesquisa com debounce de 300ms e filtros por categoria (Ação, Drama, Ficção)."
Etapa 3: Modal de Trailer "Ao clicar em um card, abra um modal trazendo a sinopse completa, notas e o trailer oficial incorporado do YouTube."
Etapa 4: Integração de Login "Conecte o Supabase Auth com modal de login por email e adicione o botão de favoritar nos cards salvando na tabela favorites."

Comandos Essenciais do Claude Code no Terminal:

/compact

Compacta o histórico da conversa, limpando tokens antigos para economizar custos e evitar degradação de raciocínio.

/clear

Reseta o contexto mantendo os arquivos intactos, ideal para iniciar uma nova funcionalidade do zero.

/cost

Mostra em tempo real o gasto em dólares da sessão atual na API da Anthropic.

Shift + Enter

Permite criar prompts com quebras de linha para enviar especificações detalhadas.

Módulo 08 • Deploy & Produção

8. Deploy Contínuo na Vercel & Resolução dos Erros Mais Comuns

Na fase final da aula, o projeto é publicado em produção para que qualquer pessoa na internet possa acessar.

Passo a Passo do Deploy:

  1. Pedir ao Claude Code para rodar o build local: npm run build e corrigir qualquer erro de tipagem no TypeScript.
  2. Inicializar o Git e enviar o código para um repositório no GitHub: git commit -m "feat: complete movie catalog".
  3. Acessar o painel da **Vercel** (vercel.com) e importar o repositório.
  4. Configurar as variáveis de ambiente na Vercel (TMDB_READ_TOKEN, NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY).
  5. Clicar em **Deploy**. Em menos de 2 minutos, o aplicativo está ao vivo com CDN global e HTTPS ativo.

Os 3 Erros Mais Comuns de Iniciantes (E Como Resolver):

1. Erro: "Image domain not allowed in next/image"

Acontece quando você tenta exibir as capas dos filmes usando o componente <Image> do Next.js sem autorizar o domínio da TMDb.

Solução: Adicionar `image.tmdb.org` em `images.remotePatterns` no arquivo `next.config.ts`.

2. Erro: "Hydration failed because the initial UI does not match"

Ocorre quando dados dinâmicos do usuário (como o estado de autenticação ou localStorage) são renderizados no servidor antes de carregar no navegador.

Solução: Usar `useEffect` ou checagem de montagem (`mounted`) antes de exibir componentes interativos dependentes de cliente.

3. Erro: "new row violates row-level security policy for table favorites"

O usuário tenta favoritar um filme sem estar autenticado ou a política de RLS não possui a cláusula correta de INSERT.

Solução: Validar se a sessão do usuário existe (`auth.uid()`) antes de disparar o INSERT e garantir que a policy do Supabase esteja ativa.

Síntese da Metodologia

A grande virada de chave demonstrada por Renato Asse nesta aula é que o desenvolvedor moderno não precisa ser um digitador de código. Ao dominar a Engenharia de Contexto, regras claras no CLAUDE.md e ferramentas de infraestrutura soberana como Supabase e Next.js, qualquer pessoa com visão arquitetural é capaz de lançar softwares completos em horas no lugar de meses.