ADR tools compared (2026): from CLI scripts to decision graphs
There's no dominant tool for architecture decision records, which is a useful signal in itself: the field is young and most teams are still figuring out what they actually need. This is an honest comparison of the real options, what each is good at, and the problem none of them solve.
If you're new to ADRs, start with the complete guide and come back here when you're picking tooling.
The options at a glance
| Tool | Type | Stores | Best for | Watch out for |
|---|---|---|---|---|
Plain Markdown in /docs/adr | Convention | Repo | Almost everyone, to start | No tooling means no nudges |
| adr-tools | Bash CLI | Repo | Solo / small repos, zero deps | Bash only, unmaintained-ish |
| dotnet-adr | .NET global tool | Repo | .NET shops, templating | Tied to the .NET toolchain |
| Log4Brains | CLI + static site | Repo + site | Teams wanting a browsable archive | Another site to host |
| adr-manager | Web UI over GitHub | Repo (via UI) | Non-CLI contributors | Web app dependency |
| Align | Decision graph | Across all tools | Teams past the "ADRs go stale" wall | Not a plain-text-only tool |
Plain Markdown (the honest default)
For most teams, a docs/adr/ folder with numbered Markdown files and the Nygard
template is enough to start, and you shouldn't let anyone talk you out of it. Zero
dependencies, lives with the code, reviewable in PRs, readable by humans and
agents. The downside is purely that there's no tooling to prompt you, so it
relies on discipline.
Start here. Adopt a tool only when you feel a specific pain Markdown can't solve.
adr-tools (Nygard)
The original. Bash scripts that scaffold and number ADRs in the Nygard format. Great if you're in a Unix shell all day and want the numbering and superseding links handled for you. It's lightweight to the point of being barely a tool, which is the appeal. Maintenance has been quiet, so don't expect new features.
dotnet-adr
A .NET global tool with templating support. If your shop is .NET-first, this fits your existing toolchain and gives you more structure than the bash scripts. Less relevant outside that ecosystem.
Log4Brains
Logs ADRs from your editor and publishes them as a static knowledge-base site. This is the pick if you want a browsable, searchable archive your whole org can read without cloning the repo. The trade-off is you're now hosting and maintaining that site.
adr-manager
A web UI for creating and managing ADRs stored as Markdown in GitHub. Good for bringing in non-CLI contributors (PMs, architects who don't live in a terminal). You're depending on the web app, but the underlying files stay in your repo.
The problem none of them solve
Every tool above is a better way to write and store ADRs. None of them solve the reason ADRs fail in practice: decisions don't stay in the file.
You write ADR 0007. Six weeks later the decision changes in a Slack thread, a
different squad ships against the old assumption, and a Jira ticket quietly
contradicts the ADR. Nobody updates the file, because the decision happened
somewhere the ADR tool can't see. Now you have two sources of truth and two teams
who each think they're right.
The ADR tools all assume the decision lives in one place (the file) and stays there. Real decisions live across Slack, GitHub, Jira and Confluence, and they move. That's the gap.
When you outgrow ADR tooling
Align is the next step when you hit that wall. Instead of storing decisions in one file format, it captures them where they actually happen, links them into a graph across all your tools, and flags when a new decision contradicts an existing one before it ships. It complements ADRs rather than replacing them: keep writing ADRs for the big architectural calls, and let Align keep them connected to reality.
The signal that you're ready: you're already feeling the "wait, didn't we decide this differently in Slack last month?" pain, and your ADRs are drifting out of sync with what the org actually does.
Recommendation
- Just starting? Plain Markdown + the Nygard template. Don't overthink it.
- Want a browsable archive? Log4Brains.
- .NET shop? dotnet-adr.
- ADRs going stale across tools, multiple squads stepping on each other? That's the decision-graph problem. See how Align handles it.
Align captures engineering decisions across the tools your team already uses and catches cross-team conflicts before they ship. Related reading: Architecture Decision Records: the complete guide.