Documentando Decisões Arquiteturais

Decisões técnicas tomadas hoje serão questionadas amanhã por novos membros da equipe, auditores ou seu futuro eu. Registros de Decisões Arquiteturais (ADRs) capturam não apenas o que foi decidido, mas por quê, quais alternativas foram consideradas e quais consequências esperar.

Benefícios dos ADRs

Formato ADR

Template Padrão

TEMPLATE REGISTRO DECISÃO ARQUITETURAL
══════════════════════════════════════

# ADR-[NÚMERO]: [TÍTULO]

## Status
[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]

## Data
[AAAA-MM-DD quando decidido]

## Contexto
[Qual é a situação? Que problema estamos tentando resolver?
Que restrições temos? Que forças estão em jogo?]

## Decisão
[Qual é a decisão que estamos tomando? Seja claro e específico.]

## Alternativas Consideradas

### Alternativa 1: [Nome]
- Prós: [lista]
- Contras: [lista]
- Por que não escolhida: [razão]

### Alternativa 2: [Nome]
- Prós: [lista]
- Contras: [lista]
- Por que não escolhida: [razão]

## Consequências

### Positivas
- [benefício 1]
- [benefício 2]

### Negativas
- [desvantagem 1]
- [desvantagem 2]

### Riscos
- [risco e mitigação]

## Decisões Relacionadas
- [ADR-XXX: Decisão relacionada]

## Referências
- [Links para documentação relevante, RFCs, etc.]

Exemplo Real

# ADR-005: Usar PostgreSQL como Banco de Dados Primário

## Status
Accepted

## Data
2024-01-15

## Contexto
Precisamos selecionar um banco de dados primário para nossa aplicação SaaS.
Requisitos:
- Forte consistência para transações financeiras
- Consultas complexas para analytics
- Suporte JSON para esquemas flexíveis
- Confiabilidade comprovada em escala
- Familiaridade da equipe
- Complexidade operacional razoável

Equipe atual tem experiência com MySQL e PostgreSQL.
Carga esperada: 10K transações/dia inicialmente, escalando para 1M+.

## Decisão
Usar PostgreSQL 16 como nosso banco de dados primário, implantado no
AWS RDS com configuração Multi-AZ.

## Alternativas Consideradas

### Alternativa 1: MySQL
- Prós: Familiaridade da equipe, configuração simples, bom desempenho
- Contras: Suporte JSON mais fraco, menos recursos avançados
- Por que não escolhida: Suporte JSON crítico para nossas necessidades de esquema

### Alternativa 2: MongoDB
- Prós: Esquema flexível, bom para documentos
- Contras: Preocupações com consistência eventual para transações
- Por que não escolhida: Precisamos de consistência forte para dados financeiros

### Alternativa 3: CockroachDB
- Prós: Distribuído por design, compatível com PostgreSQL
- Contras: Complexidade excessiva para nossa escala atual, custo
- Por que não escolhida: Otimização prematura para nossa escala

## Consequências

### Positivas
- Ecossistema forte com ferramentas extensivas
- Suporte JSONB para porções flexíveis do esquema
- Planejador de consultas excelente para analytics complexos
- Equipe pode aproveitar conhecimento PostgreSQL existente
- RDS simplifica operações

### Negativas
- Escala horizontal requerá réplicas de leitura ou sharding
- Não ideal para dados de séries temporais (pode precisar solução separada)
- Custos RDS maiores que auto-gerenciado

### Riscos
- Teto de escala: Mitigar com réplicas de leitura, camada de cache
- Lock-in de fornecedor no RDS: Trade-off aceitável para operações reduzidas

## Decisões Relacionadas
- ADR-012: TimescaleDB para dados de métricas
- ADR-003: Redis para camada de cache

## Referências
- Documentação PostgreSQL: https://postgresql.org/docs/16/
- Análise de preços AWS RDS: [documento interno]

Quando Criar ADRs

Critérios de Decisão

CRIE UM ADR QUANDO:
═══════════════════

ALTO IMPACTO:
├── Afeta múltiplos serviços/componentes
├── Difícil ou caro de reverter
├── Esforço significativo de desenvolvimento
├── Equipe teve debate substancial
└── Interesse de stakeholder externo

EXEMPLOS:
├── Escolhendo um banco de dados
├── Selecionando um framework
├── Definindo arquitetura de API
├── Escolhendo abordagem de autenticação
├── Decidindo estratégia de implantação
├── Estabelecendo padrões de codificação
├── Escolhendo provedor de nuvem
└── Definindo política de retenção de dados

NÃO PRECISA ADR:
├── Escolhendo nomes de variáveis
├── Seleção menor de biblioteca
├── Abordagens de correção de bug
├── Estilo de componente UI
└── Escolhas facilmente reversíveis

