Architecture Decision Record

Registro de decisão de arquitetura (ADR)

Modelos, exemplos e orientações para registrar decisões de arquitetura.

Um registro de decisão de arquitetura (ADR) é um documento que registra uma decisão de arquitetura importante, junto com seu contexto e suas consequências.

Traduções: العربية, বাংলা, Cymraeg, Dansk, Deutsch, English, Ελληνικά, Română, Polski, Español, Eesti, Suomi, Français, हिन्दी, Bahasa Indonesia, Íslenska, Italiano, 日本語, 한국어, Nederlands, Português, Русский, Svenska, Kiswahili, ไทย, Türkçe, اردو, Tiếng Việt, 中文

Faça sua própria diligência prévia sobre estes recursos antes de usá-los em quaisquer sistemas críticos.

Conteúdo:

Modelos:

Exemplos:

O que é um registro de decisão de arquitetura?

Um registro de decisão de arquitetura (ADR) é um documento que captura uma decisão arquitetural importante tomada, juntamente com seu contexto e suas consequências.

Uma decisão de arquitetura (AD) é uma escolha de design de software que atende a um requisito significativo.

Um registro de decisões de arquitetura (ADL) é a coleção de todos os ADRs criados e mantidos para um projeto (ou organização) específico.

Um requisito arquiteturalmente significativo (ASR) é um requisito que tem um efeito mensurável na arquitetura de um sistema de software.

Tudo isso está dentro do tópico da gestão do conhecimento de arquitetura (AKM).

O objetivo deste documento é fornecer uma visão geral rápida dos ADRs, de como criá-los e de onde procurar mais informações.

Abreviações:

  • AD: decisão de arquitetura

  • ADL: registro de decisões de arquitetura

  • ADR: registro de decisão de arquitetura

  • AKM: gestão do conhecimento de arquitetura

  • ASR: requisito arquiteturalmente significativo

Como começar a usar ADRs

Para começar a usar ADRs, converse com seus colegas de equipe sobre estas áreas.

Identificação da decisão:

  • Quão urgente e quão importante é o AD?

  • Ele precisa ser tomado agora ou pode esperar até que se saiba mais?

  • Tanto a experiência pessoal e coletiva quanto métodos e práticas de design reconhecidos podem ajudar na identificação de decisões.

  • Idealmente, mantenha uma lista de decisões a tomar que complemente a lista de tarefas do produto.

Tomada de decisão:

  • Existem várias técnicas de tomada de decisão, tanto gerais quanto específicas de arquitetura de software, por exemplo, o mapeamento de diálogo.

  • A tomada de decisão em grupo é um tópico de pesquisa ativo.

Promulgação e aplicação da decisão:

  • Os ADs são usados no design de software; portanto, precisam ser comunicados e aceitos pelas partes interessadas do sistema que o financiam, desenvolvem e operam.

  • Estilos de codificação arquiteturalmente evidentes e revisões de código que se concentram em preocupações e decisões arquiteturais são duas práticas relacionadas.

  • Os ADs também precisam ser (re)considerados ao modernizar um sistema de software na evolução do software.

Compartilhamento da decisão (opcional):

  • Muitos ADs se repetem entre projetos.

  • Portanto, as experiências com decisões passadas, boas e ruins, podem ser ativos reutilizáveis valiosos ao empregar uma estratégia explícita de gestão do conhecimento.

Documentação da decisão:

  • Existem muitos modelos e ferramentas para captura de decisões.

  • Veja as comunidades ágeis, por exemplo, os ADRs de M. Nygard.

  • Veja os processos tradicionais de engenharia de software e design de arquitetura, por exemplo, os layouts de tabela sugeridos pela IBM UMF e por Tyree e Akerman, da CapitalOne.

Para saber mais:

Como começar a usar ADRs com ferramentas

  • MySpec — Plataforma automatizada de especificação e decisão de arquitetura que estrutura a constituição do projeto, a arquitetura técnica e os ADRs em Markdown limpo servido via MCP.

Você pode começar a usar ADRs com ferramentas da maneira que quiser.

