Refactoring antes da AI: por que agentes amplificam a desordem

Agentes de AI amplificam a estrutura que recebem. Um modelo de domínio limpo com estados explícitos, fronteiras nomeadas e restrições documentadas se torna uma superfície de automação confiável. Um codebase desorganizado com ownership ambíguo, transições de estado implícitas e conhecimento tribal se torna caos acelerado — os mesmos bugs, os mesmos tickets mal direcionados, as mesmas respostas erradas, agora geradas na velocidade de inferência em vez da velocidade de um engenheiro junior lendo histórico de Slack.

A indústria quantificou isso: a atividade de refactoring caiu 60% desde que ferramentas de AI coding se popularizaram, enquanto o code churn — linhas revertidas ou reescritas em duas semanas — dobrou. Times geram mais código e consolidam menos. A arquitetura se degrada mais rápido porque ninguém faz o trabalho estrutural que mantém um sistema navegável. O resultado são codebases onde agentes de AI passam nos testes mas violam a arquitetura, onde código gerado é comportamentalmente correto mas estruturalmente errado. Refatorar antes de automatizar com AI é a intervenção que quebra esse ciclo.

A automação magnifica a estrutura — incluindo a estrutura ruim

Agentes de AI operam sobre os artefatos que conseguem ler: código, configuração, documentação, definições de workflow. Quando esses artefatos são claros, a saída do agente é previsível. Quando são ambíguos, a saída do agente é confiantemente errada — e a confiança é o que a torna perigosa.

Um agente de automação de suporte falha porque dois módulos definem "cliente" de forma diferente — um se refere à entidade de faturamento, o outro ao usuário final. O agente resolve um ticket atualizando o registro de cliente errado. Uma automação de workflow quebra porque as regras de escalação vivem em uma thread de Slack que três pessoas lembram mas nenhum sistema codifica. O agente direciona tickets para o time errado por duas semanas antes que alguém perceba o padrão.

Esses não são falhas de AI. São falhas estruturais que existiam antes do agente chegar. Um humano as navegava por memória institucional e troca de contexto. O agente as navega pelas únicas sinais que tem: o código, o schema, a configuração. Se esses sinais são contraditórios, o comportamento do agente é contraditório — em escala, continuamente, sem fadiga ou auto-questionamento.

Agentes de AI precisam de fronteiras de domínio estáveis para operar com segurança

Um agente que modifica código precisa saber onde um módulo começa e termina. Um agente que direciona tickets de suporte precisa saber qual time é dono de qual domínio. Um agente que gera relatórios precisa saber qual definição de "receita" se aplica em qual contexto. Essas são fronteiras de domínio — e na maioria das organizações, são implícitas, disputadas, ou diferentes dependendo de quem se pergunta.

Refatorar antes de automatizar com AI significa tornar essas fronteiras explícitas:

• Entidades nomeadas com definição única. Se "cliente" significa três coisas em três lugares, o agente não consegue determinar qual significado se aplica. Um refactor que introduz ContaFaturamento, UsuarioFinal e MembroOrganizacao dá ao agente — e ao time — um vocabulário inequívoco.
• Máquinas de estado explícitas. Se um ticket pode estar "aberto," "pendente," "escalado," ou "resolvido" mas as transições válidas não estão documentadas, o agente tentará transições inválidas. Um refactor que codifica a máquina de estados como restrição torna impossíveis as transições inválidas, seja quem for — ou o que for — que as dispare.
• Fronteiras de ownership no código. Se mudar um módulo afeta silenciosamente outro, o agente não consegue delimitar suas alterações com segurança. O raio de explosão do agentic coding se amplifica quando as fronteiras de módulo não são enforced pelo build system.
• Invariantes documentados. Se o sistema de faturamento nunca deve gerar uma fatura negativa mas essa regra só vive na memória de um engenheiro senior, o agente eventualmente gerará uma fatura negativa. Uma restrição codificada como regra de validação, teste ou schema check previne isso independentemente de quem — ou o que — dispare a operação.

