SINTOMA 02
A IA gera código que funciona, mas não parece nosso
O código passa nos testes e não passa na revisão. Usa uma biblioteca que o time abandonou, trata erro de um jeito que ninguém mais usa, atravessa uma fronteira de domínio que existia por um motivo. Localmente correto, sistemicamente errado.
atualizado em
Como isso aparece no dia a dia
- a mesma funcionalidade aparece implementada de três formas diferentes no mesmo repositório
- tratamento de erro e log variam de arquivo para arquivo sem razão
- uma dependência que o time decidiu abandonar reaparece em código novo
- a revisão gasta mais tempo com padrão do que com lógica
- decisões antigas são refeitas porque ninguém sabia que já tinham sido tomadas
Por que acontece
Um modelo de linguagem trabalha com o que consegue ler. Na prática, isso é o arquivo aberto, alguns vizinhos e o que estiver no histórico da conversa. Ele não tem acesso à razão pela qual aquela camada existe, nem à decisão que proibiu aquela dependência, nem ao padrão que o time convergiu depois de três incidentes.
Na ausência dessas informações, o modelo faz a coisa mais razoável possível: imita o vizinho mais próximo. Se o vizinho está desatualizado, o código novo nasce desatualizado — e com a aparência de estar certo, o que é pior.
O conhecimento arquitetural existe na empresa. Ele só não existe num formato que uma máquina consiga ler: está em decisões tomadas em reunião, em convenções aprendidas por osmose e em revisões de pull request que ninguém indexou.
Por que a correção óbvia não resolve
Escrever um prompt melhor, ou colar as convenções do time num arquivo de instruções na raiz.
Um arquivo solto de instruções resolve os primeiros casos e para de escalar rápido: fica longo demais para ser lido inteiro, genérico demais para decidir casos concretos, e desatualiza sem que ninguém perceba porque não faz parte de nenhuma revisão.
O que muda o quadro
Isso não se resolve com mais uma ferramenta. Resolve-se instalando, no repositório, o sistema que a IA precisa ler — o que chamamos de Sistema Operacional de Engenharia.
O que muda o quadro é transformar o contrato arquitetural em arquivos versionados: quais camadas existem, quais dependências são proibidas, como se trata erro, o que exige teste, quais decisões já foram tomadas e por quê. Texto, no repositório, revisado em pull request como qualquer código.
A partir daí a geração muda de natureza. O modelo passa a ter um critério para consultar antes de propor, e a revisão humana volta a ser sobre lógica de negócio, que é onde ela vale mais.
No framework de transformação, isso é o pilar AI-Native Repository Architecture. A definição completa da categoria está em Sistema Operacional de Engenharia.
Como saber se melhorou
Nenhuma dessas métricas significa alguma coisa sem o valor de partida. O baseline é levantado antes de qualquer mudança, com a janela e a fórmula registradas junto — o método está em métricas.
- Consistência arquitetural
- violações de regra detectadas por ciclo de revisão
- Redução de retrabalho
- proporção de código reescrito dentro de 30 dias
- Tempo médio de revisão de pull request
- da abertura ao primeiro parecer humano
Por onde se começa
Para este problema, o degrau adequado costuma ser AI-Native Repository Foundation — 4 a 8 semanas, time que já sabe onde dói e quer o sistema instalado em um produto antes de escalar para os outros.
Antes disso, o diagnóstico gratuito já indica se o gargalo é mesmo este. Os outros quatro sintomas estão em problemas.