Seis regras contra vibe coding dentro do AI-DLC

O ciclo de vida segura o vibe coding nos gates. Não faz nada pelo engenheiro que abre o arquivo e corrige na mão.

Vibe coding é o hábito de mandar prompt para um agente até a coisa parecer funcionar, sem ler o código nem decidir nada de propósito. O AI-DLC foi desenhado como o oposto: especificar primeiro, deixar a IA conduzir, aprovar cada passo num gate. No papel, um time rodando AI-DLC não consegue fazer vibe coding.

Na prática, ele volta, entre os gates. Alguém vê um bug no código gerado e corrige direto. Alguém faz uma pergunta curiosa ao agente e o agente reescreve uma spec em resposta. Alguém pergunta ao agente se o próprio design dele está bom, na mesma conversa em que ele escreveu esse design. Nada disso quebra uma regra do método. Tudo isso desfaz o método sem fazer barulho.

As seis regras abaixo não são minhas. Elas vêm de um time que roda AI-DLC em produção e que as escreveu depois de ver os próprios engenheiros cometerem esses erros. Reescrevi com as minhas palavras e acrescentei o raciocínio que eu vi por trás de cada uma. As palavras para digitar são a parte para roubar.

Por que um ciclo de vida ainda deixa vazar vibe coding

Toda regra desta lista existe pelo mesmo motivo: o atalho é mais rápido agora, e o custo aparece depois, em outro lugar.

O AI-DLC mantém uma cadeia de artefatos, dos requisitos ao design e ao código, e cada um deveria descrever o seguinte. Essa cadeia é a memória que o agente usa em toda sessão futura. No momento em que você muda o código sem mudar o design, a cadeia mente. Na próxima vez que o agente gerar código para aquela área, ele constrói a partir de um design que não bate mais com a realidade, e a sua correção some sem aviso ou bate de frente com o que ele escreve.

Um dos desafios levantados no piloto resumiu bem: é tentador, e mais rápido no curto prazo, corrigir o erro em vez de corrigir o que fez o erro acontecer. Cada regra aqui te obriga a corrigir a causa.

Corrigir o erro

1. 01Remendar o código gerado na mão
2. 02Pedir para o agente só fazer o teste passar
3. 03Seguir numa sessão longa e cansada
4. 04Confiar no review que o agente faz do próprio trabalho

Corrigir a causa

1. 01Corrigir o design, depois gerar de novo
2. 02Achar qual requisito ou decisão estava errado
3. 03Fazer commit, limpar o contexto, retomar pelo estado
4. 04Pegar a crítica num contexto limpo

As seis regras

Seis regras, e o que digitar

1. 01

   Nunca edite código gerado na mão. Volte para o design.

   Um remendo manual faz os artefatos mentirem sobre o código. A próxima geração constrói a partir do design antigo e desfaz a sua correção, ou briga com ela.

   Em vez de

   Abrir o arquivo, mudar três linhas, fazer commit e seguir.

   Digite isto

   I found a problem in the order service: cancelled orders keep their stock reservation. Let's review the design and make a plan to fix it.

2. 02

   Coloque um prefixo em toda pergunta exploratória.

   Sem o prefixo, o agente lê uma pergunta curiosa como pedido de mudança e edita a spec no meio da conversa.

   Digite isto

   Do not update any documents. What happens if we move the reservation release into a background job?

3. 03

   Antes de uma mudança grande, peça o impacto sem editar.

   Uma mudança grande de design em cima de trabalho já aprovado se propaga por requisitos, histórias e Units prontas. Você quer o mapa do estrago antes de aprovar a mudança.

   Digite isto

   Do not change anything. Assess the impact of splitting the order service in two on the requirements, the user stories, and the Units already implemented.

4. 04

   Diga ao agente quais bibliotecas internas existem antes de ele escrever código.

   Toda empresa tem os próprios starters e bibliotecas para autenticação, tracing e feature flags. Um agente que não conhece essas bibliotecas inventa dependências ou reescreve o que você já tem.

   Digite isto

   Before generating code, read docs/internal-libraries.md. Use these for auth, tracing, and feature flags, and do not add a dependency that duplicates one of them.

