Vibe coding é o termo utilizado para descrever o ato de desenvolver soluções utilizando ferramentas de Inteligência Artificial (IA) entregando a responsabilidade do código inteiramente para a IA. Atualmente é associado a soluções mal construídas e recebe chacotas nas redes sociais. As críticas são variadas, mas a raiz de todas elas mora na falta de conhecimento da pessoa que está criando a solução e não em como a solução foi criada.
Note que eu utilizei a palavra solução múltiplas vezes no parágrafo acima. Isso é intencional. Um aplicativo, sistema, programa de computador é criado para resolver (ou descrever) algo, sendo assim, uso a palavra solução pra me referir a tudo isso. Porém, como fica estranho e cansativo repetir o mesmo termo múltiplas vezes, faço aqui uma pausa para avisar que, quando eu falar coisas como sistema, código, app, aplicativo, aplicação, programa, solução e talvez outros, provavelmente estarei falando da mesma coisa.
Para quem é esse tutorial
Esse tutorial é primariamente destinado para qualquer pessoa que queira aprender sobre como utilizar a IA para criar soluções e não sabe programar. Isso não exclui, porém, as pessoas que já têm conhecimento técnico e querem apenas aprender sobre as melhores formas de utilizar a IA para ser mais produtivo.
Vou além. Como este tutorial é destinado primeiro a pessoas não técnicas, utilizarei linguagem simples e acessível a todas as idades, níveis de conhecimento e formação.
O que você vai aprender aqui
Neste tutorial você vai aprender como criar uma aplicação do zero, sem nenhuma interação direta com código. Tudo escrito, testado e gerenciado pela sua ferramenta de IA de preferência.
Fora as capacidades técnicas, eu vou falar sobre as considerações que você deve fazer antes de tomar decisões. Ou nesse caso, antes de deixar a IA tomar decisões por você. Minha meta é te deixar ciente dos problemas que podem surgir frente a cada decisão para que você possa escolher os problemas que quer enfrentar e evitar os que não quer.
Nos meus exemplos eu utilizarei o Claude Code mas acredito (não tenho certeza pois não testei) que os mesmos procedimentos funcionarão em outras ferramentas como o Aider, o OpenCode, o Gemini CLI ou o OpenAI Codex.
Além disso, vou te explicar como o Docker resolve o problema das dependências do projeto e como desenvolver e testar tudo utilizando apenas o seu computador pessoal.
O que você vai precisar
Para acompanhar esse tutorial você precisa ter um computador com navegador e acesso à internet. Qualquer sistema operacional funciona. O processo será o mesmo.
Programas
Você precisa instalar os seguintes programas no seu computador:
- Claude Code
- Git
- Docker
- Visual Studio Code - Opcional mas altamente recomendável
As instruções de download e instalação estão nos links de cada ferramenta.
Investimento
Este tutorial é inteiramente gratuito, porém, para usar o Claude Code você precisa de uma assinatura ativa nível Pro ou superior. Isso se você for utilizar o Claude. Para outras ferramentas, não sei dizer.
O que vamos construir
Nós vamos construir uma aplicação web (um sistema que você acessa pelo navegador) que vai servir como um site de anúncios digitais. Este é um sistema simples e genérico e existem várias formas de criar essa solução. A forma na qual eu vou construí-lo aqui não é pessoalmente como eu faria mas acredito que vai te beneficiar mais pois através dela poderemos falar sobre tópicos interessantes que seriam ignorados caso eu simplesmente focasse em como eu penso ser a melhor forma de resolver este problema.
Arquitetura
Nosso sistema será composto de três componentes. Nós teremos um front-end (ou interface web), um backend ou API (Application Programming Interface ou interface de aplicação numa tradução literal) e também teremos um banco de dados.
Front-end
Aqui vai morar o código responsável por gerar as telas do nosso sistema. Basicamente HTML, CSS e JavaScript (não se preocupa se você não sabe o que é isso) que vai ser consumido pelo navegador e proporcionar uma experiência para os nossos usuários.
Backend
Aqui vai morar o código responsável por controlar o acesso ao banco de dados, definir as regras de negócio e entregar as informações para o nosso front-end.
Sem o backend o front-end não funciona, sendo assim, o backend é o que conecta os dois.
Banco de dados
Aqui vão residir os nossos dados, parte vital da nossa solução. Sem o banco de dados nada funciona.
A decisão de ter três componentes separados é a mais comum nesse tipo de aplicação. Fica mais fácil manter cada parte sem quebrar as outras, e mais fácil encontrar ajuda porque essa estrutura é familiar pra qualquer desenvolvedor. O lado ruim é que a gente precisa orquestrar os três ao invés de uma peça só. O Docker Compose vai resolver isso.
Docker e Docker Compose
Antes de entrar no código, preciso falar sobre uma ferramenta que vai resolver um problema chato. O problema de instalar e configurar as dependências do nosso código.
Quando a gente instala um programa, ele geralmente precisa de outras coisas pra funcionar. Uma versão específica do Python. Uma biblioteca. Uma configuração de sistema. Essas dependências podem conflitar com outras coisas já instaladas no seu computador, ou simplesmente não existir nele. Isso requer que você tenha conhecimento técnico para configurar o seu sistema e é uma trava real pra quem está começando. O Docker resolve isso empacotando tudo que o programa precisa numa caixa isolada chamada container. Com o Docker o seu programa roda dentro da “caixa”, com tudo que precisa pra funcionar.
O Docker Compose é uma ferramenta que gerencia múltiplos containers ao mesmo tempo. No nosso caso, a gente vai ter três. Um pro frontend, um pro backend e um pro banco de dados. O Docker Compose sabe como iniciar os três na ordem certa, conectá-los entre si e derrubá-los quando a gente não precisar mais.
Claude Code
O Claude Code é uma ferramenta de terminal. Terminal (ou linha de comando) é aquela janela onde você digita comandos e o computador executa. Se você nunca usou, não se preocupa. A gente vai abrir um terminal integrado dentro do VS Code mais adiante, então você não precisa procurar nada agora.
Pra iniciar o Claude Code, você digita claude num terminal e pressiona Enter. Ele vai te cumprimentar e aguardar o seu próximo prompt.
Cada mensagem que você enviar é um prompt. O Claude vai ler, pensar e escrever código em resposta. Você pode pedir uma coisa de cada vez ou descrever uma tarefa maior. Tópicos menores são mais fáceis de corrigir se algo sair errado.
Criando o projeto
Crie uma pasta no seu computador pra guardar os arquivos do projeto. Pode ser em qualquer lugar, mas um lugar comum é dentro da pasta de documentos ou na área de trabalho. Dê um nome simples, sem espaços e sem acentos. Algo como anuncios ou meu-projeto.
Depois, abra o Visual Studio Code. Vá em File > Open Folder (ou Arquivo > Abrir Pasta) e selecione a pasta que você acabou de criar. O VS Code vai abrir com a pasta do projeto no painel lateral esquerdo.
Com o projeto aberto no VS Code, abra o terminal integrado pelo menu Terminal > New Terminal (ou pelo atalho Ctrl + `). Esse terminal já vai estar posicionado dentro da pasta do projeto, o que é exatamente o que a gente precisa.
Antes de iniciar o Claude Code, inicialize o Git na pasta do projeto. O Git é um sistema de controle de versão que registra todas as alterações feitas nos arquivos ao longo do tempo. Isso é importante porque o Claude Code usa o Git pra entender o que mudou no projeto e pra te dar a opção de desfazer alterações se algo sair errado. No terminal, execute:
git init
Depois disso, pra iniciar o Claude Code, você digita claude e pressiona Enter. Ele vai te cumprimentar e aguardar o seu próximo prompt.
Antes de construir qualquer coisa, a gente vai criar um arquivo especial chamado CLAUDE.md. Pensa nele como um briefing permanente. Toda vez que você abrir uma nova sessão do Claude Code nessa pasta, ele vai ler esse arquivo primeiro. Isso garante que ele nunca esqueça o contexto do projeto, de como ele é estruturado ou de que ferramentas a gente está usando.
Os prompts de infraestrutura são os únicos nesse tutorial onde eu passo especificações técnicas detalhadas. Estou sendo deliberadamente específico aqui pra que os resultados sejam consistentes e você consiga acompanhar sem surpresas.
Na prática, antes de chegar nesse ponto, você deveria perguntar ao próprio Claude como escolher as ferramentas. As perguntas que eu teria feito são essas:
Qual é o melhor framework de frontend para desenvolver uma aplicação web se eu quiser encontrar freelancers facilmente para me ajudar no futuro?
Qual é uma boa linguagem ou framework para o backend? Quero algo simples, com boa documentação e comunidade grande.
Qual banco de dados gratuito e open source eu deveria usar para uma aplicação pequena que precisa guardar dados de forma confiável?
Essas perguntas provavelmente vão te trazer ao mesmo lugar. React domina o mercado de frontend e tem uma das maiores comunidades de desenvolvedores do mundo, o que facilita muito encontrar ajuda quando você precisar. Python com FastAPI é simples de ler, rápido de desenvolver e tem suporte massivo. PostgreSQL é gratuito, confiável e escala bem, de aplicações pequenas a sistemas grandes, sem precisar trocar de banco de dados no meio do caminho. São escolhas seguras. O preço é que, por serem populares, às vezes têm mais complexidade do que o necessário pra um projeto pequeno. Mas num primeiro projeto, popularidade é uma vantagem.
Envie o seguinte prompt:
Crie um arquivo CLAUDE.md na raiz do projeto com as especificações da nossa aplicação de anúncios digitais. O projeto usa Docker Compose para orquestrar todos os serviços. A aplicação terá três serviços: um frontend feito com Vite e React, um backend feito em Python, e um banco de dados PostgreSQL. Toda a infraestrutura deve ser configurada via Docker e Docker Compose, sem que o usuário precise instalar nenhuma dependência diretamente. Os comandos para interagir com a aplicação são apenas: docker compose build, docker compose up e docker compose down.
O Claude vai criar o arquivo com uma descrição do projeto, as tecnologias envolvidas e as convenções de desenvolvimento. Leia o que ele criou. Se algo estiver errado ou incompleto, corrija no prompt seguinte antes de continuar.
Com o CLAUDE.md criado, a gente pode começar a montar os arquivos de infraestrutura. Os próximos prompts têm termos técnicos que você não precisa entender agora. O que importa é saber o que você está pedindo: um conjunto de arquivos que descrevem como os três serviços da aplicação vão funcionar juntos. O Claude vai criar tudo.
O passo inicial é criar o docker-compose.yml, o arquivo que vai descrever os três serviços.
Crie o arquivo docker-compose.yml com três serviços: frontend (Vite + React), backend (Python com FastAPI) e db (PostgreSQL). O frontend deve ser acessível na porta 5173, o backend na porta 8000. O banco de dados deve ter um volume persistente para que os dados não se percam quando a gente derrubar os containers. Os serviços de frontend e backend devem depender do banco de dados para iniciar.
Depois, o Dockerfile do backend:
Crie o Dockerfile do backend Python com FastAPI. Ele deve instalar as dependências a partir de um arquivo requirements.txt e iniciar o servidor com uvicorn na porta 8000. O ambiente deve ser de desenvolvimento, com reload automático ativado.
E o do frontend:
Crie o Dockerfile do frontend com Node.js. Ele deve instalar as dependências com npm install e iniciar o servidor de desenvolvimento do Vite na porta 5173. Configure o Vite para aceitar conexões de fora do container.
Por último, a estrutura inicial de cada serviço:
Crie a estrutura inicial do projeto frontend com Vite e React dentro da pasta frontend/. Use o template padrão do React com JavaScript.
Crie a estrutura inicial do projeto backend com FastAPI dentro da pasta backend/. Inclua um arquivo requirements.txt com as dependências necessárias (fastapi, uvicorn, psycopg2-binary, sqlalchemy) e um arquivo main.py com um endpoint de healthcheck em GET /health que retorna {"status": "ok"}.
Antes de avançar, vale verificar se a estrutura básica está funcionando. Abra o terminal integrado do VS Code, execute docker compose build e depois docker compose up. Quando os três serviços estiverem no ar, abra o navegador e acesse http://localhost:5173 pra ver o frontend e http://localhost:8000/health pra confirmar que o backend está respondendo. Se os dois carregarem sem erro, a infraestrutura está pronta e a gente pode continuar.
Modelo de dados
Antes de escrever qualquer endpoint, a gente precisa definir como os dados vão ser organizados no banco de dados. Isso se chama modelo de dados e é uma das decisões mais importantes de uma aplicação. É difícil de mudar depois que ela estiver em uso. O exercício antes de qualquer prompt é simples: o que você precisa saber sobre cada item que vai armazenar? Pra um anúncio, a resposta está abaixo. Pra uma aplicação própria, faça a mesma pergunta antes de começar.
Preciso armazenar anúncios no banco de dados. Cada anúncio vai ter: um título, uma descrição longa, um preço que é opcional (o anunciante pode deixar em branco se preferir negociar), uma categoria para organizar os anúncios, uma forma de contato do anunciante e a data em que o anúncio foi publicado. Crie o modelo de dados no banco de dados e configure o backend para criar a tabela automaticamente quando iniciar.
Backend
Com o modelo de dados criado, a gente pode construir os endpoints da API. A aplicação vai precisar de três operações básicas. Listar todos os anúncios, criar um novo anúncio e visualizar um anúncio específico.
Quero que o backend permita três coisas: ver todos os anúncios publicados, publicar um novo anúncio e ver os detalhes de um anúncio específico. Use o modelo de dados que já foi criado no banco de dados. Crie também testes automáticos que verifiquem se cada uma dessas funcionalidades está funcionando corretamente.
Pedir testes é um hábito que faz diferença. Um teste automático não serve só pra encontrar bugs agora. Serve pra garantir que quando você fizer uma mudança no futuro, algo vai te avisar se você quebrou o que estava funcionando. Pra quem não é técnico, isso é especialmente útil porque você não vai lembrar de testar tudo manualmente toda vez que pedir uma alteração ao Claude.
Frontend
Com a API pronta, é hora de construir as telas. A aplicação vai ter três páginas. Uma listagem de todos os anúncios, um formulário pra criar um novo e uma página de detalhes de um anúncio específico.
Quero três telas na aplicação: uma página inicial que lista todos os anúncios publicados, uma página com formulário para publicar um novo anúncio e uma página de detalhes que mostra todas as informações de um anúncio específico. O frontend deve se conectar ao backend da aplicação. Verifique a documentação da API disponível em http://localhost:8000/docs para entender quais endpoints existem e como usá-los. Crie também testes que verifiquem se o frontend consegue se comunicar corretamente com o backend.
Pedir pro Claude verificar a documentação da API é melhor do que descrever os endpoints manualmente. Ele vai ler o que realmente existe no backend, no estado em que está agora, não o que você acredita que existe. Erros de integração entre frontend e backend são chatos de rastrear e esse simples hábito evita boa parte deles.
Um aviso aqui. O Claude provavelmente vai criar telas funcionais mas visualmente simples. Isso está bom por agora. Não misture estilo e funcionalidade no mesmo prompt. Fica mais difícil corrigir se algo der errado. Depois que a aplicação estiver funcionando, se quiser melhorar o visual, use um prompt separado:
Melhore o visual da aplicação. A estética deve ser limpa e minimalista. Use apenas CSS puro, sem bibliotecas externas.
Testando localmente
Com tudo criado, é hora de ver se funciona. No terminal integrado do VS Code, execute:
docker compose build
Esse comando vai construir os containers. Na primeira vez, pode demorar alguns minutos. O Docker vai baixar as imagens base e instalar todas as dependências dentro dos containers.
Depois, inicie a aplicação:
docker compose up
Você vai ver os logs dos três serviços aparecendo no terminal. Quando o backend estiver pronto, vai aparecer algo como Uvicorn running on http://0.0.0.0:8000. Quando o frontend estiver pronto, algo como VITE v5.x.x ready in ...ms.
Abra o navegador e acesse http://localhost:5173. Você deve ver a listagem de anúncios, vazia por enquanto. Clique em criar novo anúncio, preencha o formulário e envie. O anúncio deve aparecer na lista.
O FastAPI também gera uma documentação automática da API. Você pode acessar em http://localhost:8000/docs e testar os endpoints diretamente pelo navegador.
Quando algo quebrar
Alguma coisa vai quebrar. É quase certo.
Olhe o terminal onde o docker compose up está rodando. O erro vai aparecer lá, geralmente com uma descrição do que deu errado. Copie a mensagem de erro completa e cole numa nova mensagem no Claude Code:
Esse erro apareceu no terminal quando tentei subir a aplicação com docker compose up. Me ajuda a corrigir?
[cole o erro aqui]
O Claude vai identificar o problema e propor uma correção. Depois de corrigir, rode docker compose down pra derrubar os containers e docker compose up novamente pra reiniciar com as correções.
Pra encerrar a aplicação a qualquer momento, pressione Ctrl + C no terminal onde o docker compose up está rodando e depois execute docker compose down.
O que vem depois
Essa aplicação funciona, mas só roda no seu computador. Pra outras pessoas acessarem, você vai precisar fazer o deploy em algum servidor. Isso está fora do escopo desse tutorial, mas não é tão complicado quanto parece. Plataformas como Railway, Render e Fly.io conseguem rodar containers Docker com uma configuração razoavelmente simples. Pra cada uma delas, você pode pedir ao Claude que te ajude com a configuração específica.
Tem também coisas que essa aplicação não tem. Autenticação, imagens nos anúncios, busca, moderação de conteúdo. Cada uma é um conjunto novo de prompts.
Mas isso é pra depois.