Por exemplo:

  • Se você gosta de usar o Google Drive e a edição online, pode criar um Google Doc ou uma Google Sheet.

  • Se você gosta de usar controle de versão de código-fonte, como o git, pode criar um arquivo para cada ADR.

  • Se você gosta de usar ferramentas de planejamento de projetos, como o Atlassian Jira, pode usar o rastreador de planejamento da ferramenta.

  • Se você gosta de usar wikis, como o MediaWiki, pode criar uma wiki de ADRs.

Como começar a usar ADRs com git

Se você gosta de usar o controle de versão git, veja como gostamos de começar a usar ADRs com git em um projeto de software típico com código-fonte.

Crie um diretório para os arquivos de ADR:

$ mkdir adr

Para cada ADR, crie um arquivo de texto, como database.txt:

$ vi database.txt

Escreva o que quiser no ADR. Veja os modelos neste repositório para ter ideias.

Faça commit do ADR no seu repositório git.

Skills do Claude Code para ADRs

Este repositório inclui duas skills do Claude Code em skills/, para que um agente de programação com IA possa escrever e manter ADRs do jeito que este projeto recomenda:

  • architecture-decision-record-skill — de uso geral, para qualquer pessoa que escreva um ADR em qualquer projeto. Ajuda a decidir se uma decisão precisa de um ADR, cria um diretório adr/ ou decisions/, nomeia o arquivo, escolhe um modelo entre os onze esqueletos incluídos e escreve seções sólidas de contexto, decisão e consequências.

  • architecture-decision-record-maintainer-skill — específica para quem mantém este repositório. Documenta a estrutura do repositório, a convenção de espelhar README e locales e os passos exatos para adicionar um novo modelo, exemplo ou link de ferramenta.

Para usar uma skill, copie a pasta dela para .claude/skills/ na raiz do repositório em que você está trabalhando (ou para ~/.claude/skills/ para deixá-la disponível em todos os projetos) e peça ao Claude Code que escreva ou revise um ADR.

Convenções de nomes de arquivo

Se você optar por criar seus ADRs usando arquivos de texto comuns, talvez queira definir sua própria convenção de nomes de arquivo de ADR.

Preferimos usar uma convenção de nomes de arquivo que tenha um formato específico.

Exemplos:

  • choose-database.md

  • format-timestamps.md

  • manage-passwords.md

  • handle-exceptions.md

Nossa convenção de nomes de arquivo:

  • O nome tem uma locução verbal no imperativo do presente. Isso ajuda a legibilidade e combina com o formato das nossas mensagens de commit.

  • O nome usa letras minúsculas e hifens (igual a este repositório). É um equilíbrio entre legibilidade e usabilidade do sistema.

  • A extensão é markdown. Isso pode ser útil para formatar facilmente.

Sugestões para escrever bons ADRs

Características de um bom ADR:

  • Justificativa: explique os motivos para tomar o AD em questão. Isso pode incluir o contexto (veja abaixo), prós e contras de várias escolhas potenciais, comparações de recursos, discussões de custo/benefício e mais.

  • Específico: cada ADR deve tratar de um AD, não de vários ADs.

  • Carimbos de data e hora: identifique quando cada item do ADR foi escrito. Isso é especialmente importante para aspectos que podem mudar com o tempo, como custos, cronogramas, escalabilidade e similares.

  • Imutável: não altere informações existentes em um ADR. Em vez disso, emende o ADR adicionando novas informações ou substitua o ADR criando um novo ADR.

Características de uma boa seção “Contexto” em um ADR:

  • Explique a situação da sua organização e as prioridades de negócio.

  • Inclua justificativas e considerações baseadas na composição social e de habilidades das suas equipes.

  • Inclua prós e contras relevantes e descreva-os em termos alinhados às suas necessidades e objetivos.

Características de uma boa seção “Consequências” em um ADR:

  • Explique o que decorre de tomar a decisão. Isso pode incluir efeitos, resultados, saídas, desdobramentos e mais.

  • Inclua informações sobre quaisquer ADRs subsequentes. É relativamente comum um ADR desencadear a necessidade de mais ADRs, como quando um ADR faz uma grande escolha abrangente, o que por sua vez cria necessidade de mais decisões menores.

  • Inclua quaisquer processos de revisão pós-ação. É típico as equipes revisarem cada ADR um mês depois, para comparar as informações do ADR com o que aconteceu na prática, a fim de aprender e crescer.