Fluxo de Trabalho ADR

FLUXO DE TRABALHO ADR
═════════════════════

PASSO 1: Identificar Decisão
├── Escolha técnica significativa à frente
├── Equipe tem opiniões diferentes
├── Afetará desenvolvimento futuro
└── Vale a pena documentar

PASSO 2: Rascunhar ADR
├── Autor cria rascunho
├── Inclui contexto e restrições
├── Lista alternativas consideradas
├── Propõe decisão
└── Status: "Proposed"

PASSO 3: Revisar
├── Compartilhar com equipes afetadas
├── Coletar feedback (comentários/PR)
├── Discussão técnica
├── Pode revisar baseado em input
└── Time-box: 1 semana típico

PASSO 4: Decidir
├── Reunião de equipe ou voto assíncrono
├── Tomar decisão final
├── Atualizar ADR com decisão
└── Status: "Accepted"

PASSO 5: Comunicar
├── Anunciar decisão
├── Link de código/docs relevante
├── Referenciar em PRs de implementação
└── Adicionar a materiais de onboarding

Organizando ADRs

Estrutura de Pastas

ORGANIZAÇÃO ADR
════════════════

NO REPOSITÓRIO:
─────────────────────────────────────
project/
├── docs/
│   └── adr/
│       ├── README.md (índice)
│       ├── 0001-record-architecture-decisions.md
│       ├── 0002-use-typescript.md
│       ├── 0003-graphql-api-design.md
│       ├── 0004-microservices-vs-monolith.md
│       └── 0005-postgresql-database.md
├── src/
└── ...

ÍNDICE README.md:
─────────────────────────────────────
# Registros de Decisões Arquiteturais

| # | Título | Status | Data |
|---|--------|--------|------|
| 1 | Registrar decisões arquiteturais | Accepted | 2024-01-01 |
| 2 | Usar TypeScript | Accepted | 2024-01-05 |
| 3 | Design API GraphQL | Accepted | 2024-01-10 |
| 4 | Microserviços vs monólito | Accepted | 2024-01-15 |
| 5 | Banco de dados PostgreSQL | Accepted | 2024-01-15 |

NUMERAÇÃO:
├── Sequencial: 0001, 0002, 0003...
├── Nunca reutilizar números
├── ADRs depreciados mantêm números
└── Superseded aponta para substituição

No NoteVault do GitScrum

ADRS NO NOTEVAULT
═════════════════

ORGANIZAÇÃO:
├── Criar espaço "Decisões Arquiteturais"
├── Marcar ADRs com #adr
├── Vincular a projetos relacionados
├── Vincular a tarefas de implementação
└── Buscar em todos os ADRs

VINCULAÇÃO:
├── ADR → Tarefa que o implementa
├── Tarefa → ADR que explica por quê
├── Projeto → ADRs chave
└── Referências bidirecionais

TEMPLATES:
├── Salvar template ADR no NoteVault
├── Criar novo ADR do template
├── Estrutura consistente
└── Campos obrigatórios aplicados

Mantendo ADRs

Gerenciamento do Ciclo de Vida

CICLO DE VIDA ADR
═════════════════

PROPOSED:
├── Estágio de rascunho
├── Aberto para discussão
├── Ainda não decidido
└── Pode ser rejeitado

ACCEPTED:
├── Decisão tomada
├── Implementação pode prosseguir
├── Referência no código
└── Estado final mais comum

DEPRECATED:
├── Não mais relevante
├── Tecnologia mudou
├── Negócio mudou
├── Manter para histórico
└── Notar por que depreciado

SUPERSEDED:
├── Substituído por ADR mais novo
├── Link para substituição
├── Original ainda valioso para histórico
└── "Superseded by ADR-XXX"

EXEMPLO:
# ADR-003: Usar API REST
## Status
Superseded by ADR-015 (Migração GraphQL)

[Conteúdo original preservado para histórico]

Melhores Práticas

Para ADRs

1. Escreva no momento da decisão — Contexto fresco
2. Mantenha-os curtos — Focados na decisão
3. Armazene com código — Fácil de encontrar
4. Nunca delete — Histórico importa
5. Referencie no código — Link implementação

Anti-Padrões

ERROS ADR:
✗ Escrever meses após decisão
✗ Muito longo (múltiplas páginas)
✗ Armazenar separadamente do código
✗ Deletar ADRs depreciados
✗ Nenhuma alternativa documentada
✗ Nenhuma consequência listada
✗ Nenhum processo de revisão
✗ Nunca referenciado novamente

Soluções Relacionadas

• Documentando decisões de projeto no NoteVault
• Base de conhecimento desenvolvedor
• Construindo equipes de compartilhamento de conhecimento