Registro de Decisões
Visão Geral
Decisões são infraestrutura durável; memória e histórico de chat não são. O custo de um registro é pago uma vez; o custo de uma decisão perdida é pago toda vez que alguém tenta engenharia reversa de intenção a partir do código.
A Estrutura do Registro
Toda decisão não trivial produz um registro com uma estrutura fixa, para que qualquer leitor saiba onde procurar:
| Seção | Contém |
|---|---|
| Arquitetura | A forma da solução e os arquivos principais |
| Modelo de Dados | Entidades, campos, relacionamentos |
| Decisões (com PORQUÊ) | Cada escolha acompanhada de sua justificativa — porquê é obrigatório |
| Interfaces | Como outro código usa isso |
| Restrições | O que deve permanecer verdadeiro |
| Pegadinhas | Armadilhas não óbvias para a próxima pessoa |
| Alternativas Rejeitadas | O que foi considerado e descartado, e porquê — evita reabrir questões já resolvidas |
Os Três Artefatos Complementares
- Um índice de todas as decisões com rastreamento explícito de dependências (quais dependem de quais) e uma seção substituído. Transforma uma pilha de registros em um grafo navegável.
- Um documento de "Considerações Futuras" — ideias adiadas e preocupações conhecidas, consultado ao iniciar novos trabalhos para que nada seja esquecido silenciosamente. Itens de ação de incidentes e decisões adiadas com gatilho vão parar aqui.
- Um arquivo — registros substituídos são movidos para cá em vez de deletados. A história é preservada, não sobrescrita.
Referência Rápida
- Convenção de localização do registro:
docs/superpowers/decisions/YYYY-MM-DD-<tema>.mdcom frontmatter YAML (title,date,component,status,supersedes,dependencies). - Considerações Futuras fica em
docs/superpowers/future-considerations.md. Cada entrada tem um status (open/triggered/done/dropped) e, onde aplicável, o gatilho que deve reativá-la. Consulte-o ao iniciar novos trabalhos. - O frontmatter alimenta o índice gerado automaticamente — mantenha-o preciso.
- O porquê e as alternativas rejeitadas são as duas seções de maior valor. Um registro sem elas é uma mina terrestre.
- Escreva o registro na etapa Registro do pipeline (veja
designing-before-building), após Executar.
Ferramentas Inclusas
Esta skill possui seus próprios scripts e template, para que funcionem em qualquer repositório onde a skill seja instalada. Eles ficam ao lado de SKILL.md:
recording-decisions/
scripts/doc-archive.sh encontrar especificações/planos sem um registro de decisão
scripts/index-rebuild.sh regenerar o índice a partir do frontmatter dos registros
templates/decision-record.md
Localize-os — a skill pode estar instalada por projeto ou globalmente:
for base in .claude/skills ~/.claude/skills; do
d="$base/recording-decisions/scripts"
[ -d "$d" ] && echo "$d" && break
done
doc-archive.sh [specs_dir] [plans_dir] [decisions_dir] [archive_dir]
Lista especificações sem um registro de decisão correspondente e exibe um prompt de conversão construído a partir do template. Padrões: docs/superpowers/{specs,plans,decisions,archive}.
index-rebuild.sh [decisions_dir] [output_file]
Reescreve docs/superpowers/index.md a partir do frontmatter de cada registro — uma tabela Ativa (componente, título, data, dependências) e uma tabela Substituído (componente, título, substituído por). Regenerado por completo, portanto nunca edite manualmente.
Ambos são scripts bash sem dependências: um projeto que usa esta skill não precisa de yq, jq ou um executor de tarefas. Se os scripts estiverem faltando, os procedimentos acima são autossuficientes — execute o trabalho diretamente.
Por que isso é importante para o contexto
Especificações e planos são propositalmente verbosos; eles são escritos para um humano seguindo o raciocínio. Essa verbosidade é cobrada no contexto toda vez que o Claude os abre. Um registro de decisão mantém o necessário para seguir em frente — decisões, o porquê, interfaces, restrições, pegadinhas, alternativas rejeitadas — em ~30-50 linhas, enquanto a especificação original é movida para archive/, onde permanece legível para humanos e não custa nada até ser deliberadamente aberta.
Quando NÃO usar
Mudanças triviais e auto-evidentes não precisam de registro. O teste: alguém no futuro perguntaria "por que isso foi feito assim?" Se sim, registre.
Justificativa completa: Artigo II da constituição, empacotado em engineering-constitution/references/engineering-constitution.md.