Fluxo de ADR — Visão geral

Fluxo de ADR — Visão geral

Toda unidade de trabalho é uma ADR: uma pasta numerada em .specs/adr/ que percorre o ciclo do trabalho através de seis arquivos fixos. A ADR substitui épicos, specs e logs de decisão — é o único contêiner de trabalho.

Anatomia de uma ADR

.specs/adr/001-nome-em-portugues/
├── 001-executive.md          ← decisão executiva (o quê, por quê, escopo, prazos)
├── 002-resources.md          ← curadoria de recursos/anexos
├── 003-plan.md               ← o plano + quiz de perguntas (a decisão técnica)
├── 004-tasks.md              ← execução viva (status, libs, decisões, estratégia)
├── 005-relatorio-tecnico.md  ← entrega: commits, testes, arquivos
├── 006-relatorio-executivo.md← resumo humano para gestão
└── resources/                ← anexos (só existe quando há material)

Detalhe de cada arquivo: Os seis arquivos.

Numeração e nome

• Numeração sequencial global no repositório: 001, 002, 003… Uma sequência única, não reinicia por módulo.
• Nome da pasta: NNN-slug-em-português, kebab-case. Ex.: .specs/adr/001-estrutura-de-permissoes/.
• Os seis arquivos têm prefixo fixo de papel: 001- a 006-, sempre na mesma ordem.

Os seis arquivos são obrigatórios

Toda ADR entrega os seis arquivos, sempre. Entregar os artefatos é o que torna o trabalho revisável (revisão implícita).

• O 002-resources.md existe mesmo quando não há anexos — nesse caso, declara explicitamente “Sem recursos para esta ADR”. A pasta resources/ só é criada quando há material.

Ciclo de vida

Em planejamento → Em execução → Concluído

• Durante o desenvolvimento, a ADR pode ser alterada à vontade.
• Após concluída, a ADR é imutável. Mudanças posteriores não editam a ADR concluída: abre-se uma nova ADR que sobrepõe a anterior e referencia a que substitui. Assim a memória histórica é preservada — vê-se o que foi decidido e o que mudou, e por quê.
• ADRs referenciam outras livremente, formando a trilha de decisões do projeto.
• O status da ADR mora apenas no 001-executive.md. Não há README/index na pasta.

Criação

A pasta e os seis arquivos são criados manualmente pela IA, seguindo este manifesto. Não há gerador de template nem comando dedicado — a estrutura é simples e estável o bastante para ser criada à mão.

Branch e commits

• Cada ADR é desenvolvida em branch própria (ver Git e commits).
• Conventional Commits obrigatório. O código é guiado pela ADR; referenciar a ADR no commit é opcional.
• Commits que alteram a documentação de uma ADR podem usar o prefixo adr/.

Quem abre uma ADR

ADRs são abertas pelo Arquiteto ou pelo CEO. O desenvolvedor executa as ADRs abertas. Ver Papéis e responsabilidades.