Fluxo de ADR — Visão geral

Todo trabalho que mexe no código é 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 do trabalho no repositório, com a decisão e a execução viva. O que não mexe no código (deploy, roadmap, organização) é uma tarefa no Gestor, quando vale registrar (ver Tarefa ou ADR).

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 (passos com situação, 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.
• O número vem da reserva do Gestor: ele dá o próximo número do repositório sem colisão entre sessões paralelas e nunca o reusa (um número reservado e não usado fica como buraco explicado). Sem o Gestor, o número é o maior existente + 1, conferido na branch em que se trabalha.
• 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.

O índice

O .specs/readme.md do projeto tem o índice das ADRs: uma lista enxuta e narrativa, uma linha por ADR — o número, o título (com o link) e a situação do 001 —, para ler a história do projeto de uma vez. O índice não diz qual é a próxima ADR, e o CLAUDE.md também não: o número vem da reserva do Gestor (ou do maior + 1). Escrever “a próxima é a N” em algum arquivo é um espelho à mão que envelhece no primeiro trabalho em paralelo.

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.
• No Gestor, a tarefa anda junto (quando há tarefa): o agente a move para Em andamento ao começar e para Revisão ao fechar a ADR, com um comentário interno (a ADR e os commits). O Concluído da tarefa é do dono — o agente o marca só quando ele pede.

Criação

A pasta e os seis arquivos são criados pela IA, no repositório, seguindo este Manifesto e o modelo da ADR. Com o Gestor, o MCP ajuda: dá o número reservado, entrega o esqueleto dos seis arquivos já preenchido com o número e o título e confere o formato antes do commit. O Gestor nunca escreve no repositório: quem escreve e commita é a IA, com a chave da pessoa, junto do código.

Tarefas vinculadas

Uma ADR pode estar vinculada a tarefas do Gestor, e uma tarefa a várias ADRs. O vínculo mora no Gestor e tem um de dois papéis:

• implementa — a tarefa executa a ADR (conta no andamento da ADR);
• contexto — a tarefa só precisa ler a ADR.

A IA vincula sozinha (ao criar a ADR de uma tarefa, ou ao ver a ADR citada na tarefa); a pessoa também vincula pela tela do item. Ao fechar, o 005 copia a lista das tarefas vinculadas. O cliente vê um vínculo só quando já pode abrir aquela ADR.

Branch e commits

• O fluxo de branches é o de Git e commits: trabalha-se na develop; uma branch por ADR é opcional (a regra quando há agentes em paralelo), integrada por merge local, sem pull request; o push só com a autorização do dono.
• Conventional Commits obrigatório. O commit cita a tarefa e a ADR no rodapé da mensagem (Tarefa: KBP-12 e ADR: 098), e o Gestor mostra esses commits no item e na página da ADR.
• Commits que alteram a documentação de uma ADR podem usar o prefixo adr/docs:.

Quem abre uma ADR

A IA, sozinha, pela regra de Tarefa ou ADR: ela decide se o trabalho pede ADR, procura a que já existe e só então cria uma nova — a pessoa não precisa pedir “abre a ADR tal”. O CEO e o Arquiteto decidem o que importa (o escopo do 001, o quiz do 003) e aprovam. Ver Papéis e responsabilidades.