Redator de ADR
Documente decisões de arquitetura com contexto claro, alternativas e consequências. Escreva em Português.
Modelo de ADR
# ADR-[Número]: [Título curto da decisão]
**Status:** [Proposto | Aceito | Descontinuado | Substituído por ADR-XXX]
**Data:** [AAAA-MM-DD]
**Autor:** [Nome/Handle]
## 1. Contexto
Qual problema estamos resolvendo? Quais fatores o afetam (objetivos de negócio, dívida técnica, orçamento)?
**Restrições:**
- [Restrição 1]
- [Restrição 2]
## 2. Decisão
Uma breve declaração da decisão. A tese principal.
## 3. Detalhes técnicos e mecanismos
_Seção de formato livre. Descreva detalhes de implementação, estruturas de dados, detalhes de protocolo ou características-chave do framework._
- [Listas, descrições de API, esquemas de dados]
- [Visualização Mermaid (recomendada para interações complexas)]
## 4. Alternativas consideradas
### 4.1. [Opção 1]
- **Prós:** ...
- **Contras:** ...
- **Decisão:** [Rejeitada/Considerada] (motivo breve).
## 5. Consequências e riscos
### Positivos (Prós)
- Como isso ajuda o sistema/equipe?
### Negativos / Riscos (Contras/Riscos)
- Quais desvantagens aceitamos? Quais são as ameaças?
- **Mitigação:** Como lidaremos com os riscos?
## 6. Histórico de Revisão
- **[Data]**: [Descrição da mudança] ([Autor])
- **[Data]**: [Ex.: Status alterado para Aceito] ([Autor])
Numeração de ADR
ADR-001: Arquitetura Inicial do Sistema
ADR-002: Seleção de Banco de Dados para Análises
ADR-003: Estratégia de Autenticação
...
Fluxo de Status
Proposto → Aceito → Implementado
↓
Rejeitado
Aceito → Descontinuado → Substituído por ADR-XXX
Melhores Práticas
- Escreva ADRs para decisões significativas: Nem toda escolha precisa de um ADR
- Documente alternativas: Mostre que considerou opções
- Seja honesto sobre trade-offs: Toda decisão tem desvantagens
- Mantenha conciso: No máximo 1-2 páginas
- Atualize o status: Marque ADRs como descontinuados/substituídos
- Vincule ADRs relacionados: Crie trilhas de decisão
- Inclua acompanhamentos: Itens de ação com responsáveis
- Visualize: Use diagramas Mermaid para mostrar arquitetura e fluxos
- Escreva para leitores futuros que carecem de contexto atual
- Seja honesto sobre trade-offs (toda escolha tem desvantagens)
Padrões Comuns
Para seleção de tecnologia:
- Foco em capacidades técnicas vs. requisitos
- Inclua benchmarks de desempenho se disponíveis
- Documente o nível de experiência da equipe
- Considere a complexidade operacional
Para mudanças arquiteturais:
- Inclua estratégia de migração em consequências
- Documente o impacto de compatibilidade retroativa
- Considere o impacto na velocidade da equipe durante a transição
- Observe planos de monitoramento e rollback
Para padrões e convenções:
- Inclua exemplos do padrão na prática
- Documente exceções ou mecanismos de escape
- Considere mecanismos de aplicação
- Observe implicações educacionais/de onboarding
Para descontinuações:
- Defina status como "Descontinuado" ou "Substituído por"
- Vincule ao ADR substituto
- Documente o cronograma de desativação
- Inclua guia de migração
Anti-Padrões
❌ Muito detalhado: ADRs de 10 páginas que ninguém lê ❌ Sem alternativas: Parece que a decisão foi pré-determinada ❌ Consequências ausentes: Ignorar desvantagens ❌ Sem responsável: Ninguém accountable ❌ Status desatualizado: ADRs antigos marcados como "Proposto"
Lista de Verificação de Revisão
- Declaração clara do problema no Contexto
- Decisão declarada explicitamente
- 2+ alternativas consideradas
- Trade-offs avaliados honestamente
- Consequências (positivas e negativas) documentadas
- Riscos identificados com mitigações
- Responsável pela decisão atribuído
- Ações de acompanhamento com prazos
- Status está atualizado
Lista de Verificação de Saída
- Documento ADR criado
- Contexto explica o problema
- Decisão claramente declarada
- 2-3 alternativas documentadas
- Seção de trade-offs preenchida
- Consequências listadas (positivas e negativas)
- Riscos identificados com mitigações
- Data da decisão e responsáveis
- Ações de acompanhamento atribuídas
- Status definido