Eu construo SaaS sozinho e programo com IA o dia inteiro, ela é rápida, entrega feature, resolve bug às 2 da manhã, mas ela tem um defeito que ninguém te conta no começo: ela não respeita a sua arquitetura. Ela lê o padrão, concorda com você, e cinco prompts depois copia o jeito errado que já existe no código, porque o objetivo dela é "fazer funcionar", não "manter o padrão".
Eu descobri isso do jeito mais concreto possível: mandei fazer uma auditoria no meu próprio SaaS e o resultado foi que 89 pontos do código chamavam uma classe do jeito que o meu próprio manual de arquitetura proíbe, contra só 6 no jeito certo, o errado tinha virado a maioria, e cada vez que eu pedia uma feature nova, a IA olhava, via que "todo mundo faz assim", e fazia igual.
A lição não é "pare de usar IA", é que o que importa de verdade você não protege com documentação, protege com um teste que quebra o build, esse post é sobre a técnica que está segurando a minha barra, e sobre o furo dela que me ensinou mais que o acerto.
Documentação não segura a IA
Eu tenho um CLAUDE.md e ADRs (registros de decisão de arquitetura) caprichados. A IA lê, e ignora quando dá, não por má vontade: é que um arquivo de texto é um pedido, não uma barreira, e no modo "só entrega logo", pedido perde pra imitação toda vez.
