Decisions (ADR template)
3 min
Use this page as a template for documenting important architectural or organizational decisions. A consistent ADR (Architecture Decision Record) format helps teams understand why decisions were made, what alternatives were considered, and how future work may be affected.
Update ADRs whenever major technical or organizational decisions are proposed, accepted, or deprecated. Keeping this history clear reduces confusion and preserves long‑term context.
How to use this template
Each ADR should clearly describe:
- Context – What problem or situation led to this decision?
- Decision – What choice was made and why?
- Alternatives – What other options were considered?
- Consequences – How does this decision impact the system, team, or future work?
- Status – Proposed, accepted, deprecated, or superseded
Use the expandable section below to create a new ADR entry.
Best practices for ADRs
- Write decisions clearly and concisely
- Avoid implementation details–focus on reasoning
- Link related ADRs to show evolution of ideas
- Keep ADRs updated as decisions evolve or are replaced
- Encourage team discussions before accepting major decisions
What to read next
Help teammates continue exploring internal documentation:
- Team handbook – Culture and communication norms
- Engineering docs – Architecture, development workflows, and runbooks
- Onboarding checklist – Steps for new teammates