Do primeiro prompt ao app no ar.

O que você vê (FRONTEND)

Quando você clica em "Comprar" em um site, você está navegando numa loja online. Vê produtos bonitos, preços, fotos. Clica no botão "Adicionar ao Carrinho". O botão muda de cor, aparece um carrinho balançando. Tudo isso acontece na sua tela, no seu navegador.

Essa parte visual — tudo que você VÊ e CLICA — se chama frontend. É tipo a vitrine de uma loja física. Fica no SEU computador ou celular, funciona no navegador (Chrome, Safari, etc).

O frontend é feito com 3 tecnologias fundamentais.

• O HTML cria a estrutura e define onde fica cada elemento da página.
• O CSS cuida da parte visual, determinando cores, tamanhos e fontes.
• E o JavaScript adiciona interatividade, fazendo as coisas acontecerem quando você clica em botões ou preenche formulários.

Mas o frontend sozinho não faz muita coisa útil. Ele é só visual. Quando você clica em "Comprar", precisa acontecer algo de verdade: salvar seu pedido, cobrar no cartão, enviar email. Isso acontece em outro lugar…

O que acontece nos bastidores (BACKEND)

Quando você clica em "Comprar", o botão no frontend manda um "pedido" pela internet. Tipo mandar uma carta: "Ei, o usuário João Silva quer comprar o produto X, cartão final 1234". Essa carta viaja pela internet e chega num servidor — um computador potente que fica ligado 24 horas por dia em algum datacenter. Nesse servidor roda o backend, que é a parte que faz o trabalho pesado.

O backend recebe o pedido e faz uma série de verificações. Ele confere se o usuário está logado, se o produto tem em estoque, se o cartão é válido. Depois disso, ele processa o pagamento, desconta do estoque, salva o pedido no banco de dados, manda email de confirmação e responde pro frontend dizendo se deu tudo certo ou se houve algum erro.

Pensa no backend como a cozinha de um restaurante. O cliente (frontend) não entra lá, mas é onde a comida (dados) é preparada. O backend pode ser feito em várias linguagens de programação. Eu uso Ruby no sistema principal, mas também existe Node.js que é JavaScript rodando no servidor, além de outras opções como Python, PHP e Java.

Onde os dados ficam guardados (BANCO DE DADOS)

Quando você faz um pedido, precisa guardar isso em algum lugar pra não esquecer, né? É aqui que entra o banco de dados. Pensa num arquivo gigante do Excel, mas muito mais poderoso. Ele tem várias "planilhas" diferentes. Uma planilha guarda os usuários com nome, email, senha e endereço. Outra planilha guarda os produtos com nome, preço e estoque. E tem uma planilha de pedidos que registra quem comprou o quê, quando e quanto pagou.

Existem dois tipos principais de banco de dados. Os bancos SQL funcionam como planilhas mesmo, com dados organizados em tabelas com linhas e colunas. O PostgreSQL é um exemplo e é o que vamos usar. Já os bancos NoSQL funcionam mais como uma pasta de documentos. O MongoDB é um exemplo — bom quando os dados mudam muito de formato.

Juntando tudo: o fluxo completo

Então quando você clica em "Comprar", acontece um fluxo completo:

1. Frontend (seu navegador) manda o pedido pro Backend
2. Backend processa, verifica tudo e salva no Banco de Dados
3. Backend responde pro Frontend dizendo "Tudo certo!"
4. Frontend mostra a mensagem "✓ Compra realizada com sucesso!"

O problema

Você precisa trabalhar em código com outras pessoas. Todo mundo mexendo nos mesmos arquivos. Como não virar bagunça? Como voltar atrás se quebrar algo? Como saber quem mudou o quê? É pra isso que existe versionamento.

Repositório: onde o código mora

Um repositório (ou "repo" pra abreviar) é a pasta que contém todo o seu projeto. Além de ter todos os arquivos, ele também armazena todo o histórico de mudanças que já foram feitas nela. O repositório existe em dois lugares.

O repositório local fica no seu PC ou Mac. É onde você trabalha e edita arquivos. Só você consegue ver o que está acontecendo nele. Se seu computador quebrar, você perde tudo, por isso precisa de backup.

Já o repositório remoto fica na nuvem, normalmente no GitHub, GitLab ou Bitbucket. Todo o time consegue acessar. Ele serve como backup e é o "ponto de encontro" do time, onde todos sincronizam suas mudanças.

Git e GitHub: as ferramentas

Muita gente confunde Git com GitHub. São coisas diferentes que trabalham juntas.

O que é Git

Git é um programa que você instala no seu computador. Ele é um "sistema de controle de versão", o que significa que ele guarda o histórico de tudo que você faz no código. O Git registra toda mudança que você faz, permite voltar atrás como um Ctrl+Z infinito, possibilita trabalho em equipe com várias pessoas no mesmo projeto sem conflito, cria branches para trabalhar em funcionalidades paralelas e mostra exatamente quem mudou o quê, garantindo rastreabilidade total.

O que é GitHub

GitHub é um site (github.com) onde você guarda repositórios Git na nuvem. É tipo Google Drive ou Dropbox, mas feito especialmente pra código. O GitHub oferece armazenamento de código na nuvem com backup automático, uma interface visual para ver código, histórico e branches sem precisar usar o terminal, ferramentas de colaboração como Pull Requests, revisão de código e comentários, um sistema de Issues para gerenciar bugs e tarefas, e funciona como seu perfil profissional, criando um portfólio do seu código.

Branch: trabalhando sem quebrar o código oficial

Imagina que o código do site tá funcionando perfeitamente em produção (no ar). Você precisa adicionar uma funcionalidade nova. Mas enquanto você tá desenvolvendo, vai quebrar coisas, fazer testes, bagunçar. Se você trabalhar direto no código que tá no ar, os usuários vão ver o site quebrado.

A solução é criar uma cópia paralela do código. Você trabalha nessa cópia e quando terminar e tudo tiver funcionando, aí sim você junta de volta no código oficial. Essa cópia paralela é uma branch.

A main é a branch principal — o código que está funcionando em produção. Não é uma boa prática mexer aqui direto, porque qualquer mudança mal sucedida pode fazer seu site cair.

A sua-branch é sua cópia para trabalhar. Aqui você pode quebrar à vontade, porque seu cliente não vê e não está usando. Quando você terminar, você junta ("merge") sua branch na main.

Por convenção, as branches seguem padrões de nomes. Você usa feature/nome para funcionalidades novas, fix/nome para corrigir bugs e hotfix/nome para correção urgente em produção.

Commit: salvando mudanças no histórico

Para salvar mudanças no histórico do Git, você faz um commit, que é tipo "tirar uma foto do projeto naquele momento e guardar num álbum".

Cada commit registra as mudanças que foram feitas, tem uma mensagem explicando o que mudou, guarda a data e hora e identifica quem fez. Se precisar voltar atrás por algum motivo, você consegue voltar para um commit anterior.

Push e Pull: sincronizando com o GitHub

Você fez commits no seu computador. Mas esses commits ainda não estão no GitHub.

Tão só no seu computador.

Push: empurrando pro GitHub

Push significa "empurrar". Você está empurrando seus commits do seu computador pra nuvem (GitHub).

Quando fazer push:

• Você fez vários commits e quer salvar no GitHub (backup)
• Quer que outras pessoas vejam suas mudanças
• Terminou o dia de trabalho (sempre faça push antes de desligar o PC)

Pull: puxando do GitHub

Pull significa "puxar". Você está puxando as mudanças que estão no GitHub pro seu computador.

Quando fazer pull:

• Antes de começar a trabalhar (pra ter a versão mais nova)
• Quando alguém do time te avisar que fez mudanças importantes
• Antes de fazer push (pra evitar conflitos)

Pull Request: pedindo pra juntar seu código

Você trabalhou na sua branch. Fez vários commits. Testou tudo. Tá funcionando. Agora você quer que essas mudanças entrem no código oficial (branch main). Mas você não junta direto. Você abre um Pull Request (PR) no GitHub. É literalmente um "pedido" para alguém revisar e depois puxar suas mudanças para main.

Por que não juntar direto? Porque o Pull Request permite revisão de código antes de juntar as mudanças. Outra pessoa olha seu código, o que evita bugs que você não viu. É também uma oportunidade de aprendizado, já que você recebe feedback pra melhorar. Além disso, fica registrado o que mudou e por quê, criando documentação.

