From Manual Files to CLI Automation
You can manage ADRs with nothing more than a text editor and a folder in your Git repository. However, as the number of decisions grows, manual management becomes tedious — you need to remember the next sequence number, apply the correct template, and update superseded records. Several tools automate this.
adr-tools (Bash-based CLI)
The most widely used tool is adr-tools, a set of Bash scripts created by Nat Pryce. It handles the mechanical parts of ADR management: scaffolding a new ADR with the next sequence number and the standard template (Status, Context, Decision, Consequences) pre-filled, and — when a decision is superseded — creating the new ADR with a link back to the old one while automatically flipping the old ADR's status to "Superseded by [new ADR]." A companion listing command gives you a quick index of every ADR in the repo, so no one has to track sequence numbers by hand.
Other tools worth knowing:
| Tool | Language | Notable Feature |
|---|---|---|
adr-tools |
Bash | The original, widely adopted |
log4brains |
Node.js | Generates a searchable static website from your ADRs |
adr-manager |
VS Code Extension | GUI for creating and browsing ADRs in your editor |
| Custom templates | Any | Many teams add fields like "Reviewers", "Related ADRs", or "Review Date" |
Integrating ADRs into your pull request workflow:
The most effective integration is requiring an ADR in the same pull request as the code change it describes, enforced with a PR checklist item — e.g., "If this introduces a new dependency, data store, or API contract, an ADR must be added in this PR."
This makes the ADR a first-class artifact of the development process, not an afterthought.
Key Point: The tool matters far less than the habit. A team that consistently writes ADRs in plain Markdown files with no tooling will outperform a team that installs sophisticated tooling but only writes an ADR once a quarter. Start with the simplest approach that your team will actually use, then add tooling when the volume of decisions justifies it. The single most important adoption strategy is having a senior engineer or tech lead model the behavior — writing the first five ADRs themselves, referencing them in code reviews, and pointing new team members to them during onboarding.