ADRs — Architecture Decision Records

Um ADR registra uma decisão de arquitetura: o porquê de uma escolha, com contexto, alternativas e consequências. É append-only — não se reescreve; se a decisão muda, cria-se um novo ADR que supersede o anterior.

Numeração: os ADRs 0001–0005 são herdados do monolito legado bmp-novo-produto-dados e estão importados abaixo em Legado. O ADR-0006 (segregação em api/web) é referenciado no código mas não tem arquivo no log legado (fantasma). Os ADRs desta plataforma continuam a sequência a partir de 0007.

Log de decisões (desta plataforma)

ADR	Título	Status	Specs relacionadas
0007	Logging estruturado via @npd/common	Accepted	spec-001
0008	Componentes de UI via @nuclea/ui	Accepted	spec-002
0009	Definition of Done: docs + testes por spec	Accepted	todas
0010	Processo: Forge spec-driven + papéis HITL	Accepted	todas
0011	Branching + Continuous Delivery (dev/uat/prod)	Accepted	(CI/CD)

Processo: o ADR-0009 define que toda spec alimenta a documentação (abas Arquitetura/Funcionamento/Observabilidade), os testes unitários e os E2E — e que toda documentação markdown gerada entra neste site.

Legado (herdados do monolito bmp-novo-produto-dados)

Registro histórico append-only; referenciam o stack antigo (Next.js/Vercel).

ADR	Título	Status
0001	Adoção do formato ADR	Aceito
0002	Lock de stack (Next.js/Supabase/Vercel)	Aceito
0003	Lock de provider LLM (Anthropic)	Superseded by 0005
0004	Compressão do SDLC (demo 15/05)	Aceito
0005	LLM multi-provider (Anthropic + OpenAI)	Proposto
0006	Segregação do monolito → api/web	referenciado, sem arquivo (fantasma)

ADR × Spec

• ADR = a decisão (política/direção) e o porquê — imutável.
• Spec = o que construir para aplicar a decisão (requisitos, critérios) — evolui.
• Fluxo: ADR → spec → plan → tasks → código. Às vezes a spec vem antes e, no planejamento, gera novos ADRs.

Template

Copie para docs/adr/ADR-NNNN-titulo.md e preencha:

---
sidebar_position: N
title: "ADR-NNNN — Título curto da decisão"
---

# ADR-NNNN — Título curto da decisão

**Status:** Proposed | Accepted | Superseded by ADR-XXXX
**Data:** AAAA-MM-DD

## Contexto
O problema, as forças e restrições que motivam a decisão.

## Decisão
O que foi decidido (voz imperativa).

## Consequências
Trade-offs: o que fica mais fácil (+) e mais difícil (−).

## Alternativas consideradas
O que foi descartado e por quê.

## Specs relacionadas
- [spec-XYZ](../specs/spec-XYZ.md)