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.

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 (creators, 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; lista de tarefas e subtarefas; 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 Creator e Produto?**
- ( ) A) Tabela de junção explícita — flexível, mais joins
- (X) B) FK direta produto→creator — 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 modelo de exemplo para referência.

004-tasks.md — Execução viva

Dono: Dev. Momento: durante a execução.

Arquivo vivo: status por tarefa (todo / doing / done / blocked), refletindo o estado atual (o histórico detalhado vem do git).

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. Vincular commit ↔ tarefa é flexível.

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).

Fechamento da ADR

Ao finalizar, a sequência é:

IA escreve 005-relatorio-tecnico → escreve 006-relatorio-executivo
→ roda o script que gera os PDFs → commita tudo
→ avisa: "PDFs prontos para envio"

O envio ao Discord é manual, feito pelo Dev. Não há webhook nem script de envio automático.

Criado por Joseph Trupel