Seu agente de IA não escreve código ruim por limitação técnica. Ele escreve o código médio do GitHub público, e faz isso com fidelidade impecável. O problema começa quando você espera que essa média se pareça com a arquitetura de um sistema de missão crítica.

Os dados de 2026 finalmente permitem sustentar essa tese com números. E, com números na mesa, a discussão sobre capacidade dos modelos perde relevância diante de uma medição muito mais útil: a distância entre o que o modelo aprendeu e o que o seu projeto exige, e quem paga essa diferença.

Diagnóstico: Três relatórios, um mesmo padrão

O relatório The AI Code Quality & Maintainability Gap, da GitClear, analisou mais de 600 milhões de linhas alteradas em repositórios reais entre 2023 e 2026. Três números resumem o cenário:

• Refatoração caiu 70% em relação a 2022. Código movido, limpo ou consolidado virou exceção.
• Copy/paste no mesmo commit subiu 41%. Diante de um problema parecido com um já resolvido, o caminho escolhido é duplicar, ajustar e seguir.
• Chamadas de função entre arquivos caíram 35%, enquanto a duplicação de blocos inteiros saltou 81%. O código novo não conversa com a arquitetura existente; nasce em silos paralelos.

O segundo dado vem do meio acadêmico. O framework CodeThread mediu o que acontece quando um agente precisa evoluir código escrito por outro agente: a taxa de sucesso cai até 13,1% em comparação com evoluir uma base escrita por especialistas humanos. O código gerado por IA é mais difícil de manter inclusive para a própria IA. A mesma linha de pesquisa aponta o mecanismo: validações de input mais fracas e tratamento de erros inconsistente, que mascaram problemas em vez de expô-los. São falhas sutis que só cobram o preço meses depois, na mão do próximo mantenedor.

O terceiro é o efeito Frankenstein: agentes resolvem problemas táticos com competência real, mas fragmentam a visão macro. O especialista humano passou a gastar menos tempo escrevendo lógica inicial e mais tempo consertando integração, revisando acoplamento e removendo code smells de infraestrutura.

São fontes independentes, com metodologias distintas, medindo o mesmo fenômeno: código que funciona no commit e degrada no sistema.

A causa: De onde vem o que o modelo sabe

O padrão se repete porque a origem dele antecede qualquer prompt: mora na base de treinamento dos modelos, um tema que raramente entra no debate sobre agentes.

Os grandes datasets públicos de código são construídos a partir de repositórios do GitHub com licenças permissivas. A referência é The Stack, do projeto BigCode, usado para treinar modelos como o StarCoder: a versão inicial reuniu 3,1 TB de código; a v2, padrão atual da indústria, expandiu para centenas de bilhões de tokens em mais de 600 linguagens. Modelos proprietários não publicam sua composição exata, mas as evidências disponíveis (papers, processos judiciais, comportamento observável) apontam para a mesma matéria-prima: código público da internet em escala massiva.

A composição desse universo é conhecida de qualquer um que já navegou o GitHub sem filtro: para cada sistema corporativo bem arquitetado (que, aliás, raramente é público) existem milhares de tutoriais, projetos de faculdade, provas de conceito abandonadas, exemplos de “get started” e forks incompletos. A estatística do corpus favorece o script isolado, a função autocontida, o exemplo didático sem contexto de sistema. O modelo aprende a distribuição do que viu. E o que ele viu, em volume esmagador, foi código sem arquitetura.

A camada seguinte agrava o viés. Os benchmarks que guiaram a evolução dos modelos, com HumanEval e MBPP à frente, avaliam funções isoladas e autocontidas: o HumanEval tem 164 problemas no nível de uma entrevista técnica simples. Enquanto isso, análises de bases de código reais mostram que mais de 70% das funções dependem de outras partes do sistema. Os modelos foram otimizados, por anos, para brilhar exatamente no cenário que menos existe em software profissional.

E há um terceiro fator, estrutural: pesquisas sobre code completion em nível de repositório identificam um desalinhamento entre o pré-treino e a tarefa real. O modelo aprendeu a prever o próximo token olhando o contexto próximo, mas manter um sistema exige atenção a dependências espalhadas por dezenas de arquivos. O RustRepoTrans, primeiro benchmark de tradução de código com contexto de repositório, mede o tamanho do buraco: ao sair de funções isoladas para tarefas que exigem lidar com as dependências do repositório, o Pass@1 dos modelos avaliados cai entre 16% e 30%, e o melhor deles despenca de 74,3% para 43,5%.

Corpus dominado por código sem arquitetura, otimização histórica para funções autocontidas e atenção enviesada para o contexto local: somadas, essas três condições transformam o resultado observado pela GitClear de surpresa em consequência.

Silos duplicados são o comportamento estatisticamente esperado de um modelo treinado assim.

Quanto mais a sua arquitetura se distancia de um get started do GitHub, maior o gap entre o que o agente produz por padrão e o que o seu projeto aceita como PR.

Consequências: O imposto de propagação

A GitClear dá nome ao custo: imposto de propagação. Cada bloco duplicado é uma cópia que precisa ser encontrada e alterada quando uma regra de negócio muda, um componente é substituído ou um bug é corrigido.

Com duplicação subindo 81%, cada decisão arquitetural passa a ter um multiplicador de custo embutido.

