Why Organizational Consistency Matters

Architectural Decision Records (ADRs) are the written history of the critical choices that shape your system – decisions about databases, frameworks, infrastructure, APIs, and integration patterns. When ADRs are organized haphazardly, they quickly become a chaotic archive where valuable context is hidden behind inconsistent file names and scattered directories. Teams waste hours searching for a specific decision, lose the ability to trace why a trade-off was made, and struggle to onboard new engineers who need to understand the system's evolution.

A consistent organizational approach transforms your ADR collection from a pile of markdown files into a living, searchable knowledge base. It reduces cognitive overhead: every team member knows exactly where to find records and how they are labeled, so the barrier to both writing and consulting ADRs drops. This encourages more frequent documentation and more disciplined decision-making. Over time, the repository becomes a trusted source of truth that prevents rehashing old debates, clarifies technical context, and helps new developers understand the "why" behind the system's architecture.

Structuring Your ADR Repository

The foundation of an efficient ADR workflow is a clear, predictable file structure. Start by designating a dedicated directory – typically docs/adr/ at the project root. This keeps decision records separate from general documentation and source code, making them easy to discover via search, file tree navigation, or CI workflows.

Sequential Numbering and Date Prefixes

Use unique, zero-padded sequential identifiers in filenames. The classic pattern is NNNN-title-with-hyphens.md, where NNNN starts at 0001 and increments with each new record. This ensures chronological order when files are sorted lexicographically and provides unambiguous references for cross-linking between ADRs. Many teams enhance this by prepending the date in ISO 8601 format, yielding filenames like 2024-04-27-0001-title.md. The date prefix makes the decision timeline visible at a glance, even before opening the file, and eliminates the need to open each ADR just to see when it was created.

Example Naming Convention

A robust naming convention follows this pattern:
YYYY-MM-DD-NNNN-short-descriptive-title.md
For example:
2024-04-27-0001-use-postgresql-for-primary-database.md
2024-05-12-0002-adopt-react-query-for-data-fetching.md

Avoid generic titles like "database-decision" or "backend-framework" – they lose meaning when listed in an index. The title should be a concise summary of the decision itself (e.g., "adopt-vitest-over-jest-for-unit-testing"). This makes scanning the directory listing or index table instantly informative.

Handling Multi-Project ADRs

In mono-repositories or organizations with multiple related services, consider subdirectories: docs/adr/service-a/, docs/adr/service-b/. Each sub-repository can maintain its own sequence, but you may also choose a global sequence for cross-cutting decisions. A master index file at the root of docs/adr/ can map each decision to its project area. Alternatively, use tags or labels in front matter (such as category: backend, security) to categorize by domain while keeping a single flat directory. This approach works well when decisions affect multiple services – the flat directory with metadata allows filtering without duplicating files.

Version Control and Branching Strategy

Treat ADRs like code: they belong in version control and should follow the same review process. When proposing a new ADR (status: Proposed), create a feature branch with the ADR file, open a pull request, and discuss the decision as part of the code review. This ties architectural discussions to your regular workflow and creates a natural audit trail. After the decision is accepted, merge the branch into the main line. Never overwrite an ADR – if a decision changes, create a new ADR that supersedes the old one. This preserves history and makes it possible to see how the architecture evolved over time.

Labeling ADRs for Quick Scannability

Labels provide instant context without reading the full document. The most important label is the file title, which should be a concise yet precise summary of the decision. Avoid vague titles like "Database Decision" in favor of "Adopt PostgreSQL with JSONB for Flexible Schema Storage." Pair this with a visible status indicator that lets anyone assess the current relevance of a decision at a glance.

Status Indicators in Filenames and Front Matter

Traditionally, ADR statuses include Proposed, Accepted, Deprecated, and Superseded. You can embed the status directly in the filename (e.g., 2024-04-27-0001-proposed-title.md) or rely on front matter metadata. The latter is more flexible because it allows status changes without renaming files – renaming can break links and clutter your Git history. Standard front matter keys might look like:

---
title: "Use PostgreSQL for Primary Database"
status: "Accepted"
date: 2024-04-27
deciders: ["alice", "bob"]
tags: ["database", "infrastructure"]
supersedes: ["2023-11-02-0012"]
---

Using YAML or TOML front matter also enables automated processing: a script can quickly list all Proposed ADRs, generate a status dashboard, or email reminders for stale records.

Consistent Metadata Fields

Beyond status, enrich ADRs with fields that improve discoverability and traceability:

  • Tags – Group decisions by technology, domain, or impact level (e.g., security, performance, cost). Tags enable filtering across the entire collection.
  • Deciders – List the people who made or approved the decision. This provides a point of contact for clarification.
  • Date – The date of the decision (not the file creation date). Useful for tracking how decisions age.
  • Supersedes / Amends / References – Links to related ADRs. This builds a web of decisions that helps readers understand dependencies and trade-offs.
  • Context – A short summary of the problem or constraints that led to the decision. While this usually goes in the body, a one-line summary in front matter can be displayed in an index table.