Um novo ADR pode tomar o lugar de um ADR anterior:

  • Quando um AD é tomado e substitui ou invalida um ADR anterior, deve-se criar um novo ADR

Modelos de exemplo de ADR

Modelos de exemplo de ADR que coletamos na rede:

Conselhos de trabalho em equipe para ADRs

Se você está pensando em usar registros de decisão com sua equipe, aqui estão alguns conselhos que aprendemos trabalhando com muitas equipes.

Você tem a oportunidade de liderar seus colegas conversando juntos sobre o “porquê”, em vez de impor o “quê”. Por exemplo, registros de decisão são uma forma de as equipes pensarem de modo mais inteligente e se comunicarem melhor; registros de decisão não têm valor se forem apenas uma exigência burocrática imposta após o fato.

Algumas equipes preferem muito mais o nome “decisões” (decisions) à abreviação “ADRs”. Quando algumas equipes usam o nome de diretório “decisions”, é como se uma lâmpada se acendesse, e a equipe começa a colocar mais informações no diretório, como decisões de fornecedores, decisões de planejamento, decisões de cronograma etc. Todos esses tipos de informação podem usar o mesmo modelo. Nossa hipótese é que as pessoas aprendem mais rápido com palavras (“decisões”) do que com abreviações (“ADRs”), que as pessoas ficam mais motivadas a escrever documentos em andamento quando a palavra “registro” é removida e que alguns desenvolvedores e alguns gerentes não gostam da palavra “arquitetura”.

Em teoria, a imutabilidade é ideal. Na prática, a mutabilidade funcionou melhor para as nossas equipes. Inserimos a nova informação no ADR existente, com um carimbo de data e uma nota de que a informação chegou depois da decisão. Esse tipo de abordagem leva a um “documento vivo” que todos nós podemos atualizar. Atualizações típicas ocorrem quando recebemos informações graças a novos colegas, novas ofertas, resultados reais dos nossos usos ou mudanças de terceiros posteriores à decisão, como capacidades de fornecedores, planos de preços, contratos de licença etc.

Perguntas de trabalho em equipe para ADRs

Quem pode criar um ADR?

Considere áreas como pessoas específicas, papéis específicos, equipes específicas ou departamentos específicos; considere também se há pessoas, papéis, equipes ou departamentos que podem encomendar um ADR, ou seja, solicitar um que outra pessoa irá redigir.

Exemplo de resposta: qualquer pessoa da nossa organização que tenha lido a página README sobre registros de decisão de arquitetura pode propor um ADR, ou seja, pode começar a escrevê-lo e compartilhá-lo com a equipe.

O que justifica abrir um ADR?

Considere áreas como as formas de trabalho das equipes da sua organização, a estrutura do seu sistema de software, a coordenação entre equipes, a manutenibilidade de longo prazo, as interfaces externas, quem você quer beneficiar e similares.

Exemplo de resposta: queremos criar um ADR quando queremos que desenvolvedores futuros entendam o “porquê” do que estamos fazendo.

O que justifica não abrir um ADR?

Considere áreas como decisões que não são sobre arquitetura, ou são minúsculas, por exemplo de risco mínimo, autocontidas ou de um único desenvolvedor, ou já estão totalmente cobertas em outro lugar, como em padrões, políticas ou documentação, ou são temporárias, como soluções paliativas, provas de conceito ou experimentos.

Exemplo de resposta: queremos dispensar um ADR quando uma decisão é limitada em escopo, tempo, risco e custo, ou já está coberta em outro lugar.

Qual é o ciclo de vida de um ADR?

Considere áreas como o processo de criação, o processo de pesquisa, o processo de decisão, o processo de implementação e o processo de desativação. Considere como acompanhar o ciclo de vida do ADR ao longo do tempo, como mover o ADR de um estado para o próximo e também como comunicar isso às partes interessadas.

