Guia de Vibe Coding v1.0: Um Manual Completo para Desenvolvimento Assistido por IA

Este documento é um guia criado para ajudar não apenas programadores experientes, mas também não-programadores a desenvolver aplicativos/serviços usando 'Vibe Coding'. Desenvolvedores juniores com pouca experiência em codificação e planejadores também podem produzir resultados estáveis seguindo estas etapas.

Princípio Central: Em vez de fazer a IA escrever código imediatamente, é melhor fazê-la criar documentos (Design.md, ToDo.md) primeiro, antes de iniciar o desenvolvimento.

0. Resumo Geral do Fluxo

[1] Solicitar a criação do Concept.md

↓

[2] Criar o Design.md (documento de referência de UI/UX)

↓

[3] Definir a Stack Tecnológica (Consulte a árvore de decisão abaixo)

↓

[4] Criar o ToDo.md (Especificações técnicas em nível de módulo + plano de desenvolvimento)

↓

[5] Criar o Repositório GitHub e fazer o commit inicial

↓

[6] Passar a descrição do app + Design.md + ToDo.md para o Claude Code ou Grok Build para iniciar o desenvolvimento

↓

[7] Repetir: Implementar por módulo → Testar → commit/push

1. Concept.md — Prompt para Começar com uma Ideia Simples

Comece descrevendo brevemente o aplicativo ou serviço que você deseja criar em 2-3 linhas, conforme vier à mente, no formato: "Quero fazer algo assim; por favor, crie um documento Concept.md detalhando os procedimentos e métodos para implementá-lo."

Baixe o documento gerado e salve-o como Concept.md.

2. Design.md — Criando Documentos de Referência de UI/Design Primeiro

Se o aplicativo tiver uma interface de usuário (UI), é bom escrever o Design.md primeiro. Ou seja, se houver um serviço ou aplicativo que você queira usar como referência, ou se você já souber como projetar a UI, pode solicitá-lo fornecendo imagens de designs feitos no Figma, etc.

Método

• Escolha um site realmente implantado que você goste. (ex.: linear.app, stripe.com, toss.im, etc.)
• Instrua o Claude ou Grok a "Analisar a estrutura de layout, paleta de cores, tipografia, margens/espaçamentos e estilos de componentes desse site e organizar tudo no Design.md."

Exemplo de Prompt

Analise o design de https://linear.app e escreva um documento Design.md. Você deve incluir os seguintes itens: 1. Estrutura geral do layout (posicionamento do Header/Sidebar/Body/Footer) 2. Paleta de cores (Cores Primária, Secundária, de Fundo e de Texto em códigos HEX) 3. Tipografia (Tipos de fonte, sistema de tamanhos, pesos) 4. Regras de margens e espaçamento (escala de espaçamento) 5. Estilos para componentes principais como botões, cards e formulários de entrada 6. Suporte a modo escuro e mapeamento de cores

Dicas

• Se você tiver senso de design, como o conteúdo do Design.md gerado é todo descrito em linguagem natural, você pode lê-lo e modificar/refinar diretamente na direção desejada. Este documento se torna o padrão para todas as implementações de UI subsequentes.
• Se você apenas disser "Faça igual a este site", os resultados variarão a cada vez. Você deve fixá-lo com um documento para manter a consistência.

2. Árvore de Recomendação para Decisão da Stack Tecnológica

Determine a stack primeiro com base no tipo de serviço que você está tentando criar.

Princípios Comuns de Servidor (Backend)

• Deve ser possível instalar e executar diretamente da CLI em qualquer ambiente local.
• A linguagem/ambiente de execução deve ser Node.js ou Python.
• Use ferramentas verificadas para implantação e suporte estáveis em todos os SOs para pacotes/ambientes de execução:
• Python → uv
• Node.js → npm

Critérios de Seleção de Banco de Dados

Instruções Detalhadas do Prompt (Se você tiver conhecimento de desenvolvimento)

Este projeto é um aplicativo web. Configure o Frontend com React, e deve ser possível testar imediatamente com npm run dev localmente, com uma estrutura que permita implantação estável. Configure o Backend com Node.js e, como um banco de dados relacional é necessário, use MariaDB. Inclua um script de configuração que possa ser instalado/executado diretamente via CLI no ambiente de desenvolvimento local. Verifique este conteúdo e o documento Concept.md para escrever um documento ToDo.md para implementação técnica detalhada.

• Prossiga anexando o documento Concept.md com este prompt ou copiando e colando o conteúdo do documento Concept.md.