Por que existem três ambientes?

Pensa assim: quando um mecânico vai consertar um carro, ele não faz o teste no carro do cliente enquanto ele está sendo usado. Ele testa num ambiente controlado, verifica que está tudo certo, e só então devolve o carro funcionando.

No desenvolvimento de software é a mesma lógica. Você não mexe diretamente no site que os usuários estão usando agora. Você trabalha numa cópia, testa nessa cópia, e só quando estiver tudo certo você sobe para o site real.

Sem essa separação, qualquer erro que você comete vai direto para produção. Os usuários veem o site quebrado, os dados podem ser corrompidos, e você fica consertando incêndio em vez de construir.

Os três ambientes

Local — seu laboratório particular

É o ambiente que roda no seu próprio computador. Ninguém mais vê. Você pode quebrar à vontade, testar ideias malucas, reverter tudo, recomeçar do zero.

• Só você acessa — nenhum usuário, nenhum colega vê o que está acontecendo aqui
• Qualquer mudança no código aparece instantaneamente no navegador
• Os erros aparecem direto no terminal — fácil de debugar
• O banco de dados é seu, isolado, cheio de dados de teste
• Se você deletar tudo, só você perde — nenhum usuário é afetado

Staging — o ensaio geral

É um servidor real na internet, mas que só o time interno acessa. Pensa como um ensaio de teatro — tudo igual ao espetáculo de verdade, mas sem o público.

• Tem uma URL própria (ex: meu-app-staging.herokuapp.com)
• O time inteiro pode acessar para testar e validar
• O banco de dados é separado do production — dados de teste, não dados reais
• Se quebrar aqui, tudo bem — nenhum usuário foi afetado
• Deploy automático a cada push — o que você sobe aparece aqui em minutos

Staging existe para pegar os bugs que você não viu no local. Às vezes algo funciona perfeitamente no seu computador mas quebra no servidor por causa de configuração diferente, variável de ambiente errada, ou dado que existe em produção mas não no local.

Production — o site real

É o ambiente que os usuários reais acessam. Aqui vivem os dados reais — cadastros, pedidos, pagamentos, tudo.

• Qualquer usuário com acesso ao site está vendo esse ambiente
• Os dados aqui são reais e irreversíveis
• Um erro aqui tem consequência real — usuário que não consegue logar, pedido que não foi registrado
• Nunca faça experimentos diretamente aqui

Regra de ouro: nunca faça nada diretamente em production sem ter testado em staging primeiro. Sem exceção.

Como identificar em qual ambiente você está

Pela URL

• Se tem -staging, -dev, -test ou localhost é staging ou local
• Se é o domínio limpo (ex: meu-dominio.com) é production
• Se começa com http://localhost é local

Pelo Heroku

No dashboard do Heroku, a pipeline mostra claramente qual é qual. Staging fica na coluna do meio, production fica na última coluna à direita.

Por que os dados somem entre ambientes?

Essa é a pergunta que todo mundo faz pelo menos uma vez: "fiz um cadastro e sumiu". A resposta é simples: cada ambiente tem seu próprio banco de dados, completamente isolado dos outros.

O que você cadastra em local não aparece em staging. O que você cadastra em staging não aparece em production. Eles não se falam. Isso é intencional e bom:

• Você pode popular o banco de staging com dados de teste sem afetar os usuários reais
• Você pode rodar um reset completo do banco em staging sem perder nada de production
• Os dados reais dos usuários ficam protegidos — nenhum teste acidental os toca

Nunca copie dados reais de production para staging sem anonimizar primeiro. Dados pessoais de usuários não devem circular em ambientes de teste.

O que acontece se você pular o staging?

Tecnicamente você consegue. Mas é uma péssima ideia. Veja por quê:

1. Você não testou em ambiente de servidor real — só no seu computador
2. Pode ter uma variável de ambiente faltando que só aparece no servidor
3. Pode ter uma migration que quebra com dados reais que não existiam no seu banco local
4. Se der problema, você conserta em produção, na frente dos usuários, sob pressão

O staging existe exatamente para você descobrir esses problemas num ambiente seguro, sem consequência.

O fluxo correto

Local (desenvolve e testa no seu PC)
  ↓
Staging (testa no servidor, valida com o time)
  ↓  (só depois de tudo OK em staging)
Production (usuários reais)

Nunca pule etapas nesse fluxo. Staging não é burocracia — é proteção.

Erros comuns e o que causam

"Funcionou no meu computador mas quebrou em staging"

Normal. Pode ser diferença de versão de Ruby, variável de ambiente faltando, ou configuração de banco diferente. É para isso que staging existe — melhor descobrir aqui do que em production.

"Fiz um cadastro mas não aparece no site"

Você cadastrou em local ou staging, mas está olhando para production (ou vice-versa). Verifique a URL em que você estava quando cadastrou.

"O deploy foi mas o site ainda está igual"

Pode ser cache do navegador. Tenta Ctrl+Shift+R (hard refresh). Se persistir, verifica o build log no Heroku — o deploy pode ter falhado silenciosamente.

"Rodei uma migration mas o app continua quebrando"

Você rodou a migration localmente mas não rodou no Heroku. Toda migration nova precisa ser rodada manualmente no Heroku:

O que é Stack recomendada?

Se o seu projeto precisar conversar com um sistema que já existe, use a mesma stack dele, para que não tenha conflito durante o processo de implementação.

A stack nada mais é do que um conjunto de tecnologias utilizadas em um projeto, o que inclui quais as linguagens de programação serão utilizadas para backend e frontend, qual é o tipo de banco de dados recomendado e quais as gems (bibliotecas) que devemos colocar.

Qual stack eu uso?

• Framework: Ruby on Rails 7.2 (Rails Way)
• Banco de dados: PostgreSQL
• Frontend: Hotwire (Turbo + Stimulus)
• Componentes UI - gem de componentes do time
• CSS: Tailwind CSS (CDN)
• JavaScript: importmap-rails (sem build step)

O que é WSL?

WSL significa Windows Subsystem for Linux — ou, em português, Subsistema Windows para Linux. É uma funcionalidade do Windows que permite rodar um sistema Linux completo dentro do Windows, sem precisar de máquina virtual nem reiniciar o computador.

Pensa assim: o Windows e o Linux são sistemas operacionais diferentes, com linguagens diferentes pra se comunicar com o computador. A maioria das ferramentas de desenvolvimento (incluindo Ruby e Rails) foi feita pra rodar em Linux/Unix. O WSL cria uma "janela" pra você usar essas ferramentas no Windows sem abrir mão do seu sistema principal.

Você precisa do WSL?

• Sim, se: você usa Windows E vai trabalhar em projetos Ruby on Rails .
• Não, se: você usa Mac — o macOS já é baseado em Unix, não precisa de WSL.
• Não, se: você vai trabalhar apenas com Next.js, Node.js ou React — essas stacks rodam bem no Windows direto.

Instalando WSL

Abra o VSCode com Antigravity (ou a ferramenta de IA que você usa) e, no modo Chat, use este prompt:

Preciso instalar WSL no Windows para trabalhar com projetos Ruby on Rails.

Me guia passo a passo:
1. Como instalar WSL 2 com Ubuntu
2. Configuração inicial (criar usuário e senha)
3. Onde vou trabalhar com meus projetos (estrutura de pastas)
4. Diferença entre arquivos do Windows (/mnt/c/) e arquivos do Linux

Explica cada passo de forma clara.

Conectando o VSCode/Antigravity com WSL

Depois de instalar o WSL, você vai precisar conectar seu editor de código nele. Isso é necessário pra você editar arquivos que estão dentro do WSL e rodar comandos no terminal do Linux.

Peça pra IA te ajudar:

Instalei WSL no Windows e agora preciso conectar o VSCode/Antigravity nele.

Me ajuda a:
1. Instalar a extensão Remote - WSL no editor
2. Conectar o editor no WSL
3. Abrir uma pasta que está dentro do WSL (/home/meu-usuario/projetos)
4. Verificar se o terminal do editor tá usando o Linux (Ubuntu)

Explica passo a passo.

O que é uma IDE?

IDE significa Integrated Development Environment — ou, em português, Ambiente de Desenvolvimento Integrado. É o programa que você usa pra escrever e rodar código. Pensa como o "Google Docs do código": um lugar onde tudo que você precisa pra criar um projeto fica junto — o editor de texto, o terminal (onde você roda comandos), o controle de versão (Git) e o chat com a IA.

