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 o commit inicial

↓

[6] Passar a descrição do aplicativo + 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 criados no Figma, etc.

Método

• Escolha um site realmente implantado de 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 toda 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 do 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 desenvolvedor 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 um relacional for exigido, 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 como essa, 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 das principais tarefas (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, métricas principais e 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 estiverem 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 utilizada / 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 de dependência)
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 núcleo 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 até a morte, por favor, 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 "Avançar" com todos os valores padrão.
4. No entanto, quando a tela "Escolhendo o editor padrão" aparecer, é bom selecionar "Usar o Visual Studio Code como editor padrão do Git" (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 para Windows.
2. Execute o instalador → Continue clicando em "Avançar". No entanto, marque estas duas opções na tela de opções:
3. "Adicionar ao PATH"
4. "Adicionar ação 'Abrir com Code' ao menu de contexto de arquivos/diretórios"
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 pop-up de guia de instalação ("Ferramentas de Desenvolvedor de Linha de Comando...") aparecer, clique em "Instalar" 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 para macOS.
2. Descompacte o arquivo baixado e arraste o Visual Studio Code.app para a pasta Aplicativos. (Importante! Não use diretamente da pasta Downloads).
3. Execute o VS Code a partir de Aplicativos.

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 → Novo repositório.
3. Preencha da seguinte forma:
4. Nome do repositório: Nome do projeto (em inglês, use hífens em vez de espaços. Ex.: my-first-app)
5. Selecione Privado (Projetos de empresa devem ser Privados!)
6. Marque a caixa "Adicionar um arquivo README" ✅ ← Iniciantes devem marcar isso. Isso torna a próxima etapa (clone) mais simples.
7. Clique em Criar repositório.
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: Clonar".
4. Cole o endereço do repositório copiado e pressione Enter.
5. Você também pode selecionar "Clonar do GitHub" → Se o navegador abrir e pedir login/autorização do GitHub, aprove. (Apenas na primeira vez).
6. Selecione um local para salvar o projeto (ex.: é bom criar uma pasta Documentos/Projetos).
7. Quando a clonagem terminar, uma notificação "Abrir" 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 → Novo Arquivo → 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 selo numérico aparece no ícone em forma de ramificação (Controle de Código Fonte) à 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 pop-up "Não há alterações preparadas" aparecer, clique em "Sim" para commitar tudo.
6. Em seguida, clique no botão Sincronizar Alterações → 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 Sincronizar Alterações 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 Conectar GitHub aparecerá → Siga o guia.
3. Você será direcionado para a página do GitHub, e a tela de instalação do aplicativo Claude GitHub aparecerá:
4. Selecione sua conta do GitHub (ou organização).
5. Selecione o escopo de acesso: É recomendado selecionar "Apenas repositórios selecionados" e especificar o repositório criado em 6-1.
6. Clique em Instalar / Autorizar.
7. Retornar ao Claude conclui a conexão. Se a tela de configurações do Ambiente aparecer, deixe como Padrão.
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/testar no meu PC local através do README ou resposta. Como sou um não desenvolvedor, explique bem, como se estivesse ensinando um iniciante. 3. Marque os itens concluídos com uma marca de verificação no ToDo.md. 4. Diga-me o nome do branch da tarefa e faça 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 a mensagem de erro inteira 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 todos os recursos estiverem concluídos e os testes aprovados

→ Faç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 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 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 → Buscar na aba Controle de Código Fonte 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 os recursos estiverem concluídos 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 → Sincronizar Alterações na aba Controle de Código Fonte.

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 estiver 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."