Mas e se eu for um não-programador que não sabe o que foi dito acima?

Basta dar instruções integradas como esta:

Não tenho certeza de como executar este projeto, então, por favor, recomende uma maneira. Recomende se um aplicativo web é melhor, se um método de instalação no SO é mais fácil de verificar durante o desenvolvimento ou se construir como um aplicativo móvel é melhor. Se puder ser exibido em um navegador web, configure o Frontend com React; se precisar ser servido como um aplicativo móvel, configure o Frontend com Flutter. Se for um método que precisa ser instalado localmente, configure-o usando npm ou uv, que podem ser facilmente implantados e instalados via CLI. Monte uma estrutura que permita implantação estável. Não tenho certeza se um Backend é necessário, mas configure uma estrutura estável para Node.js ou implantação/instalação. Se um banco de dados for necessário, use MariaDB se for relacional, e se for apenas um banco de dados chave-valor, use AWS DynamoDB localmente para desenvolvimento e configure-o para fácil implantação na AWS. Se for um formato que possa ser instalado/executado diretamente via CLI em um ambiente de desenvolvimento local, inclua todos os scripts de configuração. Recomende uma stack técnica detalhada assim, verifique este conteúdo e o documento Concept.md, e escreva um documento ToDo.md para implementação técnica detalhada.

3. Painel de Administração — Essencial se houver um servidor

Você pode não saber se é um serviço com servidor, mas geralmente é bom construir um para que o desenvolvedor possa compreender pessoalmente o status operacional e o progresso de todo o aplicativo.

• Projetos com servidor devem incluir a implementação de um painel de administração (Admin dashboard) como padrão.
• Itens mínimos a incluir no painel:
• Verificação de integridade do servidor (health check)
• Status dos dados principais (métricas essenciais como número de assinantes, número de casos processados, etc.)
• Erros/logs recentes
• Progresso do processamento de tarefas principais (lotes, filas, etc.)

Exemplo de Prompt

Se este serviço incluir um servidor, inclua um painel de administração no plano de desenvolvimento. O painel deve permitir verificar o status do servidor, as métricas principais e os logs/erros recentes. Defina a conta de administrador padrão como 'admin' com senha '12345', e inclua a capacidade de alterar a senha no painel de administração. Verifique o ToDo.md e inclua isso no plano de desenvolvimento se julgar necessário.

4. Finalizando o ToDo.md — Plano de Desenvolvimento em Nível de Módulo

A base da programação é a modularização. Se você adicionar conteúdo ao ToDo.md para subdividir em módulos antes de escrever o código, uma boa arquitetura para manutenção futura pode ser criada.

Exemplo de Prompt

Verifique o documento ToDo.md e confirme se ele está bem escrito de acordo com o guia abaixo, e modifique/complemente quaisquer partes que estejam faltando. Requisitos do ToDo.md: 1. Projete todo o sistema para ser modularizado com design orientado a objetos. 2. Especifique claramente a função, entrada/saída e estrutura de dados de cada módulo para garantir o máximo encapsulamento. 3. Crie uma sequência de implementação como uma lista de caixas de seleção (começando pelos módulos sem dependências). 4. Inclua o design do esquema do banco de dados. 5. Descreva quando e como pessoas não técnicas podem testar facilmente.

Itens a verificar no ToDo.md concluído:

1. Visão Geral do Projeto (um parágrafo)
2. Stack Tecnológica Confirmada (Resultado da árvore de decisão na etapa 2)
3. Lista de módulos e especificações técnicas detalhadas para cada módulo (Pessoas não técnicas podem achar isso difícil de entender)
4. Nome e função do módulo
5. Entrada/Saída (Endpoints da API e formatos de requisição/resposta)
6. Estrutura de dados usada / design da tabela (ou coleção) do banco de dados
7. Relações de dependência com outros módulos
8. Sequência de implementação (em forma de caixa de seleção, na ordem das dependências)
9. Verifique se cada método de teste está escrito em um nível que eu possa entender.

Importante

• Você não precisa necessariamente ler e revisar o ToDo.md gerado pessoalmente. Embora pareça que as coisas vão correr bem se você se preparar perfeitamente, o cerne do Vibe Coding é o processo de criar um resultado primeiro e depois modificá-lo gradualmente para obter o que deseja — essa é a parte mais valiosa e divertida.

Parte Prática: Configuração do Ambiente → GitHub → Iniciando o Desenvolvimento com Claude Code

