ADR Architecture Writer
Workflow
- Identify the decision that needs a durable record.
- Read
references/adr-template.mdbefore adding or changing ADRs. - Keep one decision per ADR.
- State context, decision, consequences, alternatives, and validation impact.
- Cross-link related specs when the decision affects contracts or behavior.
- Update status instead of rewriting history when a decision changes.
Rules
- Use sequential filenames:
NNN-short-title.md. - Prefer
Proposta,Aceita,Substituida, orRejeitadafor status. - Do not bury unresolved tradeoffs in prose; list them directly.
- Record consequences for adapters, tests, data migration, and user-facing behavior.
- If the ADR affects schemas, mention versioning and reprocessing impact.
Review Checklist
- The decision is explicit.
- The rejected alternatives are clear enough to prevent reopening the same debate.
- The consequences include at least one downside.
- The validation plan is actionable.
- The ADR does not depend on provider-specific behavior unless the decision is about an adapter.