Subtrair, Alinhar, Provar: Três Habilidades Que Impedem os Agentes de IA de Transformar Seu Repositório em Espaguete

Entregamos tickets reais para agentes de codificação todos os dias, e eles quase sempre entregam algo que funciona. Essa nunca foi a preocupação. A preocupação é como eles trabalham: um novo helper ao lado de três que já fazem o trabalho, uma abstração nova para um único consumidor, uma correção que remenda o único caminho que o ticket mencionava e deixa quatro irmãos quebrados, um achado que é “provavelmente um bug” sem prova alguma. Cada mudança é localmente razoável. No agregado, elas são entropia.

TL;DR: Em cinco pull requests Tier-3 no nosso núcleo de orquestração de agentes, três habilidades combináveis — ponytail (subtrair), grain (alinhar) e review-proof (provar) — removeram 821 linhas enquanto entregavam cinco funcionalidades, pegaram uma quebra silenciosa de contrato que a plausibilidade sozinha teria mesclado, e mantiveram cada mudança seguindo a fibra da arquitetura existente. Veja abaixo o que cada uma faz, com os diffs reais como respaldo.

Tire os trilhos de proteção e um agente de codificação se torna um gerador muito rápido de passivos que parecem plausíveis. Por isso nos apoiamos em três pequenas habilidades que empurram na direção oposta — um instinto cada: subtrair, alinhar, provar.

• ponytail — escreva a coisa mais preguiçosa que realmente funciona. Apague antes de adicionar. (Não fomos nós que escrevemos esta — é uma habilidade de código aberto de Dietrich Gebert que adaptamos para a nossa stack.)
• grain / grain-review — coloque onde a base de código já decidiu que aquilo vai. Não invente um segundo jeito.
• review-proof — não acredite em um achado até que ele se reproduza como um teste que falha.

grain e review-proof nós construímos no mesmo espírito do ponytail, ajustadas à nossa arquitetura. Cada um dos cinco PRs abaixo mexe no nosso núcleo de orquestração de agentes — o lugar mais caro do repositório para se fazer bobagem — e todos são classificados como Tier 3: cobertura extra de testes e revisão humana além do revisor automatizado, sem exceções.

As três habilidades em resumo: ponytail subtrai, grain alinha, review-proof prova.

Parte 1 · O QUÊ — a entropia é o padrão

Eis a coisa sobre a qual ninguém te avisa quando você entrega um repositório para agentes de IA: cada agente otimiza localmente e não lembra de nada. Ele vê o ticket, não os meses de convenções nos quais sua equipe convergiu. Ele não tem motivo para preferir o seu serviço de e-mail existente a um novo, não tem memória de que o conjunto de status de redirecionamento já está definido três arquivos adiante, não tem instinto de que “a correção vai na função compartilhada, não neste único ponto de chamada”. Deixados rodando, N agentes produzem N formas ligeiramente diferentes de fazer a mesma coisa. Isso não é um problema de qualidade de código que você resolve com linter — é um desvio estrutural que se acumula.

As três habilidades atacam cada uma um eixo desse desvio.

ponytail — a coisa mais preguiçosa que funciona

Ponytail é um desenvolvedor sênior que já foi acordado às 3 da manhã por causa da abstração esperta de outra pessoa e se recusa a escrever a próxima. Ele percorre uma escada e para no primeiro degrau que se sustenta: isso precisa existir? (YAGNI) → já existe nesta base de código? → a biblioteca padrão dá conta? → recurso nativo da plataforma? → dependência já instalada? → dá para ser uma linha? → só então, o mínimo de código que funciona.

O degrau que mais importa para agentes é “já existe nesta base de código?”. Reimplementar o que está a alguns arquivos de distância é a forma mais comum de lixo gerado por agente. E a regra de correção de bugs do ponytail mantém os diffs honestos: corrija a causa raiz, não o sintoma. Faça grep em cada ponto de chamada da função que você está prestes a tocar; uma guarda na função compartilhada é um diff menor do que uma guarda em cada ponto de chamada — e não deixa os irmãos quebrados.

grain / grain-review — siga a fibra

Se o ponytail governa quão pouco você escreve, o grain governa onde aquilo vai e que forma toma. Sua única regra: encontre o exemplo existente mais próximo, copie sua forma, nomeie o que você copiou. O código novo deve parecer ter sido escrito pela mesma pessoa que escreveu o arquivo ao lado.

O grain também é onde a arquitetura é imposta. Nosso backend é um layout bastante padrão de vertical slice + hexagonal — apresentação chama aplicação, que chama domínio, a infraestrutura depende para dentro, e o domínio nunca alcança para fora. Um achado como “esta rota pula seu controller e puxa o serviço diretamente” não é pedantismo — é a diferença entre uma base de código que um agente consegue navegar no mês que vem e uma que ele não consegue. O grain-review caça exatamente isso: helpers duplicados, fronteiras de camada cruzadas, acesso às entranhas de outra feature, uma segunda convenção para algo que já é feito de uma só forma.

review-proof — conquiste o achado

