No artigo anterior, resumi três custos do Vibe Coding — em outras palavras, os problemas que surgem quando você desenvolve sem ler o código.
Os bugs ficam impossíveis de corrigir, a mesma funcionalidade aparece em vários lugares e uma brecha de segurança silenciosa é criada. Como soluções, sugeri ler apenas as áreas críticas, ler resumos gerados por IA e executar scanners.
Mas essas soluções têm algo em comum: todas são verificações posteriores, que detectam o problema só depois que algo dá errado.
Este artigo vai um passo além: como impor regras para impedir que a IA crie esse tipo de código desde o início, antes da verificação.
As ferramentas já estão disponíveis. São arquivos de regras como CLAUDE.md, .cursorrules e AGENTS.md.
O resultado do Vibe Coding é decidido na etapa de escrever o primeiro arquivo de regras, não na de ler o código.
Por que arquivos de regras? — A IA é uma pessoa recém-contratada em todas as sessões
Vamos começar por uma característica fundamental das ferramentas de programação com IA: quando a sessão termina, a IA esquece a maior parte do conteúdo.
Mesmo que ontem você tenha dito para “tirar as chaves de API e colocá-las em variáveis de ambiente”, na nova sessão de hoje essa conversa deixa de existir.
Por isso, as instruções repetidas em todas as sessões precisam ser registradas em um arquivo, não ficar apenas na conversa.
CLAUDE.md (Claude Code), .cursorrules (Cursor) e AGENTS.md (ferramentas de uso geral, como o Codex) são exemplos. Esses arquivos de regras são adicionados automaticamente ao prompt sempre que uma sessão começa.
Para uma pessoa, eles são como documentos de onboarding entregues a uma pessoa recém-contratada que chega ao trabalho todas as manhãs.
Isso combina especialmente bem com vibe coding porque, por definição, vibe coding é uma forma de programar sem que as pessoas leiam o código.
Algo precisa preencher o espaço deixado pela revisão humana, e o primeiro candidato são as regras aplicadas no momento da geração. É muito mais barato impedir a criação de código ruim do que filtrá-lo depois.
Aos três problemas do episódio anterior, somaremos dois erros próprios da IA que só podem ser detectados lendo o código. Veja como impedir os cinco com regras.
Regra 1. Segurança — Escreva não apenas “não faça”, mas também “faça assim”
Vamos começar pelas chaves de API codificadas diretamente que vimos no episódio anterior. No arquivo de regras, escreva assim:
## Regras de segurança (em caso de violação, interromper a geração de código e relatar)
- API Nunca codifique chaves, tokens ou senhas diretamente no código.
Leia sempre de variáveis de ambiente(.env) ou de um gerenciador de segredos.
- .env Nunca faça commit do arquivo. .env.example; faça commit apenas de.
- Não confie na entrada do usuário. SQL; use vinculação de parâmetros,
HTML Use escape na saída por padrão.
- Ao escrever código para excluir arquivos·DB , migrações ou chamadas API de pagamentos externos,
sempre peça a confirmação do usuário antes da execução.
- Não instale bibliotecas novas sem autorização. Primeiro proponha o nome do pacote e
o motivo da escolha e só então adicione-o, após a aprovação.Aqui há dois pontos principais.
Primeiro, escreva a alternativa junto com a proibição. Se você disser apenas “Não use hardcode”, a IA terá de encontrar um desvio por conta própria.
Se você escrever “Leia de uma variável de ambiente”, ela seguirá esse caminho sem hesitar. A taxa de conformidade com uma regra é proporcional à especificidade da alternativa.
Segundo, use procedimentos diferentes para tarefas com diferentes níveis de risco. Se você determinar que exclusões, pagamentos e migrações exigem “confirmar antes de prosseguir”, o fluxo freará justamente nesses pontos, mesmo quando todo o restante seguir o processo de Accept All.
A regra de dependências na última linha também é uma extensão da segurança. Uma pesquisa constatou que 5–21% dos nomes de pacotes recomendados pela IA não existem de fato nos registros, mas o mais preocupante vem depois.
Atacantes se antecipam e registram nomes falsos que a IA costuma inventar para publicar pacotes maliciosos com eles. Ataques de slopsquatting estão realmente acontecendo.
No vibe coding, em que até os comandos de instalação passam com Accept All, esse caminho pode levar diretamente a um incidente na cadeia de suprimentos. Por isso, é mais seguro estabelecer como procedimento que novos pacotes sejam propostos e aprovados depois.
Regra 2. Duplicação — Formalize “pesquise antes de criar”
O motivo de a mesma funcionalidade surgir em vários lugares não é que a IA seja preguiçosa. A IA trata como inexistente o código que não consegue ver no contexto.
À medida que o projeto cresce, o código inteiro deixa de caber no contexto. Assim, criar uma nova função semelhante se torna uma escolha razoável do ponto de vista da IA.
Por isso, forçamos a exploração por meio de uma regra.
## Regra de prevenção de duplicação
- Antes de criar uma nova função ou componente, sempre pesquise no código existente
para verificar se já existe algo com a mesma função.
- O tratamento de datas src/utils/date.ts, API as chamadas vão src/lib/api.tspara
Use uma função existente. Se não houver, adicione-a ao arquivo.
- Extraia imediatamente para um módulo compartilhado a lógica usada em dois ou mais lugares.
- Se parecer necessário criar uma função quase igual a uma existente, não crie outra
Primeiro avalie se é possível estender a função existente e sugira isso ao usuário.A segunda linha é especialmente eficaz. Um mapa dizendo “o tratamento de datas está neste arquivo” funciona muito melhor do que a regra abstrata “não crie duplicações”.
Mesmo que a AI pule a busca, os caminhos registrados no arquivo de regras estão sempre à vista. Manter uma lista das localizações dos módulos compartilhados do projeto nesse arquivo reduz significativamente a criação de duplicações.
Regra 3. Arquitetura — Transforme a estrutura de pastas e a direção das dependências na constituição
Das três, a arquitetura é a que desmorona de forma mais silenciosa. Incidentes de segurança são percebidos quando acontecem e duplicações aparecem quando você pesquisa, mas, na arquitetura, um dia você olha para trás e ela já virou um espaguete.
A AI tende a escrever “o código que resolve esta solicitação da forma mais rápida agora”. Por isso, abre atalhos entre camadas sem hesitar.
Por exemplo, chamar o banco de dados diretamente a partir de uma view.
Isso também pode ser impedido com regras. O ponto central é explicitar a estrutura e a direção das dependências.
## Regras de arquitetura
Estrutura do projeto:
- src/views/ : UI. Lida apenas com estado e eventos
- src/services/ : Lógica de negócio
- src/repositories/ : Acesso a dados. DB·API as chamadas acontecem somente aqui
A direção das dependências é views → services → repositories unidirecional.
- viewsnão repositoriesdiretamente import
- repositoriesnão views import
- Novos recursos também devem seguir esta 3estrutura em camadas.
Se houver um motivo para sair da estrutura, explique-o ao usuário antes de escrever o códigoO verdadeiro valor desta regra aparece depois que o esqueleto inicial está definido.
A IA tende a imitar fortemente os padrões do código existente. Se o código inicial seguir a arquitetura de três camadas, o código posterior naturalmente seguirá a mesma linha.
Por outro lado, se um único atalho for aberto no início, a IA aprenderá isso como “um padrão permitido neste projeto”.
Por isso o subtítulo deste artigo é “O esqueleto inicial”.
Logo após criar o projeto, defina primeiro o arquivo de regras e a estrutura de pastas, enquanto o código ainda tem 10 linhas. Isso custa centenas de vezes menos do que refatorar 10 mil linhas depois.
Regra 4. Critério de conclusão — distinguir “parece pronto” de “está pronto”
A partir daqui, veremos um tipo de raciocínio próprio da programação com IA que não foi abordado no artigo anterior.
A IA costuma dizer “Concluído” sem verificar nada quando termina de escrever o código. Mesmo quando o código nem sequer compila.
Em um fluxo de trabalho no qual uma pessoa lê o diff, isso é descoberto rapidamente, mas no vibe coding você confia apenas na palavra “concluído” e passa para a próxima solicitação. Por isso, a definição de concluído precisa ser estabelecida como uma regra.
## Regra de definição de concluído
- Antes de declarar o trabalho concluído, sempre typecheck·lint·execute os testes
e informe os resultados junto com eles
- Se um teste falhar, corrija o código. Não modifique nem exclua os testes para fazê-los passar
Se você julgar que o próprio teste está errado, não o force a passar; em vez disso
informe primeiro sem alterá-lo
- Não envolva os erros para try/catchengoli-los silenciosamente.
Sempre registre os erros capturados ou propague-os para cimaA segunda regra é o ponto central. Quando o objetivo dado à IA é “faça os testes passarem”, ela pode acabar corrigindo os testes que falham em vez de corrigir o código.
Ela encontrou o caminho mais curto para atingir o objetivo. Quem não lê o código pode ver apenas a luz verde sem perceber que o mecanismo de validação foi neutralizado.
A terceira regra está diretamente ligada ao problema 1 da parte anterior (ficar impossibilitado de corrigir bugs).
A IA tende a envolver o código em um try/catch que engole os erros sob o pretexto de escrever de forma defensiva. Assim, mesmo quando surge um problema, a tela pode parecer normal. Mais tarde, as mensagens de erro realmente necessárias não estarão registradas em lugar algum, tornando a depuração ainda mais difícil.
Regra 5. Escopo — Faça apenas o que foi solicitado
Outro erro clássico da programação com IA é fazer coisas que ninguém pediu, o chamado scope creep. Você pede para mudar a cor de um botão e ela, “já que está por ali”, refatora o código ao redor, extrai novas funções auxiliares e até altera a estrutura de arquivos.
Pode parecer uma boa intenção, mas no vibe coding isso é perigoso. Se você não lê o diff, pode não perceber mudanças não solicitadas no meio do trabalho e, quando algo quebrar depois, o número de causas possíveis aumenta várias vezes.
## Regras de escopo
- Faça apenas o trabalho solicitado. Liste as melhorias encontradas durante o trabalho e sugira-as
depois de concluí-lo, sem alterar o código
- Não modifique arquivos sem relação com a solicitação
- Só faça refatoração quando isso for solicitado separadamenteO efeito também pode ser confirmado por números. Segundo os dados, adicionar algumas linhas de regras de escopo ao arquivo de regras reduziu a taxa de revert e de desvios de escopo de 41% para 12%.
Esses números vêm de um relatório de medição em campo realizado por 30 dias. Entre os cinco tipos de regras, esse eixo tem o maior retorno sobre o investimento.
Regras sozinhas não bastam — use um bloqueio duplo
Depois de ler até aqui, você pode pensar: “Então, se eu escrever boas regras, não preciso ler o código”. Mas existe uma armadilha: regras aumentam a probabilidade de conformidade, mas não são uma garantia.
A IA pode esquecer as regras quando o contexto fica longo e, quando está com pressa — ou, mais precisamente, quando a situação parece ser essa — pode escolher atalhos.
Por isso, quanto mais importante for a regra, mais ela deve ser combinada com uma verificação mecânica. A regra é o primeiro bloqueio; a ferramenta, o segundo.
| Regras (prevenção no momento da geração) | Ferramentas (verificação no commit e na CI) |
|---|---|
| Nunca codifique segredos diretamente | Hook pre-commit do gitleaks |
| Não duplicar lógica | Um detector de duplicação como o jscpd |
| Forçar a direção das dependências entre camadas | dependency-cruiser, eslint-plugin-boundaries |
| Critério de conclusão (testes · verificação de tipos) | Gate do pipeline de CI |
| Não modificar arquivos de teste sem autorização | Proteger a pasta de testes com CODEOWNERS |
| Estilo de código | ESLint·Prettier·SwiftLint |
A força dessa combinação está no loop de feedback. Quando uma ferramenta detecta uma violação de regra, a mensagem de erro volta para a IA, que consulta o arquivo de regras novamente e corrige o problema.
O loop de prevenção → verificação → correção funciona sem intervenção humana. O princípio do artigo anterior — “Se as pessoas não vão ler, faça a máquina ler” — se completa quando combinado com regras.
Mova para o lint tudo o que puder ser imposto por regras de lint. O ideal é deixar no arquivo de regras o que as ferramentas não conseguem detectar: procedimentos de verificação, intenção de design e contexto do projeto.
Na prática: checklist de 10 minutos para iniciar um projeto
Antes de começar a programar por vibe em um projeto novo, faça isto antes de digitar o primeiro prompt.
- Crie o arquivo de regras — cinco seções sobre segurança, duplicação, arquitetura, critérios de conclusão e escopo. Copie o exemplo acima, adapte-o ao seu projeto e termine em 10 minutos.
- Faça primeiro o commit do esqueleto de pastas — mesmo vazias, elas estabelecem a estrutura, e a IA seguirá esse padrão.
- Instale um hook de varredura de segredos — só o gitleaks já evita os piores incidentes.
- Crie o .env.example — isso sinaliza, no nível da base de código, que “as chaves ficam aqui”.
Durante a operação, lembre-se de uma coisa: se a IA cometer o mesmo erro duas vezes, a culpa não é da IA; isso indica que essa regra não existe no arquivo de regras.
Reforce as regras uma linha por vez após cada incidente. O arquivo de regras não é um documento escrito uma vez e esquecido; ele cresce junto com o projeto.
P. É verdade que as regras acabam sendo menos seguidas quando o arquivo fica longo demais?
R. Sim. As regras também ocupam contexto; quanto mais longo o arquivo, mais o peso de cada regra individual se dilui.
Mantenha-o enxuto com base na pergunta “isso precisa ser sempre seguido?” e deixe para as ferramentas o que elas conseguem detectar. Pela experiência, quando passa de uma tela — cerca de 100 linhas — é hora de enxugar.
P. Isso também ajuda em um projeto que já virou um espaguete?
R. Ajuda, mas a ordem é diferente.
Primeiro, peça à IA para analisar a estrutura atual e gerar um rascunho do arquivo de regras. Depois, explicite uma estratégia gradual: “O código novo deve seguir estas regras, e o código existente é corrigido quando for tocado”.
P. Preciso gerenciar CLAUDE.md, .cursorrules e AGENTS.md separadamente?
R. Normalmente, você escreve o conteúdo uma vez e duplica apenas os arquivos.
Recentemente, também surgiu a prática de tratar o AGENTS.md como padrão e fazer com que os outros arquivos o referenciem. Se você usa várias ferramentas, recomendamos adotar o AGENTS.md como fonte única da verdade.
Em resumo: se a conclusão do artigo anterior foi “a velocidade fica com a IA, e o julgamento fica comigo”, a conclusão deste artigo é:
Não tome a mesma decisão repetidamente; transforme em regra cada decisão tomada uma vez.
Ler código é descobrir o raciocínio por trás dele; escrever regras é prevenir problemas antes que aconteçam. Projetos que ganham velocidade com Vibe Coding sem desmoronar têm algo em comum: não prompts sofisticados, mas arquivos de regras bem desenvolvidos.
Se o projeto em andamento hoje não tem um arquivo de regras, crie as cinco seções acima antes de pedir a implementação da próxima funcionalidade.
A diferença entre arquivos de regras e recursos de memória, além de quais conteúdos devem ficar em cada lugar, é explicada em detalhes em outro artigo. Vale a pena conferir também.
Materiais de referência
- Claude Code Memory - Anthropic Docs
- Rules - Cursor Docs
- AGENTS.md - Padrão de arquivos de regras para agentes
- AI Agent Failure Modes - NimbleBrain
- CLAUDE.md Rules: How to Cut AI Coding Mistakes - DEV Community