5. 05

   Peça a segunda opinião num contexto limpo.

   Na mesma conversa, o agente defende as decisões que tomou. Ele racionaliza. Um contexto limpo lê o artefato como um estranho leria.

   Digite isto

   /clear
   Read design/order-service.md. Produce a critique of it as if you hadn't written it.

6. 06

   Limpe o contexto em todo gate de aprovação, depois de fazer commit e push.

   A qualidade cai conforme a sessão cresce: tentativas erradas, idas e vindas, rascunhos velhos. Limpar no gate obriga o agente a reconstruir o contexto só a partir do que é oficial, os arquivos aprovados e o estado.

   Digite isto

   git add -A && git commit -m "Approve requirements" && git push
   /clear

Regra um: a fonte da verdade é o design, não o código

É a regra que os times mais quebram, porque parece desperdício. O bug está ali. A correção são três linhas. Por que voltar para um documento de design?

Porque no AI-DLC o documento de design não é documentação. É a entrada da próxima geração. Remende o código e, na próxima vez que alguém pedir para o agente mexer naquela área, ele gera de novo a partir do design antigo e a sua correção some, ou pior, some pela metade. Corrija o design e gere de novo, e a correção sobrevive a todas as sessões futuras.

Tem um segundo retorno. Voltar para o design faz a pergunta que um remendo nunca faz: por que o agente errou isso? Muitas vezes a resposta é um requisito faltando ou uma resposta ambígua no arquivo de perguntas. Corrigir isso corrige uma classe de bugs, não um bug.

Regras dois e três: pergunta não é instrução

Um agente trabalhando dentro do AI-DLC está pronto para agir. Ele tem artefatos abertos, um workflow para avançar e uma tendência forte de tratar qualquer coisa que você diga como pedido para mudar algo. Então, quando você pergunta “e se a gente fizesse isso de outro jeito?”, muitas vezes ele faz de outro jeito, ali mesmo, na spec.

O prefixo é a proteção mais barata desta lista. “Do not update any documents” transforma o agente de executor em consultor por uma resposta. Use toda vez que você estiver pensando em voz alta.

A regra três é a mesma ideia numa escala maior. Antes de aprovar uma mudança que mexe na arquitetura, peça o impacto como relatório, com a edição explicitamente proibida. Você recebe uma lista de requisitos, histórias e Units prontas que a mudança invalidaria. Aí você decide, com o custo na sua frente, em vez de descobrir um arquivo regenerado de cada vez.

Regra quatro: o agente não conhece a sua empresa

Um modelo leu boa parte da internet pública. Não leu o seu starter interno de autenticação, a sua biblioteca de tracing nem o cliente de feature flags que todo serviço deveria usar. Deixado sozinho, ele pega o equivalente open source popular, e você recebe um pull request que adiciona uma dependência que o seu time de plataforma passou um ano removendo.

A solução é avisar, explicitamente, antes de a geração de código começar. Mantenha um documento curto que liste as bibliotecas internas, para que serve cada uma e quais alternativas públicas são proibidas e por quê. O porquê importa. Um agente avisado de “não use a biblioteca X” vai achar a biblioteca Y. Um agente avisado de “a gente usa o nosso próprio cliente porque ele cuida de retries e dos headers de tenant” vai procurar o nosso cliente.

Esse também é o tipo de correção que o AI-DLC 2 consegue tornar permanente. Quando você corrige o agente durante um estágio, o loop de aprendizado dele oferece guardar a correção como regra do projeto, e essa regra vale a partir do próximo workflow. Diga sim para essa. Você só quer digitar isso uma vez.

Regra cinco: nunca peça para o autor revisar a si mesmo

Pergunte a um agente, na mesma conversa, se o design que ele acabou de escrever está bom, e ele vai explicar por que está bom. Isso não é desonestidade. O raciocínio que produziu o design ainda está no contexto dele, e ele lê o próprio trabalho através desse raciocínio.

