Como registrar decisões de arquitetura para uso com IA

Meses depois de uma escolha arquitetural, a equipe pode voltar ao mesmo ponto sem perceber: por que esta integração existe, quais alternativas foram descartadas e que consequência foi aceita?

Quando uma IA sugere uma mudança, o problema raramente é só sintaxe ou teste local. O risco maior é ela responder bem a uma tarefa pequena e mal ao desenho do sistema. Um bom registro reduz essa ambiguidade para pessoas e agentes.

O critério de registro é este: quando alguém, humano ou agente, for alterar o sistema daqui a algum tempo, a informação essencial precisa estar recuperável para não repetir uma discussão antiga como se fosse descoberta nova.

Essa pergunta muda o papel do registro de decisão de arquitetura, também conhecido como ADR, do inglês architecture decision record. Ele deixa de ser um documento de conformidade e passa a ser uma unidade pequena de contexto. Pequena o bastante para ser lida durante uma revisão. Independente o bastante para sobreviver fora da memória de quem participou da escolha. Testável o bastante para orientar uma alteração concreta.

Esse cuidado afeta a adoção de IA no processo de engenharia. Se a organização está estruturando uma estratégia de inteligência artificial conectada ao negócio, a documentação técnica não pode ser tratada como arquivo morto. Ela passa a fazer parte do ambiente em que decisões assistidas por IA são tomadas, revisadas e corrigidas.

Registre decisões que limitam mudanças futuras

Nem toda decisão técnica merece um ADR. Se a equipe registrar cada preferência local, o repositório vira um cemitério de documentos que ninguém consulta. O critério deve ser consequência, não gosto.

Uma decisão de arquitetura precisa ser registrada quando cria limite para alterações futuras. Isso inclui escolhas que afetam mais de um módulo, definem padrões de integração, criam dependências operacionais, impõem exceções relevantes ou tornam uma mudança tecnicamente possível, mas indesejada no desenho atual.

Alguns sinais ajudam:

A escolha afeta mais de uma equipe, serviço ou domínio.
Uma alternativa tecnicamente viável foi rejeitada por um motivo de arquitetura.
A mudança exige um padrão que deve ser repetido em outras partes do sistema.
Uma exceção foi aceita e pode parecer erro para quem chegar depois.
Um teste, contrato ou verificação passa a proteger a decisão.
A decisão deve ser reaberta se uma condição específica mudar.

O ponto não é documentar tudo. É documentar o que cria fronteira.

O DORA recomenda trabalhar com unidades pequenas, independentes e testáveis para obter retorno sobre mudanças e revisar hipóteses mais cedo. A mesma orientação alerta para a dificuldade de revisar e integrar grandes mudanças geradas com IA em um fluxo de engenharia DORA. Um ADR útil segue a mesma lógica: ele deve ser pequeno, independente e revisável.

Quando o registro vira tratado, ele atrapalha. Quando vira uma frase solta, ele não orienta. O formato certo está no meio: contexto suficiente para decidir, pouca narrativa e consequência explícita.

O contexto para IA precisa separar restrição de circunstância

A Anthropic define engenharia de contexto como a seleção e manutenção das informações disponíveis ao modelo durante a inferência. Esse conjunto inclui instruções, ferramentas, dados externos e histórico, dentro de uma janela limitada Anthropic. Em outras palavras, contexto não é tudo que existe. É o que entra na mesa no momento em que a IA vai responder.

Por isso, um ADR precisa distinguir informações persistentes de informações transitórias.

Informações persistentes são aquelas que continuam relevantes para futuras alterações: limites de domínio, dependências críticas, requisitos de consistência, padrões de comunicação, regras de isolamento, premissas de segurança operacional, restrições de observabilidade ou compatibilidade com componentes existentes.

Informações transitórias são pressões do momento: prazo de entrega, disponibilidade de uma pessoa, uma restrição temporária de infraestrutura ou uma decisão tomada para destravar uma etapa específica. Elas podem entrar no registro, mas não devem parecer fundamento permanente.

Um bom campo de contexto responde:

Qual problema estava sendo resolvido?
Que restrições realmente limitaram a escolha?
Que parte do sistema é afetada?
Que condição era temporária e não deve ser confundida com regra arquitetural?