Escrito para que mesmo aqueles que estão instalando ferramentas de desenvolvimento pela primeira vez possam acompanhar.

• No entanto, se parecer muito complexo e você não entender por que deveria usá-lo e estiver entediado, vá ouvir uma palestra gratuita no link abaixo primeiro.

https://nomadcoders.co/git-for-beginners

5. Preparando o Ambiente de Desenvolvimento (Instale apenas 2 coisas)

Vamos instalar duas coisas.

E você precisa de uma conta no GitHub. Cadastre-se gratuitamente em https://github.com (complete a verificação de e-mail). Usar o Claude Code ou Grok Build requer um plano pago do Claude (Pro/Max/Team) ou uma conta paga do Grok.

5-1. 🪟 Etapas de Instalação para Usuários Windows

① Instalar o Git

1. Acesse https://git-scm.com/download/win no seu navegador → O download começa automaticamente.
2. Execute o instalador baixado.
3. Muitas opções de instalação aparecerão; apenas continue clicando em "Next" com todos os valores padrão.
4. No entanto, quando a tela "Choosing the default editor" aparecer, é bom selecionar "Use Visual Studio Code as Git's default editor" (se você ainda não instalou o VS Code, o padrão está ok).
5. Verifique a instalação: Execute o PowerShell no menu Iniciar e digite:

git --version

→ Se uma versão como git version 2.xx.x aparecer, é sucesso. Se não, tente fechar e reabrir o PowerShell.

② Instalar o VS Code

1. Acesse https://code.visualstudio.com → Clique em Download for Windows.
2. Execute o instalador → Continue clicando em "Next". No entanto, marque estas duas opções na tela de opções:
3. "Add to PATH"
4. "Add 'Open with Code' action to file/directory context menus"
5. Execute o VS Code após a instalação. Se uma notificação de instalação do pacote de idiomas aparecer na primeira tela, você pode instalá-lo.

5-2. 🍎 Etapas de Instalação para Usuários Mac

① Instalar o Git

1. Abra o Terminal: Cmd + Espaço → Digite "Terminal" → Enter.
2. Digite:

git --version

1. Se a versão aparecer imediatamente, já está instalado → Vá para ②. Se um popup de guia de instalação ("Command Line Developer Tools...") aparecer, clique em "Install" e aguarde. (Esta é a instalação do Git).
2. Verifique novamente com git --version após a conclusão.

② Instalar o VS Code

1. Acesse https://code.visualstudio.com → Clique em Download for macOS.
2. Descompacte o arquivo baixado e arraste o Visual Studio Code.app para a pasta Applications. (Importante! Não o use diretamente da pasta Downloads).
3. Execute o VS Code a partir de Applications.

5-3. (Comum) Registrando Meu Nome no Git — Apenas na Primeira Vez

Esta configuração serve para deixar um registro de "quem trabalhou" nos commits. No PowerShell (Windows) ou Terminal (Mac):

git config --global user.name "Seu Nome" git config --global user.email "seu-email-github@exemplo.com"

Digite o mesmo e-mail que você usou para se cadastrar no GitHub.

6. Criando um Repositório GitHub e Conectando ao Meu PC com VS Code

Pense em um "Repositório" como uma pasta na nuvem que contém um projeto. O fluxo é: Criar um repositório vazio no site do GitHub → Cloná-lo para o meu PC com VS Code → Enviar documentos de planejamento → Conectar esse repositório ao Claude Code web.

6-1. Criando um Repositório no Site do GitHub

1. Faça login em https://github.comhttps://github.com/).
2. Clique no botão + no canto superior direito → New repository.
3. Preencha da seguinte forma:
4. Repository name: Nome do projeto (em inglês, use hífens em vez de espaços. ex.: my-first-app)
5. Selecione Private (Projetos de empresa devem ser Private!)
6. Marque a caixa "Add a README file" ✅ ← Iniciantes devem marcar isso. Isso torna a próxima etapa (clone) mais simples.
7. Clique em Create repository.
8. Na página do repositório criado, clique no botão verde <> Code → Copie o endereço na aba HTTPS.

6-2. Clonando para o Meu PC com VS Code

1. Execute o VS Code.
2. Ctrl + Shift + P (Cmd + Shift + P no Mac) → A paleta de comandos abre.
3. Digite clone → Selecione "Git: Clone".
4. Cole o endereço do repositório copiado e pressione Enter.
5. Você também pode selecionar "Clone from GitHub" → Se o navegador abrir e pedir login/autorização do GitHub, aprove-a. (Apenas na primeira vez).
6. Selecione um local para salvar o projeto (ex.: é bom criar uma pasta Documents/Projects).
7. Quando a clonagem terminar, uma notificação "Open" aparecerá no canto inferior direito → Clique nela.
8. Se você vir README.md no explorador de arquivos à esquerda, sucesso! 🎉 Esta pasta agora é a pasta de trabalho conectada entre meu PC e o GitHub.

