Registros de Decisões de Arquitetura

Padrões abrangentes para criar, manter e gerenciar Registros de Decisões de Arquitetura (ADRs) que capturam o contexto e a justificativa por trás de decisões técnicas significativas.

Quando Usar Esta Habilidade

• Tomar decisões arquiteturais significativas
• Documentar escolhas de tecnologia
• Registrar compromissos de design (trade-offs)
• Integrar novos membros da equipe
• Revisar decisões históricas
• Estabelecer processos de tomada de decisão

Conceitos Principais

1. O que é um ADR?

Um Registro de Decisão de Arquitetura captura:

• Contexto: Por que precisávamos tomar uma decisão
• Decisão: O que decidimos
• Consequências: O que acontece como resultado

2. Quando Escrever um ADR

3. Ciclo de Vida do ADR

Proposed → Accepted → Deprecated → Superseded
              ↓
           Rejected

Antes de redigir um ADR padrão, leve ou Y-statement, leia modelos de decisão.

Antes de redigir um ADR de depreciação ou RFC, leia modelos de depreciação e RFC.

Gerenciamento de ADRs

Estrutura de Diretório

docs/
├── adr/
│   ├── README.md           # Index and guidelines
│   ├── template.md         # Team's ADR template
│   ├── 0001-use-postgresql.md
│   ├── 0002-caching-strategy.md
│   ├── 0003-mongodb-user-profiles.md  # [DEPRECATED]
│   └── 0020-deprecate-mongodb.md      # Supersedes 0003

Índice de ADRs (README.md)

# Architecture Decision Records

This directory contains Architecture Decision Records (ADRs) for [Project Name].

## Index

| ADR                                   | Title                              | Status     | Date       |
| ------------------------------------- | ---------------------------------- | ---------- | ---------- |
| [0001](0001-use-postgresql.md)        | Use PostgreSQL as Primary Database | Accepted   | 2024-01-10 |
| [0002](0002-caching-strategy.md)      | Caching Strategy with Redis        | Accepted   | 2024-01-12 |
| [0003](0003-mongodb-user-profiles.md) | MongoDB for User Profiles          | Deprecated | 2023-06-15 |
| [0020](0020-deprecate-mongodb.md)     | Deprecate MongoDB                  | Accepted   | 2024-01-15 |

## Creating a New ADR

1. Copy `template.md` to `NNNN-title-with-dashes.md`
2. Fill in the template
3. Submit PR for review
4. Update this index after approval

## ADR Status

- **Proposed**: Under discussion
- **Accepted**: Decision made, implementing
- **Deprecated**: No longer relevant
- **Superseded**: Replaced by another ADR
- **Rejected**: Considered but not adopted

Automação (adr-tools)

# Install adr-tools
brew install adr-tools

# Initialize ADR directory
adr init docs/adr

# Create new ADR
adr new "Use PostgreSQL as Primary Database"

# Supersede an ADR
adr new -s 3 "Deprecate MongoDB in Favor of PostgreSQL"

# Generate table of contents
adr generate toc > docs/adr/README.md

# Link related ADRs
adr link 2 "Complements" 1 "Is complemented by"

Processo de Revisão

## ADR Review Checklist

### Before Submission

- [ ] Context clearly explains the problem
- [ ] All viable options considered
- [ ] Pros/cons balanced and honest
- [ ] Consequences (positive and negative) documented
- [ ] Related ADRs linked

### During Review

- [ ] At least 2 senior engineers reviewed
- [ ] Affected teams consulted
- [ ] Security implications considered
- [ ] Cost implications documented
- [ ] Reversibility assessed

### After Acceptance

- [ ] ADR index updated
- [ ] Team notified
- [ ] Implementation tickets created
- [ ] Related documentation updated

Melhores Práticas

Fazer

• Escrever ADRs cedo - Antes do início da implementação
• Mantê-los curtos - 1-2 páginas no máximo
• Ser honesto sobre os compromissos - Incluir contras reais
• Vincular decisões relacionadas - Construir um grafo de decisões
• Atualizar o status - Depreciar quando substituído

Não Fazer

• Não alterar ADRs aceitos - Escrever novos para substituir
• Não omitir o contexto - Leitores futuros precisam de histórico
• Não esconder falhas - Decisões rejeitadas são valiosas

…