as ferramentas que eu recomendo são baseadas no VS Code, editor open source da Microsoft, então a interface vai parecer familiar se você já usou qualquer uma delas.

IDEs vs. Modelos de IA: qual a diferença?

Essa é uma das confusões mais comuns pra quem tá começando. São coisas diferentes que trabalham juntas.

Modelos de IA

São os "cérebros" — os sistemas de inteligência artificial que entendem seu prompt e geram o código. Exemplos: Claude (da Anthropic), GPT-4 (da OpenAI), Gemini (do Google). Você não acessa um modelo diretamente pelo terminal — você acessa por dentro de uma ferramenta.

IDEs com IA (ferramentas)

São os programas que conectam o modelo de IA ao seu projeto. Elas leem os arquivos do seu repositório, mandam o contexto certo pro modelo, e aplicam as respostas direto no código. É aqui que o vibecoding acontece de fato.

A diferença prática: o modelo sabe escrever código, mas não sabe que arquivo editar, qual é a estrutura do seu projeto, ou como rodar um comando no terminal. A IDE cuida disso tudo.

Ferramentas que eu recomendo

VSCode

Editor open source da Microsoft, gratuito e disponível pra Mac, Windows e Linux. É a base de todas as outras ferramentas dessa lista. Por si só é apenas um editor de texto — a IA entra via extensões como o GitHub Copilot ou o Antigravity.

Antigravity (recomendado)

Extensão do VSCode com IA integrada. Grátis pra quem faz login com e-mail do trabalho. Você instala no próprio VSCode e já tem um chat com Claude disponível direto no editor, com acesso ao seu projeto. É a opção mais prática pra quem está começando.

TRAE (opção paga)

Editor desktop pago com IA integrada. Permite trocar de modelo (Claude, GPT, Gemini) sem sair do programa. Tem interface idêntica ao VSCode. Só vale a pena se você precisar de recursos avançados que o Antigravity não oferece.

Qual modelo escolher?

Dentro do Antigravity ou TRAE, você escolhe o modelo num dropdown no topo do chat. No Copilot, você escolhe o modelo nas configurações da extensão. A recomendação geral:

• Claude Sonnet: padrão pra maioria das tarefas. Rápido, bom em código e em seguir instruções.
• Claude Opus: mais poderoso, mas mais lento e caro. Use só pra problemas complexos que o Sonnet não resolve.
• GitHub Copilot: disponível pra quem tem licença da empresa. Integrado ao VSCode, bom pra completar código enquanto você escreve.
• Gemini (via CLI): bom pra automações e tarefas no terminal

O que é o Gemini CLI?

O Gemini CLI é uma ferramenta de linha de comando do Google que permite usar IA diretamente pelo terminal — sem abrir nenhuma interface gráfica, sem colar em chat. Você escreve um prompt no terminal e recebe a resposta ali mesmo.

É especialmente útil pra tarefas rápidas, automações e scripts onde você não quer sair do terminal pra abrir o VSCode com Antigravity, Copilot ou outra ferramenta de IA.

Instalando o Gemini CLI

Abra o terminal e rode o comando abaixo. Se estiver no PowerShell (Windows), use as aspas como mostrado:

PowerShell (Windows)

Terminal (Mac ou WSL)

Verifique se instalou corretamente:

Autenticando na primeira vez

Depois de instalar, rode:

Na primeira vez, vai aparecer uma tela pedindo autenticação. Escolha a opção de login com Google, vai abrir o navegador automáticamente. Faça login com sua conta do trabalho e pronto — não precisa configurar nada mais.

Use sua conta do trabalho, não uma conta pessoal.

Como usar

Dentro de qualquer pasta de projeto, você pode rodar:

Pra passar um arquivo específico como contexto:

Pra abrir uma sessao interativa (tipo um chat no terminal):

Usando skills com o Gemini CLI

Crie um arquivo GEMINI.md na raiz do projeto com as instruções da skill. O Gemini vai ler esse arquivo automáticamente toda vez que for rodado dentro daquela pasta.

O arquivo de contexto do Gemini CLI se chama GEMINI.md (sem ponto na frente) — diferente do .CLAUDE e .AGENTS usados no TRAE e Antigravity.

A lógica dos três bancos

Assim como você tem três ambientes (local, staging, production), você tem três bancos de dados — um pra cada ambiente. Eles são completamente isolados. O que você faz no banco local não afeta o staging. O que você faz no staging não afeta a production.

Isso é intencional: você testá com dados falsos localmente, valida com dados de teste em staging, e só aí os dados reais dos usuários ficam em production, protegidos.

Banco local: Docker + PostgreSQL

No seu computador de desenvolvimento, você vai rodar o banco dentro de um container Docker. Docker é uma ferramenta que cria ambientes isolados e portáteis — assim o banco roda igual em qualquer máquina, sem conflito com outros programas.

Instalando Docker

Baixe e instale o Docker Desktop em docker.com/products/docker-desktop. Depois de instalar, abra o Docker Desktop e deixe rodando em segundo plano (você vai ver o ícone da baleia na barra de tarefas).

Configurando o banco local

Na raiz do seu projeto, crie (ou verifique se já existe) um arquivo docker-compose.yml. Se não existir, use este prompt:

Preciso configurar PostgreSQL local com Docker para o projeto.

Me ajuda a:
1. Criar arquivo docker-compose.yml com PostgreSQL 15
2. Configurar o arquivo de conexão com o banco (database.yml ou .env)
3. Comandos para subir/parar o banco
4. Criar o banco e rodar migrations

Pra subir o banco depois de configurado:

Pra parar: docker-compose down. Pra verificar se tá rodando: docker ps.

Banco em Staging: Heroku Postgres

No staging, o banco fica no próprio Heroku como um add-on. Veja a seção Heroku para o passo a passo de como adicionar o Heroku Postgres ao seu app de staging.

A variável DATABASE_URL é criada automáticamente pelo Heroku quando você adiciona o PostgreSQL. Você não precisa configurar nada manualmente.

O banco de staging deve ter dados de teste, não dados reais. Nunca copie o banco de production pra staging sem anonimizar os dados.

Banco em Production: Heroku Postgres (separado)

Igual ao staging, mas é um banco diferente, com dados reais. Configure seguindo os mesmos passos da seção Heroku, no app de production.

NUNCA rode rails db:reset ou db:drop em production. Esses comandos apagam todos os dados sem confirmação. Em production, use apenas rails db:migrate.

Passo 1: Planeje antes de abrir o editor

Antes de abrir a IDE, faça o planejamento (Etapas 1-4 da metodologia):

• Entenda o problema
• Defina o escopo
• Desenhe a arquitetura
• Quebre em tarefas pequenas
• Salve tudo em docs/feature-nome.md

Tempo: 30-60 minutos de planejamento. Parece muito? Vai economizar 3-4 horas de refazer código depois.

Passo 2: Crie a branch

Agora sim, abre o VSCode com Antigravity (ou a ferramenta de IA que você usa).

Prompt (Chat mode):

Baseado neste plano:
[cola docs/feature-nome.md]

Cria uma branch apropriada seguindo o padrão feature/nome-em-kebab-case

IA vai sugerir nome e executar:

Passo 3: Implemente tarefa por tarefa

3a. Implementar (Build mode)

CONTEXTO:
[cola docs/feature-nome.md]

TAREFA ATUAL:
Tarefa #1: [descrição da tarefa]

Implementa essa tarefa.

###

3b. Testar manualmente

Abre o navegador, testá se funcionou. Se quebrou algo:

Deu esse erro:
[cola o erro]

Resolve.

###

3c. Escrever testes (opcional mas recomendado)

Se o projeto tem testes configurados:

Escreve testes para a tarefa que acabei de implementar:
[descreve o que fez]

Cobre:
- Fluxo normal (happy path)
- Entradas inválidas (sad path)

IA escreve e roda os testes. Se algum falhar, ela mesma corrige.

3d. Fazer commit

Terminei a tarefa #1: [descrição].

Faz commit com mensagem apropriada:
- feat: para funcionalidade nova
- fix: para correção
- Presente do indicativo, primeira letra maiúscula

IA cria o commit. Importante: Um commit por tarefa. Não junta tudo num commit gigante.

3e. Repetir para todas as tarefas

Vai fazendo tarefa por tarefa. Implementa → testá → commit → próxima tarefa.