6-3. Enviando Documentos de Planejamento — Concept.md, Design.md, ToDo.md

O Claude Code web pode ler arquivos dentro do repositório. Portanto, colocar documentos de planejamento no repositório é o mesmo que "enviar documentos".

1. Clique com o botão direito em um espaço vazio no explorador de arquivos do VS Code → New File → Digite o nome Concept.md.
2. Cole a descrição do aplicativo que você preparou e salve (Ctrl+S / Cmd+S).
3. Crie e insira os arquivos Design.md (se houver UI) e ToDo.md da mesma forma.
4. Agora, envie para o GitHub (commit & push) — usando o método em 6-4.

6-4. Fazendo Commit e Push no VS Code — Apenas com o Mouse

1. Quando você salva um arquivo, um emblema numérico aparece no ícone em forma de ramificação (Source Control) à esquerda do VS Code.
2. Clique nesse ícone → Você verá uma lista de arquivos alterados.
3. Na caixa de entrada de mensagem no topo, escreva uma linha sobre o que você fez. (ex.: Documentos de planejamento adicionados).
4. Clique no botão ✔ Commit → Salvamento concluído no meu PC.
5. Se um popup "There are no staged changes" aparecer, clique em "Yes" para commitar tudo.
6. Em seguida, clique no botão Sync Changes → Upload (push) para o GitHub concluído.
7. Atualize o repositório no site do GitHub para ver o Concept.md que você acabou de enviar. Agora o Claude Code web também pode ler este documento.

Puxar (pull) também é feito na mesma tela: Se houver alterações que o Claude enviou para a nuvem, o botão Sync Changes cuidará tanto do download quanto do upload.

7. Conectando o Repositório ao Claude Code Web e Iniciando o Desenvolvimento

Agora abra o Claude Code web no seu navegador e conecte o repositório GitHub que você acabou de criar.

7-1. Conectando Claude Code Web ↔ Repositório GitHub (Apenas na Primeira Vez)

1. Acesse https://claude.ai/code → Faça login com sua conta Claude.
2. Quando você acessar pela primeira vez, um guia Connect GitHub aparecerá → Siga o guia.
3. Você será levado para a página do GitHub, e a tela de instalação do Claude GitHub App aparecerá:
4. Selecione sua conta do GitHub (ou organização).
5. Selecione o escopo de acesso: Recomenda-se selecionar "Only select repositories" e especificar o repositório criado em 6-1.
6. Clique em Install / Authorize.
7. Retornar ao Claude conclui a conexão. Se a tela de configurações do Ambiente aparecer, deixe-a como Default.
8. Ao iniciar uma nova sessão (tarefa), selecione seu repositório na lista de seleção de repositórios, digite um prompt e a tarefa começa.

7-2. Entendendo Como Funcionam o Claude Code e o Grok Build Web (Importante!)

O Claude Code e o Grok Build web funcionam em um computador virtual na nuvem, não no meu PC. O fluxo é:

① Eu digito um prompt

↓

② Claude Code/Grok Build clona meu repositório na nuvem e escreve o código

↓

③ Envia o resultado para o GitHub como um "novo branch de tarefa"

↓

④ Eu puxo esse branch para o meu PC para testar, ou verifico as alterações via Pull Request no GitHub

↓

⑤ Se eu gostar, faço o merge no main.

• Como ele sempre envia os resultados para um novo branch sem tocar no branch main diretamente, não há preocupação com a quebra do código existente. (O Grok Build trabalha no branch main, mas pode ser desfeito, então não se preocupe com erros).

7-4. Prompt de Início do Desenvolvimento

Assim que os três documentos (Concept.md / Design.md / ToDo.md) estiverem prontos no main, finalmente inicie o desenvolvimento em uma nova sessão.

Desenvolva este projeto. Prossiga com base nos seguintes documentos no repositório: - Concept.md: Descrição do aplicativo a ser criado - ToDo.md: Plano de desenvolvimento em nível de módulo (implemente nesta ordem) - Design.md: Padrões de design (toda a UI segue este documento)

