O problema
Seis meses depois de um sistema de triagem de tickets ir pra produção, alguém pergunta: "por que decidimos usar um único agente em vez de múltiplos agentes especializados aqui?" Ninguém no time atual sabe responder — a pessoa que tomou a decisão saiu da empresa, e a única memória do raciocínio era uma conversa de Slack que ninguém consegue mais encontrar. O time considera reabrir a decisão do zero, gastando semanas para redescobrir uma conclusão à qual já tinham chegado antes.
Esse é o custo de uma decisão de arquitetura não documentada: ela não desaparece quando a pessoa sai, mas o raciocínio por trás dela desaparece — e sem o raciocínio, a decisão vira algo que ninguém consegue defender, questionar de forma informada, ou confiar o suficiente pra manter.
O que faz uma decisão sobreviver a quem a tomou
Documentar arquitetura não significa escrever um relatório extenso sobre tudo que foi considerado. Significa registrar, de forma enxuta e estruturada, o suficiente para que alguém que não estava na sala consiga entender e questionar a decisão depois:
- O contexto real — não o pedido literal que chegou, mas a restrição de negócio por trás dele.
- A decisão em si — em uma frase que alguém consegue repetir de memória, não um parágrafo ambíguo.
- O que foi descartado e por quê — especificamente qual restrição cada alternativa violava, não uma lista genérica de "outras opções".
- A consequência aceita — o que essa decisão custa, em troca do que ela resolve.
Esse formato (um Architecture Decision Record, ou ADR) não é burocracia — é o que transforma uma decisão implícita, guardada só na cabeça de quem decidiu, em um artefato que sobrevive à saída dessa pessoa, a uma auditoria, ou a uma pergunta de um novo integrante do time seis meses depois.
Comunicar trade-offs sem perder precisão
A segunda parte desta lição é sobre quem lê essas decisões: normalmente não é só outro arquiteto. É um stakeholder de negócio que precisa aprovar orçamento, um time de produto que precisa priorizar, ou um executivo que precisa decidir entre duas propostas concorrentes — pessoas que não vão avaliar a decisão pelo mérito técnico de baixo nível.
O erro comum aqui tem duas direções opostas, ambas ruins:
- Traduzir demais — remover todo o detalhe técnico até a comunicação virar só otimismo genérico ("essa solução vai funcionar bem"), sem dar ao stakeholder informação suficiente pra realmente avaliar o trade-off que está sendo pedido.
- Não traduzir o suficiente — apresentar a decisão em termos que só outro arquiteto entenderia, forçando o stakeholder a aprovar algo que não consegue avaliar de verdade.
A resposta certa preserva o trade-off real (custo, risco, tempo, o que fica pior em troca do que fica melhor) na linguagem do stakeholder, sem simplificar a ponto de esconder a decisão que está sendo tomada. Um stakeholder de negócio não precisa saber o que é RAG — precisa saber que essa escolha custa X a mais por mês em troca de reduzir o tempo de resposta em Y, e que a alternativa mais barata teria um risco Z que o time considerou inaceitável.
Sustentar o sistema além do lançamento
A última peça é reconhecer que o trabalho do arquiteto profissional não termina quando o sistema entra em produção. O ciclo de vida completo — discovery, design, handoff, monitoramento e iteração — significa que a documentação e a comunicação precisam continuar existindo depois do lançamento, não só até ele.
Isso aparece de forma prática em dois lugares: um runbook de handoff que permite que o time de operação sustente o sistema sem depender de quem o construiu, e um canal estabelecido para revisitar decisões quando a realidade de produção diverge do que foi planejado (uma SLA que não está sendo cumprida, um custo que ficou acima do estimado). Um sistema sem esse canal de feedback tende a acumular desvio silencioso — a arquitetura documentada para de refletir o que realmente está rodando, e ninguém percebe até um incidente forçar a descoberta.
Coloque em prática
O laboratório desta lição pede que você monte e valide a estrutura de um pacote de comunicação de decisão — um ADR técnico e sua tradução para stakeholder de negócio — verificando que o trade-off real (não só o benefício) aparece nas duas versões, e que a versão para stakeholder não perde a informação necessária pra uma aprovação informada.