Passo 4: Revisão antes de abrir PR

Quando terminar todas as tarefas do H1:

Prompt (Chat mode):

Terminei de implementar a feature.

Antes de abrir o PR, preciso que você:

1. Revise o código procurando:
   - Problemas de segurança
   - Edge cases não tratados
   - Código duplicado ou confuso
   - console.log ou debugs esquecidos

2. Gere um roteiro de teste manual para eu validar cada fluxo:
   - O que precisa existir antes (pré-condição)
   - Passos exatos para testar
   - Resultado esperado
   - O que pode ter quebrado (regressão)

IA vai: analisar o código e sugerir melhorias, criar checklist de teste manual. Você testá tudo localmente.

Se encontrar problemas: volta pro Passo 3, corrige, testa, commita.

Se tudo OK: avança pro Passo 5.

Passo 5: Push e abrir PR

Push da branch

Faz push da branch pro GitHub.

Abrir Pull Request

Abre um Pull Request para essa branch.

O PR precisa ter:
- Título no formato: tipo: Descrição clara em português
- Corpo explicando:
  - O que essa feature faz (contexto)
  - Decisões técnicas relevantes (por que fiz assim)
  - O que tem mais risco (onde focar a revisão)
  - Roteiro de teste para o revisor

Cria como draft.

IA vai: gerar título e corpo do PR, criar PR no GitHub como rascunho, te dar o link.

Passo 6: Acompanhar revisão

Alguém do time vai revisar seu PR. Pode pedir mudanças.

Se pedir mudanças

1. Faz as mudanças solicitadas (Passo 3 de novo)
2. Commita
3. Push (atualiza o PR automáticamente)
4. Responde os comentários do revisor

Se aprovar

1. Faz merge no GitHub
2. Deploy automático pro staging
3. Testá em staging
4. Se tudo OK, promove pra production

Resumo do fluxo completo

O que é OAuth?

OAuth é o que está por trás do botão "Entrar com Google" que você vê em vários sites. Em vez de criar um usuário e senha novos, o usuário clica nesse botão, o Google confirma quem ele é, e devolve pro app uma confirmação: "sim, essa pessoa é quem ela diz ser".

Pra quem desenvolve, OAuth é vantajoso porque você não precisa guardar senhas (menos responsabilidade), o login é mais fácil pro usuário (um clique) e o Google cuida da segurança da autenticação.

A lógica das chaves por ambiente

O ponto que mais confunde quem configura OAuth pela primeira vez é este: você precisa de um par de chaves diferente para cada ambiente. Local, staging e production são apps separados do ponto de vista do Google.

Pensa assim: o Google precisa saber exatamente quais endereços têm permissão de usar seu OAuth. Se você liberar só o endereço de production, o login vai funcionar lá mas vai dar erro no seu computador local e em staging. Por isso você configura três vezes — uma pra cada ambiente.

Regra prática: nunca copie chaves de production pra staging, nem de staging pro local. Cada ambiente tem suas chaves próprias.

Como configurar no Google Cloud

Você vai precisar acessar o Google Cloud Console (console.cloud.google.com) pra criar as credenciais. Se nunca acessou, peça ajuda a alguém do time técnico na primeira vez.

O fluxo geral é:

1. Criar um projeto no Google Cloud pra representar seu app
2. Configurar a "Tela de Consentimento" — é o que o usuário vê quando clica em "Entrar com Google"
3. Gerar as credenciais (Client ID e Client Secret) — uma vez pra cada ambiente
4. Adicionar as URLs do seu app em cada credencial (local, staging e production)

Se quiser fazer esse setup com ajuda da IA, use este prompt:

Preciso configurar OAuth do Google no meu projeto.

Tenho 3 ambientes:
- Local: http://localhost:3000
- Staging: https://meu-app-staging.herokuapp.com
- Production: https://meu-dominio.com

Me guia passo a passo pelo Google Cloud Console:
1. Criar o projeto
2. Configurar a tela de consentimento
3. Gerar as credenciais pra cada ambiente
4. Quais URLs adicionar em cada uma

Onde colocar as chaves no seu projeto

Depois de gerar as credenciais no Google Cloud, você vai ter para cada ambiente um Client ID e um Client Secret. Eles precisam ser colocados como variáveis de ambiente — nunca direto no código.

• Local: crie um arquivo .env.local na raiz do projeto e adicione as chaves do ambiente local
• Staging: adicione as chaves de staging nas Config Vars do app de staging no Heroku
• Production: adicione as chaves de production nas Config Vars do app de production no Heroku

Se travar, use este prompt:

Preciso configurar OAuth do Google no Heroku.

URL do app: [cola a URL do seu app]
Ja tenho o Client ID e Client Secret.

Me mostra como:
1. Adicionar as variáveis no Heroku (Config Vars)
2. Quais outras variáveis preciso configurar
3. Como testar se funcionou

Quando o OAuth quebra em staging

É muito comum o login funcionar local mas dar erro em staging. As causas mais comuns são:

• As chaves de staging não foram adicionadas nas Config Vars do Heroku
• A URL do app de staging não foi cadastrada no Google Cloud como URL autorizada
• A variavel NEXTAUTH_URL (ou equivalente) está apontando pra URL errada

Quando isso acontecer, cole o erro que aparece no console do Heroku e pergunte pra IA:

Meu OAuth do Google ta dando erro em staging.

O erro é: [cola o erro]
URL do app de staging: [cola a URL]

O que pode estar errado?

##

Por que revisar PR é importante?

Quando alguém abre um PR, está pedindo um segundo par de olhos antes de juntar o código na branch principal. Revisar PR não é só caçar bugs — é garantir que o que foi feito faz sentido, que os fluxos funcionam como deveriam, e que nada quebrou no caminho.

Você não precisa ser dev experiente para revisar. Você precisa entender o que a funcionalidade deveria fazer e testar se ela faz isso.

Antes de começar: use a skill review-pr

A skill review-pr do repositório do time foi feita exatamente para esse momento. Ela lê o PR e transforma o que precisa ser testado em um roteiro de ações concretas.

Abra o Antigravity ou VSCode com IA e cole esse prompt:

Preciso revisar esse Pull Request:
[cola o link do PR do GitHub]

Gera:
1. Um roteiro de teste manual com passos exatos
   (onde clicar, o que preencher, o que deve aparecer)
2. Um resumo do que foi alterado e por que
3. Pontos de atenção onde posso focar a revisão

O fluxo completo de revisão

Passo 1: Entenda o que o PR faz

Antes de testar qualquer coisa, leia o título e a descrição do PR no GitHub. Um bom PR tem:

• O que foi implementado (contexto)
• Por que foi feito assim (decisões técnicas)
• Onde focar a revisão (o que tem mais risco)
• Um roteiro de teste para o revisor

Se a descrição estiver vaga, peça mais contexto antes de revisar. É mais rápido perguntar agora do que testar no escuro.

Passo 2: Suba a branch localmente

###

###

Não sabe qual é o nome da branch? Está no topo do PR no GitHub, logo abaixo do título.

Se preferir testar em staging (mais fácil), o Heroku cria automaticamente um Review App para cada PR aberto. Acesse pelo dashboard do Heroku na coluna "Review Apps".

Passo 3: Execute o roteiro de testes

Com o app rodando, siga o roteiro que a IA gerou. Para cada fluxo:

1. Teste o caminho normal (happy path) — o fluxo funcionando como deveria
2. Teste os erros (sad path) — o que acontece quando você preenche errado, deixa campo vazio
3. Teste casos extremos — nome com caracteres especiais, valor zero, campo gigante
4. Verifique se algo que funcionava antes parou de funcionar (regressão)

Passo 4: Documente o que encontrou

No GitHub, você pode deixar comentários diretamente no código ou no corpo do PR:

• Bloqueante: algo que impede o merge. Ex: "O botão de salvar não funciona, dá erro 500"
• Sugestão: melhoria que vale fazer mas não bloqueia. Ex: "Essa mensagem de erro poderia ser mais clara"
• Nitpick: detalhe menor, opcional. Ex: "Esse espaçamento ficou um pouco estranho"
• Aprovação: se tudo estiver OK, aprova o PR diretamente no GitHub

Passo 5: Aprove ou solicite mudanças

