Contexto é infraestrutura no vibe coding

Vibe coding não começa no prompt.

Começa no contexto.

Um agente sem contexto trabalha por aproximação. Ele tenta adivinhar o projeto, o tom, as restrições, a arquitetura e o critério de pronto.

Às vezes acerta. Muitas vezes só parece que acertou.

Contexto não é enfeite. É infraestrutura de trabalho.

Cada etapa pede um contexto próprio.

Diagnóstico não usa o mesmo contexto do planejamento.

Planejamento não usa o mesmo contexto da implementação.

Juntar tudo no mesmo prompt é pedir que o agente misture pergunta, decisão e execução.

O que conta como contexto

Contexto não é despejar tudo no chat.

Contexto bom é informação organizada, atual e útil para a tarefa.

Pode estar em:

• AGENTS.md;
• README.md;
• PLANS.md;
• documentação em docs/;
• código existente;
• testes;
• decisões registradas;
• critérios de pronto;
• comandos de validação.

O agente precisa entender onde está pisando.

Não para obedecer cegamente. Para agir com menos ruído.

O erro do chat único

Uma prática ruim é tentar rodar todo o vibe coding em um único chat, conversa ou tarefa.

Parece eficiente.

Não é.

Conversas longas acumulam intenção, correção, desvio, exceção e improviso. Depois de muitas voltas, ninguém sabe exatamente qual decisão ainda vale.

O agente perde nitidez.

A pessoa também.

Exploração, planejamento, implementação e revisão são fases diferentes. Misturar tudo em uma conversa só transforma o processo em uma massa difícil de auditar.

O mesmo vale para o prompt.

Não peça diagnóstico, planejamento e implementação no mesmo pedido.

Cada etapa deve ser uma tarefa separada, com entrada, objetivo e saída próprios.

Um projeto não deve depender da memória frágil de uma janela aberta.

Deve depender de arquivos, histórico, validações e decisões registradas.

Uma etapa por tarefa

O melhor fluxo é menor.

Mais simples.

Mais verificável.

Diagnóstico é uma tarefa.

Planejamento é outra.

Implementação é outra.

Elas devem acontecer nessa ordem.

E devem acontecer em prompts separados.

Essa regra também vale para qualquer prompt de exemplo.

Um prompt sugerido deve focar em uma única etapa: diagnóstico, planejamento ou implementação.

Se o prompt é de diagnóstico, ele não deve pedir plano.

Se o prompt é de planejamento, ele não deve pedir alteração de código.

Se o prompt é de implementação, ele deve partir de um plano aprovado e executar apenas uma parte dele.

O exemplo precisa ensinar a fronteira.

Não apenas resolver o caso.

Diagnóstico

O diagnóstico serve para entender o estado atual.

Ele não deve planejar a solução inteira.

Ele não deve editar arquivos.

Etapa: diagnóstico.

Leia AGENTS.md, README.md e os documentos relevantes.
Faça apenas um diagnóstico.
Não implemente nada.
Não crie plano detalhado ainda.
Liste contexto encontrado, lacunas, riscos e dúvidas.

Planejamento

O planejamento serve para transformar diagnóstico em sequência de trabalho.

Ele não deve implementar.

Ele deve criar etapas pequenas, verificáveis e ordenadas.

Etapa: planejamento.

Com base no diagnóstico aprovado, crie um plano incremental.
Não altere código.
Separe as etapas por objetivo, arquivos prováveis e validações.
Indique a primeira etapa pequena o bastante para implementação isolada.

Implementação

A implementação serve para executar uma etapa específica do plano.

Ela não deve reabrir todo o diagnóstico.

Ela não deve reinventar o planejamento.

Etapa: implementação.

Implemente apenas a etapa 1 do plano aprovado.
Antes de editar, diga quais arquivos pretende alterar.
Depois rode as validações disponíveis.
Liste arquivos alterados, riscos e pendências.

