architecture-decision-record
暂无简介
- License 许可
- MIT
- 所属仓库
- allanpablo/forja
- 最近更新
- 2026-11-15
- Stars
- ★ 2
- Forks
- 0
03 SKILL.md 正文
Registro de Decisão de Arquitetura (ADR)
Registra uma decisão técnica relevante e, acima de tudo, por que ela foi tomada, para que qualquer pessoa (inclusive o autor, meses depois) consiga entendê-la sem reconstruir a discussão.
Um ADR é curto. Se precisa de mais de uma página, provavelmente é mais de uma decisão.
Quando escrever
Escreva um ADR quando a decisão:
- for cara de reverter (banco de dados, linguagem, framework, modelo de implantação, fronteiras do modelo de dados);
- afetar mais de um módulo, contexto ou time;
- não for óbvia, a ponto de alguém depois perguntar "por que fizemos assim?";
- for o resultado de uma prova de conceito (spike).
Não escreva ADRs para escolhas rotineiras que qualquer pessoa do time faria do mesmo jeito.
Regras
- Uma decisão por ADR.
- Imutável depois de aceito. Não edite a decisão; escreva um ADR novo que o substitua e atualize só o status do antigo.
- Escrito no repositório, junto ao código, numerado em sequência e nunca renumerado. Use a pasta que o projeto já usa (
docs/adr/NNNN-slug-curto.mdquando não houver uma). - O contexto enuncia forças, não opiniões: requisitos, restrições, prazos, habilidades do time, evidência de spikes ou de produção.
- As alternativas são reais. Cada uma traz o motivo de ter perdido. Uma decisão sem alternativas consideradas é um anúncio, não uma decisão.
- As consequências incluem as ruins. Toda decisão tem custos; nomeá-los é o que torna o registro confiável.
- Declare a reversibilidade e um gatilho de revisão: o que faria valer a pena revisitar esta decisão.
- Se um fato é desconhecido, escreva-o como suposição. Não invente evidência.
Status
Proposed → Accepted → (Deprecated | Superseded by NNNN)
Rejected também é válido: registrar a decisão de não fazer algo impede que a mesma discussão recomece.
Modelo
# NNNN. <Decisão como uma frase curta no imperativo>
- Status: <Proposed | Accepted | Rejected | Deprecated | Superseded by NNNN>
- Data: <AAAA-MM-DD>
- Decisores: <nomes ou papéis>
- Relacionados: <ADRs, spikes, issues>
## Contexto
<O problema e as forças em jogo. Restrições, requisitos, evidência. Ainda sem solução.>
## Decisão
<O que foi decidido, de forma direta. "Vamos ...">
## Alternativas consideradas
- <Alternativa> — <por que não foi escolhida>
## Consequências
- Positivas: <...>
- Negativas: <...>
- Neutras / desdobramentos: <trabalho que isso cria, riscos a acompanhar>
## Reversibilidade
<Barata | Custosa | Sem volta>. <O que reverter envolveria.>
## Gatilho de revisão
<Condição que deve levar a revisitar esta decisão, por exemplo volume acima de X, crescimento do time, uma dependência chegando ao fim do suporte.>
Processo
- Confirme que a decisão merece um ADR (veja "Quando escrever").
- Reúna o contexto da conversa, do código e de resultados de spikes. Liste os fatos faltantes como suposições.
- Escreva a decisão em uma ou duas frases antes de qualquer outra coisa; se não couber nisso, divida.
- Preencha alternativas e consequências, depois reversibilidade e gatilho de revisão.
- Se ele substitui um ADR anterior, marque o antigo como
Superseded by NNNN.
No Forja
No Forja, os ADRs ficam em memory/90-decisions/NNNN-slug.md, a partir de memory/90-decisions/_template.md (cabeçalho - **Status**:, - **Data**:, - **Autor(es)**:, - **Tags**:). Use os status do template do projeto (proposed, accepted, superseded by ADR-NNNN, deprecated) e mantenha Reversibilidade e Gatilho de revisão como seções ao final.
- Próximo número e status:
forja adr:list; detalhe de um ADR:forja adr:show <id>. - Depois de gravar:
forja sync:universal, para o ADR entrar na memória consultável. - Mudança estrutural sem ADR é reprovada pelo papel governance.
Evite
- Escrever o ADR como documento de design ou tutorial.
- Um contexto que defende a decisão em vez de descrever a situação.
- Esconder consequências negativas.
- Editar um ADR aceito para mudar a decisão.
- Registrar decisões que ninguém nunca vai questionar.