rhpxgr8pzm-max/claude-skills

Registros de Decisão Arquitetural (ADR)

Capture decisões arquiteturais conforme elas 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 acompanham o 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 "nós decidimos..." ou "a razão pela qual estamos 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**: YYYY-MM-DD
**Status**: proposta | aceita | depreciada | substituída por ADR-NNNN
**Decisores**: [quem estava envolvido]

## Contexto

Qual é o problema que estamos vendo que motiva esta decisão ou mudança?

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

## Decisão

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

[1-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 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 for detectado:

1. Inicializar (apenas na primeira vez) — se docs/adr/ não existir, peça confirmação ao usuário antes de criar o diretório, um README.md 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-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 existir, 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 | aceita | 2026-01-15 |
| [0002](0002-postgres-over-mongo.md) | PostgreSQL sobre MongoDB como armazenamento primário | aceita | 2026-01-20 |
| [0003](0003-rest-over-graphql.md) | API REST sobre GraphQL | aceita | 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 de X"
• "Deveríamos 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 schema 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 deploy após avaliar alternativas

O Que Torna 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 presente — "Usamos X", não "Usaremos X"

Não Faça

• Registrar decisões triviais — escolhas de nomenclatura de variáveis ou formatação não precisam de ADRs
• Escrever ensaios — se a seção de contexto exceder 10 linhas, está muito longa
• Omitir alternativas — "apenas escolhemos" não é uma justificativa válida
• Preencher retroativamente sem marcar — se estiver registrando uma decisão passada, anote a data original
• Deixar ADRs ficarem obsoletos — decisões substituídas devem referenciar sua substituição

Ciclo de Vida do ADR

proposta → aceita → [depreciada | substituída por ADR-NNNN]

• proposta: decisão está em discussão, ainda não foi confirmada
• aceita: decisão está em vigor e sendo seguida
• depreciada: decisão não é mais relevante (ex.: funcionalidade removida)
• substituída: um ADR mais novo substitui este (sempre vincule a substituição)

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 schema, decisões de normalização, estratégia de cache
Infraestrutura	Modelo de deploy, 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 releases

Integração com Outras Skills

• Agente planejador: quando o planejador propuser mudanças arquiteturais, sugira criar um ADR
• Agente revisor de código: sinalize PRs que introduzam mudanças arquiteturais sem um ADR correspondente