3. Fluxo de ADR · versão 2.0.0
Os seis arquivos
Cada ADR é composta por seis arquivos numerados. Cada um tem um dono, um propósito e um momento. As seções de cada arquivo seguem um conjunto obrigatório + recomendado + flexível: o obrigatório sempre existe; o recomendado entra quando ajuda; a IA pode acrescentar o que fizer sentido, desde que mantenha o padrão.
001-executive.md — Decisão executiva
Dono: CEO + Arquiteto. Momento: abertura da ADR.
Decisões de negócio: o quê e o porquê, sem detalhe técnico pesado (menção leve a tecnologia é aceitável quando for decisão executiva). Pode ser produzido em plan mode, com a IA entrevistando o CEO/Arquiteto e registrando perguntas, alternativas e respostas — nada técnico nesta fase.
Obrigatório: Status; Decisões executivas; Escopo (entra agora / pode adiar / fica de fora);
Prazos (datas absolutas, com prazo esperado e, ao fechar, real); Referências e links;
campo Aprovado por / em.
Recomendado: Brainstorming; Recursos a implementar; Objetivos de negócio / KPIs; módulos/áreas
afetados (com link para .specs/stack/ quando aplicável).
O status da ADR vive aqui (e só aqui): Em planejamento · Em execução · Concluído.
A ADR é muito mais detalhada que a tarefa do Gestor: no Gestor a tarefa pode ser só “mudar a
cor do botão”; na ADR estão as perguntas, a análise e os recursos. Por isso o 001 guarda a
situação e os prazos do trabalho técnico, mesmo quando há tarefa vinculada; o Gestor guarda o
controle do dono (o prazo da tarefa, o ciclo, a coluna do quadro).
002-resources.md — Curadoria de recursos
Dono: Arquiteto. Momento: após o executive, antes do plano.
Índice comentado dos materiais de apoio (cada item com uma linha: o que é e por que importa).
Os anexos ficam na pasta resources/ ao lado, só quando existirem.
- Versionar é caso a caso: referenciar um link (planilha, pasta no Drive) é caminho válido; vira arquivo no repositório apenas o que é importante e reutilizável no futuro. Dumps de banco não vão para o repositório.
- Dados sensíveis reais (clientes, contratos): tratar caso a caso, com cuidado — preferir anonimização ou referência.
- Quando não há recursos, o arquivo existe assim mesmo e declara: “Sem recursos para esta ADR”.
003-plan.md — O plano (a decisão técnica)
Dono: Dev + Arquiteto (a IA propõe, o humano decide). Momento: antes de qualquer código.
É uma coisa só: a ADR clássica e o quiz de decisões no mesmo arquivo.
Contém: título, data, contexto, decisão, consequências; a lista de passos (T1, T2…); o quiz de perguntas (agrupado por tema); e o pós-plan (riscos, dependências, fora de escopo — flexível).
O quiz é o registro da decisão técnica. Cada pergunta é feita em plan mode, com a IA propondo a resposta recomendada e o humano confirmando. Formato:
### Tema: Banco de dados
**P1. Como modelar a relação entre Tarefa e Projeto?**- ( ) A) Tabela de junção explícita — flexível, mais joins- (X) B) FK direta tarefa→projeto — simples, 1:N suficiente aqui- ( ) C) Campo JSON — rápido, perde integridade referencial
Justificativa: a relação é 1:N e não há atributos na ligação. FK direta basta.As alternativas descartadas permanecem (memória técnica), mas o que é certo × errado deve ficar enfático, para não confundir o contexto da IA em sessões futuras.
Não há número fixo de perguntas — faça quantas fizerem sentido, com um piso mínimo razoável. Há um exemplo completo para referência, e o modelo da ADR traz o esqueleto dos seis arquivos.
004-tasks.md — Execução viva
Dono: Dev. Momento: durante a execução.
Arquivo vivo: a situação de cada passo (todo / doing / done / blocked), refletindo o
estado atual (o histórico detalhado vem do git). É o checklist do agente durante o trabalho.
Uma tarefa do Gestor costuma gerar um checklist grande aqui: o agente chama o Gestor para pôr a
tarefa em andamento, e o controle fino, passo a passo, fica interno, no 004. O passo que é
também uma tarefa do Gestor leva o identificador ao lado (T3 — Tela de lista (KBP-12)); o
resto não vai ao Gestor.
Registra obrigatoriamente:
- Bibliotecas instaladas (nome + versão + porquê).
- Decisões e contradições tomadas em execução (desvios do plano, documentados).
- Estratégia da IA usada por tarefa: agente único, subagentes, agentes exploradores, paralelismo em massa.
Se houver plan mode durante a execução, as novas perguntas e respostas são registradas aqui (não voltam ao 003).
005-relatorio-tecnico.md — Entrega técnica
Dono: Dev (a IA redige; a ação parte do Dev). Momento: ao finalizar tudo.
Detalha a entrega: commits (hash + mensagem), testes automatizados criados, smoke tests, arquivos tocados e por quê, bibliotecas, decisões e as tarefas do Gestor vinculadas (o identificador, o título e o papel: implementa ou contexto), copiadas do Gestor no fechamento — a cópia no git do vínculo que viveu no Gestor. Sem tarefa vinculada, a seção diz “Nenhuma”.
A IA redige o texto a partir do contexto e roda o script que gera o PDF (ver Relatórios e PDF).
006-relatorio-executivo.md — Resumo executivo
Dono: Dev (a IA redige). Momento: junto com o 005.
Resumo humano, curto (poucas páginas), zero técnico, em linguagem de gestor/CEO. Modelo recomendado: Entregue · Impacto · Próximos passos. Não inclui status de prazo (isso vive no 001-executive e no 004). É o arquivo que o cliente sempre pode ler: com o Gestor, ele chega ao cliente pela Documentação do projeto.
Fechamento da ADR
Ao finalizar, a sequência é:
IA escreve 005-relatorio-tecnico (com as tarefas vinculadas) → escreve 006-relatorio-executivo→ marca o 001 como Concluído → atualiza o 004 e a linha do índice→ roda o script que gera os PDFs → commita tudo→ no Gestor: move a tarefa para Revisão, com um comentário interno (a ADR e os commits)→ avisa: "PDFs prontos para envio"Com o Gestor, o 006 (e o resto, com a liberação da parte técnica) chega ao cliente pela
Documentação do projeto; mandar os PDFs por outro canal (Discord, e-mail) é opcional e manual.
Não há webhook nem script de envio automático.