architecture-decision-records

Registros de Decisão Arquitetural (ADR)

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 residem 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..." ou "a razão de fazermos 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 leve de ADR proposto por Michael Nygard, adaptado para desenvolvimento assistido por IA:

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

**Data**: YYYY-MM-DD
**Status**: proposed | accepted | deprecated | superseded by 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

Qual é a mudança que estamos propondo e/ou implementando?

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

## Alternativas Consideradas

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

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

## Consequências

O que se torna 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 um Novo ADR

Quando um momento de decisão é detectado:

1. Inicializar (primeira vez apenas) — se docs/adr/ não existir, peça confirmação ao usuário 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/mais 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-titulo-da-decisao.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 ao 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 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: "Nenhum ADR encontrado para essa decisão. Gostaria de registrar um agora?"

Estrutura do Diretório ADR

docs/
└── adr/
    ├── README.md              ← índice de todos os ADRs
    ├── 0001-use-nextjs.md
    ├── 0002-postgres-over-mongo.md
    ├── 0003-rest-over-graphql.md
    └── template.md            ← modelo 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 | accepted | 2026-01-15 |
| [0002](0002-postgres-over-mongo.md) | PostgreSQL em vez de MongoDB como armazenamento principal | accepted | 2026-01-20 |
| [0003](0003-rest-over-graphql.md) | API REST em vez de GraphQL | accepted | 2026-02-01 |

Sinais de Detecção de Decisão

Observe os seguintes 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 (sugira registrar um 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 Faz um Bom 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 — um ADR deve ser legível em 2 minutos
• Use o tempo presente — "Usamos X", não "Usaremos X"

Não Faça

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

Ciclo de Vida do ADR

proposed → accepted → [deprecated | superseded by ADR-NNNN]

• proposed: decisão está em discussão, ainda não comprometida
• accepted: decisão está em vigor e sendo seguida
• deprecated: decisão não é mais relevante (ex.: funcionalidade removida)
• superseded: um ADR mais novo substitui este (sempre link a substituta)

Categorias de Decisões Que Valem 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 teste, metas de cobertura, equilíbrio E2E vs integração
Processo	Estratégia de branching, processo de revisão, cadência de release

Integração com Outras Skills

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