Como separar fato, hipótese e opinião em uma decisão de arquitetura

O problema começa antes da decisão

Uma equipe precisa decidir se deve extrair um serviço, atualizar o framework ou reescrever um módulo crítico. A reunião começa com um diagrama antigo, algumas histórias de incidentes e a sensação compartilhada de que “essa parte do sistema está ficando impossível de mudar”.

Então alguém afirma que o módulo é o principal gargalo. Outra pessoa diz que quase ninguém entende o código. Um terceiro participante lembra que houve muitos bugs ali no último trimestre. As frases parecem apontar para a mesma conclusão, mas não significam a mesma coisa.

Uma parte pode ser observada diretamente no repositório. Outra depende de contexto operacional. Outra ainda é apenas uma hipótese plausível. Quando tudo entra no documento final com o mesmo tom de certeza, a decisão ganha uma aparência de precisão que não tem.

Esse é um problema comum em diagnósticos de arquitetura: não falta apenas informação. Falta distinguir o que foi medido, o que foi respondido por alguém e o que continua desconhecido.

Um laudo sem lastro vira opinião bem formatada

Considere um achado como “o módulo de pagamentos tem alto acoplamento”. Para ser útil, essa frase precisa responder a algumas perguntas:

• Quais arquivos pertencem ao módulo?
• Quais dependências foram consideradas?
• O acoplamento é entre componentes, classes, bancos ou equipes?
• A conclusão vem de imports, chamadas em runtime, histórico de mudança ou entrevista?
• Existe uma linha de corte possível para a mudança proposta?

Sem essas respostas, o achado pode até estar correto, mas não é verificável. Quem lê precisa confiar no autor do relatório e repetir a investigação quando surgir uma contestação.

O mesmo vale para afirmações aparentemente simples. “A cobertura de testes é baixa” pode significar cobertura estrutural baixa, ausência de testes de contrato ou falta de cenários para falhas. “O código muda muito” pode ser uma impressão baseada em incidentes recentes ou uma observação sustentada pelo histórico do Git. “A arquitetura é monolítica” pode descrever o deploy, o repositório ou a ausência de fronteiras internas — três coisas diferentes.

O documento que não separa essas camadas cria dois custos. Primeiro, o time discute a validade do diagnóstico em vez de discutir a decisão. Depois, qualquer plano de remediação começa a ser executado sobre premissas que ninguém sabe mais de onde vieram.

O que uma análise confiável precisa mostrar

Uma análise técnica útil não precisa fingir que sabe tudo. Ela precisa deixar claro o alcance do que sabe.

1. A evidência precisa ser localizável

Um fato sobre o sistema deve apontar para sua origem: arquivo, linha, configuração, rota, dependência ou trecho do histórico. Isso não transforma automaticamente a observação em uma boa decisão, mas permite que outra pessoa a verifique.

Por exemplo, “há tratamento silencioso de erro” é mais útil quando vem acompanhado de um local específico e de uma explicação do impacto possível. O leitor pode abrir o código, confirmar o comportamento e contestar a interpretação sem recomeçar a investigação inteira.

2. A incerteza precisa aparecer

Nem toda informação importante está no repositório. O código pode mostrar que existe um fluxo de personalização, mas não dizer se ele é essencial para o negócio. Pode mostrar retries em uma integração, mas não revelar se o endpoint remoto aceita chamadas repetidas com segurança.

Nesses casos, o correto não é preencher a lacuna com uma suposição apresentada como fato. É marcar a questão como inconclusiva, registrar a pergunta e capturar a resposta de quem conhece o contexto. Uma estimativa também pode ser útil, desde que esteja identificada como estimativa.

A incerteza não enfraquece o laudo. Ela informa onde uma decisão depende de investigação adicional.

3. O achado precisa levar a uma escolha

Uma lista de problemas não é ainda um plano. O time precisa entender por que determinado ponto merece atenção agora, qual risco reduzido está em jogo e que opções existem.

Um hotspot de alta complexidade e alta frequência de mudança pode justificar uma costura para colocar o legado sob teste. Uma dependência sem manutenção pode alterar a ordem de uma migração. Uma API usada por muitos consumidores pode tornar uma extração aparentemente simples em um projeto de compatibilidade.

A conexão entre evidência e ação deve ser explícita. Sem ela, a priorização tende a seguir quem fala mais alto, quem conhece melhor o histórico ou quem tem uma preferência tecnológica já formada.

Um processo prático para melhorar o diagnóstico

Antes de aprovar uma grande mudança, vale conduzir uma revisão curta com quatro saídas concretas:

1. Inventário verificável: linguagens, runtimes, componentes, integrações e pontos de entrada encontrados no código.
2. Achados com contexto: cada problema ligado à evidência, ao possível impacto e ao grau de confiança.
3. Perguntas abertas: informações que dependem do negócio, da operação ou de decisões que não estão registradas.
4. Plano em ondas: ações priorizadas por risco, dependências, esforço e reversibilidade.

O formato importa menos que a disciplina. Um documento em Markdown pode cumprir esse papel tão bem quanto uma ferramenta sofisticada, desde que o time consiga navegar da conclusão até a evidência e da evidência até a ação.

Também é importante comparar versões do diagnóstico. Se o sistema mudou, o time deve conseguir distinguir uma melhora real de uma alteração no método de medição. Sem essa comparação, cada nova avaliação vira um retrato isolado e não uma trajetória.

Onde o ArchGenerator entra

Esse tipo de problema é uma das situações em que uma plataforma de diagnóstico pode ajudar sem substituir o julgamento da equipe. O ArchGenerator conecta-se ao repositório, executa análises de arquitetura, segurança, saúde do código, integrações, migração e evolução, e apresenta os achados com a evidência correspondente.

Quando o repositório não responde a uma pergunta de negócio, a ausência de informação não é convertida em certeza artificial. A questão pode ser direcionada ao responsável, com a resposta registrada separadamente do fato apurado no código. O resultado é um diagnóstico que mostra o que foi encontrado, o que foi informado e o que continua inconclusivo.

A parte mais útil vem depois do relatório: os achados podem dar origem a um kit SDD com especificações, contratos, governança e sensores de progresso. Assim, a análise não precisa terminar em um PDF arquivado. Ela pode servir como ponto de partida para mudanças menores, verificáveis e ordenadas.

A decisão continua sendo do time. O ganho está em reduzir a discussão sobre “quem está certo” e aumentar a clareza sobre “qual evidência sustenta esta escolha, qual risco ela reduz e o que ainda precisamos descobrir”.