adr

ADR (Architecture Decision Record)

Produz ADRs em Markdown seguindo o formato canônico do Michael Nygard e do adr-tools do Nat Pryce. Foco: registrar uma decisão por documento, com contexto, decisão e consequências, em prosa curta que sobrevive ao tempo.

Princípio do Nygard: "One of the hardest things to track during the life of a project is the motivation behind certain decisions." ADRs resolvem isso documentando por que uma escolha foi feita, não como implementá-la.

Workflow

Step 1: Discovery

Antes de escrever, alinhe uma coisa: qual é a decisão exata?

ADR é uma decisão por documento. Se o usuário trouxer algo amplo demais ("vou redesenhar o serviço X", "documenta a arquitetura nova"), não é caso de ADR — é caso de design doc. Defira para a skill design-doc e diga isso explicitamente.

Critério rápido:

• É ADR? "Vamos usar Postgres em vez de Mongo." · "Adotar gRPC pro tráfego interno." · "Mudar o formato de data padrão pra ISO 8601." · "Padronizar erros como problem+json."
• NÃO é ADR (é design doc): "Vamos construir o sistema de recomendação." · "Migração do checkout pro novo gateway." · "Plano para o novo onboarding."
• Não é nem um nem outro: decisões triviais (nome de variável, layout de pasta), facilmente reversíveis. Não escreva ADR pra essas.

Se o pedido for vago, faça uma pergunta: qual é a escolha exata e quais alternativas estavam na mesa? Não invente alternativas que o usuário não mencionou.

Step 2: Compose

Trabalhe as 5 seções na ordem canônica. Use a linguagem do usuário (PT/EN/ES) — Nygard escreveu em inglês mas o formato é language-agnostic.

Use references/template.md se quiser começar do esqueleto vazio. Use references/example.md se quiser ver o ADR canônico (recursivo — o primeiro ADR adota ADRs).

Princípios de escrita (Nygard):

• Prosa em frases completas. Bullets só pra estilo visual, nunca como atalho pra fragmentos.
• Voz ativa, futuro. "We will..." na Decision.
• Conversacional. Escreva como se conversasse com um dev que herdou o sistema daqui a 2 anos.
• 1–2 páginas. Se passou disso, provavelmente é mais de uma decisão — divida em múltiplos ADRs.
• No implementation code. Documente a decisão e suas consequências, não como implementar (mesmo princípio do design-doc).

Step 3: Validate and self-review (não pule)

(a) Validação mecânica. Rode contra o draft:

python3 scripts/validate.py < 0042-some-decision.md

Pega: title sem # N. numerado, Date faltando ou fora de ISO 8601, seção required ausente (Status/Context/Decision/Consequences), Status fora dos 4 canônicos (Proposed/Accepted/Deprecated/Superseded by). Avisa: ADR > 100 linhas, Decision sem voz ativa.

(b) Self-review semantic. Carregue references/checklist.md. Pontos críticos que o validator NÃO pega:

• Title é frase nominal (não verbo no infinitivo)?
• Context descreve fatos e forças neutras (não a decisão)?
• Consequences cobrem positivos e negativos?
• Prosa, não bullets fragmentados?
• É uma decisão única (não várias empacotadas)?

Step 4: Deliver

Entregue como um único arquivo Markdown. Sugira:

1. Filename — NNNN-kebab-slug.md (4 dígitos zero-padded). Slug deve refletir a essência do título.
2. Localização — doc/adr/ por padrão. Se o projeto já tem outra convenção (docs/adr/, architecture/decisions/, rfcs/), use a existente. Pergunte se incerto.
3. Numbering — rode python3 scripts/next_number.py {dir} pra obter o próximo número, ou python3 scripts/next_number.py {dir} {slug} pra receber direto o filename completo NNNN-slug.md. Se não tiver acesso ao filesystem, proponha um número e peça pro usuário rodar o script e ajustar.

---

A 5-section canon

Ordem fixa (não troque):

1. Title — # N. Short noun phrase
2. Date — Date: YYYY-MM-DD
3. Status — Proposed · Accepted · Deprecated · Superseded by [link]
4. Context — fatos e forças (neutro)
5. Decision — "We will..." (ativo)
6. Consequences — positivos · negativos · neutros

1. Title

Frase nominal curta. Comece com substantivo ou gerúndio, não com verbo no infinitivo.

• ✓ "# 17. Use PostgreSQL as primary database"
• ✓ "# 23. Adoption of gRPC for internal communication"
• ✗ "# 17. Decide on a database" (vago)
• ✗ "# 23. To adopt gRPC" (não é nominal)

2. Date

ISO 8601 (YYYY-MM-DD). Data em que o ADR foi escrito/aceito, não a data em que a decisão original foi tomada.

Date: 2026-05-08

3. Status

Exatamente um valor canônico:

Status	Quando usar
Proposed	ADR em discussão, decisão ainda não tomada
Accepted	Decisão em vigor (default para a maioria dos ADRs commitados)
Deprecated	Não é mais a recomendação, mas não há substituto formal
Superseded by [NNNN-link]	Substituído por outro ADR; coloque o link relativo ([0042](0042-new-decision.md))

Lifecycle: quando um ADR supersede outro, o ADR antigo recebe Superseded by [NNNN] no Status. Não edite outros arquivos automaticamente — peça permissão e mostre o diff.

4. Context

Fatos e forças que motivam a decisão — técnicas, sociais, políticas, econômicas. Voz neutra: não introduza a decisão aqui, não argumente a favor da solução escolhida.