Limpe o contexto, carregue só o artefato e peça uma crítica como se ele não tivesse escrito aquilo. A diferença no que volta é grande. Ele acha a suposição que fez em silêncio, o caso que não tratou, o requisito que leu sem rigor.

O AI-DLC 2 já embute parte disso. Os agentes revisores rodam como subagents separados depois que um estágio produz os artefatos, então eles leem o trabalho sem o raciocínio do autor no contexto. É o mesmo princípio. Use, e mantenha o hábito para todo artefato que os revisores não cobrem.

Regra seis: a conversa é descartável, os arquivos não

Sessões longas degradam. A janela enche de tentativas erradas, correções e rascunhos que foram substituídos três passos atrás, e o agente começa a perder o fio das decisões que tomou antes. Nos times que eu acompanhei, a qualidade caía visivelmente quando a context window passava de uns três quartos.

A resposta é tratar a conversa como papel de rascunho. Em todo gate de aprovação, faça commit e push dos artefatos aprovados, depois limpe o contexto. O agente retoma a partir do arquivo de estado e dos arquivos aprovados, que são exatamente as coisas que deveriam ser verdadeiras. O que vai para o lixo é o ruído.

A ordem importa. Primeiro o commit, depois a limpeza. Limpe primeiro e você pode perder o único artefato de que a próxima sessão precisava. Se uma sessão travou numa investigação longa, peça ao agente um resumo curto do que ele achou e do que descartou antes de limpar, e carregue esse resumo na sessão nova. O gerenciamento de tudo isso numa codebase grande está em AI-DLC em brownfield.

Regra sete: limite o tamanho de toda Unit

A lista do time tinha seis regras. O rollout ensinou a sétima, e é a que tem o efeito mais mensurável.

Quando o AI-DLC gera código, ele gera muito, rápido. Antes da construção, o agente divide o trabalho em Units, as partes independentes que são construídas e revisadas separadamente. Deixado sozinho, ele propõe sem a menor cerimônia uma Unit que entrega uma feature inteira: migration, entidade, API, testes, tudo num merge request com centenas de mudanças. Ninguém revisa isso com atenção de verdade. O throughput sobe, os merge requests se acumulam no review, e o tempo entre o primeiro commit e o deploy piora em vez de melhorar. Esse padrão tem artigo próprio: por que o AI-DLC te deixa mais lento primeiro.

A correção acontece quando o agente propõe as Units. Peça para ele estimar o tamanho de cada uma, e divida qualquer uma acima de um limite que o seu time combinar. Cem mudanças por merge request é um ponto de partida razoável. Um review de cinquenta mudanças dá para fazer. Um review de trezentas mudanças é carimbo.

A sétima regra

1. 01

   Limite o tamanho de cada Unit antes de aprovar o plano.

   O review vira o gargalo quando gerar fica barato. Uma Unit pequena recebe um review de verdade. Uma enorme recebe uma olhada. Decida o limite com quem revisa, e escreva, para as próximas sessões respeitarem.

   Digite isto

   Before I approve the Units, estimate the files and lines each one will change. Split any Unit above about a hundred changes: one per endpoint, and migrations in a Unit of their own.

O que o AI-DLC 2 já garante para você

O motor novo fecha algumas dessas portas sozinho, e vale saber quais, para não brigar com a ferramenta.

Ele roda cinco guardas que chama de fences, que recusam trabalho que ninguém pediu. Elas reabrem uma aprovação quando algo que você já aprovou foi mudado por baixo, congelam um artefato enquanto ele está em review, bloqueiam escrita direta no estado do workflow, mantêm os revisores dentro do escopo de leitura deles e exigem que uma pessoa de verdade responda o gate. Uma configuração chamada Guard Policy decide o quanto as quatro primeiras seguram. Nada afrouxa a última. Toda Unit também precisa da própria aprovação de plano. O comando que verifica cada Unit é escolhido e autorizado por uma pessoa, e mudá-lo exige uma autorização nova. Os revisores rodam no próprio contexto. O arquivo de estado sobrevive à compactação de contexto.