Esse cuidado evita um erro comum em fluxos assistidos por IA: o agente encontra uma decisão antiga, mas não sabe se ela ainda representa uma restrição do sistema ou apenas um atalho histórico. Se a equipe não separa as duas coisas, a ferramenta pode preservar o que deveria ser revisto ou propor quebrar o que deveria ser protegido.

Para equipes que estão amadurecendo o uso de IA, essa distinção também se conecta ao diagnóstico de capacidades. Um diagnóstico de maturidade em IA não deveria olhar apenas para ferramentas disponíveis, mas para a qualidade do contexto que sustenta decisões e revisões.

Alternativas devem ser registradas sem congelar a discussão

Registrar alternativas não significa reabrir o debate toda vez que alguém lê o ADR. Significa explicar por que uma opção plausível não foi escolhida.

Esse é um ponto especialmente relevante para decisões de arquitetura e IA. Um agente de código pode sugerir uma solução tecnicamente correta porque ela é comum, simples ou bem representada em exemplos públicos. Mas o sistema real pode ter rejeitado essa solução por causa de acoplamento, consistência, latência, operação, dependência entre times ou custo de mudança.

O registro deve descrever alternativas com três elementos:

O que foi considerado.
Por que foi descartado naquele contexto.
Em que condição poderia voltar a ser considerado.

A terceira parte é a que separa arquitetura viva de dogma. Uma decisão não precisa ser eterna para ser respeitada. Ela precisa dizer quando deve ser reaberta.

Por exemplo, em vez de escrever apenas “não usar chamada síncrona entre estes serviços”, o ADR pode registrar: “a chamada síncrona direta foi descartada porque aumentaria o acoplamento entre o fluxo de pedido e o serviço de faturamento. Ela pode ser reavaliada se a dependência operacional entre os serviços mudar e se houver um critério de degradação explícito para falha de faturamento”.

Isso dá trabalho, mas evita uma revisão improdutiva. O revisor não precisa dizer apenas “já discutimos isso”. Ele pode apontar: “a sugestão repete uma alternativa descartada e não apresenta a condição nova que justificaria reabrir a decisão”.

Esse é o tipo de frase que transforma memória oral em critério operacional.

Consequência arquitetural precisa virar critério de revisão

A parte mais fraca de muitos registros de decisão é a consequência. A equipe escreve a opção adotada, lista uma justificativa genérica e segue em frente. Meses depois, ninguém sabe qual custo foi aceito conscientemente.

Toda decisão de arquitetura compra alguma coisa e paga com outra. Pode facilitar evolução de um módulo e dificultar rastreamento de fluxo. Pode reduzir acoplamento e aumentar latência eventual. Pode simplificar operação e limitar autonomia de domínio. Pode tornar o código mais explícito e aumentar repetição.

Se a consequência não aparece, a revisão humana fica presa ao funcionamento local do código. O revisor pergunta se passou no teste, se compila, se segue o estilo. Mas deixa de perguntar se a mudança preserva o desenho escolhido.

Um ADR útil transforma consequência em pergunta de revisão:

O que esta decisão torna mais fácil?
O que torna mais difícil?
Que risco a equipe aceitou?
Que tipo de acoplamento passou a existir?
Que teste ou verificação protege a escolha?
Que alteração exigiria revisão humana mais cuidadosa?

A documentação do GitHub sobre agentes do Copilot descreve recursos com ambientes e permissões distintos e ressalta supervisão humana e revisão das saídas GitHub. O ponto aqui não é transferir decisão para a ferramenta. É desenhar um fluxo em que a revisão humana consiga enxergar o que a ferramenta pode ter ignorado.

É nesse ponto que o ADR vira critério de revisão.

Se uma alteração assistida por IA contradiz uma consequência assumida, o problema não é apenas “o agente errou”. Pode ser uma de três coisas: a mudança está desalinhada, o ADR ficou incompleto ou a decisão antiga precisa ser reaberta. Cada uma exige uma ação diferente.

Um formato mínimo para ADRs utilizáveis por pessoas e agentes

O valor de um ADR não está no tamanho. Está na precisão da decisão. Um formato mínimo pode funcionar melhor do que um modelo extenso, desde que capture os pontos que orientam futuras alterações.

Um registro enxuto pode conter:

