Estratégia de engenharia brownfield
Como fazer a transição de uma base de código existente para o desenvolvimento nativo em IA: quando remediar no lugar, quando usar strangler-fig, quando reconstruir, quando isolar, e a metodologia que torna cada abordagem viável.
Sua base de código é realmente brownfield?
Os quatro modos desta página se aplicam a bases de código brownfield: código existente com decisões acumuladas, usuários em produção e uma equipe trabalhando dentro dele. Antes de escolher um modo, verifique o estado da base de código. Três aparecem na prática:
| Estado | O que significa | O que fazer |
|---|---|---|
| Greenfield (em desenvolvimento, pré-GA) | Base de código nova, ainda não em produção, ou em produção mas jovem o suficiente para que todo o código ainda esteja sendo ativamente projetado. Pontuações baixas de maturidade aqui são decisões de cronograma, não dívida. | Continue o desenvolvimento. Feche as lacunas de maturidade no cronograma do roadmap. Execute novamente a avaliação de maturidade na GA e trate as lacunas não fechadas como brownfield a partir de então. |
| Brownfield (produção, acumulado) | O código existe, roda em produção, tem usuários reais, carrega anos de decisões. As lacunas de maturidade são dívida. | Escolha um modo usando os quatro abaixo. |
| Híbrido | Um novo serviço pronto para o Nível 5 dentro de uma organização cujos outros sistemas são brownfield. O novo serviço é greenfield; a fronteira de integração legada é brownfield. | Avalie o novo serviço como greenfield. Para cada fronteira legada, escolha um modo separadamente. Versão mais comum: um novo app nativo em IA lendo ou escrevendo dados por meio de uma API legada. |
Os quatro modos
Cada modo é um caminho diferente para o Nível 5. A pergunta não é "qual modo a equipe tem capacidade para" (isso é uma decisão de alocação de recursos a jusante). A pergunta é "qual modo é o caminho mais curto para o Nível 5 para esta base de código, com base nas evidências." Tamanho da equipe, prioridades estratégicas e custo de oportunidade são entradas que um humano pondera após ler a recomendação; não são entradas para a recomendação em si.
| Modo | O que "caminho para o Nível 5" significa |
|---|---|
| Remediar no lugar | O Nível 5 acontece nesta base de código por meio de construção de harness por etapas. |
| Strangler-fig | O Nível 5 acontece gradualmente: novas partes são construídas prontas para o Nível 5 enquanto as antigas se aposentam. |
| Reconstrução completa | O Nível 5 acontece em uma nova versão desta base de código; a versão antiga se aposenta na transição. |
| Isolar e contornar | O Nível 5 não acontece nesta base de código. Acontece em novas bases de código prontas para o Nível 5 ao lado; esta permanece congelada. |
Modo 1: Remediar no lugar
Mantenha o código existente. Invista no harness: testes, tipos, convenções, intenção documentada. Use IA para acelerar a própria remediação por meio da metodologia Pesquisa-Revisão-Reconstrução abaixo.
Quando é o certo: a arquitetura é fundamentalmente sólida (o problema é o harness, não a estrutura); a equipe tem expertise de domínio ligada à base de código atual; a continuidade de negócio não pode tolerar sistemas paralelos.
O risco: você remedia o harness e o código permanece fundamentalmente no Nível 3 porque a estrutura resiste. Você gastou seis meses e ainda não consegue chegar ao Rung 5.
Modo 2: Migração strangler-fig
Construa novas funcionalidades prontas para o Nível 5 ao lado do sistema antigo. Roteie o tráfego por uma fachada. Elimine partes do sistema antigo uma por uma à medida que as novas se provam. O Strangler Fig Pattern de Martin Fowler é a referência canônica.
Quando é o certo: o sistema existente tem costuras limpas para extração; a continuidade de negócio é importante; o tempo de reconstrução de todo o sistema excederia a tolerância do negócio.
O risco: a identificação de costuras é difícil. Se as costuras não forem limpas, você acaba com dois sistemas acoplados em vez de um: o dobro da complexidade, nenhum dos benefícios.
Modo 3: Reconstrução completa
Comece de novo com uma base de código pronta para o Nível 5. Execute os dois sistemas em paralelo, migre os dados, faça a transição quando o novo sistema provar equivalência ou superioridade.
Quando é o certo: a estrutura existente impede ativamente o trabalho necessário; o custo da remediação contínua excede o custo da reconstrução; a economia da reconstrução assistida por IA torna a reconstrução viável em um prazo que antes não era; o domínio está bem compreendido (você está substituindo o como, não redescobrir o o quê).
O risco: o efeito do segundo sistema. Reconstruções acumulam cada funcionalidade diferida do sistema antigo e afundam sob seu próprio peso. Mantenha o escopo disciplinado.
Modo 4: Isolar e contornar
Congele o legado. Mantenha-o com mãos humanas no nível que o negócio ainda requer. Construa novo valor como novos apps prontos para o Nível 5 ao lado, roteando por qualquer API ou camada de dados que já funcione. Não tente modernizar o próprio legado.
Quando é o certo: o custo de remediação excede o valor restante no legado; novo valor pode ser entregue em paralelo sem integração profunda; o legado tem uma costura de integração viável (API, banco de dados, fila) pela qual novos apps podem rotear; o negócio tolera o modo de manutenção por um período prolongado.
O risco: o legado ignorado acumula mais dívida ao longo do tempo. Eventualmente algo força a decisão: um patch de segurança que não pode ser aplicado, um EOL de plataforma, um modelo de dados que não consegue absorver novos requisitos. Isolar e contornar compra tempo; não resolve o problema.
"Não investir" é um resultado legítimo aqui. Nem todo legado vale a pena corrigir. O sinal: você está escrevendo seu terceiro plano de remediação para o mesmo módulo, os testes que você adicionou no trimestre passado não estão mais verdes e o negócio ainda entrega valor por esse código. Essa não é uma base de código esperando para ser modernizada. É uma base de código esperando para ser substituída.
Critérios de decisão
| Pergunta | Remediar | Strangler | Reconstruir | Isolar |
|---|---|---|---|---|
| A arquitetura é fundamentalmente sólida? | Sim | Principalmente | Não | Não importa |
| Há costuras limpas para extração? | N/A | Sim | N/A | Pelo menos um ponto de integração utilizável |
| A equipe consegue descrever a intenção do sistema? | Sim | Sim | Sim (ou use Black Box to Blueprint) | Não obrigatório para o legado |
| O negócio pode tolerar sistemas paralelos? | N/A | Sim | Sim | Sim |
| O pagamento contínuo da dívida é mais barato que a substituição? | Sim | Parcialmente | Não | Sim, enquanto novo valor é publicado ao lado |
| O legado tem valor restante que vale preservar? | Sim | Sim | Sim | Sim, mas não vale corrigir |
| Você tem capacidade de equipe para a opção mais difícil? | Menor | Médio | Maior | Baixo (o legado permanece congelado) |
Sem um "sim" claro na linha de reconstrução? Não reconstrua. O efeito do segundo sistema pune equipes que escolheram reconstruir por razões que não se encaixam.
Várias respostas "não" nas colunas Remediar/Strangler/Reconstruir, mas o legado ainda tem valor de negócio? Isolar e contornar é provavelmente o modo certo.
O Technical Debt Quadrant aguça a decisão de reconstrução:
| Tipo de dívida | Causa | Remediação |
|---|---|---|
| Prudente, deliberada | Sabíamos do atalho ao publicar. | Geralmente remediável. |
| Prudente, inadvertida | Aprendemos melhor depois. | Remediável, mas verifique se o aprendizado invalidou decisões estruturais. |
| Imprudente, deliberada | Sabíamos melhor, fizemos assim mesmo. | Frequentemente remediável com disciplina, mas sinaliza problemas de processo que sobrevivem à base de código. |
| Imprudente, inadvertida | Não sabíamos o que estávamos fazendo. | Candidato à reconstrução. A estrutura reflete ignorância que o conhecimento posterior não consegue desfazer no lugar. |
Precisa de ajuda para escolher o modo certo? A skill codebase-readiness para Claude Code avalia uma base de código em relação ao modelo de maturidade de nove dimensões e recomenda um caminho para o Nível 5, incluindo qual dos quatro modos se aplica.
A metodologia: Pesquisa, Revisão, Reconstrução
Publicada por Fowler e EPAM em Research, Review, Rebuild, esta é a metodologia brownfield mais concreta disponível. Ela se aplica diretamente aos Modos 1 a 3; no Modo 4, aplica-se à costura de integração mesmo que o legado permaneça congelado. A implantação direta de agentes em uma base de código legada opaca produz de forma confiável output confidentemente errado. A estrutura em fases evita isso.
Fase 1: Pesquisa. A IA analisa o código existente: reconstrói a intenção, extrai contratos comportamentais, identifica padrões, documenta o grafo de dependências. Ferramentas como conectores MCP permitem que os agentes percorram sistematicamente a base de código. Output: um mapa de intenção, ou seja, o que o sistema faz, independentemente de como está estruturado.
Fase 2: Revisão. Especialistas de domínio validam o mapa de intenção. A IA pode extrair o que o código faz. Apenas humanos conseguem distinguir comportamento intencional de acidente histórico. Este é o gargalo de throughput: no caso de estudo Bahmni (AngularJS para React), a revisão humana levou cerca de 20 minutos por componente. Planeje capacidade para a revisão, não apenas para a geração.
Fase 3: Reconstrução. Com a intenção validada, a IA gera código de substituição com ambiguidade mínima. No Bahmni: cerca de US$ 2 por componente em menos de uma hora, contra 3 a 6 dias manualmente. A economia é convincente quando as Fases 1 e 2 são disciplinadas, e pior do que a tradicional quando são puladas.
A ordem é estruturalmente importante. Equipes que pulam pesquisa e revisão para chegar mais rápido à reconstrução não economizam tempo; elas produzem outputs errados mais rápido e gastam o tempo economizado depurando comportamentos alucinados.
Economia: o que os números implicam
O ponto de dados do Bahmni reorganiza a matemática: o que era uma migração de 18 meses se torna uma de 6 meses, onde a restrição é a capacidade do revisor, não as horas de engenharia. Seu desempenho vai variar com arquitetura, cobertura de testes e complexidade de domínio, e a economia só funciona quando Pesquisa e Revisão são disciplinadas. Pulá-las colapsa o ganho de velocidade.
Black Box to Blueprint: engenharia reversa da intenção
Quando a equipe original foi embora, a documentação está errada e o código é a única fonte de verdade, a Fase 1 se torna um problema de engenharia reversa. O Black Box to Blueprint de Fowler descreve cinco técnicas:
- Reconstrução da camada de UI: inferir comportamento a partir da interface do usuário e suas transições de estado.
- Change data capture: observar como o sistema modifica dados em produção para inferir a lógica de negócio.
- Inferência de lógica de servidor: analisar fronteiras de API e padrões de requisição/resposta para reconstruir a lógica por trás deles.
- Arqueologia binária: reconstruir a partir de binários, logs e interfaces externas quando o código-fonte é perdido.
- Enriquecimento progressivo multi-passagem: dividir artefatos em fragmentos gerenciáveis, extrair insights parciais por passagem, construir contexto incrementalmente. A análise de sistema completo em uma única passagem falha em escala.
Duas disciplinas são inegociáveis: triangulação (toda hipótese sobre intenção confirmada em duas fontes independentes: UI + logs, API + banco de dados, código + comportamento observado) e rastreamento de linhagem (para cada afirmação, registre a evidência em que se baseia, para que evidências não confiáveis sejam identificáveis depois).
Spec-from-code: a inversão brownfield
Os Padrões de Execução de IA e o Guia de Especificação assumem que as specs precedem o código. O brownfield inverte isso: o código já existe e a spec precisa ser extraída por engenharia reversa. Este é um fluxo de trabalho diferente.
Ferramentas de desenvolvimento guiado por spec como spec-kit, Kiro e Tessl são orientadas principalmente para greenfield. O "Brownfield Bootstrap" do spec-kit é a exceção: descubra automaticamente a arquitetura existente para estabelecer uma Constituição (princípios governantes persistentes), depois aplique o desenvolvimento guiado por spec apenas ao novo trabalho enquanto Pesquisa e Revisão alcançam a superfície legada.
O padrão que funciona:
- Extraia a especificação implícita. O que o sistema realmente faz? Veja a sequência brownfield do Lab de IA para a versão disciplinada.
- Escreva cenários ponta a ponta que descrevam o comportamento esperado atual a partir da spec extraída.
- Verifique que os cenários passam no código existente. Isso se torna seu harness de regressão.
- Aplique spec-first a todo novo trabalho. Sem exceções.
- Migre strangler-fig componente por componente, usando os cenários como proteção durante a migração.
O primeiro passo é o trabalho mais difícil da transição. Os agentes conseguem documentar o que o sistema faz; apenas humanos conseguem responder se é o que ele deveria fazer.
Armadilhas comuns
Subestimar o gargalo de revisão humana. Os custos de geração de IA caíram por ordens de grandeza. Os custos de revisão humana não. Planeje a capacidade do revisor como restrição de primeira classe, não como reflexo.
Brownfield de meio Lab. Executar parte do projeto em modo nativo em IA e parte no modo tradicional porque "essa parte é mais rápida do jeito antigo" não produz nenhum benefício. A lista de armadilhas do Lab de IA nomeia isso especificamente.
Tratar costuras como dadas quando são implícitas. O strangler-fig parece bem nos quadros brancos. Na prática, "costuras limpas" são onde as responsabilidades podem ser extraídas sem acoplamento a outros oito módulos. Se isso não for verdade para sua base de código, o strangler-fig se torna uma reconstrução completa com etapas extras.
Confundir custo de modernização com custo de substituição. A decisão "remediar vs. reconstruir" não é sobre se consertar custa dinheiro, pois ambos custam. É sobre se a estrutura consegue suportar o que você precisa que ela suporte. Dívida imprudente e inadvertida não pode ser desfeita no lugar, independentemente do orçamento.
Panorama de ferramentas (instantâneo)
O framework não recomenda ferramentas específicas; o panorama muda rápido demais. Mas vale saber sobre: desenvolvimento guiado por spec (spec-kit, Kiro, Tessl; veja a comparação de Fowler); conectores MCP para percorrimento sistemático de bases de código; plataformas de agentes (Claude Code, Cursor, Aider, Devin) com diferentes trade-offs de autonomia/humano-no-loop; benchmarks (SWE-bench, IDE-Bench), mas pontuações em problemas curados não preveem desempenho brownfield no seu código.
Espelho: estratégia e confiabilidade
Engenharia para Confiabilidade é sobre fazer sistemas confiáveis a partir de outputs de IA não confiáveis. A estratégia brownfield é sobre tornar os agentes de IA eficazes em bases de código não confiáveis. Os dois convergem no harness: sensores rápidos, intenção documentada, validação em nível de cenário. Uma migração brownfield que não termina com a base de código no Nível 5 de maturidade e não corresponde à disciplina de Confiabilidade teve sucesso na forma, mas não na função.
Relacionados
- Maturidade do código: o diagnóstico do qual esta página depende
- O Lab de IA: o modo de trabalho do Rung 5 quando você chegar lá
- Engenharia para Confiabilidade: o problema espelho
- Padrões de Execução de IA e Guia de Especificação: engenharia de especificação
- Padrões de trabalho herdados: os padrões humanos que frequentemente acompanham o código legado
Fontes
- Fowler, M. (2026). "Harness Engineering for Coding Agent Users." martinfowler.com
- Fowler, M. (2026). "From Black Box to Blueprint: Reverse-Engineering Legacy Systems with AI." martinfowler.com
- Fowler, M. & EPAM. (2026). "Research, Review, Rebuild: AI-Assisted Legacy Modernization." martinfowler.com
- Fowler, M. (2024). "Rewriting the Strangler Fig Application." martinfowler.com
- Fowler, M. "Strangler Fig Application." martinfowler.com
- Fowler, M. "Technical Debt Quadrant." martinfowler.com
- Fowler, M. (2026). "Spec-Driven Development: The Three Tools." martinfowler.com
- GitHub. "Spec Kit." github.com/github/spec-kit
- Duvall, P. (2026). "AI Development Patterns." github.com/PaulDuvall/ai-development-patterns
- Feathers, M. (2004). Working Effectively with Legacy Code. Addison-Wesley.
- "Artificial Intelligence for Software Architecture: A Literature Review." (2025). arXiv. arxiv.org/abs/2504.04334
- "IDE-Bench: Evaluating LLM Agents on Real Codebases." (2026). arXiv. arxiv.org/abs/2601.20886
- SWE-bench. swebench.com
← Voltar para o início · Maturidade do código · O Lab de IA · Engenharia para Confiabilidade · Glossário