Exemplo de resposta: queremos que um ADR tenha cinco estágios de ciclo de vida: Iniciando → Pesquisando → Avaliando → Implementando → Mantendo → Desativando.

Quais são os critérios para as etapas do ciclo de vida de um ADR?

Considere áreas como os critérios de aceitação de um ADR, ou seja, como você sabe que ele está bom o suficiente para avançar de uma etapa do ciclo de vida para a seguinte? O problema está claramente articulado? As alternativas foram consideradas? Os trade-offs estão bem compreendidos e documentados? Todo o contexto relevante está presente? Todas as partes interessadas relevantes estão envolvidas? Todo o feedback foi incorporado?

Exemplo de resposta: queremos que um ADR seja votado pelas partes interessadas quando a equipe ativa tiver 1) concluído sua pesquisa, 2) concluído sua avaliação, 3) publicado a proposta de ADR para as partes interessadas com um pedido de comentários e um prazo de uma semana, 4) incorporado e tratado todos os comentários das partes interessadas.

Quais papéis e responsabilidades interagem com um ADR?

Considere papéis como proponente, pesquisador, avaliador, revisor, aprovador, mantenedor e similares. Considere responsabilidades como comunicação com as partes interessadas, garantia de que as expectativas sejam atendidas, compartilhamento no site ou na intranet e revisão periódica do trabalho, especialmente quando ocorrerem mudanças relevantes.

Exemplo de resposta: queremos que cada ADR sempre tenha uma pessoa de contato principal, uma pessoa de contato secundária e uma equipe responsável; elas são responsáveis por comunicações, publicações, manutenção, revisão periódica pelo menos uma vez por ano e eventual desativação, conforme necessário.

Como a governança interage com um ADR?

Considere áreas como as formas de trabalho da sua organização, quaisquer necessidades especiais de conformidade, por exemplo em aspectos jurídicos ou de recursos humanos, e como você quer lidar com consenso versus conflito versus escalonamento. Existem áreas, pessoas ou equipes que podem ter mais influência que outras sobre um ADR, como poder aprová-lo, votar nele ou vetá-lo?

Exemplo de resposta: a governança de um ADR obedece a esta ordem de prioridade: o CEO, o CTO, o CLO, a equipe que implementa um ADR, os especialistas da equipe mais conhecedores do ADD. Ninguém mais tem governança, a menos que descrito no ADR.

Quais princípios interagem com um ADR?

Considere áreas como as formas de trabalho da sua organização, que incluem agir rápido versus agir devagar, consenso de decisão versus conflito de decisão, preferências de risco versus preferências de segurança, discussão pública versus discussão privada e similares.

Exemplo de resposta: usamos os princípios de liderança de viés para a ação, discordar e comprometer-se, estimativas de 70% são boas o suficiente para decisões facilmente reversíveis e facilmente isoláveis, e formas de trabalho públicas, com exceção de informações confidenciais conforme descrito no acordo de confidencialidade da nossa organização.

Conceitos do próximo passo para ADRs

O Arc42 responde a duas perguntas de forma pragmática e pode ser adaptado às suas necessidades. O que você deve documentar/comunicar sobre a sua arquitetura? Como deve documentar/comunicar? O Arc42 inclui registros de decisão de arquitetura e orientações sobre metas, restrições, contextos, qualidade, riscos e mais.

O modelo C4 é uma abordagem fácil de aprender e amigável para desenvolvedores de diagramar a arquitetura de software. O C4 é um conjunto de diagramas hierárquicos de contexto, contêineres, componentes e código, além de diagramas de apoio para panorama de sistemas, dinâmica e implantação.

Diagramas, visões e pontos de vista de arquitetura

Um diagrama de arquitetura é chamado de "visão de arquitetura".

Uma "visão de arquitetura" é uma instância de um "ponto de vista de arquitetura".

Um "ponto de vista de arquitetura" considera um público específico com preocupações específicas.

Exemplos de pontos de vista, visões e diagramas de arquitetura:

