Registros de Decisões de Arquitetura

Capture decisões de arquitetura conforme elas acontecem durante as sessões de codificação. Em vez de as decisões ficarem apenas em threads do Slack, comentários de PR ou na memória de alguém, esta habilidade produz documentos ADR estruturados que vivem ao lado do 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..." ou "o motivo pelo qual estamos fazendo X em vez de Y é..."
• O usuário pergunta "por que escolhemos X?" (ler ADRs existentes)
• Durante as fases de planejamento, quando os 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: [Decision Title]

**Date**: YYYY-MM-DD
**Status**: proposed | accepted | deprecated | superseded by ADR-NNNN
**Deciders**: [who was involved]

## Context

What is the issue that we're seeing that is motivating this decision or change?

[2-5 sentences describing the situation, constraints, and forces at play]

## Decision

What is the change that we're proposing and/or doing?

[1-3 sentences stating the decision clearly]

## Alternatives Considered

### Alternative 1: [Name]
- **Pros**: [benefits]
- **Cons**: [drawbacks]
- **Why not**: [specific reason this was rejected]

### Alternative 2: [Name]
- **Pros**: [benefits]
- **Cons**: [drawbacks]
- **Why not**: [specific reason this was rejected]

## Consequences

What becomes easier or more difficult to do because of this change?

### Positive
- [benefit 1]
- [benefit 2]

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

### Risks
- [risk and mitigation]

Fluxo de Trabalho

Capturando um Novo ADR

Quando um momento de decisão é detectado:

1. Inicializar (apenas primeira vez) — se docs/adr/ não existir, pergunte ao usuário a confirmação antes de criar o diretório, um README.md semeado 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 se torna mais fácil/difícil?
6. Atribuir um número — escaneie ADRs existentes em docs/adr/ e incremente
7. Confirmar e escrever — apresente o rascunho do ADR ao usuário para revisão. Escreva em docs/adr/NNNN-decision-title.md apenas após aprovação explícita. Se o usuário recusar, descarte o rascunho sem escrever nenhum arquivo.
8. Atualizar o índice — anexe a docs/adr/README.md

Lendo ADRs Existentes

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

1. Verifique se docs/adr/ existe — se não, responda: "Nenhum ADR encontrado neste projeto. Gostaria de começar a registrar decisões de arquitetura?"
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: "Nenhum ADR encontrado para essa decisão. Gostaria de registrar um agora?"

Estrutura do Diretório ADR

docs/
└── adr/
    ├── README.md              ← index of all ADRs
    ├── 0001-use-nextjs.md
    ├── 0002-postgres-over-mongo.md
    ├── 0003-rest-over-graphql.md
    └── template.md            ← blank template for manual use

Formato do Índice ADR

# Architecture Decision Records

| ADR | Title | Status | Date |
|-----|-------|--------|------|
| [0001](0001-use-nextjs.md) | Use Next.js as frontend framework | accepted | 2026-01-15 |
| [0002](0002-postgres-over-mongo.md) | PostgreSQL over MongoDB for primary datastore | accepted | 2026-01-20 |
| [0003](0003-rest-over-graphql.md) | REST API over GraphQL | accepted | 2026-02-01 |

Sinais de Detecção de Decisão

Observe estes padrões na conversa que indicam uma decisão arquitetural:

Sinais explícitos

• "Vamos com X"
• "Devemos usar X em vez de Y"
• "O trade-off vale a pena porque..."
• "Registre isso como um ADR"

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

• Comparando dois frameworks ou bibliotecas e chegando a uma conclusão
• Tomando uma decisão de design de esquema de banco de dados com justificativa declarada
• Escolhendo entre padrões arquiteturais (monolito vs microsserviços, REST vs GraphQL)

…