A revisão de código com IA padrão produz achados plausíveis. Alguns são reais; outros são bobagem confiante; vistos de fora, são idênticos. O review-proof se recusa a confiar em si mesmo: ele revisa e então força todo achado de correção a se reproduzir como um teste que realmente falha ou um repro executável, e descarta tudo o que não conseguir. Ele fecha com uma passagem de grain-review para adequação estrutural. O que é entregue é uma revisão em que cada item vem com evidência executável — não com uma sensação.

O que devemos ver se isso funcionar

• H1 — A exclusão aparece em PRs de funcionalidade. Se ponytail + grain estiverem funcionando, adicionar uma funcionalidade deve frequentemente remover estrutura líquida, não apenas adicioná-la.
• H2 — As correções acontecem uma vez, no lugar compartilhado. Correções de causa raiz devem colapsar muitos pontos de chamada em uma única guarda, não espalhar guardas por ponto de chamada.
• H3 — A revisão pega quebras de contrato que um humano passa batido. Revisão respaldada por prova deve revelar bugs que a revisão do tipo “parece bom” deixa passar — especialmente os silenciosos.

Parte 2 · E DAÍ — cinco PRs, um instinto cada

Cinco mudanças reais no nosso núcleo de agentes. Mantemos os detalhes internos vagos de propósito — o repositório é privado — mas os números são calculados a partir dos diffs reais, e as lições são a parte transferível.

Subtrair: uma guarda para uma dúzia de pontos de fetch

Uma família de passos de fluxo buscava URLs fornecidas pelo usuário sem uma verificação de segurança com resolução de DNS, então um hostname que resolvia para um endereço interno podia alcançar metadados de nuvem a partir do backend. A correção tentadora adiciona uma verificação em cada um dos mais de uma dúzia de pontos de fetch. A resposta do ponytail foi o oposto: um único helper de fetch compartilhado e protegido, usado em todos os lugares — e nós apagamos uma tabela de rede privada feita à mão que um truque de DNS com curinga atravessava direto, além de três loops de redirecionamento duplicados e uma verificação de rede copiada e colada em vários arquivos.

O diff adicionou o helper compartilhado e removeu ~90 linhas de duplicação em 22 arquivos. Essa exclusão é a história: isso é o H2 em carne e osso — a correção de causa raiz encaminhou todos os pontos de chamada por uma única guarda, em vez de remendar o único caminho que o ticket mencionava.

A correção de causa raiz: uma dúzia de pontos de fetch improvisados colapsa em um único helper compartilhado e protegido. A correção preguiçosa e a correção segura são a mesma correção.

Subtrair + provar: uma guarda de forma, provada no runtime real

Nosso runtime de workers persiste o resultado de uma execução como uma string serializada, às vezes envolta em uma lista de um único elemento. Consumidores que esperavam um objeto simples quebravam com isso. A correção errada espalha verificações defensivas de tipo em cada consumidor. Em vez disso: um pequeno helper de normalização de forma, e cada consumidor redirecionado para ele — uma adição quase pura de uma guarda que substitui as N guardas improvisadas que um agente menos disciplinado teria escrito (+558 / −24, 7 arquivos).

A parte que faz disso uma história de review-proof é o teste. Em vez de afirmar contra uma forma de serialização suposta, rodamos um fluxo de trabalho real pelo runtime e pelo armazenamento de verdade — sem mocks — e provamos a forma que o runtime de fato persiste. A questão em aberto no ticket era literalmente o que o runtime serializa aqui? — e a única resposta honesta é uma que você consegue executar.

Provar: a revisão pegou uma quebra silenciosa de contrato

Funcionalidade: um modelo de fallback por nó, para que um fluxo fixado em um provedor degrade com elegância durante uma indisponibilidade. A primeira versão óbvia envolvia o modelo no combinador de fallback embutido do framework.

Funcionava no caminho feliz. Também desligava silenciosamente dois recursos do provedor que dependem do tipo concreto do modelo via isinstance — um objeto envolvido não é mais daquele tipo, então a saída estruturada nativa e o cache de prompt se desligavam discretamente. Sem erro. Sem teste de caminho feliz falhando. Exatamente o tipo de coisa que uma revisão humana passa batido e um agente do tipo “parece bom” aprova.

O review-proof não aprovou — ele reproduziu ambas as quebras como testes que falham, o que forçou o redesenho: aplicar o fallback mais abaixo, em tempo de execução, para que cada modelo permaneça em seu tipo concreto e os recursos dependentes de tipo continuem funcionando. H3, confirmado de forma decisiva: a prova pegou um bug que a plausibilidade teria entregado.

Alinhar: um seletor, não duas cópias

Adicionar um segundo canal de notificação significou que a interface de seleção de canal passou a ter dois lugares — um assistente de criação e um modal de configurações. O movimento padrão do agente adiciona o novo ramo nos dois, gerando duas cópias da mesma máquina de estados. O grain disse: já existe uma forma de isso ser moldado — torne-o compartilhado. Extraímos um único hook de seletor e conduzimos as duas telas por ele, encaixamos o novo canal na união de configuração existente e reutilizamos o serviço de e-mail existente em vez de adicionar nova maquinaria de envio.