Diagramas relacionados:

  • Um diagrama de casos de uso mostra casos de uso à gerência/aos clientes, o que precede os requisitos, que precedem a arquitetura de software.

  • Um diagrama de implantação mostra o hardware/os computadores físicos nos quais os componentes de software são implantados.

  • Um diagrama de fluxo de dados mostra como os dados se movem pelo sistema e são transformados.

  • Um diagrama de sequência é usado para mostrar como protocolos como HTTP funcionam em um eixo de tempo.

  • Um diagrama de atividades retrata o fluxo de trabalho das atividades que um sistema de software executa, como uma IA de NPC.

Funções de aptidão para decisões como código

Funções de aptidão (fitness functions) são verificações automatizadas e objetivas, escritas com código de programação, que verificam se as decisões estão sendo mantidas.

  • As funções de aptidão tornam as decisões testáveis e asseguráveis.

  • As funções de aptidão para decisões podem ajudar muito a garantia de qualidade, os processos regulatórios e os objetivos de governança.

Como as funções de aptidão se conectam às decisões

Um registro de decisão documenta a decisão, enquanto uma função de aptidão a assegura.

  • Exemplo de decisão: usamos event sourcing para requisitos de auditoria.

  • Exemplo de função de aptidão: usamos o servidor de integração contínua para testar que toda mudança de estado deve produzir eventos.

Por que as funções de aptidão ajudam as decisões

Medições objetivas: as funções de aptidão passam ou falham, então o trabalho fica visível e claro.

Uso contínuo: as funções de aptidão são suas regras vivas, executadas a cada commit e build.

Confiança para refatorar: as funções de aptidão detectam automaticamente erros nas regras de decisão.

Governança escalável: as funções de aptidão asseguram padrões sem criar gargalos.

As funções de aptidão podem usar IA?

As funções de aptidão podem aproveitar LLMs de IA para decisões, fazendo perguntas sobre o seu trabalho, como seus planos, código, esquemas, APIs e mais:

IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning.
IMPORTANT: Turn on extended thinking. Turn on expert advice. Turn on search.

This is a fitness function to evaluate if our work is
using all our decisions, and is correct and accurate.

- Our decisions are here: {url}
- Our work to evaluate is here: {url}

Explain any errors, problems, gaps, weaknesses. Be direct. Be decisive.

Teste unitário de arquitetura

ArchUnit: verifique regras de arquitetura de código Java usando qualquer framework de teste unitário Java comum.

ArchUnitTS: verifique regras de arquitetura de código TypeScript e JavaScript usando Jest, Vitest, Jasmine etc.

Proteções de decisão para pull requests

O Decision Guardian mostra automaticamente os registros de decisão certos no momento certo, ou seja, quando um desenvolvedor está modificando o código que essas decisões cobrem. Em vez de esperar que os desenvolvedores leiam uma pasta de documentos antes de mesclar, o contexto relevante aparece diretamente no pull request.

Isso funciona para qualquer tipo de registro de decisão: decisões de arquitetura, de dados, de conformidade, clínicas e médicas, de segurança e mais.

Funciona com qualquer sistema de CI (GitLab, Jenkins, CircleCI) e como hook de pre-commit. Código aberto. Licença MIT.

O ADR Guard é uma GitHub Action que reprova um pull request quando caminhos de código monitorados mudam sem que um registro de decisão de arquitetura seja adicionado ou atualizado. As isenções são explícitas: uma linha ADR-Exempt: com um motivo passa pelo portão e é escrita no resumo do job. Independe de modelo, sem dependências. Código aberto. Licença MIT.

Para mais informações

Introdução:

Modelos:

Aprofundamento:

Ferramentas:

Orientações específicas de empresas:

Exemplos:

Vídeos:

Podcasts:

Livros:

Veja também:

  • REMAP (Representation and Maintenance of Process Knowledge)

  • DRL (Decision Representation Language)

  • IBIS (Issue-Based Information System)

  • QOC (Questions, Options, and Criteria)

  • IBM’s e-Business Reference Architecture Framework

  • Decision Reasoning Format (DRF) - Um formato YAML/JSON neutro quanto a fornecedores e legível por máquina para representar decisões com raciocínio explícito, premissas, estado cognitivo e trade-offs. Complementa os ADRs ao adicionar raciocínio estruturado e validável à documentação de decisões.