7 min leitura • Guide 432 of 877
Registros de Decisão Técnica
Decisões técnicas moldam sistemas por anos. Bons registros de decisão explicam o porquê, não apenas o quê. Documentação ruim significa repetir erros e confusão sobre escolhas de design. Este guia cobre documentação efetiva de decisões.
Benefícios de ADRs
| Benefício | Descrição |
|---|---|
| Contexto histórico | Saber por que decisões foram tomadas |
| Onboarding | Novos membros entendem sistema |
| Revisitar | Saber quando reconsiderar |
| Alinhamento | Equipe entende direção |
Formato de ADR
Template Padrão
TEMPLATE DE ADR
═══════════════
# ADR-001: [Título da Decisão]
## Status
[Proposto | Aceito | Depreciado | Substituído por ADR-XXX]
## Contexto
[Qual é o problema? Por que estamos tomando esta decisão?
Background, restrições, requisitos.]
## Decisão
[O que decidimos? Seja específico.]
## Consequências
### Positivas
[Quais são os benefícios?]
### Negativas
[Quais são os trade-offs ou riscos?]
### Neutras
[Que outros efeitos isso tem?]
## Alternativas Consideradas
[Que outras opções avaliamos?
Por que não as escolhemos?]
## Relacionados
[Links para ADRs relacionados, issues ou docs]
Exemplo de ADR
# ADR-003: Usar PostgreSQL como Banco de Dados Principal
## Status
Aceito (2024-01-15)
## Contexto
Precisamos de um banco de dados principal para nossa aplicação SaaS.
Requisitos:
- Transações ACID para dados financeiros
- Suporte a JSON para schemas flexíveis
- Bom ecossistema e ferramentas
- Opções de serviço gerenciado
## Decisão
Usaremos PostgreSQL como nosso banco de dados principal.
## Consequências
### Positivas
- Banco maduro e confiável
- Excelente suporte a JSON/JSONB
- Excelente ecossistema de ferramentas
- Disponível como serviço gerenciado (RDS, Cloud SQL)
- Equipe tem experiência com PostgreSQL
### Negativas
- Mais complexo que SQLite para dev local
- Escalar writes requer mais planejamento
- Precisa gerenciar connection pooling
### Neutras
- Usaremos migrations para mudanças de schema
- Precisa monitoramento de performance
## Alternativas Consideradas
- **MySQL**: Capacidade similar, menos suporte a JSON
- **MongoDB**: Schema flexível, mas equipe menos experiente
- **SQLite**: Muito simples para necessidades de produção
- **CockroachDB**: Exagero para escala atual
## Relacionados
- ADR-004: Estratégia de Migration de Banco
- Guia de setup de infraestrutura
Quando Escrever ADRs
Critérios de Decisão
QUANDO ESCREVER ADR
═══════════════════
ESCREVA ADR QUANDO:
─────────────────────────────────────
├── Escolhendo tecnologia/framework
├── Decisão de padrão arquitetural
├── Trade-offs significativos
├── Preocupações transversais
├── Reverter é caro
├── Afeta múltiplas equipes
├── Tem implicações de longo prazo
└── "Vou querer lembrar por quê"
NÃO PRECISA DE ADR:
─────────────────────────────────────
├── Escolhas de implementação pequenas
├── Coisas fáceis de mudar
├── Decisões temporárias
├── Preferências pessoais de código
├── Mudanças de biblioteca minor
└── Já coberto por guias de estilo
REGRA PRÁTICA:
─────────────────────────────────────
Se daqui a 6 meses alguém perguntar
"Por que fizemos assim?" e não houver
resposta óbvia no código, documente.
Exemplos de Decisões
| Decisão | ADR? | Por quê |
|---|---|---|
| Usar React vs Vue | Sim | Afeta todo frontend |
| Tabs vs spaces | Não | Coberto por linter |
| Microserviços vs monolito | Sim | Arquitetura fundamental |
| Nome de variável | Não | Fácil mudar |
| Estratégia de autenticação | Sim | Segurança, longo prazo |
Processo de ADR
Workflow de Criação
PROCESSO DE ADR:
┌─────────────────────────────────────────────────────────────┐
│ │
│ 1. IDENTIFICAR DECISÃO │
│ ───────────────────── │
│ • Reconhecer que decisão significativa é necessária │
│ • Avaliar se merece ADR │
│ │
│ 2. PROPOR (status: Proposto) │
│ ────────────────────────── │
│ • Escrever draft do ADR │
│ • Documentar contexto e opções │
│ • Compartilhar com equipe │
│ │
│ 3. DISCUTIR │
│ ────────── │
│ • Reunião de arquitetura ou async │
│ • Coletar feedback │
│ • Considerar alternativas │
│ • Atualizar ADR com input │
│ │
│ 4. DECIDIR (status: Aceito) │
│ ───────────────────────── │
│ • Escolher abordagem │
│ • Documentar decisão final │
│ • Atualizar status para Aceito │
│ │
│ 5. IMPLEMENTAR │
│ ─────────── │
│ • Seguir decisão documentada │
│ • Referenciar ADR em PRs relevantes │
│ │
│ 6. REVISITAR (quando necessário) │
│ ──────────────────────────── │
│ • Contexto mudou? │
│ • Marcar como Depreciado ou Substituído │
│ • Criar novo ADR se mudando │
└─────────────────────────────────────────────────────────────┘
Organizando ADRs
Estrutura de Arquivos
ORGANIZAÇÃO DE ADRs:
┌─────────────────────────────────────────────────────────────┐
│ │
│ OPÇÃO 1: NO REPOSITÓRIO │
│ ───────────────────────── │
│ │
│ /docs/adr/ │
│ ├── 0001-usar-postgresql.md │
│ ├── 0002-arquitetura-microservicos.md │
│ ├── 0003-estrategia-autenticacao.md │
│ ├── 0004-framework-frontend.md │
│ └── README.md (índice) │
│ │
│ VANTAGENS: │
│ • Versionado com código │
│ • Fácil de encontrar │
│ • Code review de ADRs │
│ │
│ OPÇÃO 2: WIKI/CONFLUENCE │
│ ───────────────────────── │
│ │
│ Space: Arquitetura │
│ └── Decisões Técnicas │
│ ├── ADR-001: PostgreSQL │
│ ├── ADR-002: Microserviços │
│ └── ADR-003: OAuth │
│ │
│ VANTAGENS: │
│ • Mais visível para não-devs │
│ • Formatação rica │
│ • Comentários/discussão embutidos │
│ │
│ OPÇÃO 3: GITSCRUM │
│ ────────────────── │
│ │
│ Epic "Decisões de Arquitetura" com tarefas para cada ADR │
│ Descrição detalhada na tarefa │
│ Discussão em comentários │
└─────────────────────────────────────────────────────────────┘
Nomeação e Numeração
CONVENÇÕES DE NOMEAÇÃO:
┌─────────────────────────────────────────────────────────────┐
│ │
│ FORMATO: │
│ XXXX-titulo-em-kebab-case.md │
│ │
│ EXEMPLOS: │
│ 0001-usar-postgresql.md │
│ 0002-adotar-typescript.md │
│ 0003-api-rest-vs-graphql.md │
│ │
│ NUMERAÇÃO: │
│ • Sequencial, nunca reutilize │
│ • 4 dígitos para ordenação │
│ • Número nunca muda │
│ │
│ QUANDO DEPRECIAR: │
│ • Manter arquivo original │
│ • Atualizar status para "Depreciado" ou "Substituído" │
│ • Linkar para novo ADR se houver │
└─────────────────────────────────────────────────────────────┘
Manutenção de ADRs
Ciclo de Vida
STATUS DE ADRs:
┌─────────────────────────────────────────────────────────────┐
│ │
│ PROPOSTO → ACEITO → (DEPRECIADO ou SUBSTITUÍDO) │
│ │
│ PROPOSTO: │
│ Decisão em discussão, ainda não finalizada │
│ │
│ ACEITO: │
│ Decisão tomada, deve ser seguida │
│ │
│ DEPRECIADO: │
│ Decisão não mais relevante │
│ (ex: sistema foi descontinuado) │
│ │
│ SUBSTITUÍDO: │
│ Nova decisão tomada que substitui esta │
│ Linkar para novo ADR: "Substituído por ADR-015" │
│ │
│ IMPORTANTE: │
│ • Nunca delete ADRs │
│ • Histórico é valioso │
│ • Ajuda entender evolução do sistema │
└─────────────────────────────────────────────────────────────┘
Dicas Práticas
O Que Fazer e Evitar
BOAS PRÁTICAS DE ADR:
┌─────────────────────────────────────────────────────────────┐
│ │
│ ✓ FAÇA: │
│ │
│ • Seja conciso (1-2 páginas) │
│ • Foque no "por quê", não no "como" │
│ • Documente alternativas rejeitadas │
│ • Inclua data da decisão │
│ • Atualize quando contexto mudar │
│ • Referencie ADRs em código/PRs relevantes │
│ │
│ ✗ EVITE: │
│ │
│ • ADRs muito longos │
│ • Detalhes de implementação │
│ • Decisões triviais │
│ • Deletar ADRs antigos │
│ • Ignorar alternativas │
│ • Deixar status como "Proposto" para sempre │
└─────────────────────────────────────────────────────────────┘