O que ele não consegue garantir são as suas mãos no teclado. Nada no motor te impede de abrir um arquivo gerado no editor e mudar. Nada te impede de fazer uma pergunta curiosa sem o prefixo. As guardas protegem o workflow. As regras protegem o código.

Coloque as regras onde o agente lê

Uma regra que mora na wiki do time é lembrada nos dias bons. Uma regra que mora onde o agente lê é aplicada todo dia, pelo agente, na sessão de cada engenheiro.

Coloque as bibliotecas internas, o limite de tamanho das Units e os prefixos nas instruções do seu agente. Pode ser o seu AGENTS.md, o seu CLAUDE.md ou, no AI-DLC 2, o arquivo de memória do time que todo workflow carrega no começo. Deixe as regras só para pessoas, como fazer commit antes de limpar, no onboarding de quem roda o workflow.

Você está fazendo vibe coding dentro do AI-DLC?

• ✗Anti-pattern:
  Alguém corrigiu código gerado na mão esta semana.Confira se o design também foi atualizado. Se não foi, a próxima geração vai desfazer a correção.
• ✗Anti-pattern:
  Uma spec mudou numa conversa que deveria ser uma pergunta.Faltou o prefixo. O agente tomou a pergunta como instrução.
• ✗Anti-pattern:
  O agente revisou o próprio design na mesma sessão.Aquele review foi uma defesa, não uma crítica.
• ✗Anti-pattern:
  Uma sessão passou de três quartos da context window.A qualidade da saída já estava caindo. Commit, limpar, retomar.
• ✗Anti-pattern:
  Um merge request com centenas de mudanças foi aprovado em minutos.Ninguém revisou. Da próxima vez, divida as Units antes da construção.
• ✓Obrigatório:
  A lista de bibliotecas internas mora onde o agente lê.Aí ninguém precisa lembrar de colar.

Perguntas frequentes

O que é vibe coding?+

Vibe coding é mandar prompt para um agente de IA até o resultado parecer funcionar, sem ler o código nem tomar decisões deliberadas sobre ele. Serve para um protótipo descartável. Quebra quando o código precisa ser mantido, porque ninguém decidiu nada e ninguém entende o que foi construído.

Dá para fazer vibe coding dentro do AI-DLC?+

Dá, entre os gates. O ciclo de vida confere a saída de cada fase, mas não consegue impedir um engenheiro de remendar código gerado na mão, de fazer perguntas exploratórias que o agente transforma em edições ou de deixar o agente revisar o próprio trabalho. Esses hábitos desfazem o método sem quebrar nenhuma regra dele.

Por que não corrigir na mão um bug pequeno no código gerado?+

Porque no AI-DLC o design é a entrada da próxima geração. Um remendo manual faz o design e o código discordarem, e na próxima vez que o agente mexer naquela área ele gera de novo a partir do design antigo e a sua correção some. Corrija o design, depois gere de novo.

Perco o meu trabalho quando limpo o contexto?+

Não, se você fizer commit e push antes. O AI-DLC guarda o trabalho em arquivos versionados e num arquivo de estado que registra onde você parou. Limpar o contexto joga fora a conversa, que a essa altura é ruído, e o agente retoma a partir dos arquivos.

Qual deve ser o tamanho de uma Unit de trabalho?+

Pequena o bastante para uma pessoa revisar o merge request dela com atenção de verdade. Um primeiro limite razoável é por volta de cem mudanças por merge request. Combine um número com quem faz os reviews, peça ao agente para estimar o tamanho de cada Unit antes de aprovar o plano e divida qualquer uma acima disso.

Para onde ir agora

O AI-DLC te dá gates. Estas regras são o que você faz entre eles. O padrão por baixo das sete é o mesmo: corrija a causa, não o sintoma, e mantenha os arquivos verdadeiros, porque os arquivos são a única memória que o agente tem.