ADRs em lote, e a regra da visibilidade

A confiança na IA não começa no modelo, começa no processo.

Esta é a oitava parte de uma série sobre a metodologia que uso para continuar sendo, de fato, o responsável pelo que um agente de IA produz. Aqui, entro na segunda metade da maquinaria mais pesada: como registrar decisões quando não houve tempo de fazer isso em tempo real.

Se você tivesse que reconstruir, agora, por que uma decisão de arquitetura de três meses atrás foi tomada daquele jeito, sem perguntar a ninguém, só olhando o que ficou escrito, você conseguiria, ou cairia no mesmo silêncio que um agente sem memória tácita cairia?

Disclaimer: este texto reflete minha visão prática sobre o tema, construída em projetos pessoais e profissionais. Não representa, necessariamente, a posição oficial de nenhuma organização à qual eu esteja afiliado.

O formato que uso para isso não é invenção minha. Michael Nygard formalizou o Architecture Decision Record (ADR) em 2011, a partir de um problema simples de nomear e difícil de resolver: uma pessoa nova num projeto, diante de uma decisão passada que não entende, só tem duas opções, aceitar cegamente ou mudar cegamente. Um ADR existe para dar a ela uma terceira opção: entender o porquê, e julgar por conta própria se aquele porquê ainda se sustenta.

O artigo sobre as três práticas que nunca esperam gatilho já descreveu a versão contínua desse problema: um prazo curto, de alguns dias, para registrar qualquer decisão relevante num ADR, para que o atraso natural entre decidir e documentar nunca vire desculpa permanente. Mas nenhum dos oito projetos vive só da versão contínua.

Durante uma janela de rigor (depois de um dos quatro eventos de risco que descrevi no artigo anterior), é normal, e aceitável, que várias decisões precisem ser registradas de uma vez, mesmo que retroativamente. É essa versão em lote, e as regras que a tornam confiável, que este artigo descreve.

Consolidar em lote não é uma versão mais fraca do registro contínuo

Registrar em lote funciona como rede de segurança para o que o prazo curto contínuo não capturou a tempo. Não é um substituto dele, nem uma desculpa para nunca registrar nada até a auditoria obrigar.

As mesmas regras de sempre valem, sem exceção: um ADR vigente nunca é reescrito, é substituído por uma nova versão que referencia o anterior, preservando o histórico de como o pensamento evoluiu.

Essa disciplina foi testada numa situação real que vale a pena contar em detalhe. Um plano de release intermediário foi descontinuado antes de chegar a ser publicado, mas um registro de decisão vigente ainda o descrevia como decisão corrente.

Corrigir esse registro no próprio documento, em vez de criar uma nova versão que o substituísse, não violava a convenção de imutabilidade, porque essa convenção protege decisões que entraram em vigor, não as que nunca chegaram a existir de fato fora de um plano descartado antes de rodar.

Reconhecer essa distinção foi uma decisão tomada de propósito, não uma sugestão aceita sem pensar. É esse tipo de julgamento, saber quando uma regra protege algo real e quando ela protegeria só a aparência de disciplina, que nenhum guardrail sozinho substitui.

Uma decisão de não fazer algo (recusar uma funcionalidade, adiar uma correção mais profunda) merece o mesmo registro que uma decisão de fazer. É, na prática, a mais fácil de ser desfeita sem querer por um agente que não tem esse contexto: sem o registro de que aquilo foi deliberado, a próxima sessão de trabalho pode “corrigir” silenciosamente uma omissão que nunca foi omissão nenhuma.

É esse mesmo cuidado que me levou a automatizar parte dessa auditoria: uso o Adrpy e o Adrpy-tui, ferramentas próprias de código aberto para ADRs, com uma integração de agente de IA que confere se a cadeia de versões está de fato íntegra (nenhuma substituição feita à mão quebrou o encadeamento) e sinaliza decisões que ficaram tempo demais sem sair do status inicial, sinal de que já foram tomadas na prática, só não formalizadas. O agente não decide nada, só devolve um relatório: o julgamento de que uma discrepância é real, como no caso do plano de release descontinuado contado acima, continua sendo meu. Volto a essa ferramenta no artigo IA no time não reduz o bus factor do seu projeto — pode aumentar.

A regra da visibilidade

Há um tipo específico de decisão que merece uma regra própria, além do registro em si: toda vez que uma decisão for “não agir automaticamente diante de uma falha” (não fazer retry, não reiniciar sozinho, não fazer failover automático), esse registro precisa incluir como a decisão continua visível enquanto estiver em efeito. Não basta documentar que a decisão foi tomada; é preciso garantir que o silêncio que ela produz, no dia a dia, não seja confundido com normalidade.

Já contei, em Metodologia de Desenvolvimento Assistido por IA Centrada na Decisão Humana, o caso que ilustra bem esse risco: um componente crítico que, ao falhar uma única vez na inicialização, fazia toda a telemetria seguinte parar de existir silenciosamente. Um sistema podia estar completamente quebrado sem gerar nenhum sinal.