Esses prompts são limitados de propósito.

Limite não atrapalha o agente. Limite dá direção.

Se o prompt pede diagnóstico, planejamento e implementação ao mesmo tempo, ele já começou errado.

Vibe coding bom não é uma grande sessão heroica.

É uma sequência de ciclos claros.

Skills não são decoração

Skills existem para ampliar a capacidade do agente em situações específicas.

Essa é a parte importante: específicas.

Usar uma skill sem necessidade é uma má prática.

Ela pode adicionar instruções demais, chamar ferramentas erradas, aumentar o custo da tarefa, produzir arquivos desnecessários ou deslocar o foco do problema real.

Nem toda tarefa precisa de uma skill.

Corrigir um texto simples não exige o mesmo aparato de criar uma apresentação. Ajustar um post não exige o mesmo fluxo de investigar uma falha de CI. Implementar uma pequena alteração de layout não exige transformar a tarefa em pesquisa ampla.

A pergunta correta é:

Esta skill ajuda diretamente a etapa atual?

Se a resposta for não, não use.

Ferramenta boa também precisa de hora certa.

Contexto demais também atrapalha

Existe o outro erro: enviar contexto demais.

Um agente não melhora só porque recebeu mais arquivos, mais links, mais regras e mais histórico.

Ele melhora quando recebe o contexto relevante.

Antes de pedir qualquer etapa, vale separar:

• o objetivo daquela etapa;
• os arquivos prováveis;
• as restrições;
• os exemplos importantes;
• os comandos de validação;
• o que não deve ser alterado.

O resto pode esperar.

Contexto bom é recorte.

Como dividir uma tarefa grande

Quando a ideia for grande, não peça tudo.

Transforme em etapas.

1. Diagnóstico: entenda o problema, o repositório e os riscos. Não planeje em detalhe. Não implemente.
2. Planejamento: transforme o diagnóstico aprovado em etapas pequenas. Não implemente.
3. Implementação: execute apenas uma etapa aprovada.
4. Validação: rode os comandos disponíveis e revise o resultado.
5. Registro: documente decisões, riscos e próximos passos.
6. Próxima etapa: só avance depois que a anterior estiver validada.

Esse fluxo protege o projeto.

Também protege a sua cabeça.

Você não precisa decidir tudo em um único fôlego. Precisa criar condições para a próxima decisão ser melhor.

Um prompt ruim

Etapa declarada: diagnóstico.

Faça o diagnóstico.
Depois, na mesma tarefa, crie o plano e implemente tudo que for necessário
para resolver o projeto inteiro.

Esse pedido abre portas demais.

O agente terá que diagnosticar, decidir e executar ao mesmo tempo.

Pode parecer produtivo no começo. Mas o custo aparece depois, quando cada ajuste exige desfazer escolhas que nunca foram realmente decididas.

Um prompt melhor

Etapa: diagnóstico.

Leia AGENTS.md e docs/convencoes-conteudo.md.
Faça apenas o diagnóstico para a publicação de um novo post.
Não planeje a implementação.
Não edite arquivos.
Liste contexto encontrado, riscos, dúvidas e próximos passos sugeridos.

Esse pedido tem fronteira.

Ele separa leitura de decisão. Separa decisão de execução. Evita que uma boa ideia vire mudança automática antes da revisão humana.

É assim que o agente trabalha melhor.

Não por liberdade total.

Por direção suficiente.

O princípio

Contexto é a diferença entre pedir ajuda e dirigir trabalho.

Skills devem entrar quando servem ao ciclo atual.

Conversas devem ser pequenas o bastante para serem compreendidas.

Tarefas devem ser pequenas o bastante para serem validadas.

Diagnóstico, planejamento e implementação devem ser separados.

Sempre em sequência.

Nunca no mesmo prompt.

O projeto deve carregar sua própria memória.

Vibe coding não é deixar a máquina correr.

É criar um ambiente onde ela corre na direção certa.