Workflows desorganizados criam uso imprevisível de ferramentas

Agentes de AI não apenas leem código. Executam ferramentas: chamadas de API, consultas a bancos de dados, operações de arquivo, notificações. A sequência de uso de ferramentas depende da compreensão que o agente tem do workflow. Quando o workflow é ambíguo, a sequência se torna imprevisível.

Considere um workflow de reembolso onde a documentação diz "reembolsar o cliente e notificá-lo" mas o processo real envolve verificar sinais de fraude, validar que o método de pagamento ainda está ativo, calcular valores parciais baseados em uso, e registrar um evento de auditoria. Um agente operando a partir do workflow documentado pula quatro passos críticos. Um agente operando a partir do código real — se o código é limpo — executa todos.

A lacuna entre workflows documentados e comportamento real é onde vivem as falhas de automação. Refatorar fecha essa lacuna:

• Substituindo sequências implícitas por orquestração explícita (uma máquina de estados, um pipeline, ou uma coreografia).
• Extraindo side effects da lógica de negócio para que o agente possa compô-los em vez de adivinhar.
• Tornando visíveis os modos de falha: o que acontece quando a verificação de método de pagamento falha? O workflow refatorado tem um branch explícito. O workflow desorganizado tem um try/catch que engole silenciosamente o erro e segue em frente.

Refactoring não é limpeza — é infraestrutura de automação

O enquadramento importa. Refactoring posicionado como "pagar dívida técnica" compete com feature work e perde. Refactoring posicionado como "construir a superfície sobre a qual agentes de AI operam" é investimento em infraestrutura com retorno mensurável: o agente funciona corretamente, ou não.

O checklist de readiness para automação:

• Nomes: cada entidade, estado e operação tem um nome canônico usado consistentemente em código, configuração e documentação.
• Estados: cada workflow tem uma máquina de estados explícita com transições válidas codificadas como restrições, não como documentação.
• Ownership: cada módulo, serviço e workflow tem um time dono único. CODEOWNERS, ownership de schemas e atribuição de runbooks estão alinhados.
• Testes: os paths críticos têm characterization tests que ancoram o comportamento atual. O agente pode modificar código sem regressão silenciosa porque a suite de testes detecta drift comportamental.
• Rollback: cada ação automatizada tem um caminho de undo definido. Se o agente comete um erro, o sistema pode se recuperar sem intervenção manual.

Cada item dessa lista é um alvo de refactoring. Nenhum é opcional se o objetivo é automação confiável. O imposto de qualidade que AI impõe a codebases sem manutenção se acumula com cada mudança gerada por agente que passa nos testes mas viola a estrutura.

A diferença na prática é mensurável. Um time que investiu duas semanas codificando a máquina de estados do seu pipeline de deployment em estágios explícitos e nomeados antes de conectar um agente de AI reportou zero deployments mal direcionados no primeiro mês. Um time que conectou um agente a um pipeline sem documentação passou três semanas debugando por que builds de staging estavam sendo promovidos para produção — o agente inferiu a regra de promoção a partir de um padrão no histórico do git que coincidentemente correlacionava com deploys mas era na verdade uma coincidência. O refactoring custou duas semanas. O debugging custou três semanas mais um incidente. A matemática favorece a preparação sempre.

Perguntas frequentes sobre refactoring antes da automação com AI?

O escopo do refactoring depende de onde o agente vai operar. Nem tudo precisa ser perfeito — mas o domínio que o agente toca deve ser legível.

Quais áreas do código precisam de refactoring antes da automação com AI?

Priorizar os paths que o agente executará. Se o agente gera código no módulo de faturamento, o módulo de faturamento precisa de fronteiras explícitas, interfaces tipadas e characterization tests. Se o agente direciona tickets de suporte, a lógica de escalação precisa existir como código — não como uma mensagem de Slack de 2023. O escopo do refactoring é definido pela superfície operacional do agente, não por um mandato global de "pagar toda a dívida."