1. No PR do GitHub, clique na aba "Files changed"
2. Clique em "Review changes" no canto superior direito
3. Escolha: Approve (tudo OK) ou Request changes (tem coisa para corrigir)
4. Escreva um resumo do que testou e o que encontrou
5. Clique em "Submit review"

Sempre escreva o que você testou, mesmo quando está aprovando. Isso cria um histórico e ajuda quem vai manter o código depois.

O que olhar além dos testes funcionais

Segurança

• A funcionalidade expõe dados que não deveria? (ex: um usuário vendo dados de outro)
• Tem campo de texto que aceita qualquer coisa? (risco de XSS ou injeção)
• A autenticação está sendo verificada em todos os pontos?

UX e interface

• Os estados de loading aparecem enquanto carrega?
• O que aparece quando a lista está vazia?
• As mensagens de erro fazem sentido para o usuário?

Dados

• Alguma migration foi adicionada? Se sim, foi rodada em staging?
• Dados existentes foram afetados pela mudança?

Quando você não é tech: o que fazer

Mesmo sem saber ler código, você consegue fazer uma revisão muito útil focando em:

• Testar todos os fluxos descritos no roteiro
• Verificar se o comportamento corresponde ao que foi prometido
• Confirmar que nada que funcionava antes parou de funcionar
• Avaliar se a experiência do usuário faz sentido

O que nunca pode ir para o GitHub

O GitHub é público (ou compartilhado com o time). Algumas informações nunca podem estar num repositório:

• Senhas de banco de dados
• Tokens de API (Google, Stripe, SendGrid, etc.)
• Chaves OAuth (Client ID e Client Secret)
• Chaves de criptografia e secrets
• Credenciais de serviços externos

Se uma dessas informações foi para o GitHub — mesmo que por 30 segundos — considere que ela está comprometida. Revogue e gere uma nova imediatamente.

O arquivo .env

O arquivo .env é onde você guarda essas configurações sensíveis localmente. Ele fica na raiz do projeto e nunca é enviado para o GitHub.

Um .env típico parece assim:

Cada linha é uma variável de ambiente no formato NOME=valor. O código lê essas variáveis em vez de ter os valores escritos diretamente nele.

O arquivo .env.example

Todo projeto bem organizado tem um arquivo .env.example que mostra quais variáveis existem, mas sem os valores reais:

Esse arquivo pode ir para o GitHub — ele não tem valores, só os nomes. Quando alguém clona o projeto pela primeira vez, copia o .env.example para .env e preenche com os valores reais.

O arquivo .gitignore

O .gitignore diz ao Git quais arquivos ignorar e nunca rastrear. Todo projeto deve ter o .env listado aqui.

Um .gitignore básico para Rails inclui:

Se o .env estiver no .gitignore, o Git vai ignorá-lo completamente. Você nunca vai subir por acidente.

Como verificar se está protegido

Antes de fazer qualquer commit, rode:

Se .env aparecer listado, ele NÃO está no .gitignore e está prestes a ser commitado. Pare. Adicione-o primeiro.

E se eu subir por acidente?

1. NÃO tente apagar o commit — o histórico fica
2. Chame alguém do time técnico imediatamente
3. Revogue todas as credenciais que estavam no arquivo (gere novas chaves)
4. Depois de revogar, o time técnico vai limpar o histórico do Git

A ordem importa: primeiro revogue as credenciais, depois limpe o histórico. Limpar sem revogar não resolve — alguém já pode ter copiado.

Boas práticas do dia a dia

• Nunca copie um .env de produção para o seu computador — use os valores de staging para desenvolvimento local
• Nunca compartilhe o conteúdo do .env por Slack ou email — use um gerenciador de senhas compartilhado
• Toda vez que alguém sai do time, as credenciais que ela tinha acesso devem ser rotacionadas
• Nunca salve credenciais diretamente no código, mesmo que seja temporário

Credencial no código é uma das vulnerabilidades mais comuns e mais evitáveis. A skill vibesec do repositório do time checa isso automaticamente antes de cada commit.

Conceitos básicos do Heroku

O que é um App no Heroku

Um app no Heroku é um container ou espaço onde seu código vai rodar. Pensa assim: seu código é como um programa que você desenvolveu. O app do Heroku é como um computador dedicado pra rodar esse programa.

