registros-de-decisao-arquitetural

Registros de Decisão Arquitetural

Capture decisões arquiteturais à medida que acontecem durante sessões de codificação. Em vez de decisões viverem apenas em threads do Slack, comentários de PR ou na memória de alguém, esta skill produz documentos ADR estruturados que ficam junto ao código.

Quando Ativar

• O usuário diz explicitamente "vamos registrar esta decisão" ou "ADR isso"
• O usuário escolhe entre alternativas significativas (framework, biblioteca, padrão, banco de dados, design de API)
• O usuário diz "decidimos que..." ou "a razão de estarmos fazendo X em vez de Y é..."
• O usuário pergunta "por que escolhemos X?" (ler ADRs existentes)
• Durante fases de planejamento quando trade-offs arquiteturais são discutidos

Formato ADR

Use o formato ADR leve proposto por Michael Nygard, adaptado para desenvolvimento assistido por IA:

# ADR-NNNN: [Título da Decisão]

**Data**: AAAA-MM-DD
**Status**: proposto | aceito | depreciado | substituído por ADR-NNNN
**Decisores**: [quem esteve envolvido]

## Contexto

Qual é o problema que estamos vendo que está motivando esta decisão ou mudança?

[2 a 5 frases descrevendo a situação, restrições e forças em jogo]

## Decisão

O que estamos propondo e/ou fazendo de diferente?

[1 a 3 frases declarando a decisão claramente]

## Alternativas Consideradas

### Alternativa 1: [Nome]
- **Prós**: [benefícios]
- **Contras**: [desvantagens]
- **Por que não**: [motivo específico pelo qual foi rejeitada]

### Alternativa 2: [Nome]
- **Prós**: [benefícios]
- **Contras**: [desvantagens]
- **Por que não**: [motivo específico pelo qual foi rejeitada]

## Consequências

O que fica mais fácil ou mais difícil de fazer por causa desta mudança?

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

### Negativas
- [trade-off 1]
- [trade-off 2]

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

Fluxo de Trabalho

Capturando uma Nova ADR

Quando um momento de decisão é detectado:

1. Inicializar (apenas na primeira vez) — se docs/adr/ não existir, pergunte ao usuário a confirmação antes de criar o diretório, um README.md preenchido com o cabeçalho da tabela de índice (veja Formato do Índice ADR abaixo) e um template.md em branco para uso manual. Não crie arquivos sem consentimento explícito.
2. Identificar a decisão — extraia a escolha arquitetural central que está sendo feita
3. Coletar contexto — qual problema motivou isso? Quais restrições existem?
4. Documentar alternativas — quais outras opções foram consideradas? Por que foram rejeitadas?
5. Declarar consequências — quais são os trade-offs? O que fica mais fácil/mais difícil?
6. Atribuir um número — escaneie as ADRs existentes em docs/adr/ e incremente
7. Confirmar e escrever — apresente o rascunho da ADR ao usuário para revisão. Escreva em docs/adr/NNNN-titulo-da-decisao.md apenas após aprovação explícita. Se o usuário recusar, descarte o rascunho sem gravar nenhum arquivo.
8. Atualizar o índice — acrescente a entrada em docs/adr/README.md

Lendo ADRs Existente

Quando um usuário pergunta "por que escolhemos X?":

1. Verifique se docs/adr/ existe — se não, responda: "Nenhuma ADR encontrada neste projeto. Gostaria de começar a registrar decisões arquiteturais?"
2. Se existir, escaneie o índice docs/adr/README.md em busca de entradas relevantes
3. Leia os arquivos ADR correspondentes e apresente as seções de Contexto e Decisão
4. Se nenhuma correspondência for encontrada, responda: "Nenhuma ADR encontrada para essa decisão. Gostaria de registrar uma agora?"

Estrutura do Diretório ADR

docs/
└── adr/
    ├── README.md              ← índice de todas as ADRs
    ├── 0001-use-nextjs.md
    ├── 0002-postgres-over-mongo.md
    ├── 0003-rest-over-graphql.md
    └── template.md            ← template em branco para uso manual

Formato do Índice ADR

# Registros de Decisão Arquitetural

| ADR | Título | Status | Data |
|-----|--------|--------|------|
| [0001](0001-use-nextjs.md) | Usar Next.js como framework frontend | aceito | 2026-01-15 |
| [0002](0002-postgres-over-mongo.md) | PostgreSQL em vez de MongoDB para banco de dados principal | aceito | 2026-01-20 |
| [0003](0003-rest-over-graphql.md) | API REST em vez de GraphQL | aceito | 2026-02-01 |

Sinais de Detecção de Decisão

Fique atento a estes padrões na conversa que indicam uma decisão arquitetural:

Sinais explícitos

• "Vamos com X"
• "Deveríamos usar X em vez de Y"
• "O trade-off vale a pena porque..."
• "Registre isso como uma ADR"

Sinais implícitos (sugira registrar uma ADR — não crie automaticamente sem confirmação do usuário)

• Comparar dois frameworks ou bibliotecas e chegar a uma conclusão
• Fazer uma escolha de design de esquema de banco de dados com justificativa declarada
• Escolher entre padrões arquiteturais (monólito vs microsserviços, REST vs GraphQL)
• Decidir sobre estratégia de autenticação/autorização
• Selecionar infraestrutura de implantação após avaliar alternativas

O Que Torna uma Boa ADR

Faça

• Seja específico — "Usar Prisma ORM" não "usar um ORM"
• Registre o porquê — a justificativa importa mais do que o quê
• Inclua alternativas rejeitadas — futuros desenvolvedores precisam saber o que foi considerado
• Declare consequências honestamente — toda decisão tem trade-offs
• Mantenha curto — uma ADR deve ser legível em 2 minutos
• Use o presente — "Usamos X" não "Usaremos X"

Não Faça

• Registre decisões triviais — escolhas de nomenclatura de variáveis ou formatação não precisam de ADRs
• Escreva ensaios — se a seção de contexto ultrapassar 10 linhas, está muito longo
• Omita alternativas — "apenas escolhemos" não é uma justificativa válida
• Preencha retrospectivamente sem marcar — se estiver registrando uma decisão passada, anote a data original
• Deixe ADRs ficarem obsoletos — decisões substituídas devem referenciar sua substituta

Ciclo de Vida das ADRs

proposto → aceito → [depreciado | substituído por ADR-NNNN]

• proposto: decisão está em discussão, ainda não comprometida
• aceito: decisão está em vigor e sendo seguida
• depreciado: decisão não é mais relevante (ex.: funcionalidade removida)
• substituído: uma ADR mais nova substitui esta (sempre link a substituta)

Categorias de Decisões que Vale a Pena Registrar

Categoria	Exemplos
Escolhas de tecnologia	Framework, linguagem, banco de dados, provedor de nuvem
Padrões arquiteturais	Monólito vs microsserviços, orientado a eventos, CQRS
Design de API	REST vs GraphQL, estratégia de versionamento, mecanismo de autenticação
Modelagem de dados	Design de esquema, decisões de normalização, estratégia de cache
Infraestrutura	Modelo de implantação, pipeline CI/CD, stack de monitoramento
Segurança	Estratégia de autenticação, abordagem de criptografia, gerenciamento de segredos
Testes	Framework de testes, metas de cobertura, equilíbrio entre E2E e integração
Processo	Estratégia de branching, processo de revisão, cadência de releases

Integração com Outras Skills

• Agente planejador: quando o planejador propõe mudanças de arquitetura, sugira criar uma ADR
• Agente revisor de código: sinalize PRs que introduzem mudanças arquiteturais sem uma ADR correspondente