Recursos · 84

Decisões de arquitetura: conservar razões e saber rever

Documentar escolhas importantes sem transformar cada reunião num dossier excessivo.

Atualizado · 3 min

Sala vazia de operações de inteligência cibernética à noite Ilustração editorial gerada com IA

O que este guia ajuda a alcançar

  • Delimitar a decisão
  • Comparar opções plausíveis
  • Registar escolha e consequências
  • Preservar o histórico
  • Definir motivos de revisão

Verificação rápida

  • Cada tarefa precisa de ADR?
  • Uma decisão aceite pode mudar?
  • O registo garante uma boa escolha?

Método passo a passo

  1. 1

    Delimitar a decisão

    Escolher uma questão com efeitos duradouros: alojamento, integração, armazenamento ou limites de componentes. Um ADR conserva as razões de uma escolha arquitetural relevante. Descrever problema e restrições reais, sem fabricar uma justificação posterior.

    Resultado: questão e âmbito.

  2. 2

    Comparar opções plausíveis

    Incluir soluções realmente consideradas, também manter o sistema atual se viável. Usar critérios comuns para utilização, segurança, operação, custos e saída. Separar medições, afirmações documentais e hipóteses ainda não verificadas.

    Resultado: tabela de critérios e evidências.

  3. 3

    Registar escolha e consequências

    Anotar opção, responsável, data e estado. Descrever dívida, migração e limitações aceites. Aprovar não elimina uma restrição conhecida. Ligar a decisão aos requisitos cumpridos e aos controlos pendentes.

    Resultado: decisão aceite e consequências explícitas.

  4. 4

    Preservar o histórico

    Uma decisão substituída deve continuar compreensível. Ligar à sucessora sem reescrever o passado. Distinguir proposta, aceite, rejeitada e substituída; manter ligações a tarefas e provas acessíveis à equipa.

    Resultado: registo e relações entre versões.

  5. 5

    Definir motivos de revisão

    Especificar mudanças de volume, disponibilidade, localização ou custos fora das hipóteses. Um sinal inicia nova comparação, não abandono automático. Confirmar se o novo responsável consegue explicar a escolha.

    Resultado: motivos e teste de passagem de responsabilidade.

Caso de aceitação reproduzível

Exemplo fictício: estes dados não descrevem clientes nem resultados observados.

Ver dados do caso
{
    "decision": "ADR-7",
    "status": "accepted",
    "assumption": {
        "requests_per_day": 1000
    },
    "current_requests_per_day": 100000
}

Decisão esperada

A hipótese de carga mudou por um fator 100. Reveja ADR-7 conservando o histórico.

Variantes fictícias a verificar

Um ADR está aceite, mas só um de três serviços o aplica.

Distinga decisão aceite e implementação concluída. Acompanhe os restantes serviços com responsável, eventual exceção e prova de adoção.

O piloto exige p95 ≤ 200 ms; o teste mede 350 ms.

O critério não foi cumprido. Guarde carga, janela e resultado; decida uma revisão em vez de declarar o piloto aprovado.

Uma exceção temporária chega à data de revisão.

Marque-a para reavaliação. O silêncio não renova automaticamente a exceção; atribua uma decisão datada com condições e responsável.

Evidências a conservar

  • Estado ADR e adoção por serviço.
  • Critérios do piloto, procedimento e resultado medido.
  • Responsável, prazo e decisão sobre a exceção.

Procedimento de verificação

  1. Registe decisão, alternativas e hipóteses de carga.
  2. Compare hipótese falhada com contexto atual.
  3. Conserve ADR anterior e ligação ao substituto. Date a hipótese alterada, nomeie o responsável e a prova necessária para decidir se a substituição responde ao novo contexto.

AWS Prescriptive Guidance — Architectural decision record process

Planilha reutilizável

Preencha com suas observações autorizadas. Estes campos são um modelo de trabalho, não resultados observados.

CampoInformações a serem registradas
QuestãoProblema, âmbito e restrições
OpçõesSoluções e critérios comuns
EscolhaEstado, responsável e consequências
RevisãoMotivo e decisão substituta

Exemplo prático fictício

Situação ilustrativa

Exemplo fictício: uma equipa escolhe pesquisa gerida por não ter a disponibilidade operacional necessária.

Decisão e evidências esperadas

O ADR conserva a restrição, os exports esperados e motivos de revisão para novas exigências linguísticas ou custos.

Distinguir os mecanismos

MecanismoFinalidadeVerificação ou limitação
AtaConserva a discussãoA decisão pode ficar dispersa
ADRConserva escolha e razõesNão substitui especificações ou testes
TarefaSegue a implementaçãoPode terminar sem guardar os motivos

Indicadores de gestão

IndicadorO que medePrimeira ação
Escolhas rastreáveisDecisões com contexto acessívelPriorizar dependências difíceis de assumir
Hipóteses verificadasSuposições decisivas testadasRever onde faltam evidências
PassagemEscolhas explicáveis pelo novo responsávelMelhorar o registo

Erros comuns

  • A decisão pode ficar dispersa
  • Não substitui especificações ou testes
  • Pode terminar sem guardar os motivos

Perguntas frequentes

Cada tarefa precisa de ADR?

Não. Usar em escolhas cujas consequências ou reversibilidade justificam conservar as razões.

Uma decisão aceite pode mudar?

Sim. Registar nova decisão, contexto e relação com a substituída, preservando os motivos anteriores.

O registo garante uma boa escolha?

Não. Torna critérios e hipóteses verificáveis; a qualidade das evidências continua decisiva.

Leituras e ferramentas complementares

Recursos editoriais para aprofundar o método.

Referências oficiais

As referências apoiam o método. Adapte as verificações ao seu contexto; elas não são uma certificação. Os títulos das referências originais e os documentos de origem podem estar em outro idioma.

Referências consultadas em .