Cross-Referencing ADRs

Decisions rarely stand alone. An ADR about adopting a new ORM may be followed by one about schema migrations, and later superseded by an ADR that switches to a different persistence layer. Link related ADRs explicitly using Supersedes, Amends, or References fields in front matter. Within the narrative, use hyperlinks like see ADR-0021 to preserve traceability. This converts a linear list of files into a navigable network of decisions, helping readers understand how choices build upon or replace each other.

Maintaining a Living Index

A master index file consolidates all ADRs into a single, readable table. Place it at docs/adr/README.md or docs/adr/index.md. The table should include columns for the ADR number, date, title, status, and a one-sentence summary. Optionally, add tags and a link to the file. Keep this index updated – automate its generation using scripts that parse front matter from every ADR file. This avoids manual drift and ensures the index is always accurate.

Example table structure in markdown:

| # | Date | Title | Status | Tags |
|---|------|-------|--------|------|
| 0001 | 2024-04-27 | Use PostgreSQL for Primary Database | Accepted | database, infrastructure |
| 0002 | 2024-05-12 | Adopt React Query for Data Fetching | Proposed | frontend, api |

Tools like adr-tools (available via npm or Go) can scaffold new ADRs and automatically update a table of contents. Similarly, static site generators (e.g., MkDocs, Docusaurus) can render the ADR directory with search and navigation, making decision history even more accessible to the whole team. If you use GitHub Pages or GitLab Pages, you can generate a searchable HTML index on every merge.

Tools and Automation for ADR Management

Manual management of ADRs becomes brittle as the collection grows. Several open-source tools enforce naming conventions, generate status reports, and integrate with version control.

adr-tools

adr-tools is a classic bash-based tool by Michael Nygard. It initializes an ADR directory, creates new records with sequential numbering and a template, and lists existing ADRs. While it doesn't handle status transitions automatically, it enforces a consistent structure and is easy to integrate into CI pipelines. You can extend it with a custom template that includes your required front matter fields.

Log4brains

Log4brains takes ADRs further by providing a web UI, search, and a knowledge base. It reads ADRs from a repository and builds an interactive documentation site. It supports automatic cross-referencing, status management, and even visual dependency graphs that show how decisions relate to each other. Log4brains is particularly valuable for larger teams that need to browse decisions without opening raw markdown files.

GitHub / GitLab Integration

Leverage version control features: use pull requests for new or updated ADRs, enforce review workflows, and tag ADRs with labels (e.g., status:accepted) directly on the repository. GitHub Actions or GitLab CI can validate that ADR filenames follow the convention and that front matter YAML is valid. You can also generate a live index page using a workflow that rebuilds a docs site on every merge. For example, a GitHub Action can run a script that parses all ADRs and generates a JSON index that a static site consumes.

Adr-view

adr-view is a browser-based tool that renders your ADR directory as a searchable, filterable list. It works directly with your repository – you just point it at the folder and it reads front matter. It's a lightweight option if you don't want a full static site generator.

Review and Evolution of ADRs

ADRs are not static artifacts; they must evolve with the system. Schedule regular reviews (e.g., quarterly architecture syncs) to reassess decisions. If a decision is no longer relevant, mark it as deprecated. When a new decision replaces an older one, use the Supersedes field to maintain the chain. This keeps the repository honest and prevents stale ADRs from misleading new engineers.

Encourage a culture of lightweight updates. An ADR's status can change from Proposed to Accepted after team consensus, which is a simple one-line front matter edit. Similarly, a Deprecated ADR should include the reason and a pointer to the new record. This living maintenance ensures that the ADR collection remains a trusted reference rather than a museum.

Automated Stale-ADR Checks

Set up a scheduled job (e.g., a cron job or GitHub Action) that scans ADRs with status "Accepted" older than a threshold (say, 18 months) and creates an issue to review them. This keeps the decision base from accumulating outdated guidance. You can also generate a report showing the age distribution of ADRs by status.

Conclusion

Organizing and labeling ADRs is not an end in itself – it is the foundation for an efficient, transparent decision-making process. By adopting a consistent directory structure, sequential numbering with date prefixes, descriptive titles, and rich metadata, teams unlock the full value of their architectural decisions. Automated tools reduce the overhead of maintenance, while regular reviews keep the collection relevant. With these practices, your ADR repository becomes a vital asset that accelerates onboarding, prevents revisiting past debates, and documents the system's architectural journey with clarity.

For further reading, see the original Documenting Architecture Decisions by Michael Nygard, and explore the ADR GitHub organization for community templates and tools. The ADR repository by Joel Parker Henderson also provides a comprehensive set of examples and templates that you can adapt to your team's needs.