Como registrar uma decisão de arquitetura a partir de uma gravação
Um ADR descreve uma decisão de arquitetura importante: contexto, alternativas, opção escolhida, consequências e status. A transcrição ajuda a recuperar os argumentos. Os participantes conferem a precisão técnica.
Como escrever um Architecture Decision Record a partir da discussão gravada
Um ADR descreve uma decisão de arquitetura importante: contexto, alternativas, opção escolhida, consequências e status. A transcrição ajuda a recuperar os argumentos. Os participantes conferem a precisão técnica.
A transcrição permite conferir o que foi dito. Preserva o contexto, as ressalvas e a sequência dos argumentos. A pessoa responsável decide o texto final e pede a revisão dos participantes.
Monte o ADR passo a passo
Escolha uma decisão
Use um registro separado para cada decisão de arquitetura independente.
Descreva o contexto
Anote os fatores e as limitações que tornaram a decisão necessária.
Compare as opções
Registre as principais vantagens, desvantagens e motivos para descartar cada opção.
Indique as consequências
Liste os benefícios, custos, novas limitações, riscos e o que levaria à revisão da decisão.
Exemplo didático: como armazenar arquivos de áudio
O exemplo didático abaixo é fictício. Nomes, condições e resultados servem apenas para explicar o método.
“O armazenamento de objetos custa menos para o arquivo, mas vamos precisar de um mecanismo separado para links temporários.”
Contexto: as gravações são grandes, o acesso deve expirar e a emissão de links precisa de controle. A escolha é o armazenamento de objetos. Além do custo, contam a escalabilidade e o modelo de acesso.
Inclua o trabalho e os riscos nas consequências: links temporários, controle de validade, registros e testes de falha. Se a premissa de custo mudar, um novo ADR pode substituir o anterior e preservar o histórico.
| Seção | Registro útil | Exemplo a evitar |
|---|---|---|
| Contexto | Arquivos grandes e acesso restrito | Precisamos de um novo armazenamento |
| Opções | Armazenamento de objetos / arquivos | Escolhemos o melhor |
| Decisão | Armazenamento de objetos pelos motivos A e B | O arquiteto decidiu |
| Consequências | Links temporários e monitoramento | Não há desvantagens |
Modelo de ADR
Copie o modelo e preencha com base em uma gravação específica. Identifique suposições como hipóteses.
Título e status: Data e participantes: Contexto e limitações: Opções consideradas: Decisão e motivos: Consequências, riscos e condição para revisão:
Quatro verificações antes de enviar
- O registro descreve uma decisão.
- O contexto inclui limitações reais.
- As alternativas e os motivos para descartá-las foram registrados.
- Há desvantagens e uma condição para revisão.
Veja os detalhes
Posso editar um ADR aceito?
Você pode corrigir erros de digitação. Se a decisão mudar, faça um novo ADR com link para o anterior.
Preciso guardar a transcrição junto do ADR?
Em geral, um link para a fonte interna e uma marca de tempo bastam para conferir uma formulação em discussão.