Registro de decisões: o que ficou combinado e por quê

De onde vem a ideia

Em "Documenting Architecture Decisions" (Cognitect, 15 de novembro de 2011), Nygard parte de uma observação: os documentos grandes de projeto ficam desatualizados, quase ninguém os lê, e a motivação por trás das escolhas se perde. Ele propõe um registro curto por decisão significativa, que ficou conhecido pela sigla ADR (Architecture Decision Record, ou registro de decisão de arquitetura). Cada registro tem título, contexto, decisão, status e consequências, boas e ruins. Os registros são numerados em sequência, e o número nunca é reaproveitado. Se a decisão é revertida, o registro antigo permanece, marcado como substituído.

O site adr.github.io define o ADR como o registro de uma única decisão e da sua justificativa, e chama de histórico de decisões o conjunto deles. Ele observa que a prática pode se estender a outras decisões de projeto. O governo do Reino Unido publicou em novembro de 2025 um guia para o setor público em que cada registro leva título, data, status, contexto, decisão, consequências, as partes consultadas e links para documentos de apoio.

Nenhuma dessas fontes é estudo. São guias de prática, e nenhum deles mede se registrar decisões melhora as decisões.

Os campos, adaptados para o dia a dia

Martin Fowler recomenda que o registro caiba, de preferência, em uma página, com a decisão logo no começo. Ele inclui as alternativas sérias, com prós e contras, o grau de confiança e as mudanças de contexto que deveriam levar a reavaliar a escolha. O guia da Microsoft sobre o tema pede que se registre o nível de confiança, porque uma decisão tomada com pouca segurança merece ser revisitada, e que as consequências não sejam escondidas, nem de propósito nem por descuido.

Sem os termos de software, os campos ficam assim:

Dois cuidados de redação vêm de Nygard. O contexto deve ser descrito em tom neutro, com as tensões à mostra, sem defender a escolha antes de ela aparecer. E a decisão deve ser uma frase completa, na voz ativa, que no original começa com "nós vamos". Na prática, "vamos contratar a gráfica B" cumpre o mesmo papel. A razão é de bom senso: "talvez", "em princípio" e "a gente vê" não dizem a quem chega depois o que foi decidido, e o registro só serve se responder isso sem rodeios.

Dois exemplos completos

O primeiro é de trabalho. A situação e os nomes são inventados.

DECISÃO: Gráfica do catálogo de 2027
Data: 2026-11-11 | Status: valendo | Decidiram: Marta e Paulo

CONTEXTO
Catálogo precisa estar pronto em 3 semanas. Orçamento fechado.

DECISÃO
Contratar a gráfica B.

MOTIVO
Entrega em 10 dias, pelo mesmo preço da gráfica A.

ALTERNATIVAS
- Gráfica A: 15% mais barata, mas entrega em 25 dias. Estoura o prazo.
- Imprimir internamente: não há máquina adequada.

O QUE SE ACEITA PERDER
Sem prova de cor impressa antes da tiragem. Confiança: média.

REVISAR EM: 2026-12-02, depois da primeira entrega

O segundo é de vida pessoal, e mostra que o método não depende de empresa.

DECISÃO: Reforma do banheiro fica para março
Data: 2026-11-11 | Status: valendo

CONTEXTO
Dois orçamentos recebidos. A obra leva cerca de 15 dias. A família
recebe visitas no fim do ano.

DECISÃO
Fazer a obra em março.

MOTIVO
Evita obra na época das visitas. Os dois orçamentos valem até 2027-03-31.

ALTERNATIVAS
- Fazer em dezembro: a obra coincide com as visitas.
- Não fazer: a infiltração no teto continua.

O QUE SE ACEITA PERDER
Mais três meses com a mancha no teto. Vigiar a cada semana.

REVISAR EM: 2027-01-15, ou antes se a mancha aumentar

Nos dois casos, o motivo e a alternativa descartada ocupam mais linhas que a decisão. É neles que o futuro vai procurar. O segundo exemplo traz um gatilho de revisão, "ou antes se a mancha aumentar", além da data, no espírito da recomendação de Fowler de anotar que mudanças de contexto devem reabrir a conversa.

Quando vale registrar e quando não vale