A correção certa ali não foi reverter a decisão original de não fazer retry automático, que continuava válida. Foi só garantir que o silêncio se tornasse visível.

Essa é exatamente a regra: a decisão de não agir automaticamente pode, e às vezes deve, continuar sendo a decisão certa. O que não pode continuar é ela ser silenciosa o bastante para ser confundida com “está tudo bem”.

Revisão de documentação como técnica de achar bug, não tarefa de redação

Uma revisão que só checa se a documentação bate com o comportamento real do código costuma ser tratada como trabalho de redação, um jeito de deixar o texto “mais bonito” ou “mais completo”. Isso subestima o que ela realmente é: uma técnica de encontrar defeitos, com o mesmo peso que um teste.

A diferença entre os dois é só onde a discrepância aparece. Um teste revela quando o código não faz o que deveria; uma revisão de documentação revela quando o código faz uma coisa e o texto que descreve esse código afirma outra, e uma das duas está errada.

Isso importa mais, não menos, com um agente de IA no meio. Um agente não tem a memória tácita do “isso aqui já mudou, o texto é que ficou pra trás” que um engenheiro humano desenvolve com o tempo. Ele lê a documentação como se fosse fato corrente, e trabalha a partir dela sem sinalizar que talvez esteja desatualizada.

Uma revisão de documentação, tratada como técnica de achar bug, é o que fecha essa lacuna antes que ela vire uma decisão errada tomada com confiança. Vale rodar essa revisão periodicamente, não só como preparação de release. Em mais de um caso, foi exatamente esse tipo de revisão, e não uma decisão prévia de “ser mais rigoroso”, que revelou um bug real e disparou o resto da disciplina.

Na prática

Trate um registro em lote como legítimo, não como sinal de que o processo falhou. O processo só falharia se as decisões nunca fossem registradas. Registrar depois, numa janela de rigor, é exatamente o que essa janela existe para fazer.

Nunca reescreva um registro vigente para refletir uma mudança de opinião. Substitua por uma nova versão que referencia a anterior. A trilha de como o pensamento evoluiu é tão valiosa quanto a decisão atual.

Reconheça a diferença entre uma decisão que entrou em vigor e uma que nunca chegou a existir de fato. A convenção de imutabilidade protege a primeira. Aplicá-la cegamente à segunda é confundir disciplina com rigidez.

Toda decisão de “não agir automaticamente” precisa de um plano explícito de visibilidade, não só de um registro. Pergunte, no momento de registrar: como alguém vai perceber que essa decisão está em efeito, no dia em que ela realmente importar?

Rode revisão de documentação como rotina de achar bug, não como preparação pontual de release. Se a única vez que a documentação é revisada é antes de publicar, ela já ficou desatualizada por tempo demais entre uma revisão e outra.

Conclusão

Registro em lote e a regra da visibilidade resolvem o mesmo problema de fundo por ângulos diferentes: o primeiro garante que uma decisão sobreviva ao momento em que foi tomada; o segundo garante que uma decisão de silêncio deliberado não vire, por acidente, um silêncio que ninguém mais nota.

Nenhum dos dois é sobre documentação por documentação. É sobre garantir que a estrutura ao redor da IA continue contando a verdade, mesmo quando ninguém está olhando naquele momento específico.

No próximo artigo desta série, um caso aplicado direto: o que acontece com o bus factor de um projeto quando um agente de IA entra no time sem que esse registro exista.

Tenham um excelente dia!

Eu sou Fernando Cerqueira e entrego estratégias digitais para os desafios do presente, com propostas de inovação para um futuro sustentável. Como arquiteto sênior, aproveito meus mais de 30 anos de experiência em arquitetura e desenvolvimento de software para projetar e implementar soluções baseadas em nuvem que ajudam os clientes a transformar seus negócios com tecnologia.

Este texto foi escrito com apoio do Claude Code, a partir da minha experiência, minhas decisões e revisão: o próprio processo que a série descreve.

Nesta série

1. Metodologia de Desenvolvimento Assistido por IA Centrada na Decisão Humana
2. Disciplina em rajada: por que o rigor não nasce junto com o código
3. O código duplicado que a IA cria enquanto parece produtiva
4. As três práticas que nunca esperam gatilho
5. Quem autorizou essa atualização de dependência? Pode ter sido sua IA
6. Os quatro eventos de risco e a auditoria multi-frente
7. Seu agente de IA resolve a issue de verdade, ou só parece resolver?
8. ADRs em lote, e a regra da visibilidade (este artigo)
9. IA no time não reduz o bus factor do seu projeto — pode aumentar
10. Calibrando a intensidade ao risco real
11. O alinhamento entre produto e engenharia começa onde a decisão fica registrada
12. Segurança psicológica também vale para o time formado por você e sua IA
13. Releitura: o papel do humano, os sinais que funcionam, e onde a metodologia ainda é fraca

Referências citadas

• Michael Nygard, “Documenting Architecture Decisions” (Cognitect, 2011): https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions
• Fernando Cerqueira, AdrPlus — ferramenta .NET CLI de código aberto para Architecture Decision Records: adrpy-ai e adrpy-tui.