Como ler: à esquerda, a seta única — a reescrita que perde as regras que ninguém documentou. À direita, o caminho da trilha: primeiro descobrir e travar o comportamento atual (ciano), depois migrar um pedaço e comparar. A IA deve reduzir risco, não ampliá-lo.
Mapa da trilha
Conteúdo detalhado
🏚️ Modernização segura de sistemas legados
Mapeamento de dependências, regras de negócio escondidas, testes de caracterização, integrações ocultas, isolamento de fronteiras e migração gradual com comparação.
O levantamento do que existe: módulos, integrações, jobs, bancos, quem chama quem e o que já é código morto.
A IA é excelente nisso — ler muito código e resumir estrutura é onde ela mais rende. E sem o mapa você não sabe onde é seguro cortar.
Inventário antes de plano · Código morto é o corte mais barato · Quem chama quem define a fronteira possível.
A extração das regras reais que vivem só no código: exceções históricas, casos especiais de clientes, arredondamentos, prazos e comportamentos regulatórios.
São elas que quebram na reescrita. E são invisíveis para quem só olha a documentação — que quase sempre descreve o sistema que se pretendia ter.
O código é a verdade · Exceção histórica costuma ter dono · Regra achada vira teste, não comentário.
Testes que registram o que o sistema faz hoje — inclusive o que parece errado — para que qualquer mudança de comportamento apareça imediatamente.
É a rede de segurança que torna a modernização possível. Sem ela, "refatorei e está tudo funcionando" é uma frase sem lastro.
Caracterizar ≠ validar · Bug conhecido também é comportamento · IA gera esses testes em volume, e é ótima nisso.
A caça a consumidores não documentados: scripts, planilhas, jobs de outro time, relatórios que leem seu banco direto.
É o principal gerador de incidente pós-migração: você desligou algo que "ninguém usava" e alguém usava.
Log de acesso revela consumidor · Desligar em etapas (avisar, depreciar, remover) · Silêncio não é prova de desuso.
A criação de um ponto de costura entre o velho e o novo — um adaptador que permite trocar a implementação sem mexer em quem consome.
Sem fronteira definida, a migração vira reescrita: cada pedaço puxa outro e o escopo estoura.
Adaptador desacopla o cronograma · Fronteira boa é a que tem poucos consumidores · Estrangulamento gradual > big bang.
Executar as duas implementações lado a lado com a mesma entrada, registrando divergências, antes de trocar de vez.
É a prova mais forte que existe de que o novo faz o que o velho fazia — inclusive nos casos que ninguém lembrou de testar.
Divergência é informação, não erro · Liberação gradual por porcentagem · A IA reduz risco, não amplia.
🗺️ Arquitetura legível para agentes
Estrutura previsível, limites claros entre módulos, documentação próxima ao código, contratos explícitos, comandos padronizados, AGENTS.md, skills, playbooks e fontes únicas de verdade.
Uma organização em que o nome do diretório e do arquivo permitem prever onde algo está — para pessoas novas e para agentes.
Repositório previsível reduz o contexto que o agente precisa carregar e o número de suposições que ele faz.
Convenção > configuração · Nome consistente é infraestrutura · Estrutura previsível ajuda humano e máquina igual.
Fronteiras declaradas entre domínios, com regras de importação que podem ser verificadas automaticamente.
Um agente respeita a fronteira que consegue enxergar. Fronteira que só existe na cabeça do arquiteto será atravessada.
Regra verificável > regra combinada · Import é a evidência · Fronteira também limita o escopo da tarefa.
Documentação versionada no repositório: arquitetura, domínios, decisões e playbooks, na mesma revisão do código que descrevem.
Doc no repositório entra na revisão e no contexto do agente. Doc fora dele vira folclore em três meses.
Documentação é parte do diff · Registro de decisão explica o porquê · Doc desatualizada é pior que ausente.
Um comando único e documentado para instalar, testar, lintar, buildar e validar — que funciona igual na máquina de todo mundo e no CI.
É o que permite ao agente fechar o loop sozinho. Sem comando padrão, ele inventa um — e inventa errado.
Teste local rápido é infraestrutura de agente · Mesmo comando local e no CI · Script > instrução em prosa.
Um arquivo com visão geral, comandos principais, regras do projeto, onde está a documentação, limitações, critérios de qualidade, ações proibidas e referências para skills e playbooks.
Ele não deve concentrar todo o conhecimento do projeto — deve funcionar como mapa. Um AGENTS.md de 900 linhas não é lido nem por humanos.
Mapa aponta, não descreve tudo · Ações proibidas em destaque · Ele é revisado como código.
Um único lugar canônico para cada informação — comandos, contratos, convenções — sem cópias divergentes espalhadas.
Diante de duas fontes conflitantes, o agente escolhe uma — e você descobre qual na revisão, no pior momento.
Poucas fontes conflitantes · Referenciar > duplicar · Verdade duplicada diverge sempre.
🪓 Overengineering e dívida técnica gerada por IA
A menor mudança possível, abstrações prematuras, dependências desnecessárias, duplicação semântica, testes superficiais e o código que passa nos testes mas viola a intenção.
A instrução padrão: implemente a menor alteração que satisfaça os critérios de aceitação; não crie novas abstrações, dependências ou camadas sem necessidade comprovada.
A IA tende a produzir soluções aparentemente completas mesmo quando uma solução menor bastaria — e o custo aparece na manutenção.
Preservar a estrutura existente · Justificar todo componente novo · Menor diff é mais revisável.
Camadas, interfaces e "frameworks internos" criados para casos hipotéticos que ninguém pediu e que talvez nunca cheguem.
Abstração errada é mais cara que duplicação: ela precisa ser desfeita antes de qualquer mudança futura.
Abstrair depois do segundo (ou terceiro) uso real · Caso hipotético não é requisito · Simples e extensível: compare os dois.
Proibir dependência nova sem aprovação e limitar o número de arquivos alterados por tarefa.
Toda dependência é superfície de ataque, custo de atualização e risco de abandono. E diff grande demais não é revisado — é aceito.
Dependência tem custo permanente · Limite de arquivos denuncia escopo estourado · Refatoração fora de escopo fica para outro PR.
Duas ou mais implementações do mesmo conceito, escritas de formas diferentes — invisíveis para busca textual, acháveis por um agente que lê o repositório.
É a forma de dívida que a IA mais gera, porque cada tarefa começa sem lembrar do que já existe.
"Já existe algo assim?" antes de criar · Inconsistência entre módulos confunde o próximo agente · Consolidar é trabalho recorrente.
Testes que executam o código sem afirmar comportamento relevante: cobrem o caminho feliz, sobem a métrica e não pegam defeito.
Eles dão a pior combinação possível: sensação de segurança com zero proteção — e travam refatorações por testarem a implementação.
Teste bom falha quando o comportamento muda · Erro e borda > caminho feliz · Teste que só executa é dívida, não ativo.
A solução que satisfaz o verificador sem resolver o problema: caso especial embutido para o teste passar, exceção engolida, cache que esconde o bug.
É o defeito mais perigoso do desenvolvimento com IA, porque atravessa todos os gates automáticos com o sinal verde.
Ler o diff, não só o resultado · Revisão de intenção é humana · Métrica vira alvo e deixa de ser boa métrica.