Regras de Trabalho: 1. Prossiga um módulo de cada vez, de acordo com a ordem de implementação no ToDo.md. 2. Quando uma unidade testável for concluída, informe-me como executar/testá-la no meu PC local via README ou resposta. Como sou um não-programador, explique bem, como se estivesse ensinando um iniciante. 3. Marque os itens concluídos com um visto no ToDo.md. 4. Diga-me o nome do branch da tarefa e faça o push com uma mensagem de commit fácil de lembrar. 5. Se houver partes pouco claras, não adivinhe; pergunte-me.

7-5. Ciclo Repetido Durante o Desenvolvimento

① Claude Code web implementa um módulo em um branch de tarefa → push

↓

② Puxo esse branch de tarefa para o meu PC (VS Code) e executo/testo diretamente

↓

③ Se houver um problema → Copio toda a mensagem de erro e colo na sessão web

Se não houver problema → "Ok, continue com o próximo desenvolvimento"

↓

Retorno a ① para o próximo módulo

↓

④ Quando todas as funcionalidades estiverem concluídas e os testes aprovados

→ Faço o merge no branch main via Pull Request

→ A implantação é sempre baseada no main

8. Branch — Testando em Branches de Tarefa e Fazendo Merge no main para Implantação

8-1. O que é um branch?

• Branch main = A vitrine do produto finalizado que sempre funciona bem. A implantação é sempre baseada no main.
• Branch de tarefa (ex.: claude/feature-login) = Um canteiro de obras criado copiando o main. Você pode construir e quebrar coisas aqui à vontade; o main está seguro.

O Claude Code web sempre cria um novo branch de tarefa e envia os resultados. Portanto, há apenas três coisas que você precisa saber:

1. Como verificar em qual branch minha pasta está atualmente.
2. Como puxar o branch de tarefa enviado pelo Claude para o meu PC para teste.
3. Como fazer o merge no main e implantar quando terminar.

8-2. Verificando em Qual Branch Você Está

• Olhe para a barra de status no canto inferior esquerdo da tela do VS Code. O nome do branch é exibido ao lado do ícone de ramificação. (ex.: main ou claude/feature-login).

8-3. Puxando Branches de Tarefa Criados pelo Claude Code/Grok Build para o Meu PC para Teste

Quando o Claude Code web disser "Eu fiz push para o branch OO," traga esse branch para o meu PC para testar. O Grok Build tem um botão 'Push to Github' no canto superior direito da tela web, então pressione este botão para fazer o push.

Com VS Code (Apenas com o Mouse):

1. Clique no nome do branch no canto inferior esquerdo → A lista de branches abre.
2. Se o novo branch não estiver visível, execute ... menu → Fetch na aba Source Control e tente novamente.
3. Selecione o branch de tarefa do Claude começando com origin/claude/... na lista → Sua pasta muda para o estado desse branch.

8-4. Fazendo Merge no main Quando Terminar — Pull Request

Se as funcionalidades estiverem concluídas e os testes aprovados no branch de tarefa, faça o merge no main via Pull Request (PR) no site do GitHub.

1. Acesse seu repositório no GitHub → Clique na aba Pull requests.
2. Clique no PR que o Claude fez. Se não houver nenhum, New pull request → base: main, compare: selecione o branch de tarefa → Create pull request.
3. Clique em Merge pull request → Confirm merge → Refletido no main!
4. Atualize o main do seu PC para a versão mais recente:
5. Clique no branch no canto inferior esquerdo do VS Code → Selecione main → Sync Changes na aba Source Control.

9. Dicas de Prompting (Comuns)

A qualidade do Vibe Coding é proporcional à qualidade dos prompts.

1. Especifique o que NÃO fazer — "Não modifique o código arbitrariamente até que eu aprove", "Não adicione bibliotecas, use apenas a stack existente."
2. Um módulo de cada vez — A qualidade cai se você pedir o aplicativo inteiro em um único prompt. Peça em pequenas partes, de acordo com a ordem do ToDo.md.
3. Cole os erros como estão — Não resuma mensagens de erro; copie toda a saída do terminal.
4. Deixe o Claude perguntar se for ambíguo — Inclua "Se houver partes pouco claras, não adivinhe; pergunte-me" no prompt.
5. Comunique-se com base em documentos — "Como eu disse antes" ❌ → "De acordo com o design do Design.md" ✅. Documentos no repositório são muito mais estáveis do que a memória da conversa.

Fim.

Como o antigo Morpheus disse:

"Neo. Eu só posso te mostrar a porta. Você é quem tem que atravessá-la."