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:

Crie um app de finanças.

A melhor forma é dirigir o trabalho:

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:

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:

AGENTS.md
README.md
PLANS.md
exploracaodoprojeto/
docs/
.vscode/

Inicialize o Git:

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:

Leia exploracaodoprojeto/.
Entenda a ideia.
Produza um resumo crítico com escopo, riscos, dúvidas e sugestões.
Não implemente nada.

Resultado esperado:

docs/visao-geral.md
docs/requisitos.md
docs/riscos.md
docs/decisoes-iniciais.md

Fase 2: planejamento

Depois, em uma nova tarefa:

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:

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:

Crie o sistema inteiro.

Prefira:

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:

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:

git status
git add .
git commit -m "feat: implementa cadastro de clientes"
git push origin main

4. Modelo de AGENTS.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

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

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

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

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:

Pense no projeto, escolha a stack, implemente tudo e faça deploy.

Prefira:

Primeiro entenda.
Depois planeje.
Depois implemente uma etapa.
Depois teste.
Depois faça commit.

Use commits pequenos

Bons commits:

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:

alterações
update
projeto quase pronto
várias coisas

Tenha um contrato de validação

Exemplo Node:

npm run lint
npm test
npm run build

Exemplo Python:

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:

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:

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:

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.