--- title: "Manual de Boas Práticas de Vibe Coding com VS Code, Codex e GitHub" summary: "Um guia prático para conduzir projetos com agentes de IA, AGENTS.md, planejamento incremental, validações e Git." slug: "manual-boas-praticas-vibe-coding" language: "pt" publishedAt: "2026-05-20" updatedAt: null tags: - "guia" - "vscode" - "codex" - "github" translationOf: null translationStatus: "original" --- Vibe coding não é pedir código e torcer. É montar um ambiente onde um agente rápido consegue trabalhar com contexto, limite e validação. ## 1. Mentalidade correta A pior forma de começar é pedir algo genérico: ```txt Crie um app de finanças. ``` A melhor forma é dirigir o trabalho: ```txt Leia AGENTS.md e PLANS.md. Implemente apenas a primeira etapa. Antes de editar, diga quais arquivos pretende alterar. Depois rode lint, testes e build. ``` O agente precisa de: - contexto do projeto; - regras claras; - critérios de pronto; - comandos de validação; - limites do que não pode fazer; - histórico versionado no Git. O `AGENTS.md` funciona como um arquivo de instruções para agentes de IA. Ele é parecido com um `README.md`, mas orienta como o agente deve navegar, alterar, testar e documentar o projeto. ## 2. Estrutura recomendada Uma estrutura inicial simples: ```txt meu-projeto/ ├── AGENTS.md ├── README.md ├── PLANS.md ├── CHANGELOG.md ├── .gitignore ├── .env.example ├── exploracaodoprojeto/ │ ├── ideia.md │ ├── referencias.md │ ├── requisitos.md │ └── restricoes.md ├── docs/ │ ├── arquitetura.md │ ├── banco-de-dados.md │ └── backlog.md ├── src/ ├── tests/ └── .vscode/ ├── settings.json ├── tasks.json └── extensions.json ``` Essa divisão separa três camadas: - `AGENTS.md`: regras permanentes para o agente. - `exploracaodoprojeto/`: material bruto de ideia, referência e restrição. - `docs/`: documentação limpa, consolidada e revisável. ## 3. Fluxo recomendado ### Fase 0: preparar o repositório Antes de pedir implementação, crie a base: ```txt AGENTS.md README.md PLANS.md exploracaodoprojeto/ docs/ .vscode/ ``` Inicialize o Git: ```bash git init git add . git commit -m "chore: estrutura inicial do projeto" ``` ### Fase 1: exploração Não peça código ainda. Peça ao agente: ```txt Leia exploracaodoprojeto/. Entenda a ideia. Produza um resumo crítico com escopo, riscos, dúvidas e sugestões. Não implemente nada. ``` Resultado esperado: ```txt docs/visao-geral.md docs/requisitos.md docs/riscos.md docs/decisoes-iniciais.md ``` ### Fase 2: planejamento Depois, em uma nova tarefa: ```txt Com base no AGENTS.md, README.md e documentos em docs/, crie um plano de implementação incremental em PLANS.md. Não altere código ainda. ``` ### Fase 3: implementação incremental Agora sim: ```txt Implemente apenas a etapa 1 do PLANS.md. Antes de editar, explique quais arquivos pretende alterar. Depois implemente, rode validações e atualize documentação se necessário. ``` A regra de ouro é uma etapa por vez. Evite: ```txt Crie o sistema inteiro. ``` Prefira: ```txt Implemente autenticação local simples. Agora implemente o CRUD de clientes. Agora adicione testes. Agora refatore o service layer. ``` ### Fase 4: validação A cada etapa, peça: ```txt 1. Rode lint. 2. Rode testes. 3. Rode build. 4. Liste arquivos alterados. 5. Explique riscos restantes. 6. Sugira o próximo commit. ``` ### Fase 5: commit e sincronização Só depois de validar: ```bash git status git add . git commit -m "feat: implementa cadastro de clientes" git push origin main ``` ## 4. Modelo de AGENTS.md ```md # AGENTS.md ## Objetivo do projeto Este projeto tem como objetivo construir uma aplicação [descreva aqui a ideia central]. O agente deve ajudar no desenvolvimento incremental, priorizando clareza, segurança, testabilidade e simplicidade. ## Como trabalhar neste projeto Antes de implementar qualquer coisa: 1. Leia este AGENTS.md. 2. Leia o README.md. 3. Leia os arquivos relevantes em docs/. 4. Consulte PLANS.md se existir. 5. Faça um breve plano antes de alterar arquivos. ## Regras de implementação - Trabalhe em etapas pequenas. - Prefira código simples, legível e testável. - Evite abstrações prematuras. - Não sobrescreva mudanças manuais do usuário. - Atualize documentação quando o comportamento mudar. ## Critérios de pronto Uma tarefa só está pronta quando: 1. o código foi implementado; 2. os testes relevantes foram criados ou atualizados; 3. as validações foram executadas ou justificadas; 4. docs foram atualizadas se necessário; 5. riscos ou pendências foram listados. ``` ## 5. Prompts úteis ### Exploração ```txt Leia AGENTS.md e todos os arquivos dentro de exploracaodoprojeto/. Não implemente nada. Produza: 1. resumo da ideia; 2. requisitos funcionais; 3. requisitos não funcionais; 4. riscos técnicos; 5. dúvidas relevantes; 6. sugestão de stack; 7. escopo sugerido para MVP. ``` ### Planejamento ```txt Com base em AGENTS.md, README.md e docs/, crie um plano incremental em PLANS.md. O plano deve dividir o projeto em etapas pequenas, testáveis e commitáveis. Não altere código-fonte ainda. ``` ### Implementação ```txt Implemente apenas a etapa 1 do PLANS.md. Antes de editar arquivos, diga: 1. quais arquivos pretende criar ou alterar; 2. por quê; 3. quais comandos pretende rodar para validar. ``` ### Revisão ```txt Revise a implementação atual como code reviewer. Verifique: 1. bugs prováveis; 2. problemas de arquitetura; 3. duplicações; 4. falta de testes; 5. riscos de segurança; 6. documentação desatualizada. Não altere arquivos ainda. Primeiro apresente o diagnóstico. ``` ## 6. Boas práticas essenciais ### Nunca misture exploração, planejamento e implementação Evite: ```txt Pense no projeto, escolha a stack, implemente tudo e faça deploy. ``` Prefira: ```txt Primeiro entenda. Depois planeje. Depois implemente uma etapa. Depois teste. Depois faça commit. ``` ### Use commits pequenos Bons commits: ```txt chore: configura estrutura inicial docs: adiciona visão geral do projeto feat: implementa cadastro de clientes test: adiciona testes do serviço de clientes fix: corrige validação de email ``` Commits ruins: ```txt alterações update projeto quase pronto várias coisas ``` ### Tenha um contrato de validação Exemplo Node: ```bash npm run lint npm test npm run build ``` Exemplo Python: ```bash ruff check . pytest python -m compileall . ``` ## 7. Checklist antes de pedir implementação - Existe `AGENTS.md`? - Existe `README.md`? - Existe `PLANS.md`? - A ideia está documentada? - As restrições estão documentadas? - A stack foi escolhida? - O projeto está em Git? - Existe pelo menos um comando de validação? - O escopo da tarefa é pequeno? ## 8. Checklist depois de cada implementação - O agente listou arquivos alterados? - Os testes foram rodados? - O build foi rodado? - O lint foi rodado? - A documentação foi atualizada, se necessário? - O diff foi revisado? - Não há segredo no código? - Não há arquivo desnecessário versionado? ## 9. Erros comuns ### Pedir o projeto inteiro de uma vez Isso gera código grande, acoplado e difícil de corrigir. ### Não usar Git desde o começo Sem Git, você perde a capacidade de voltar para um estado bom. ### Não criar testes Sem testes, o agente corrige uma coisa e quebra outra. ### Não documentar decisões Depois de três sessões, ninguém lembra por que a stack foi escolhida. ### Deixar o agente escolher tudo sozinho O agente pode escolher uma stack desnecessariamente complexa. Imponha restrições: ```txt Prefira a solução mais simples possível. Não use microsserviços. Não use Docker no MVP, salvo necessidade clara. Não use autenticação externa antes do MVP validar a ideia. ``` ## 10. Regra de ouro para dados Antes de implementar persistência, peça: ```txt Antes de criar código, modele as entidades principais. Para cada entidade, indique: 1. campos; 2. tipos; 3. obrigatoriedade; 4. relacionamentos; 5. índices prováveis; 6. regras de validação; 7. exemplos de registros. ``` Salve em: ```txt docs/banco-de-dados.md ``` ## 11. Rotina ideal no VS Code 1. Abrir projeto. 2. Verificar branch atual. 3. Rodar testes. 4. Abrir `PLANS.md`. 5. Escolher uma pequena etapa. 6. Pedir ao agente para implementar só aquela etapa. 7. Revisar diff. 8. Rodar validações. 9. Commitar. 10. Sincronizar com GitHub. ## Manual em uma frase Use `AGENTS.md` para ensinar o agente como trabalhar, `exploracaodoprojeto/` para dar contexto bruto, `PLANS.md` para quebrar o projeto em etapas, VS Code para revisar diffs e GitHub para preservar cada avanço em commits pequenos.