Usando IA para mapear domínios em código legado e medir acoplamento

Trilha bônus · IA para arquitetura · ~30 min · pleno/sênior

Herdei 400 mil linhas de um ERP sem documentação, sem os autores originais (todos já tinham saído da empresa) e com a missão de "modularizar isso antes que trave o negócio". O mapa mental que eu precisava — quais são os domínios reais escondidos ali dentro, o que está acoplado com o quê — levaria meses para construir lendo classe por classe. Foi a primeira vez que usei IA a sério para arquitetura, e a lição que tirei molda esta aula: a IA é excelente para gerar hipóteses de fronteira em velocidade sobre-humana, e péssima para decidir se elas estão certas. Ela leu as 400 mil linhas numa tarde e me deu um mapa de candidatos a bounded context. Vários estavam certos. Alguns estavam sedutoramente errados — agrupavam coisas por semelhança de nome, não por semelhança de negócio (o erro da coesão lógica da aula Coesão: o outro lado da moeda). Meu trabalho não foi "deixar a IA modularizar"; foi usar as hipóteses dela como ponto de partida e validá-las contra a Linguagem Ubíqua (aula DDD estratégico + Arquitetura Hexagonal no FakeFlix) e a realidade do negócio.

Este bônus é sobre esse uso profissional: a IA como um analista incansável que lê o que você não teria tempo de ler e propõe recortes — e você como o arquiteto que julga, mede e decide. Quem inverte esses papéis (deixa a IA decidir e só revisa por cima) recria, em escala industrial, os dois vilões da aula Por que não existe arquitetura perfeita.

O princípio: IA gera hipóteses, humano valida fronteiras

Antes de qualquer prompt, o enquadramento que evita todos os desastres. A IA tem uma força e uma fraqueza específicas para arquitetura:

• Força: ler volume e reconhecer padrões estatísticos em velocidade impossível para um humano. Ela vê que 40 classes mencionam invoice, que PaymentService e TaxCalculator sempre mudam juntos no histórico, que UserManager tem 3 mil linhas e 8 responsabilidades. Isso é levantamento — e é imenso o valor de ter isso em minutos.
• Fraqueza: ela não conhece o seu negócio. Ela não sabe que, na sua empresa, "conta" no contexto de faturamento é uma coisa completamente diferente de "conta" no contexto de acesso, mesmo que a palavra seja idêntica. Ela agrupa por semelhança de texto/estrutura; bounded contexts se separam por semelhança de significado no negócio (aula DDD estratégico + Arquitetura Hexagonal no FakeFlix). Onde os dois divergem, a IA erra com confiança.

A regra inegociável do bônus: a IA propõe fronteiras candidatas a partir de sinais do código; você decide se são fronteiras reais confrontando-as com a Linguagem Ubíqua e com quem entende o negócio. Nunca aceite um recorte de domínio só porque a IA o sugeriu com segurança — a segurança dela não é conhecimento do negócio, é fluência estatística.

Isso não diminui a IA — muda o papel dela. Ela é o analista que faz o trabalho braçal de mapear 400 mil linhas e traz uma primeira versão do mapa. O arquiteto é o editor que corrige o mapa onde o negócio contradiz o código.

Identificando bounded contexts implícitos

O código legado tem domínios escondidos — eles existem no comportamento, mas não estão nomeados nem separados (é o oposto do FakeFlix, onde os domínios são pastas explícitas). O objetivo é fazer a IA revelar esses domínios latentes. A técnica: dar à IA sinais estruturais e pedir agrupamentos com justificativa, para você poder auditar o raciocínio.

Um prompt de análise eficaz não é "modularize isso". É estruturado, pede evidência e admite incerteza:

Contexto: você é um analista de arquitetura. Abaixo está a lista de classes/arquivos
de um sistema legado, com: nome, responsabilidades inferidas do código, e as entidades
de negócio que cada uma manipula.

Tarefa:
1. Agrupe as classes em candidatos a bounded context, baseando-se em quais entidades
   de negócio elas compartilham e em quais mudam pelos mesmos motivos.
2. Para cada grupo, liste os TERMOS de negócio que aparecem (o vocabulário do grupo).
3. Aponte termos AMBÍGUOS — a mesma palavra usada com sentidos diferentes em grupos
   diferentes (forte sinal de fronteira entre contextos).
4. Marque com [INCERTO] qualquer agrupamento em que os sinais sejam fracos ou conflitantes,
   e explique o conflito.
5. NÃO invente coesão de negócio que os dados não suportam. Se um grupo parece unido só
   por semelhança de nome, diga isso.

[dados das classes...]