Cada app tem um nome único (ex: meu-projeto-staging), uma URL própria (ex: https://meu-projeto-staging.herokuapp.com), recursos próprios de memória e processamento (dynos), variáveis de ambiente próprias (Config Vars) pra senhas e configurações, banco de dados próprio (se você adicionar PostgreSQL) e conexão com uma branch específica do GitHub.

O que é uma Pipeline

Uma pipeline no Heroku é uma forma de conectar vários apps que fazem parte do mesmo projeto. Ela organiza seus apps em um fluxo lógico de desenvolvimento.

Uma pipeline típica tem 3 ambientes: Review (apps temporários criados automáticamente pra cada Pull Request), Staging (ambiente de testes onde você valida antes de ir pra produção) e Production (site real onde os usuários finais acessam).

A pipeline fácilita muito o trabalho porque permite promover código de staging pra production com um clique, garante que o código testado em staging é EXATAMENTE o mesmo que vai pra production e organiza visualmente o fluxo staging → production.

O que são Dynos

No Heroku, o termo dyno é como chamamos o "container" que roda seu código. Pensa num dyno como um mini-computador virtual dedicado só pro seu app.

O Heroku oferece diferentes planos de dynos:

• Eco ($5/mês por conta): ideal pra começar. O dyno "dorme" depois de 30 minutos sem requisições e demora cerca de 10 segundos pra acordar. Perfeito pra staging e projetos pessoais.
• Basic ($7/mês por app): nunca dorme, responde imediatamente. Tem SSL automático (HTTPS). Ideal pra apps pequenos em produção.
• Standard ($25-$50/mês por dyno): mais memória e CPU, permite autoscaling automático. Ideal pra apps com tráfego médio.
• Performance ($250-$500/mês por dyno): alto poder de processamento. Pra apps enterprise com alto tráfego.

Criando a Pipeline do Zero

Criando a Pipeline

1. Faça login no Heroku (heroku.com)
2. No dashboard do Heroku, clique em "New" → "Create new pipeline"
3. Dê um nome pra pipeline (ex: meu-projeto ou meu-app)
4. Em "Connect to GitHub", conecte com seu repositório
5. Clique em "Create pipeline"

Pronto! Sua pipeline foi criada. Você vai ver uma tela com três colunas vazias: Review, Staging e Production.

Criando o app de Staging

Na sua pipeline, na coluna "Staging":

1. Clique em "Add app..."
2. Escolha "Create new app..."
3. Dê um nome pro app (ex: meu-projeto-staging). O nome precisa ser único no Heroku inteiro.
4. Escolha região: "United States" ou "Europe"
5. Clique em "Create app"

Pronto! Agora toda vez que você fizer git push origin staging, o Heroku vai fazer deploy automáticamente.

Adicionando banco de dados no Staging

1. No app de staging, vá na aba "Resources"
2. Na seção "Add-ons", digite postgres na busca
3. Clique em "Heroku Postgres"
4. Selecione o plano "Essential 0" (é grátis até certo limite)
5. Clique em "Submit Order Form"

O Heroku vai criar um banco PostgreSQL completo e vazio, e adicionar automáticamente a variável DATABASE_URL nas Config Vars. Você não precisa configurar manualmente.

Configurando variáveis de ambiente (Config Vars) no Staging

⚠️ Importante: antes de cadastrar as VARs no heroku, pergunte para a IA que estiver usando no seu projeto quais as VARs devem ser cadastradas. Elas mudam de projeto para projeto. Depois que você tiver todas em mãos, siga o passo a passo indicado abaixo.

1. No app de staging, vá na aba "Settings"
2. Procure a seção "Config Vars"
3. Clique em "Reveal Config Vars"
4. Você vai ver DATABASE_URL já criada pelo Postgres

Para cada variável que precisar adicionar: clique em "Add", coloque o nome em KEY e o valor em VALUE, aperte Enter. O Heroku reinicia o app automáticamente pra aplicar as mudanças.

Fazendo deploy e testando o Staging

Preciso fazer deploy do projeto no Heroku staging.

Me mostra como:
1. Fazer push pra branch staging (se configurei deploy automático) OU
2. Fazer deploy manual pelo dashboard do Heroku

Depois me mostra como acompanhar o progresso do deploy.

Quando o deploy terminar, clique em "Open app" (canto superior direito do Heroku). Teste tudo: cadastro, login, funcionalidades principais. Isso é ambiente de TESTES, então pode quebrar à vontade. Dados aqui não são reais.

Criando o app de Production

Na sua pipeline, na coluna "Production":

1. Clique em "Add app..." → "Create new app..."
2. Dê um nome pro app (ex: meu-projeto ou meu-app). NÃO use "-production" no nome.
3. Escolha a mesma região que você escolheu pro staging
4. Clique em "Create app"

No app de production, vá na aba "Deploy" e configure deploy automático pra branch main.

Repita os MESMOS passos do staging pra configurar banco, vars e migrations. MAS:

CRÍTICO: Cada variável de PRODUCTION deve ser DIFERENTE da de STAGING! Secrets → gere NOVOS valores. NEXTAUTH_URL → use a URL de production. Chaves de API → use chaves REAIS de produção. NÃO rode seeds em production!

Configurando domínio customizado (apenas Production)

No app de production:

1. Vá na aba "Settings" → role até "Domains" → clique em "Add domain"
2. Digite seu domínio (ex: app.meu-dominio.com) e salve
3. O Heroku vai te mostrar um DNS Target (ex: magical-unicorn-xyz123.herokudns.com). Copie esse valor.
4. Passe o DNS Target pra pessoa que gerencia o DNS do domínio. Ela precisa criar um registro CNAME apontando pra esse endereço.
5. Aguarde 10-30 minutos e verifique o SSL em "Refresh ACM Status".

Usando Promote to Production (fluxo do dia a dia)

Quando tudo tiver OK em staging:

1. Vá na sua Pipeline no dashboard do Heroku
2. Na coluna "Staging", clique no botão "Promote to production..."
3. Confirme

Pronto! O Heroku vai copiar EXATAMENTE o que tá rodando em staging pra production. É o mesmo código, a mesma versão, sem surpresas.

NUNCA faça merge direto na main sem passar por staging primeiro! O fluxo correto é sempre: feature → staging (testa) → promote → production

Usando uma Pipeline que já existe

Se o projeto que você está trabalhando JÁ tem Heroku configurado (caso mais comum), você não precisa criar pipeline, staging, production, banco de dados, etc. O fluxo normal é:

1. Trabalha no código localmente
2. Faz commits e push pra branch
3. Deploy automático acontece no staging
4. Testá em staging
5. Faz merge na main (via Pull Request)
6. Deploy automático acontece no production (ou usa "Promote to production")

Preciso fazer deploy das minhas mudanças no Heroku.

Projeto: [nome-do-projeto]

Me mostra como:
1. Fazer push pra branch staging
2. Verificar se o deploy automático tá funcionando
3. Acessar o app em staging pra testar
4. Se tiver ok, como promover pra production

Você está vibecodando, subiu uma feature em staging, abriu no navegador — e algo não funcionou. A página ficou em branco, o botão não salvou, o login deu erro. O que você faz?

A resposta está no DevTools: um conjunto de ferramentas que todo navegador moderno tem embutido e que mostra exatamente o que está acontecendo por baixo do capô. Não precisa saber programar pra usar. Precisa saber onde olhar.

Este guia te ensina isso.

Como abrir o DevTools

Em qualquer navegador (Chrome, Edge, Firefox, Safari), clique com botão direito em qualquer local da tela e selecione ‘Inspecionar’ ou use os atalhos:

O DevTools vai abrir — geralmente do lado direito ou embaixo da página. Você pode arrastar pra mudar a posição.

Visão geral das abas

O DevTools tem várias abas no topo. A maioria você nunca vai precisar. As que importam pra vibecodar são:

Para o dia a dia de vibecoding, você vai viver entre Console e Network. Elements aparece quando algo visual está errado. Application quando login ou dados estranhos acontecem.

Console: onde os erros aparecem

O Console é sua primeira parada quando algo dá errado. É aqui que o JavaScript grita quando quebra.

Como interpretar as mensagens

Cada mensagem tem uma cor que indica o tipo:

• Vermelho (erro): algo quebrou. Leia com atenção — geralmente diz o arquivo, a linha e o motivo.
• Amarelo (aviso): algo suspeito mas que não quebrou ainda. Pode ignorar se a página funcionar normal.
• Azul/branco (info): mensagem de debug que o desenvolvedor deixou de propósito. Pode ignorar.

Erros mais comuns e o que significam

Cannot read properties of undefined

O código tentou acessar uma propriedade de algo que não existe. Tipo tentar abrir a gaveta de uma mesa que não tem gaveta. O que fazer: cola o erro no chat da IA:

Console mostrando esse erro: "Cannot read properties of undefined"

Erro completo: [cola o erro]
Página: [descreve o que você estava tentando fazer]

O que pode estar errado?

404 Not Found / Failed to fetch

A página tentou buscar um dado ou arquivo que não existe. Pode ser uma API offline, uma URL errada, ou um recurso que foi movido. O que fazer: vá pra aba Network (próxima seção) pra ver qual requisição falhou.

CORS error

O navegador bloqueou uma requisição por questão de segurança — acontece quando o frontend tenta chamar uma API de outro domínio sem permissão. O que fazer: é um problema de configuração no backend. Cola o erro pra IA:

Deu erro de CORS no console:
[cola o erro completo]

Frontend rodando em: [URL do frontend]
API sendo chamada em: [URL da API]

Como resolver?

Uncaught SyntaxError

Tem um erro de sintaxe no código JavaScript — uma vírgula faltando, um parêntese que não fechou. Geralmente indica que um deploy foi feito com código quebrado.

401 Unauthorized / 403 Forbidden

A requisição foi feita mas o servidor recusou. 401 significa que o usuário não está autenticado (não fez login). 403 significa que está autenticado mas não tem permissão pra aquilo.

Como usar o Console pra debugar

Além de ver erros, você pode digitar comandos no Console pra investigar o estado da página. Útil quando algo parece estranho:

// Ver o que está no localStorage (dados salvos no navegador)
localStorage

// Ver os cookies da página
document.cookie

// Ver o tamanho da janela atual
window.innerWidth + 'x' + window.innerHeight

Não sabe o que digitar? Descreve o que quer investigar pra IA e ela te dá o comando.

Filtrar mensagens

Quando o Console está cheio de mensagens, use o campo de busca (ícone de lupa) ou os botões de filtro: Errors, Warnings, Info. Marque só Errors pra focar no que importa.

Network: rastreando requisições

O Network mostra tudo que a página baixa e envia: HTML, CSS, JavaScript, imagens, chamadas de API. É aqui que você descobre se uma API está falhando, se um dado não está chegando, ou se algo está demorando demais.

Como usar

1. Abra o DevTools e clique na aba Network
2. Recarregue a página (Ctrl+R ou Cmd+R) — as requisições só aparecem depois que o Network está aberto
3. Você vai ver uma lista de tudo que foi carregado

Entendendo a lista de requisições

Cada linha é uma requisição. As colunas mais importantes:

Códigos de status que você vai ver

• 200 OK — funcionou.
• 201 Created — funcionou e criou algo (comum em posts de formulário).
• 304 Not Modified — o navegador usou o cache. Normal.
• 400 Bad Request — o dado enviado estava errado ou incompleto.
• 401 Unauthorized — usuário não está logado.
• 403 Forbidden — usuário não tem permissão.
• 404 Not Found — o endpoint ou arquivo não existe.
• 422 Unprocessable — dado enviado não passou nas validações do servidor.
• 500 Internal Server Error — o servidor quebrou. Veja os logs do Heroku.
• 502 / 503 — o servidor está fora do ar ou sendo reiniciado.

Inspecionando uma requisição

Clique em qualquer linha da lista pra ver os detalhes. Um painel abre do lado. As abas que mais importam:

• Headers: mostra os cabeçalhos da requisição. Aqui você vê a URL exata que foi chamada, o método (GET, POST, etc) e o código de status.
• Payload (ou Request): mostra o dado que foi enviado pra API. Útil pra confirmar se o formulário está mandando os campos certos.
• Response: mostra o que o servidor respondeu. Se deu erro, geralmente tem uma mensagem aqui explicando o motivo.
• Preview: versão formatada da resposta. Mais fácil de ler que o Response bruto.

Filtrar por tipo de requisição

Quando a lista tem muita coisa, use os filtros no topo: Fetch/XHR mostra só as chamadas de API (o que você quer na maioria das vezes). Doc mostra o HTML. Img mostra imagens.

Caso prático: botão que não salva

Você clicou em Salvar mas nada aconteceu. Veja no Network:

1. Abra o Network antes de clicar no botão
2. Clique no botão
3. Veja se apareceu uma nova linha na lista
4. Se não apareceu nada: o problema é no frontend — o clique não está disparando a requisição. Cola o erro do Console pra IA.
5. Se apareceu com status 4xx ou 5xx: clique na linha e veja o Response — geralmente tem uma mensagem de erro explicando o motivo.
6. Se apareceu com status 200 mas não funcionou: o problema é em como o frontend está interpretando a resposta.

Caso prático: página lenta

Clique na coluna Time pra ordenar por tempo. A requisição mais lenta vai aparecer no topo. Isso te diz se o problema é:

• Uma imagem grande que está sendo baixada sem compressão
• Uma API que demora pra responder (latência do servidor)
• Muitos recursos sendo carregados em sequência

Copie o nome do endpoint mais lento e pergunte pra IA como otimizar.

Elements: inspecionando o visual

A aba Elements mostra o HTML e CSS da página em tempo real. Útil quando algo está na posição errada, invisível, com cor errada, ou com tamanho quebrado.

Como abrir no elemento certo

Em vez de navegar pelo HTML manualmente, clique com o botão direito no elemento que está com problema na página e escolha Inspecionar. O DevTools vai abrir direto naquele elemento.

Editando ao vivo

Você pode mudar CSS e HTML direto no DevTools pra testar correções antes de mexer no código. As mudanças são temporárias — somem ao recarregar a página. É uma boa forma de experimentar antes de pedir pra IA implementar. Como fazer:

• Clique num elemento no painel esquerdo (HTML) pra selecioná-lo
• No painel direito (Styles) você vê o CSS aplicado — pode clicar em qualquer valor e editar
• Desmarcando a caixinha ao lado de uma propriedade você a desativa temporariamente
• Clicando no final de um bloco de CSS, você adiciona novas propriedades

Casos práticos

• Elemento invisível: selecione o elemento e procure nos Styles por display: none, visibility: hidden ou opacity: 0.
• Elemento na posição errada: veja as propriedades de position, margin e padding no painel de Styles.
• Texto cortado: procure por overflow: hidden ou white-space: nowrap no elemento ou nos pais dele.
• Cor errada: procure por color ou background-color e veja qual regra CSS está sendo aplicada (às vezes uma regra mais específica sobrescreve outra).

Dica: quando encontrar o problema no DevTools, tire um print ou copie o CSS e descreva pra IA o que quer mudar. Ela implementa a correção no código real.

Application: dados salvos no navegador

A aba Application mostra o que está guardado no navegador do usuário. Útil quando o login está com comportamento estranho, dados antigos aparecem do nada, ou algo que deveria ter sumido ainda está lá.

O que você vai usar

• Cookies: tokens de autenticação e preferências ficam aqui. Se o login está com problema, verifique se o cookie de sessão existe e não está expirado.
• Local Storage: dados que o app salva localmente no navegador (sem expirar). Se o app está com dados velhos, pode ser que o localStorage esteja desatualizado.
• Session Storage: igual ao localStorage mas some quando você fecha a aba.

Como limpar dados salvos

Se você suspeita que dados velhos estão causando problema:

1. No painel esquerdo, clique em Local Storage → no seu domínio
2. No painel direito, selecione tudo (Ctrl+A) e aperte Delete
3. Recarregue a página

Ou, mais rápido: clique com o botão direito no ícone de cadeado da URL → Configurações do site → Limpar dados.

Caso prático: logout não funciona

O usuário clicou em sair mas continua vendo a página logada. Verifique:

• Abra Application → Cookies
• Veja se o cookie de autenticação ainda existe depois do logout
• Se existir, o logout não está apagando o cookie — cole esse diagnóstico pra IA resolver

Outras abas (visão rápida)

Você provavelmente não vai precisar dessas no dia a dia, mas é bom saber pra que servem caso alguém mencione:

Sources

Mostra todos os arquivos JavaScript que estão rodando na página. Você pode colocar breakpoints (pontos de parada) pra pausar a execução do código em qualquer linha e inspecionar o estado. Poderoso mas avançado — use só se a IA pedir.

Performance

Grava e analisa o desempenho da página: quanto tempo cada script levou, quantos frames por segundo estão sendo renderizados, onde está o gargalo. Use quando a página está visivelmente lenta e as otimizações básicas não resolveram.

Memory

Analisa o uso de memória RAM pelo JavaScript. Use quando a página fica mais lenta com o tempo sem recarregar — sinal de memory leak (memória que cresce e nunca é liberada).

Lighthouse

Roda uma auditoria completa na página e gera um relatório de performance, acessibilidade, boas práticas e SEO. Útil antes de lançar algo pra produção. Clique em Analisar página e espere — ele gera um relatório com nota e sugestões específicas.

Fluxo de investigação: da erro à solução

Quando algo não funciona, siga essa ordem:

1. Abra o DevTools antes de reproduzir o problema. Se você abrir depois, pode perder informações.
2. Console primeiro. Tem algum erro vermelho? Se sim, copie o erro completo.
3. Network em seguida. Tem alguma requisição com status 4xx ou 5xx? Clique nela e veja o Response.
4. Cole tudo pra IA. Erro do console + detalhe da requisição + o que você estava tentando fazer. Quanto mais contexto, melhor a resposta.
5. Se o problema for visual, use Elements pra inspecionar o elemento e identificar qual propriedade CSS está causando o problema.
6. Se o problema for de dados persistentes (login, cache, dados velhos), vá pra Application e limpe o localStorage e cookies.

Template de prompt pra IA quando encontrar um erro

Encontrei um problema na aplicação. Aqui está o diagnóstico:

O que eu estava tentando fazer:
[ex: clicar no botão Salvar do formulário de cadastro]

O que aconteceu:
[ex: nada, o formulário não salvou e não deu mensagem de erro]

Console (aba Console do DevTools):
[cola os erros que apareceram, ou 'sem erros no console']

Network (aba Network do DevTools):
[ex: apareceu uma requisição POST /api/users com status 422]
[Response: {'error': 'email já cadastrado'}]

O deploy terminou — e agora?

Depois de fazer o promote para production (ou merge na staging), o deploy não termina no clique. Tem um processo acontecendo no servidor que leva alguns minutos. Saber acompanhar esse processo é fundamental para saber se deu certo — e para agir rápido se algo errou.

Acompanhando o build no Heroku

Pelo dashboard

1. Acesse o Heroku e abra o app que você deployou
2. Vá na aba Activity
3. Você vai ver o deploy mais recente com status: Building, Deploying ou Deployed
4. Clique em "View build log" para ver o processo em tempo real

O que o build log mostra

Num projeto Rails, a sequência normal é:

-----> Building on the Heroku-22 stack
-----> Ruby app detected
-----> Installing gems
-----> Compiling assets
-----> Launching...
       Released v42
       https://meu-app.herokuapp.com/ deployed to Heroku

Se o log terminar com "deployed to Heroku", o deploy funcionou. Se terminar com erro, leia o que está logo acima — geralmente está a causa.

Erros comuns no build log

"Gem not found":

Uma gem foi adicionada ao Gemfile mas não existe na versão especificada. Cole o erro na IA:

Meu deploy no Heroku falhou com esse erro:
[cola o erro]

O que causou e como resolver?

"PG::UndefinedTable" ou erro de coluna:

Uma migration foi criada mas não foi rodada no Heroku. Rode manualmente:

"Assets precompile failed":

Erro na compilação de CSS ou JavaScript. Geralmente é um arquivo com sintaxe errada. Cole o erro completo na IA.

Verificando depois do deploy

Smoke test rápido

Depois que o build terminar, abra o app e teste o básico:

• Consegue acessar a página inicial?
• Consegue fazer login?
• A funcionalidade que você deployou está funcionando?
• Algo que funcionava antes parou de funcionar?

Logs em tempo real

Se algo estiver estranho depois do deploy, os logs do Heroku são o primeiro lugar para olhar:

O --tail mantém o log aberto em tempo real. Cada request que chega no servidor aparece aqui. Se der erro, você vai ver o stack trace completo.

Cole o erro na IA:

Meu app em production está com esse erro nos logs:
[cola o erro]

O que pode estar causando?

Rollback: como voltar atrás

Se o deploy quebrou algo grave em production e você precisa voltar para a versão anterior rapidamente:

1. No Heroku, vá na aba Activity do app
2. Você vai ver o histórico de deploys
3. Clique nos três pontos ao lado do deploy anterior
4. Selecione "Roll back to here"
5. O Heroku vai restaurar a versão anterior em 1-2 minutos

Rollback não reverte migrations. Se a versão nova adicionou uma tabela ou coluna no banco, essa mudança permanece mesmo depois do rollback.

Monitoramento contínuo

• Aba Metrics no Heroku — mostra tempo de resposta, uso de memória e erros recentes
• Aba Activity — histórico de tudo que aconteceu no app (deploys, restarts, erros)

Termos técnicos explicados em linguagem humana. Quando travar numa palavra estranha, procura aqui primeiro.

Git e versionamento

• Branch: cópia paralela do código onde você trabalha sem afetar o código oficial. Você desenvolve na sua branch e só junta na main quando tiver pronto e testado.
• Commit: uma "foto" do estado do projeto num momento específico. Registra o que mudou, quando e quem fez. Se der ruim, você volta pra uma foto anterior.
• Push: enviar os commits do seu computador pro GitHub (da máquina pra nuvem).
• Pull: puxar as mudanças que estão no GitHub pro seu computador (da nuvem pra máquina).
• Clone: fazer uma cópia completa de um repositório do GitHub pro seu computador.
• Merge: juntar o código de uma branch em outra.
• Rebase: reorganizar os commits da sua branch em cima dos commits mais recentes da main. Mantém o histórico mais limpo que o merge.
• Conflict / Conflito: quando duas pessoas mexeram na mesma parte do mesmo arquivo e o Git nao sabe qual versao manter. Precisa resolver manualmente.
• Pull Request (PR): pedido formal pra juntar seu código no código oficial. Alguém revisa antes de aprovar.
• Draft PR: rascunho de Pull Request. Indica que ainda nao está pronto pra revisão, mas já existe no GitHub.
• Main: branch principal do repositório — o código que está (ou vai pra) produção.
• Repositório (repo): pasta do projeto com todo o histórico de mudanças.
• Behind / Ahead: quantos commits sua branch está "atrás" ou "à frente" da main. Behind = desatualizada. Ahead = tem trabalho novo.
• Diff: visualização do que mudou entre duas versões do código. Linhas verdes = adicionadas, linhas vermelhas = removidas.

Ferramentas e ambiente

• IDE: Integrated Development Environment. O programa onde voce escreve codigo — editor, terminal e Git integrados num so lugar. Ex: VSCode, TRAE.
• TRAE: editor de codigo pago com IA integrada. Interface identica ao VSCode, permite trocar de modelo de IA. Terceira opcao apos VSCode+Antigravity e Copilot.
• Antigravity: extensao do VSCode com IA integrada. Gratuita com e-mail do trabalho. Opcao recomendada pra quem esta comecando.
• GitHub Copilot: extensao do VSCode com IA integrada do GitHub. A empresa pode ter licenças pra algumas pessoas do time.
• Terminal: interface de linha de comando. Onde você digita (ou a IA digita) comandos pra controlar o computador.
• WSL: Windows Subsystem for Linux. Permite rodar Linux dentro do Windows sem máquina virtual. Necessário pra projetos Ruby no Windows.
• Docker: programa que cria ambientes isolados (containers). Usado pra rodar o banco de dados localmente sem instalar direto na máquina.
• Container: ambiente isolado criado pelo Docker. Funciona igual em qualquer máquina.
• Chat mode: modo da IA onde ela responde em texto. Você conversa, planeja, tira dúvidas. A IA nao mexe nos arquivos.
• Build mode: modo da IA onde ela age direto no código. Cria arquivos, edita código, roda comandos.

Backend e banco de dados

• Frontend: a parte visual do sistema — o que o usuário vê e clica no navegador.
• Backend: a parte que processa dados nos bastidores — servidor, regras de negócio, banco.
• Banco de dados: onde os dados ficam guardados de forma organizada. Eu uso PostgreSQL.
• PostgreSQL: banco de dados relacional (tipo planilha) que eu uso.
• Migration: arquivo que define uma mudança na estrutura do banco de dados — criar tabela, adicionar campo, remover coluna. Precisa ser rodada pra ter efeito.
• Seed: dados iniciais populados no banco pra facilitar desenvolvimento. Não use em production.
• ORM: camada de código que traduz entre JavaScript/Ruby e o banco de dados. Em vez de escrever SQL, você escreve código normal. Ex: Prisma (Next.js), ActiveRecord (Rails).
• SQL: linguagem usada pra consultar e manipular bancos de dados relacionais.
• API: interface que permite que dois sistemas se comuniquem. Quando o frontend pede dado pro backend, faz isso via API.
• Variável de ambiente: configuração que fica fora do código — senhas, tokens, URLs. Muda por ambiente (local, staging, production) sem mexer no código.
• .env: arquivo que guarda variáveis de ambiente localmente. Nunca sobe pro GitHub.

Deploy e infraestrutura

• Deploy: processo de subir uma versão nova do código pra um servidor (staging ou production).
• Heroku: plataforma de nuvem onde os apps que eu construí ficam hospedados.
• Pipeline: no Heroku, visão do fluxo staging → production com botão de promote.
• Staging: ambiente de testes. Time interno acessa, usuários nao.
• Production: ambiente real. Usuários reais, dados reais. Cuidado!
• Local: ambiente no seu próprio computador. Só você vê.
• Promote: no Heroku, copiar exatamente o que está rodando em staging pra production. Garante que o que foi testado é o que vai pro ar.
• Dyno: no Heroku, o container que roda o código do app. Você paga por dyno.
• Config Vars: variáveis de ambiente no Heroku. Onde ficam senhas, tokens e URLs de cada app.
• Add-on: serviço extra que você adiciona a um app no Heroku. Ex: Heroku Postgres (banco), Redis (cache).
• SSL / HTTPS: protocolo de segurança que criptografa a comunicação entre o navegador e o servidor. O cadeado que aparece no navegador.
• DNS: sistema que traduz um domínio (ex: meu-dominio.com) num endereço de servidor. Tipo a lista telefônica da internet.
• CNAME: tipo de registro DNS que aponta um domínio pra outro endereço. Usado pra conectar domínio customizado ao Heroku.

Código e desenvolvimento

• Stack: conjunto de tecnologias usadas num projeto. Ex: Ruby on Rails + PostgreSQL + Heroku.
• Framework: estrutura pronta que define como o código é organizado. Ex: Rails (Ruby), Next.js (JavaScript).
• Gem: biblioteca de código externo pra projetos Ruby.
• npm / yarn: gerenciadores de pacotes pra projetos JavaScript. Instalam bibliotecas externas.
• bundle install: comando Rails que instala as gems do projeto.
• Kebab-case: convenção de nomenclatura com palavras separadas por hífen. Ex: minha-feature-nova.
• feat / fix / refactor: prefixos usados em mensagens de commit pra indicar o tipo de mudança.
• Happy path: o fluxo normal quando tudo funciona. Ex: usuário preenche o formulário corretamente e salva.
• Sad path: os fluxos de erro ou exceção. Ex: usuário deixa campo obrigatório vazio.
• Edge case: situação limite ou incomum que pode causar comportamento inesperado. Ex: nome com 500 caracteres, arquivo vazio.
• Debug: processo de encontrar e corrigir bugs. Console.log é uma técnica de debug (remova antes de commitar).
• Mock / dado mocado: dado falso usado durante o desenvolvimento antes de plugar banco real.
• Refactor: reescrever código sem mudar o comportamento. Melhora legibilidade ou performance.
• OAuth: protocolo que permite login com conta de outro serviço. Ex: "Entrar com Google".
• Token: chave de acesso a uma API ou serviço. Trate como senha — nunca compartilhe nem suba pro GitHub.
• Skill (IA): arquivo com instruções especializadas que você instala no projeto pra guiar o comportamento da IA.
• AGENTS.md: arquivo de briefing que a IA lê antes de qualquer tarefa no projeto. Define contexto, convenções e regras.

Comandos básicos para usar no terminal quando você já sabe o que fazer:

Comandos Rails

Comandos Git — Branches

Comandos Git — Commit e Push

Comandos Docker

Comandos Heroku CLI