Título: escrito com domínio, módulo ou padrão afetado.
Status: proposto, aceito, substituído ou reaberto.
Data: a data real da decisão no repositório.
Contexto: problema, restrições persistentes e circunstâncias transitórias relevantes.
Decisão: a opção adotada, escrita como escolha concreta.
Alternativas: opções consideradas, motivo de descarte e condição de retorno.
Consequências: custos aceitos, riscos assumidos e comportamento esperado.
Verificação: teste, regra de revisão, contrato ou evidência que protege a decisão.
Sinais de reabertura: condições que justificam mudar a decisão.
Links internos: arquivos, módulos, pull requests ou documentos relacionados no repositório.

O título merece atenção. Para uma pessoa, ele ajuda a encontrar o documento. Para um agente, ele ajuda a recuperar o contexto certo quando a tarefa menciona um módulo, domínio ou padrão. Um título como “Comunicação assíncrona no fluxo de confirmação de pedido” é melhor do que “ADR 014”. O identificador pode existir, mas não deve carregar sozinho o significado.

O campo de verificação também é decisivo. Se não há teste automatizado, pode haver um critério explícito de revisão. O DORA descreve integração contínua como integração frequente ao código principal, acompanhada de construção e testes automatizados. Corrigir uma construção quebrada deve ter prioridade sobre novas mudanças DORA. O ADR não substitui esse fluxo, mas pode dizer que tipo de teste ou verificação precisa existir para proteger a escolha.

Para quem está organizando um roadmap de IA, esse ponto costuma ser menos vistoso do que escolher ferramentas. Ainda assim, ele pesa na capacidade de usar IA sem depender de memória informal a cada alteração.

Critérios mínimos para registrar uma decisão de arquitetura utilizável por IA

Use estes critérios antes de considerar um ADR pronto para orientar pessoas e agentes:

Contexto: o registro explica qual problema estava sendo resolvido e quais restrições eram relevantes no momento da escolha? Sinal de aceite: uma pessoa ou agente consegue distinguir o motivo da decisão de uma preferência técnica genérica.
Alternativas: o registro apresenta pelo menos uma alternativa considerada e por que ela foi descartada? Sinal de aceite: uma próxima sugestão de código que repita a alternativa rejeitada precisa trazer uma condição nova.
Decisão: a opção adotada está escrita como escolha concreta, não como princípio abstrato? Sinal de aceite: é possível apontar no código quais mudanças obedecem ou violam a decisão.
Consequências: o registro declara o custo aceito, o risco assumido e o comportamento esperado do sistema depois da escolha? Sinal de aceite: a revisão consegue avaliar não só se o código funciona, mas se preserva o desenho escolhido.
Teste ou verificação: existe algum teste, verificação automatizada ou critério de revisão associado à decisão? Sinal de aceite: a decisão não depende apenas de memória oral para ser protegida.
Reabertura: o registro diz em quais condições a decisão deve ser revista? Sinal de aceite: a equipe sabe quando mudar de ideia sem tratar toda mudança como quebra de arquitetura.
Recuperação por IA: o título, os termos e os links internos ajudam o registro a aparecer no contexto de uma tarefa relacionada? Sinal de aceite: um agente ou desenvolvedor consegue encontrar a decisão a partir do módulo, domínio ou padrão afetado.

Esse checklist não prova que a arquitetura é boa. Ele apenas testa se a escolha foi escrita de modo que possa ser recuperada, discutida e revisada.

Como usar o ADR na revisão de mudanças assistidas por IA

O ADR precisa entrar no fluxo de revisão, não ficar isolado em uma pasta que só aparece em retrospectivas. Quando uma mudança assistida por IA toca um módulo com decisão registrada, o revisor deveria fazer quatro perguntas.

Primeira: a mudança respeita o contexto da decisão? Se o ADR afirma que o módulo não deve depender diretamente de outro serviço, a revisão precisa verificar se a sugestão criou essa dependência por conveniência.

Segunda: a mudança contradiz alguma consequência assumida? Se a arquitetura aceitou latência eventual em troca de menor acoplamento, uma alteração que tenta simular consistência imediata pode estar desfazendo a decisão sem declarar isso.

Terceira: a IA introduziu uma alternativa implícita? Às vezes o código não diz “vamos mudar a arquitetura”, mas cria um padrão novo que passa a competir com o anterior.