Repare no que esse prompt faz de proposital: pede justificativa por evidência (item 1), extrai a linguagem de cada grupo (item 2, conectando com a aula DDD estratégico + Arquitetura Hexagonal no FakeFlix), procura ativamente os termos ambíguos que revelam fronteiras (item 3 — o sinal mais valioso do DDD estratégico), e força a IA a admitir incerteza em vez de fabricar confiança (itens 4 e 5). O item 5 é o antídoto direto contra o erro da coesão lógica (aula Coesão: o outro lado da moeda): impedir que a IA agrupe validateCreditCard com validateVideoFormat só porque ambos têm "validate" no nome.

O termo ambíguo (item 3) merece destaque porque é onde a IA mais ajuda. Ela é ótima em achar "a palavra conta aparece em AccountBalanceService (com sentido financeiro) e em AccountLoginService (com sentido de credencial)". Um humano lendo 400 mil linhas pode não notar; a IA nota na hora. E esse é exatamente o sinal de bounded context da aula DDD estratégico + Arquitetura Hexagonal no FakeFlix (uma palavra que muda de sentido = uma fronteira). A IA acha o sinal; você confirma que a divergência de sentido é real no negócio.

Onde a IA vai errar (e você precisa pegar)

Três erros recorrentes, todos conectados a conceitos do curso:

• Coesão lógica disfarçada de contexto (aula Coesão: o outro lado da moeda): agrupar tudo que "faz a mesma categoria de coisa" (todos os validators, todos os controllers) em vez de por domínio. Sinal: o grupo tem um nome genérico e entidades de negócio dispersas.
• Fronteira no lugar errado por acoplamento acidental: se o legado tem uma GodClass que toca tudo, a IA pode inferir que "tudo é um contexto só" porque tudo depende dela. O acoplamento acidental (aula As dimensões do acoplamento: força, distância e tempo) mascara as fronteiras reais.
• Ignorar o não-óbvio no negócio: dois conceitos que o código trata igual mas o negócio trata diferente (ou vice-versa). A IA não tem como saber; só quem conhece o negócio pega.

Por isso a saída da IA nunca é a decisão — é a pauta da reunião com quem conhece o domínio.

Medindo acoplamento e coesão com objetividade

A segunda força da IA é transformar "eu acho que está acoplado" em números. Aqui ela é mais confiável, porque medir acoplamento estrutural é uma tarefa mecânica (contar dependências), e a IA pode extrair e resumir isso em escala. Conecte cada métrica aos conceitos do curso:

• Acoplamento aferente/eferente (fan-in/fan-out): quantos módulos dependem de X (aferente) e de quantos X depende (eferente). Alto fan-in num módulo instável = perigo (mudá-lo quebra muitos). Alto fan-out = X sabe demais sobre o mundo.
• Coacoplamento no histórico (git): quantos commits que tocam A também tocam B (a evidência objetiva de acoplamento que citamos lá na aula Por que não existe arquitetura perfeita). A IA pode processar o log do git e produzir essa matriz.
• Tipo de acoplamento (aula As dimensões do acoplamento: força, distância e tempo): a IA pode classificar cada dependência cruzada — "content importa a entity de billing" (stamp/content coupling) vs. "content chama um método público" (data coupling).
• Coesão por proximidade de mudança (aula Coesão: o outro lado da moeda): se elementos de um módulo mudam por motivos diferentes (aparecem em commits com contextos distintos), sinal de baixa coesão.

Um prompt de medição, que pede número + interpretação + a fronteira sugerida:

A partir do grafo de dependências e do histórico de commits abaixo, para cada par de
módulos (A, B):
1. fan-in e fan-out de cada módulo;
2. % de commits que tocam A e B juntos (coacoplamento temporal);
3. classifique o tipo de acoplamento das dependências A→B: {content, common, control,
   stamp, data} e cite a linha/import que evidencia;
4. sinalize os pares com acoplamento FORTE (content/common/control/stamp) a DISTÂNCIA
   grande (módulos diferentes) — são os candidatos prioritários a refatoração.

Apresente como tabela ordenada por risco (força × coacoplamento). Cite a evidência de
cada classificação; não classifique sem apontar o trecho que a sustenta.

A exigência "cite a evidência de cada classificação" é o que separa medição de alucinação. A IA é capaz de inventar uma métrica plausível se você deixar; forçá-la a apontar o import/linha/commit que sustenta cada número te dá algo auditável. Você confere uma amostra; se as evidências batem, confia no resto; se não batem, o prompt (ou o modelo) não é confiável para aquilo e você recalibra.