Como transformar conhecimento tribal em restrições executáveis?

Cada regra que só vive na memória de uma pessoa é uma regra que o agente violará. O processo de conversão: entrevistar os especialistas do domínio, documentar a restrição em linguagem simples, codificá-la como regra de validação ou teste, e conectá-la ao path que o agente exerce. Um glossário de domínio que define termos como "assinatura ativa," "cliente churned," e "evento faturável" com critérios precisos e computáveis elimina a ambiguidade que causa mau comportamento do agente.

Quando o codebase está pronto para automação segura com AI?

Readiness não é um estado binário. Um módulo está pronto quando: os nomes de entidades são inequívocos dentro do contexto do agente, as transições de estado são explícitas e enforced, os paths críticos têm cobertura de testes que detecta regressão comportamental, e os modos de falha têm caminhos de recuperação definidos. Se alguma dessas condições falta no domínio onde o agente operará, o refactoring não está terminado.

Um teste prático: um engenheiro novo — alguém que nunca viu esse módulo — consegue ler o código e prever o que o agente fará em cada estado? Se a resposta requer conhecimento tribal, o módulo não está pronto. O agente é permanentemente um engenheiro novo. Nunca vai construir o contexto institucional que humanos acumulam em meses. O código deve ser legível sem esse contexto, ou o agente agirá com informação incompleta e confiança total.

Um ponto de vista oposto

Um argumento frequente sustenta que AI é a melhor ferramenta para refatorar. Agentes podem gerar characterization tests, propor grafos de dependência, sugerir extrações de módulos e executar transformações mecânicas mais rápido que humanos. Esperar para refatorar antes de automatizar atrasa o valor que a automação entrega — e em mercados competitivos, velocidade importa mais que pureza estrutural.

Esse argumento está correto sobre a utilidade de AI como ferramenta de refactoring. Está errado sobre a sequência. Um agente gerando characterization tests para um módulo que não compreende produz testes que ancoram o comportamento errado ou perdem os invariantes que importam. Um agente propondo um grafo de dependências sem conhecimento do ownership de negócio produz um mapa tecnicamente preciso mas operacionalmente inútil. O julgamento humano que determina o que refatorar — quais definições estão erradas, quais fronteiras são disputadas, quais estados são implícitos — deve preceder a automação que executa o refactoring. AI acelera o trabalho mecânico. Não pode substituir as decisões de domínio que tornam significativo esse trabalho mecânico.

O que vale a pena lembrar

• Agentes de AI amplificam a estrutura — incluindo a estrutura ruim. Um sistema desorganizado automatizado é um sistema desorganizado se movendo na velocidade de máquina.
• Refatorar antes de automatizar com AI é investimento em infraestrutura, não limpeza. Constrói a superfície sobre a qual agentes operam com segurança.
• Entidades nomeadas, máquinas de estado explícitas, fronteiras de ownership enforced, characterization tests e paths de rollback definidos são os cinco pré-requisitos para automação segura.
• O escopo do refactoring é definido pela superfície operacional do agente, não por um mandato global de dívida técnica.
• Conhecimento tribal que só vive na memória é uma regra que o agente violará. Convertê-lo em restrições executáveis antes que o agente o encontre.
• AI pode acelerar o trabalho mecânico do refactoring, mas as decisões de domínio sobre o que refatorar devem vir de humanos primeiro.

Conclusão

Os times que extraem mais valor da automação com AI não são os que têm mais agentes. São aqueles cujos sistemas eram legíveis o suficiente para que os agentes operassem sem amplificar cada falha ambiental. O refactoring que torna um codebase navegável para um engenheiro novo é o mesmo que o torna seguro para um agente — nomes explícitos, domínios delimitados, invariantes enforced, comportamento testável. A pergunta não é se refatorar. É se fazer isso antes do agente chegar, quando o custo é um sprint planejado, ou depois, quando o custo é um incidente em escala.