• Em um monólito modular .NET, isso aparece como três implementações paralelas de retry para o mesmo broker RabbitMQ, cada uma com timeouts diferentes.
• Em um sistema distribuído, como validações de idempotência reinventadas por consumer, cada uma com uma falha sutil distinta. O sistema continua passando no build. Os testes de unidade continuam verdes.

E a coesão sistêmica, a propriedade que determina quanto custa a próxima mudança, erode silenciosamente a cada merge.

O dado do CodeThread mostra que essa erosão penaliza até o próprio agente. Cada PR aceito sem governança arquitetural torna o repositório um pouco mais hostil para o PR seguinte, humano ou não. É dívida técnica com juros compostos, contraída na velocidade de quem gera código dez vezes mais rápido do que revisa.

Solução: harness como camada de reforço

Se a causa é a distância entre a distribuição de treinamento e a sua arquitetura, a solução tem um formato claro: injetar no contexto do agente aquilo que o corpus nunca teve. Esse é o papel do harness:

O conjunto de skills, rules e verificações que cerca o agente e transforma conhecimento arquitetural implícito em restrição explícita.

A arquitetura não foi projetada para modelos nem para agentes. Foi projetada para atender requisitos, independente de quem está do outro lado do teclado. O harness só faz com o agente o que onboarding, code review e documentação sempre fizeram com desenvolvedores: comunicar as regras do sistema antes que o código seja escrito.

A diferença prática aparece no primeiro PR. Sem harness, um agente que precisa publicar um evento de domínio tende a produzir a versão estatística do GitHub:

// gerado sem harness: silo funcional, ignorando a infraestrutura existente
public class OrderService
{
    public async Task CompleteOrder(Guid orderId)
    {
        var factory = new ConnectionFactory { HostName = "localhost" };
        using var connection = await factory.CreateConnectionAsync();
        using var channel = await connection.CreateChannelAsync();

        var body = JsonSerializer.SerializeToUtf8Bytes(new { orderId, status = "completed" });
        await channel.BasicPublishAsync("", "orders", body: body);
    }
}

Funciona. Passa no teste. E ignora a camada de mensageria do projeto, o outbox pattern que garante atomicidade, a convenção de nomes de eventos, a serialização padronizada e a telemetria. Com uma skill que descreve o estereótipo DomainEventPublisher (quando usar, o que é proibido, qual abstração consumir), o mesmo agente produz:

// gerado com harness: conectado à arquitetura, observável, transacional
public class CompleteOrderHandler(IOrderRepository repository, IDomainEventOutbox outbox)
    : ICommandHandler<CompleteOrderCommand>
{
    public async Task HandleAsync(CompleteOrderCommand command, CancellationToken ct)
    {
        var order = await repository.GetRequiredAsync(command.OrderId, ct);
        order.Complete();

        await outbox.EnqueueAsync(new OrderCompleted(order.Id, order.CompletedAt), ct);
        await repository.UnitOfWork.CommitAsync(ct);
    }
}

Entre as duas versões não houve troca de modelo. Houve contexto que o modelo jamais teria como inferir, porque a sua arquitetura não está na massa de treinamento, e nunca estará.

É por isso que a quantidade de skills de um harness acompanha o tamanho da arquitetura, e não a vaidade de quem o escreve. Um CRUD precisa de pouco; um plan mode e um arquivo de contexto resolvem. Um sistema com estereótipos ricos, mensageria, cache distribuído e requisitos de observabilidade precisa que cada uma dessas decisões vire restrição verificável.

Quarenta regras podem parecer exagero até você contar quantas decisões arquiteturais o seu sistema realmente carrega, e quantas delas um agente viola no primeiro PR sem supervisão.

O gap não vai fechar sozinho

Os números de 2026 desenham uma tesoura: a capacidade tática dos agentes cresce, a saúde estrutural do código que eles produzem cai. Esperar que a próxima geração de modelos resolva isso é apostar contra a própria natureza do treinamento: a distribuição do código público continuará distante da sua arquitetura, e cada vez mais contaminada por código gerado pelos próprios modelos.

O harness existe para ocupar exatamente esse espaço.
Nenhuma skill nasce do desejo de criar skills;
nasce da recusa em descartar agentes que não conseguiam entregar um PR aceitável.

Quem mede a distância entre o que o agente produz por padrão e o que o projeto exige, e codifica essa distância em restrições explícitas, transforma a IA de gerador de dívida em multiplicador de arquitetura.

Antes do próximo merge, vale rodar uma análise de duplicação no seu repositório e responder com honestidade: quantos silos ele ganhou nos últimos seis meses sem que ninguém tenha decidido, conscientemente, que eles deveriam existir?

Referências

• GitClear: The AI Code Quality & Maintainability Gap
• Patel, Hou et al.: Is Agent Code Less Maintainable Than Human Code? (framework CodeThread)
• AlterSquare: Why AI-Generated Code Costs More to Maintain
• Kocetkov et al.: The Stack: 3 TB of Permissively Licensed Source Code
• Cracks in The Stack: Hidden Vulnerabilities in LLM Pre-Training Datasets
• Beyond Synthetic Benchmarks: Class-Level Code Generation
• aiXcoder-7B-v2 / CoLA: o desalinhamento entre pré-treino e contexto de repositório
• K³Trans: queda de performance em contexto de repositório