O guia da Microsoft sugere incluir só escolhas que afetam a estrutura do sistema, as qualidades essenciais ou que são difíceis de reverter. Traduzindo para o dia a dia, vale registrar a decisão que custa dinheiro ou tempo relevante, que é difícil de desfazer, que envolve mais de uma pessoa ou que alguém vai perguntar de novo. Escolher o horário do almoço não entra. O mesmo guia lembra que uma decisão tomada e nunca registrada tende a ser esquecida, o que leva a debates repetidos e a mudanças que contradizem a intenção original.

Muitas decisões saem de reunião. Nesse caso, a nota da reunião tem a linha curta da decisão e o registro tem a versão completa. Fowler observa ainda que escrever o registro esclarece o raciocínio e expõe divergências que precisam ser discutidas. Por isso convém escrevê-lo na hora, em uns cinco minutos, quando o contexto está fresco. O prazo de cinco minutos é regra prática da equipe, não resultado de pesquisa.

Onde guardar e como revisar

Guarde tudo no mesmo lugar, em ordem de data: um caderno, uma pasta de documentos ou um aplicativo de notas, o que for achado com facilidade. Nygard guardava os registros no próprio repositório do projeto, ao lado do material que eles explicam. O equivalente é manter o registro perto do que ele afeta.

Registro aceito não se reescreve. Nygard, Fowler e o guia da Microsoft dizem a mesma coisa: quando a decisão muda, escreve-se um registro novo, o antigo recebe o status "substituído" e os dois ficam ligados. O histórico mostra quando e por que a direção mudou. Três estados bastam para o uso comum: proposta, valendo e substituída.

A revisão fica por conta da data que você escreveu. O guia do governo britânico recomenda revisar e atualizar o registro quando o contexto ou as consequências mudam. A data de revisão é adaptação nossa para decisões pessoais e de trabalho. Coloque-a na agenda da semana ou na revisão semanal das notas, e deixe no diário de trabalho uma linha que aponte para o registro.

Erros comuns

• Registrar só a decisão, sem o motivo. O guia da Microsoft afirma que um registro sem justificativa perde o valor com o tempo, pois ninguém consegue avaliar se a decisão ainda vale.
• Escrever semanas depois. Nesse ponto já se está descrevendo de memória.
• Apagar ou reescrever o registro antigo quando a decisão muda, em vez de criar um novo.
• Registrar tudo. Quando cada escolha miúda vira registro, o que importa fica enterrado.
• Esconder as consequências ruins. Elas são o que mais ajuda quem revisar a escolha.
• Transformar o registro em relatório. O guia da Microsoft pede textos curtos e objetivos; a decisão deve ficar clara sem depender de anexos.

Perguntas frequentes

Isso serve só para quem trabalha com software?

Não. A origem é a engenharia de software, mas o modelo é simples: contexto, escolha, motivo, alternativas e revisão. A adaptação para o trabalho em geral e para a vida pessoal é da equipe, sem estudo que a comprove.

Preciso de um aplicativo específico?

Não. Serve qualquer lugar em que os registros fiquem em ordem de data e possam ser achados depois. A recomendação das fontes é manter o registro perto do material que ele explica.

E se a decisão se mostrar errada?

O registro mostra o que se sabia na época, o que ajuda a separar uma escolha razoável de uma escolha que só deu errado. É um argumento de bom senso, sem estudo citado aqui. Na revisão, o caminho é escrever uma decisão nova e marcar a antiga como substituída.

Quanto o registro deve ter?

Fowler sugere no máximo algumas páginas, idealmente uma. Para decisões pessoais, dez a quinze linhas costumam bastar.

Fontes

• Documenting Architecture Decisions. Michael Nygard, Cognitect, 2011. Consultado em 11/11/2026.
• Architectural Decision Record Framework. Department for Science, Innovation and Technology e Government Digital Service (GOV.UK), 2025. Consultado em 11/11/2026.
• Architectural Decision Records (ADRs). Organização adr, GitHub. Consultado em 11/11/2026.
• Architecture Decision Record. Martin Fowler. Consultado em 11/11/2026.
• Maintain an architecture decision record (ADR). Microsoft Azure Well-Architected Framework, Microsoft Learn, 2026. Consultado em 11/11/2026.