+1.735 / −340 em 24 arquivos. Uma funcionalidade desse tamanho removendo 340 linhas é o H1 tornado visível: a desduplicação de duas cópias do seletor em uma pagou por boa parte do novo canal.

Alinhar + provar: reutilize o endpoint, espelhe o caminho

Permitir que usuários anexem arquivos na criação de um issue poderia ter significado um novo endpoint de upload, um novo mecanismo de despacho, um novo caminho de prompt. O grain encaminhou quase tudo para trilhos existentes: o endpoint de upload existente, uma lista de aceitação no frontend que espelha exatamente a lista de permissões do backend, e uma correção de despacho adiado que reutilizou o mecanismo de elegibilidade que o trabalho agendado já usava. Foi entregue com correções respaldadas por prova, incluindo um bug real de isolamento de transação que teria perdido dados sob uploads paralelos. +1.776 / −218 em 27 arquivos — uma funcionalidade grande que ainda assim encontrou 218 linhas para remover ao se juntar a fatias existentes em vez de inventar novas.

O placar

Cinco PRs Tier-3: o que cada um adicionou, o que removeu e o instinto por trás dele.

Cinco PRs de funcionalidade e correção no núcleo de agentes removeram 821 linhas — não por fazer menos, mas por se recusar a duplicar o que já existia e a manter remendos de sintoma que uma correção de causa raiz tornou redundantes.

Divulgação completa

• Estas são habilidades, não um estudo. Isto não é um experimento controlado com um braço de referência; são cinco PRs reais nos quais a disciplina foi aplicada. O contrafactual — o que o mesmo agente teria entregado sem as habilidades — é uma estimativa informada, não uma medição. A história da quebra silenciosa de contrato é a evidência mais limpa, porque vimos a revisão reproduzir o bug antes do redesenho.
• Contagens de linhas são indicadores indiretos. O −821 é um número real vindo dos diffs, mas “linhas removidas” representa “duplicação e flexibilidade morta evitadas”. Uma habilidade que convence um agente a não escrever 200 linhas especulativas não deixa rastro nenhum em um diff — as maiores vitórias são invisíveis aqui.
• A economia de tokens é direcional. Diffs menores, menos arquivos tocados e estruturas reutilizadas significam menos tokens gastos gerando, revisando e revisando de novo — mas não estamos citando um delta de tokens rígido por PR.
• ponytail não é nosso. É uma habilidade de código aberto de Dietrich Gebert ; nós a adaptamos. grain e review-proof são nossos, construídas no mesmo espírito. As três rodam como habilidades locais de projeto no Claude Code — prompt e procedimento, não um binário que você instala.

Pronto para expandir seu negócio?

Comece seu teste gratuito hoje e veja resultados em dias.

Solicitar demo Entrar

Parte 3 · E AGORA

O que foi entregue. Três habilidades combináveis. ponytail e grain rodam enquanto se escreve; ponytail-review, grain-review e review-proof rodam sobre um diff. O review-proof encadeia o grain-review como sua fase final, então uma única revisão comprovada também ganha uma passagem estrutural de graça.

O que você pode fazer na segunda-feira — você não precisa das nossas habilidades exatas:

1. Faça de “reutilizar” o segundo degrau, não o décimo. Antes que um agente escreva um helper, faça-o procurar com grep por um que já exista. “Já existe nesta base de código?” pertence acima de “consigo escrever isso de forma limpa?”
2. Corrija na raiz, prove com a lista de pontos de chamada. Exija que toda correção de bug nomeie cada ponto de chamada da função tocada. Uma guarda na função compartilhada vence uma guarda por ponto de chamada — e é um diff menor.
3. Dê ao código novo um irmão mais próximo para copiar. “Encontre o exemplo existente mais próximo e espelhe sua forma” transforma a arquitetura de um documento que ninguém lê em um padrão que o agente segue.
4. Imponha as fronteiras de camada na CI, não na intuição. Uma catraca que falha apenas em imports novos entre camadas permite segurar a linha sem ter que resolver todo o oceano de dívida existente.
5. Não entregue um achado que você não consegue reproduzir. Faça o agente escrever primeiro o teste que falha. Se ele não consegue fazer o bug se reproduzir, não é um bug — é uma opinião. Descarte.
6. Deixe a revisão apagar. Direcione uma passagem de revisão especificamente para engenharia excessiva — “o que podemos cortar” — separada da correção. O melhor resultado de um diff é ele ficar mais curto.

Experimente, especialmente se falhar para você. Se você roda agentes de codificação em uma base de código real, a entropia já está acontecendo — você só ainda não a mediu. Transforme uma dessas em uma passagem de revisão nos seus próximos dez PRs de agente e conte as exclusões. Se subtrair-alinhar-provar não encolher seus diffs ou pegar uma quebra silenciosa, nós realmente gostaríamos de saber. Correções e contraexemplos são especialmente bem-vindos.

Um agente adiciona. O trabalho é fazer o agente merecer cada linha.