Engenharia agnética em codebases antigas exige expor restrições ocultas

O problema do código brownfield

Addy Osmani argumenta que engenharia agéntica em codebases antigas depende de tornar visíveis restrições ocultas e de tornar baratas as mudanças confiáveis. Em sistemas brownfield, o repositório não descreve completamente o comportamento real: conhecimento institucional, serviços legados e expectativas de outros times vivem fora da árvore. Jogar agentes sem supervisão nesses ambientes pode gerar código que "funciona", mas com design errado e testes frágeis.

Zonas e raio de impacto

Osmani propõe classificar o código em zonas: verde (boa cobertura de testes, isolamento, convenções modernas), amarela (qualidade mista, exige testes de caracterização antes) e vermelha (autenticação, cobrança, permissões, folha de pagamento). Três regras tornam as zonas um procedimento operacional: o mapa é desenhado por pessoa, não pelo agente (o agente, deixado à vontade, começa pelo arquivo mais assustador); zonas só mudam quando merecidas, com testes de caracterização e revisão do dono do módulo; e a zona define os verbos - verde permite loop fechado, amarela exige testes primeiro, vermelha exige pareamento humano em cada passo ou o trabalho não acontece. Autonomia deve seguir raio de impacto, observabilidade e recuperabilidade, não a confiança do modelo.

Documentar o que o código não diz

Agentes inferem bastante do código em si, então arquivos markdown excessivos não ajudam. O que se deve documentar é o que não pode ser inferido: nuances de negócio, trade-offs que explicam a estrutura, diretrizes não aplicadas por ferramentas, regras de domínio e contexto histórico de implementações contraintuitivas. Para trabalho em zonas amarela e vermelha, ele recomenda um artefato de pesquisa durável - um memorando de compreensão com pontos de entrada, donos, callers, abstrações, testes e questões em aberto, com alegações citando arquivos ou dashboards. O histórico de chat não é um bom registro; sem isso, o próximo agente paga de novo pela mesma "arqueologia".

Harness e trabalho de risco zero

Instruções registram fatos incomuns do repositório; skills empacotam procedimentos reutilizáveis; o harness é o ambiente de trabalho (contexto, ferramentas, permissões, testes, recuperação). Cada correção repetida é uma peça faltando no harness: transforme o comentário de revisão recorrente em regra de lint, hook, tipo, teste ou skill. A adoção deve começar com trabalho de risco zero: primeiro explicar como o sistema funciona e gerar testes de caracterização que fixem o comportamento atual - incluindo as partes feias, que o negócio pode usar. Quando um agente fizer testes passarem, a sessão não deve ser a única autora dos testes, senão a suíte verde codifica a implementação recém-inventada. Osmani cita a Netflix, que usou replay e tráfego sombra comparando caminhos antigos e novos antes de promover mudanças.

Migrações completas e lições de grandes casos

Migrações pela metade confundem agentes, que veem precedente contraditório (quarenta arquivos com o padrão antigo, doze com o novo). Prefere-se terminar uma rota de ponta a ponta, incluindo a remoção do caminho antigo: se a deleção fica para um ticket futuro, a unidade de migração não está completa. O SWE Refactor Bench chama isso de "Blindness": em 520 execuções de agente, apenas 28 passaram na auditoria de migração, testes comportamentais e verificação independente.

Casos citados: o port de Zig para Rust do Bun rodou cerca de 50 workflows em 11 dias sobre 535 mil linhas, com dois revisores adversariais por unidade e horas investidas num guia de porting antes de qualquer agente rodar. Um estudo controlado de VB6 para C# mediu 92% de equivalência comportamental em funcionalidades simples e 47% nas complexas - o tamanho da unidade é a alavanca. A Stripe migrou 3,7 milhões de linhas para TypeScript em um PR via codemods, sem agentes. A Spotify relata mais de 650 PRs de agentes mesclados por mês sobre trilhos do Backstage. A Asana limpou um backlog de Enzyme de vários anos em duas semanas por cerca de US$ 12 mil em custo de modelos e infraestrutura - valor reportado pelo fornecedor, não estudo controlado de economia.

O que mudou de fato

Agentes mudaram o preço de tentar várias implementações plausíveis, não a evidência necessária para escolher uma. Times agora podem ter agentes implementar reescritas concorrentes em diferentes stacks, validar contra testes e perfilar, antes de decidir. A Shopify refez o app Shop de React Native para Swift e Kotlin nativos em doze semanas com time pequeno e checkpoints por tela; o app maior de merchants continua sendo o problema brownfield.

Paralelização deve vir por último: paralelismo multiplica o gargalo existente, e revisão humana cerimonial não serve. Osmani sugere medir lead time, minutos de revisão, intervenções humanas, defeitos escapados e rollbacks - não linhas geradas. Na visão dele, agentes colocam um preço visível na ambiguidade: convenções tribais viram comentários de revisão recorrentes, o que fortalece o argumento por manutenção que os times já sabiam ser necessária.