The architecture decision record collection: thirteen templates and a process guide

What an ADR is according to the definition page

The opening definition is short enough to quote and specific enough to be useful: an architecture decision record is a document that captures an important architecture decision made along with its context and consequences. Three other terms follow, and they do real work in the rest of the repository.

An architecture decision is a software design choice that addresses a significant requirement. The adjective matters, because a record of every small choice is noise. An architecture decision log is the collection of all ADRs for a project or organisation. An architecturally-significant requirement is a requirement with a measurable effect on the system's architecture, which is the test you apply before deciding something deserves a record.

The repository places all of this under a heading it calls architecture knowledge management. That framing is what separates an ADR from a meeting note. A meeting note records what was said; an ADR records what was decided, why, and what it costs you later. The consequences clause is the one most teams skip, and it is the only part that becomes useful when the decision is being revisited two years on.

The README also carries an instruction worth repeating: do your own due diligence for these resources before using them in any critical systems. A repository that hosts thirteen different templates cannot vouch for all thirteen, and it says so at the top.

Thirteen templates from independent authors

The template index is the reason to come to this repository. It lists a decision record template by Jeff Tyree and Art Akerman, one by Michael Nygard, one by EdgeX, one by arc42, one for the Alexandrian pattern, one for a business case, one from the MADR project, one using Planguage, one by Paulo Merson, one by Olaf Zimmermann built on Y-statements, one by Gareth Morgan, one from GIG Cymru NHS Wales, and one for Important Technical Decisions by Ignacio Larrañaga.

That list spans genuinely different traditions. Nygard's is the agile-community original and is famously minimal. arc42 comes from the same German software architecture community as the quality goals it usually accompanies. Y-statements is a fixed four-sentence format with slots to fill in. MADR is structured around markdown headings and has a status field, which makes it easy to automate. Planguage, by Peter Hahndel, uses a deliberately artificial notation that some teams love and most find hard to read.

The spread is the point. A reader who has never written an ADR can look at three or four of these and notice which sections each author considers mandatory. The sections that appear in all of them are the ones worth keeping in your own template.

Templates live under `locales/en/templates/`, one directory each, and the same tree structure holds the translations, so a team working in another language has a path to follow rather than a translation to commission.

Worked examples for decisions people actually argue about

The examples directory answers the question templates cannot, which is what a filled-in record looks like. The listed examples are CSS framework, environment variable configuration, metrics monitors alerts, Microsoft Azure DevOps, monorepo versus multirepo, programming languages, secrets storage, and timestamp format, with a many more link for the rest.

Each of those is a decision with real cost and no obvious default, which is the test the project seems to apply. Timestamp format looks trivial until two teams ship incompatible logs. Secrets storage is a decision with security consequences. Monorepo versus multirepo is the kind of question that resurfaces every eighteen months.

Compare that with what is not in the list. There is no example of choosing between two logging libraries, or picking a JSON schema validator, because those are reversible and nobody needs a record. The selection reads as a deliberate filter on reversibility rather than a demonstration that every code choice deserves paperwork.

They are also written in the same document format as the templates, so an example doubles as a worked demonstration of its template. For a team deciding between Nygard and MADR, reading one real record in each format is more informative than comparing the empty headings.

Five activities: identify, decide, enact, share, document

The how-to-start section breaks the work into named phases, and the naming is what makes it usable as a checklist rather than a philosophy.

Decision identification asks how urgent and how important the decision is, and whether it has to be made now or can wait until more is known. It suggests maintaining a decision todo list that complements the product todo list, which is a small idea with a large effect: most teams have a backlog of things to build and no list of things they have not decided.

Decision making points at the existence of techniques, general and architecture-specific, naming dialogue mapping as one example, and it notes that group decision making is an active research topic rather than a solved one.

Decision enactment and enforcement is the phase teams skip. A decision has to be communicated to and accepted by the stakeholders who fund, develop and operate the system, which means code review and coding style are part of the same problem. The section also notes that decisions have to be reconsidered when a system is modernised.

Decision sharing, marked optional, is about reuse: many decisions recur across projects, so past records, good and bad, are assets. Decision documentation is the last phase, and it is where the template list and the tool list live.

Where ADRs meet git, AI skills and pull requests

The table of contents has grown beyond templates. Alongside the classic sections there are entries for starting with ADRs using tools, starting with ADRs using git, Claude Code skills for ADRs, file name conventions, suggestions for writing good ADRs, teamwork advice and teamwork questions, next step concepts, architecture diagrams and viewpoints, fitness functions for decisions as code, and decision guardrails for pull requests.

The git angle is the one with the clearest mechanism. Storing ADRs in the same repository as the code means records change in the same commit as the decision, get reviewed by the same reviewers, and survive the departure of the person who made the choice. The file name convention section exists because that only works if the numbers are stable and sortable.

The Claude Code skills directory in the repository tree is a newer addition, and it is the part to be careful about. An agent generating a decision record for you will produce a well-formed document that is confidently wrong about your context, and the consequences field is exactly the field it will fill with plausible fiction. Treat generated records as drafts a human has to argue over, which is the same standard you would apply to any code an assistant writes.

Fitness functions for decisions as code is the most interesting idea on that list. The idea is to make the decision enforceable rather than merely recorded, so that a pull request which violates the ADR fails instead of relying on a reviewer to remember.

A documentation site with a version header and a citation file

The repository layout explains how it is built and maintained. There is `README.md`, `CODE_OF_CONDUCT.md`, `LICENSE.md`, `CITATION.cff`, an `icon.svg` and `[email protected]`, then two directories that carry everything: `architecture-decision-record.github.io/` for the published site and `locales/` for the per-language content that both the README and the site draw from. A `skills/` directory holds the agent skills.

The README is not written by hand in one language. It uses include directives that pull text in from `locales/en/documents/`, which is why the same sentence appears on the README and on the website without being maintained twice. That structure is why the translations directory is a first-class part of the project rather than an afterthought.

At the top of the README sits an HTML comment with machine-readable fields: browser, tracker, version 3.2.0, an updated timestamp of 2025-05-29, a contact, and a summary line. The repository language is reported as JavaScript, which reflects the site's tooling rather than any runtime component, and there are no published GitHub releases, so the version in that header is the one to cite. The last push was on 2026-09-18.

One gap to note honestly: the repository metadata reports the licence as unasserted rather than naming one, though a `LICENSE.md` file is present. If you intend to copy templates into a codebase with a licence policy, read that file rather than relying on the repository listing.

Editorial conclusion

Treat this repository as a reference library rather than something to install. Its value is that it lets you compare thirteen real templates side by side instead of guessing at the section headings, and its worked examples such as monorepo versus multirepo and secrets storage show the level of specificity an ADR needs to be worth reading. Pick one template, copy it into a `doc/adr` directory, and write the first record about a decision you actually argued about. If you want tooling that writes and enforces ADRs, this is not it, and the project's own tools section is where to look next.

Frequently asked questions

Official sources

1. architecture-decision-record/architecture-decision-record on GitHub
2. Issues
3. README