Nesta página
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.