Course contentsShow
← Software Engineering
Lesson 1704 of 1,93349. Technical Writing and DocumentationFree lesson

Storing and Discovering ADRs

Learn best practices for versioning ADRs in the codebase and making them discoverable to the team.

Storing and Discovering ADRs

You'll learn: Where to keep Architecture Decision Records and how to ensure your team can actually find them when needed.

The Discovery Problem

ADRs are only valuable if people know they exist and can find them easily. A brilliant decision record hidden in someone's email folder might as well not exist. The storage location and discoverability strategy matter as much as the content itself.

Version Control is Your Friend

Store ADRs in the codebase itself, typically in a dedicated directory like /docs/adr/ or /adr/. This approach offers several advantages:

  • ADRs version alongside the code they describe
  • Pull request workflows apply to decision documentation
  • Git history shows when and why decisions changed
  • No separate system to maintain or lose access to

Think of it like keeping recipes in the kitchen rather than in a storage unit across town—context matters.

Naming and Numbering

Use a consistent naming convention:

  • 0001-use-postgres-for-primary-database.md
  • 0002-adopt-graphql-api-layer.md

Sequential numbers create a chronological record, while descriptive filenames make browsing meaningful.

Making ADRs Discoverable

Create an index file (README.md in the ADR directory) that lists all decisions with one-line summaries. This becomes your team's decision catalog.

Link to relevant ADRs from:

  • Your main project README
  • Code comments at decision points
  • Architecture documentation
  • Onboarding guides

Some teams add ADR links directly in configuration files or at module entry points, creating breadcrumbs from code to context.

Tools and Automation

Consider using ADR tools (adr-tools, log4brains) that generate indexes automatically and enforce consistent structure. These reduce friction in creating and maintaining your decision log.

Key Takeaway: Store ADRs in version control alongside your code, use consistent naming, maintain an index, and link to them from relevant places—discoverability requires intentional design, not hope.