Markdown Architectural Decision Records (MADR)
Os Markdown Architectural Decision Records (MADR) são o padrão adotado pela Amplimed para registrar decisões técnicas e arquiteturais relevantes de forma clara, versionável e acessível.
Uma Decisão Arquitetural (AD) é qualquer escolha justificada de design de software que impacte requisitos funcionais ou não funcionais de maneira significativa. Essa decisão é documentada em um Architectural Decision Record (ADR), que registra a decisão, seu contexto e o racional que levou à sua adoção.
O MADR fornece um template enxuto e estruturado em Markdown, permitindo que decisões importantes sejam registradas próximas ao código, com baixo custo operacional e alto valor histórico.
Visão Geral
Na Amplimed, consideramos como decisão arquitetural qualquer escolha que possa impactar a evolução do sistema ao longo do tempo, incluindo, mas não se limitando a:
- Escolha de tecnologias, frameworks ou bibliotecas
- Definição de padrões arquiteturais
- Estruturação de domínios, serviços ou integrações
- Decisões relacionadas a requisitos não funcionais
- Processos técnicos que afetam diretamente o produto
O termo “arquitetura” não deve ser interpretado de forma restritiva. Sempre que uma decisão tiver impacto estrutural, operacional ou de longo prazo, ela deve ser registrada como um ADR.
Os objetivos principais do uso de MADR na Amplimed são:
- Tornar explícitas decisões que normalmente ficariam implícitas
- Preservar o contexto e o racional das escolhas técnicas
- Facilitar revisões arquiteturais e code reviews
- Criar um histórico confiável de decisões ao longo do tempo
Exemplo de ADR
# Utilização das asserções nativas do PHPUnit em testes Laravel
## Contexto e Declaração do Problema
Como garantir asserções legíveis, consistentes e suficientes em testes automatizados mais complexos no Laravel, sem aumentar desnecessariamente o número de dependências no projeto?
## Opções Consideradas
- PHPUnit puro (asserções nativas)
- Pest plugins adicionais
- Bibliotecas externas de asserção (ex: Kahlan, custom matchers)
## Decisão
Opção escolhida: **PHPUnit puro**, utilizando as asserções nativas já integradas ao Laravel.
O PHPUnit é o framework de testes padrão do ecossistema PHP e já vem plenamente integrado ao Laravel. As funcionalidades oferecidas por bibliotecas adicionais não trazem ganhos suficientes de legibilidade ou expressividade que justifiquem o aumento de dependências, complexidade de manutenção e curva de aprendizado.
A decisão prioriza simplicidade, previsibilidade e alinhamento com o ecossistema oficial do framework.
## Aplicando MADR nos projetos da Amplimed
### Estrutura inicial
Cada repositório deve conter um diretório dedicado aos ADRs, preferencialmente:
docs/decisions/
Nesse diretório ficam todos os registros de decisão do projeto, separados do restante da documentação, mas versionados junto ao código.
### Criação de um novo ADR
1. Copie o template padrão de ADR adotado pela Amplimed.
2. Salve o arquivo no formato:
NNNN-titulo-descritivo.md
Onde:
- `NNNN` é um número sequencial.
- O título deve ser curto, descritivo e em letras minúsculas, usando hífens.
- A extensão deve ser `.md`.
3. Preencha o ADR seguindo o template, iniciando com o estado `proposed`.
O número sequencial garante ordem cronológica e facilita referências entre ADRs.
---
## Uso de MADR em projetos maiores
Em projetos com muitos ADRs, é permitido organizar os registros em subdiretórios, desde que exista consenso no time. Um exemplo de organização é por domínio ou camada arquitetural:
```tree
docs/decisions
├── backend
│ └── 0001-uso-microservicos.md
└── frontend
└── 0001-uso-react.md
Nesse modelo, a numeração é local ao diretório. A estratégia de organização deve refletir a forma como o sistema é estruturado e mantido.
Template oficial
O template de ADR adotado pela Amplimed é baseado no MADR 4.x, com pequenas adaptações de linguagem e governança. Ele deve ser utilizado como base para todos os novos registros de decisão.