O resultado é uma matriz de risco priorizada: os pares com acoplamento forte a distância grande (a combinação venenosa da aula As dimensões do acoplamento: força, distância e tempo) sobem ao topo. Isso responde a pergunta que todo refactoring de legado precisa responder e quase nunca responde com evidência: por onde começar?. Você não começa pelo que "parece feio"; começa pelo que a matriz mostra como forte-acoplado-e-muda-junto — o maior retorno por unidade de esforço.

O fluxo completo: da leitura à decisão

Juntando tudo, o fluxo de análise arquitetural assistida por IA tem quatro etapas, e o papel humano cresce a cada uma:

1. Levantamento (IA faz quase tudo): a IA lê o código, extrai responsabilidades, entidades, grafo de dependências e histórico. Volume puro — deixe a máquina fazer.
2. Hipóteses de fronteira (IA propõe, você audita): a IA agrupa em candidatos a contexto, extrai vocabulários e termos ambíguos. Você lê as justificativas procurando os três erros da seção 2.
3. Medição (IA calcula, você verifica a evidência): a IA produz a matriz de acoplamento/coesão com trechos citados. Você confere uma amostra das evidências.
4. Decisão (você, com o negócio): você leva as hipóteses validadas e a matriz de risco para quem conhece o domínio, confronta com a Linguagem Ubíqua, e decide as fronteiras reais e a ordem de refatoração. A IA não participa desta etapa — ela não conhece o negócio.

A proporção que importa: a IA comprime meses de levantamento em dias e te dá evidência priorizada. Mas a fração final — decidir a fronteira — continua sendo o trabalho de mais alto valor do arquiteto, e é justamente a que a IA não pode fazer. Usar IA bem em arquitetura é automatizar o levantamento para ter mais tempo para o julgamento, não terceirizar o julgamento.

Essa comprensão de tempo é o ROI real: no ERP da abertura, o levantamento que levaria três meses virou três dias, e eu gastei as semanas seguintes onde importava — validando fronteiras com o pessoal de negócio e planejando a extração incremental (aula Quando (e quando NÃO) migrar para microserviços). A IA não me deu a arquitetura; me deu de volta o tempo para pensá-la.

Antes → Depois

Tradeoffs e armadilhas

• Confiança fabricada é o maior risco. A IA apresenta um recorte errado com a mesma fluência de um certo. Sem a exigência de evidência citada e de marcar [INCERTO], você aceita erros por não ter como distingui-los dos acertos. Sempre force a evidência e sempre valide com o negócio.
• Ela codifica o acoplamento existente como se fosse desejável. Se o legado é um espaguete, a IA pode inferir que "tudo é um contexto só" porque tudo depende de tudo. A IA descreve o que é, não o que deveria ser; separar descrição de prescrição é trabalho seu.
• Contexto limitado em bases enormes. Um sistema de 400k linhas não cabe de uma vez. Você precisa fatiar (por diretório, por módulo suspeito) e a IA pode perder relações cross-fatia. Compense analisando o grafo de dependências global (que é compacto) separadamente do código detalhado.
• Métrica vira meta (Goodhart). Se você otimizar cegamente "reduzir fan-out" que a IA mediu, pode criar indireção acidental (aula Complexidade essencial vs. acidental e carga cognitiva) só para melhorar o número. As métricas guiam o diagnóstico; elas não são o objetivo. O objetivo é o design saudável.
• A IA não substitui a aula Governança automatizada: fitness functions com ESLint + Husky. O mapa que a IA produz é um retrato de um momento. Depois de refatorar, é a fitness function no CI que mantém as fronteiras — não uma nova análise de IA a cada sprint. IA para descobrir; automação para defender.

Cola mental

• IA em arquitetura: excelente para gerar hipóteses de fronteira em escala, ruim para decidir se estão certas. Ela conhece o texto/estrutura; não conhece o seu negócio.
• Regra inegociável: IA propõe fronteiras candidatas; você valida com a Linguagem Ubíqua (aula DDD estratégico + Arquitetura Hexagonal no FakeFlix) e o negócio. Confiança dela ≠ conhecimento do negócio.
• Sinal de ouro que a IA acha bem: termo ambíguo (mesma palavra, sentidos diferentes = fronteira, aula DDD estratégico + Arquitetura Hexagonal no FakeFlix).
• Faça a IA medir (fan-in/out, coacoplamento no git, tipo de acoplamento da aula As dimensões do acoplamento: força, distância e tempo) e citar a evidência de cada número — medição auditável, não opinião.
• Erros a pegar: coesão lógica disfarçada de contexto (aula Coesão: o outro lado da moeda), fronteira mascarada por acoplamento acidental (aula As dimensões do acoplamento: força, distância e tempo), divergência código-vs-negócio.
• Fluxo: IA levanta e mede (dias, não meses) → você decide a fronteira com o negócio. O ROI é tempo de volta para o julgamento, não julgamento terceirizado.
• IA descobre; fitness function (aula Governança automatizada: fitness functions com ESLint + Husky) defende.