Exemplo (Nygard, slightly adapted): "Our service is approaching 10k requests/second peak load. The current SQLite-backed cache is hitting write contention; on Tuesdays we see 5–10s of degradation between 14h and 16h UTC. The team has experience with both Postgres and MongoDB."

Cobre o suficiente pra que um dev futuro entenda por que a decisão fazia sentido naquele momento (mesmo que hoje não faça mais).

5. Decision

Voz ativa, futuro: "We will...". Uma decisão por documento.

Exemplo: "We will replace the SQLite cache with PostgreSQL, using the existing primary database cluster. Reads use a dedicated read replica; writes go to the primary."

Específica o suficiente pra ser implementável, mas sem entrar em código ou comandos. "Use Postgres" é vago demais; "Use Postgres como cache, com leituras numa read replica e escritas no primário" é específico sem ser implementação.

6. Consequences

O que fica mais fácil, o que fica mais difícil, riscos. Cubra positivos e negativos. Não é seção pra agradecimentos — é o balanço honesto da decisão.

Exemplo:

• Easier: aproveita backups e monitoramento já configurados pro Postgres; remove uma dependência do stack.
• Harder: TTL de cache passa a ser nossa responsabilidade (SQLite tinha vacuum automático adequado); precisamos rodar pg_repack mensalmente.
• Risk: aumento de ~15% na carga do cluster Postgres; coordenado com o time de Plataforma.

---

Numbering and filename convention

• Format: NNNN-kebab-case-slug.md (4 dígitos, zero-padded).

• Slug: frase do title em kebab-case, sem palavras supérfluas (use-postgres-as-primary-database, não decision-to-use-postgres-as-our-primary-database).

• Number: sequencial no diretório alvo. Use o script bundled scripts/next_number.py em vez de contar à mão:

  python3 scripts/next_number.py {dir}            # imprime NNNN
  python3 scripts/next_number.py {dir} {slug}     # imprime NNNN-slug.md
  

  O script lê o diretório, encontra o maior NNNN existente que bate com ^[0-9]{4}-.+\.md$ e devolve max+1 (ou 0001 se vazio). Não preenche buracos — 0001, 0007 retorna 0008. Falha com exit não-zero se o diretório não existir.

• Diretório default: doc/adr/. Outras convenções comuns: docs/adr/, decisions/, architecture/decisions/, adr/. Use a do projeto se já existir.

Exemplos:

doc/adr/0001-record-architecture-decisions.md
doc/adr/0017-use-postgres-as-primary-database.md
doc/adr/0023-adopt-grpc-for-internal-communication.md

---

Quando escrever ADR — quando NÃO escrever

✅ Escreva ADR para

• Escolha entre tecnologias (banco, linguagem, framework, message broker, plataforma).
• Estabelecimento de uma convenção (formato de data, formato de erro, schema versioning).
• Introdução de uma restrição de design ("não fazer chamadas síncronas entre serviços").
• Reversão ou superseção de uma decisão anterior.
• Adoção de uma metodologia (CI/CD strategy, branching model).

🚫 NÃO escreva ADR para

• Decisões triviais ou facilmente reversíveis (nome de variável, layout de pasta).
• Detalhes de implementação (uso de uma lib específica que pode trocar amanhã).
• Projetos completos com múltiplas decisões interligadas — esse é caso de design doc (delegue para a skill design-doc).
• Documentação de funcionalidade pra usuário final (README, API docs).
• Postmortems de incidente (formato diferente).

Se o usuário trouxer algo que cabe em "não escreva", diga isso antes de escrever. Sugira a alternativa apropriada.

---

Composability

• design-doc skill (mesmo repo): design-doc tem seção Alternativas Consideradas para decisões dentro do projeto. ADR é para decisões avulsas que merecem documento próprio. Um design doc grande pode referenciar vários ADRs (see ADR-0017 for the database choice). ADR não chama design-doc; design-doc pode citar ADRs.
• sequence-diagram skill: ADRs raramente precisam de sequência (são focados em decisão, não em fluxo). Mas se a decisão envolve protocolo de comunicação ("adotar SAGA pra transações distribuídas"), pode usar a mesma convenção do design-doc — bloco ```mermaid inline, que renderiza direto no Markdown.
• High-level vs implementation: igual ao design-doc. ADR documenta a decisão e suas consequências, não como implementar. Se está com kubectl, decoradores ou snippets — não é ADR, é manual de implementação.

---

Anti-padrões

• Bullets-only. Nygard avisa explicitamente. Use frases completas em parágrafos. Bullets só pra listas curtas com paralelismo claro (status options, lista de consequences).
• Sem rationale. "We will use Postgres." sem dizer por quê é manual de instalação, não ADR. Context + Decision + Consequences explicam o porquê.
• Consequences vagas. "Pode haver impacto em performance." não conta. Quantifique ou descreva o mecanismo ("+15% de carga no cluster, coordenado com Plataforma").
• Várias decisões por documento. Se você tem dois "We will..." independentes, é dois ADRs.
• Status omitido ou inventado. Use os quatro canônicos.
• Sem data. Sem data, é impossível saber se o contexto ainda vale.
• Filename solto. ADRs sem numeração e sem slug consistente quebram a busca cronológica.

---

When to load references

Quando	Carregue	Por quê
Usuário pediu "me dá um esqueleto"	references/template.md	Template do Pryce com convenções de preenchimento
Usuário pediu "me mostra um exemplo"	references/example.md	ADR 0001 (recursivo, canônico)
Sempre antes do Step 4	references/checklist.md	Self-review

Os três são opcionais durante a composição; o checklist não é opcional antes de entregar.