ADR Template
A copy-paste starter file so authors spend time on content, not formatting.
Why
Friction kills documentation. If an engineer has to remember which sections an ADR needs and in what order, most will skip writing one entirely. A checked-in template removes that cognitive load: copy the file, fill the blanks, done. Teams with a template write 3-5x more ADRs than teams that 'just write a markdown file', because the blank-slate problem is the real bottleneck, not the writing itself.
When
Set up once per repo, then copy for each new decision. The template itself takes 20 min to author and never needs redoing.
How
1. Create docs/adr/0000-template.md with the standard sections as headings - Add inline comments (<!-- ... -->) explaining what each section wants 2. Add a justfile/Makefile target: 'make adr TITLE="use-redis"' that: - Finds the next free number - Copies the template to docs/adr/NNNN-use-redis.md - Opens it in $EDITOR 3. Add a CONTRIBUTING.md line: "Architectural decisions require an ADR — run make adr" 4. Optionally add adr-tools (npm) to lint that every ADR has all required sections
Example
# NNNN. <title> - Status: Proposed - Date: YYYY-MM-DD - Deciders: @alice, @bob - Context: <!-- What forces, constraints, and alternatives? ≥3 paragraphs --> - Decision: <!-- One bold sentence. --> - Consequences: + <!-- positive --> - <!-- negative --> ~ <!-- neutral --> $ make adr TITLE="use-redis-for-cache" → created docs/adr/0012-use-redis-for-cache.md
Common Problems
- ⚠Making the template too elaborate with 12 sections — authors see it as a chore and skip it; keep it to 5 core sections.
- ⚠Forgetting to update the template when the team's needs evolve, so it asks for fields nobody cares about anymore.
Best Practices
- ✓Keep the template under 30 lines so it fits on one screen — anything longer signals over-engineering.
- ✓Include a 'Deciders' field so it's clear who has authority to flip Status to Accepted.
- ✓Version the template in git and mention template changes in the architecture sync so everyone stays aligned.