Quarta: a alteração exige novo ADR ou reabertura do anterior? Nem toda divergência é erro. Às vezes o contexto mudou. O problema é mudar sem nomear a mudança.

Esse desenho torna a revisão mais explícita. Não porque a IA passa a obedecer sempre, mas porque a equipe consegue revisar com critérios visíveis.

Exemplo fictício: comunicação entre serviços em um fluxo de pedido

Considere um exemplo fictício. Uma equipe mantém um sistema de pedidos e um serviço de faturamento. Ao implementar a confirmação de pedido, um agente sugere uma chamada síncrona direta: quando o pedido é confirmado, o serviço de pedidos chama o serviço de faturamento e aguarda a resposta.

A solução parece simples. Passa nos testes locais do módulo. O código é legível. Mas existe um ADR aceito pela equipe para aquele fluxo.

O registro diz que a comunicação entre pedidos e faturamento, nesse caso específico, deve ser assíncrona. O contexto: o fluxo de pedido precisa continuar disponível mesmo quando o faturamento estiver temporariamente indisponível. A restrição persistente: pedidos e faturamento têm ritmos operacionais diferentes. A circunstância transitória: havia pressão para simplificar a primeira entrega, mas ela não deveria virar justificativa permanente.

A alternativa descartada foi chamada síncrona direta. O motivo: ela aumentaria o acoplamento operacional entre os serviços e faria uma indisponibilidade de faturamento bloquear a confirmação do pedido. A alternativa poderia ser reaberta se o produto passasse a exigir confirmação de faturamento antes de aceitar o pedido e se o desenho de degradação fosse definido.

A decisão adotada foi publicar um evento de pedido confirmado e permitir que o faturamento processe esse evento de forma assíncrona. As consequências aceitas foram latência eventual, necessidade de idempotência no consumidor e maior atenção à observabilidade do fluxo. A verificação associada inclui testes para evitar processamento duplicado do mesmo evento e revisão humana cuidadosa quando uma mudança tentar introduzir dependência direta entre os serviços.

Nesse cenário fictício, a revisão da sugestão da IA não precisa depender de gosto. O revisor pode dizer: “a mudança propõe uma alternativa já descartada e não apresenta condição nova para reabrir o ADR”. Também pode pedir uma alteração mais precisa: “mantenha a publicação de evento, preserve idempotência e atualize o teste que protege duplicidade”.

Os efeitos esperados dessa prática seriam hipóteses a medir, não resultados presumidos. A equipe poderia observar se menos sugestões repetem alternativas descartadas, se revisões ficam mais objetivas e se mudanças arquiteturais passam a ser reabertas explicitamente. Mas isso precisa ser acompanhado no fluxo real, não declarado como benefício automático.

O limite: ADR não salva arquitetura ruim nem substitui julgamento

Um ADR ruim pode dar aparência de rigor a uma escolha fraca. Registrar uma decisão não a torna correta. Também não transfere autoridade para a IA reinterpretar arquitetura antiga.

A IA pode recuperar, comparar e sugerir. Pode ajudar a localizar documentos, resumir consequências e apontar possíveis conflitos. Mas, quando uma mudança altera direção arquitetural, a revisão humana continua sendo parte do desenho do processo. Não como correção tardia. Como decisão deliberada sobre risco, custo e evolução.

Também vale reconhecer que algumas decisões não precisam virar ADR. Preferências locais, ajustes reversíveis e mudanças sem consequência arquitetural podem ficar no pull request ou na documentação do módulo. Forçar formalidade onde não há impacto cria ruído e reduz adesão.

Na próxima semana, escolha um módulo com mudanças frequentes, identifique uma decisão arquitetural que limita alterações futuras e registre-a em formato mínimo: contexto, alternativa, decisão, consequência, verificação e reabertura. Depois, use esse histórico para reabrir decisões explicitamente quando o contexto mudar.

Se quiser discutir essa decisão no contexto da sua empresa, converse com a dooop.

Leituras para continuar

Fontes

PRÓXIMA DECISÃO

Conversar sobre a aplicação na empresa

Conversa sobre o contexto da empresa de software

Conteúdo de dooop. O cadastro permite relacionar esta pauta à jornada do leitor e acompanhar o interesse pelo tema.