Referências para Aprofundamento

Medir antes de decidir

• Your Code as a Crime Scene — Adam Tornhill — A base das métricas desta aula: coacoplamento por histórico, pontos quentes de mudança, complexidade por arquivo.
• Code Maat e CodeScene — A ferramenta aberta e a comercial que implementam essas análises; rodar em cima do próprio repositório vale mais do que qualquer exemplo.
• dependency-cruiser — Extrai o grafo de dependências real, que é o insumo objetivo para conferir o que a IA propôs.

Descoberta de fronteira com o negócio

• EventStorming — Alberto Brandolini — O método de workshop para descobrir fronteiras conversando com quem entende o domínio. É a etapa que a IA não substitui.
• DDD Starter Modelling Process — DDD Crew — Roteiro para transformar a hipótese da IA em decisão validada.

Sobre confiar na saída do modelo

• Working Effectively with Legacy Code — Michael Feathers — O contraponto necessário: antes de recortar legado, é preciso conseguir testá-lo. As técnicas de seam continuam sendo trabalho humano.

Exercícios

Exercício 1 — Critique o recorte

A IA analisou um legado e propôs este bounded context: NotificationContext, agrupando EmailValidator, SmsSender, PushNotificationService, PaymentReceiptGenerator e MarketingCampaignScheduler, justificando: "todas lidam com comunicação com o usuário". Aplicando a aula Coesão: o outro lado da moeda, esse agrupamento é sólido? Que erro a IA provavelmente cometeu, e como você validaria/corrigiria com o negócio?

Exercício 2 — Ache a fronteira pelo termo ambíguo

A IA reporta: a palavra order aparece em OrderFulfillmentService (manipula shippingAddress, warehouse, trackingCode) e em OrderBillingService (manipula taxRate, invoice, paymentMethod). Que sinal da aula DDD estratégico + Arquitetura Hexagonal no FakeFlix isso representa? Quantos bounded contexts há provavelmente, e por quê? O que você perguntaria ao negócio para confirmar?

Exercício 3 — Interprete a matriz

A IA produziu, para o par (inventory, pricing): fan-in de inventory = 12; coacoplamento no git = 68%; tipo de dependência pricing → inventory = "stamp (importa a entity Product inteira de inventory)". Traduza cada número para risco arquitetural usando as aulas As dimensões do acoplamento: força, distância e tempo e Por que não existe arquitetura perfeita, e diga se este par é prioritário para refatoração.

Exercício 4 — Escreva o prompt

Você quer que a IA classifique as dependências cruzadas entre billing e content num legado, distinguindo data coupling de formas mais fortes, e exija evidência. Escreva o prompt, incluindo as salvaguardas contra confiança fabricada (o que você força a IA a fazer/admitir).

Você é um analista de arquitetura. Abaixo estão os imports e chamadas entre os módulos
`billing` e `content` de um sistema legado, com trechos de código.

Para cada dependência cruzada (billing→content e content→billing):
1. Classifique o tipo de acoplamento em {content, common, control, stamp, data}, onde
   data = troca apenas do dado mínimo via método público, e stamp/content/common/control
   = formas mais fortes (expõe estrutura interna, estado global, ou flags de controle).
2. Cite o trecho EXATO (arquivo + linha/import) que sustenta a classificação. Não
   classifique nenhuma dependência sem apontar a evidência.
3. Marque [INCERTO] quando o trecho não deixar claro o tipo, e explique a ambiguidade —
   não escolha um tipo para "completar a tabela".
4. Ao final, liste apenas as dependências classificadas como mais fortes que data coupling,
   pois são os alvos de refatoração para Public API.

Não infira intenção de negócio; se precisar do significado de um termo para classificar,
sinalize isso em vez de assumir.

Exercício 5 — Papel da IA vs. papel humano

Um gestor diz: "já que a IA mapeou os domínios, vamos deixá-la também aprovar o plano de refatoração e definir as fronteiras finais, para ganhar velocidade". Responda com dois argumentos concretos sobre por que a decisão de fronteira deve permanecer humana, conectando com a força/fraqueza da IA e com o custo de errar uma fronteira (aulas Por que não existe arquitetura perfeita e Quando (e quando NÃO) migrar para microserviços).