MADR: a Markdown template for architectural decision records, not a tool

The problem MADR solves is the shape of a decision record

Teams write architecture decisions in chat threads, wiki pages and pull request comments, and the result is a record that nobody can compare with the next one. MADR attacks that by fixing a section layout. The repository is named Markdown Architectural Decision Records, and the README points users to the published documentation at adr.github.io/madr rather than explaining the format inline. The templates themselves live in template/, and package.json lists only "template/" under files, so the npm package exists to ship the templates and nothing else.

That narrow scope is the point. MADR is for engineers and architects who already keep design documents next to code and want a decision record that reads the same way every time. It is not for someone looking for a service that stores, links or queries decisions. The topics on the repository (architectural-decision-records, design-documents, documentation) describe a documentation convention, not a runtime.

Four template variants and what each one commits you to

The README lists four files in template/ and describes them precisely. adr-template.md has all sections with explanations about them. adr-template-minimal.md contains only the mandatory sections, again with explanations. adr-template-bare.md has all sections but empty, with no explanations, and adr-template-bare-minimal.md has the mandatory sections without explanations. In other words, the choice is two-dimensional: full versus minimal section set, and annotated versus bare.

The annotated versions are teaching material. They tell a first-time author what belongs in each field, which is why they suit a team introducing the practice. The bare versions are for people who already know the format and do not want comment scaffolding in every file. A minimal template drops everything the project marks optional, so if your organisation requires, for example, a status field on every record, you are editing the template rather than using it as shipped. The README notes in an HTML comment that the Consequences section is contained in the minimal templates even though it is marked as optional, which is a small inconsistency worth knowing before you trim sections.

The four-way split is a reasonable design. It does mean four files to keep in sync when your local conventions drift, and the release checklist in the README shows the maintainers feel that cost: releasing a version involves updating examples, updating concrete decisions under docs/decisions, adapting the template files there, and copying .markdownlint.yml into template/.

Installing MADR and writing your first decision record

There is no CLI. The README's quick start is a file copy: take a template, put it in docs/decisions, and for each decision copy the template to a file named nnnn-title.md and adapt it. The package is published to npm under the name madr, so if you prefer pulling the templates through a package manager rather than copying from the repository, that is the route.

npm install madr

After that, the templates are available under the package's template directory, and you copy the variant you chose into your own docs tree.

mkdir -p docs/decisions
cp node_modules/madr/template/adr-template-minimal.md docs/decisions/0001-use-madr.md

Open the copied file and fill in the sections. The naming convention is the part that carries the ordering: the README specifies nnnn-title.md, so a four-digit sequence number followed by a short title. Keep the numbers monotonic and never reuse one, because the filename is the only index MADR gives you.

If you want to see the format rendered rather than read raw Markdown, the homepage is built from the docs directory with Jekyll. The README gives the local commands for that, and they need Ruby and Bundler first.

bundle install
jekyll serve --livereload

The README says the site is then reachable at http://localhost:4000/madr/. On Windows the README recommends the dockerized alternative instead:

docker run -p 4000:4000 --rm -v "C:\git-repositories\adr.github.io\madr\docs":/site bretfisher/jekyll-serve

That Jekyll path is for previewing the MADR project's own documentation, not a requirement for using the templates in your repository.

What MADR does not do: no index, no supersession, no CLI

The most common wrong expectation is that MADR will manage decisions for you. It will not. Nothing in the README or package.json describes a command that creates a record, lists existing ones, or marks an old record as superseded. The npm package ships template/ and nothing else. If you need a decision log with statuses and links between records, you are assembling that yourself, either by hand or with a separate tool.

There is a second limitation that follows from the first. Because the filename is the only ordering mechanism and the README does not document a rollback or amendment procedure, changing a decision means either editing the record in place, which loses the history, or writing a new numbered record and relying on prose to point at the old one. Teams that need an auditable chain of revisions should decide their own convention before the first record, because retrofitting one across fifty files is unpleasant.

MADR is also the wrong tool if your decisions live outside version control. The whole workflow assumes files in a repository, reviewed like code. If your organisation's decisions are approved in a ticketing system and never committed, copying Markdown templates adds a second place to look and no single source of truth.

MADR against the Nygard template and ADR tooling

The obvious comparison is Michael Nygard's original ADR format, which is the ancestor of most of this space. Nygard's template is deliberately short: a title, a status, a context, a decision and consequences. MADR keeps that skeleton and expands it, splitting context into the problem and the considered options, and adding fields for decision drivers, considered options and pros and cons of each option, plus links. The practical difference is that a Nygard record documents the choice, while a MADR record documents the deliberation that produced it. That is more useful in review and more work to write.

Tooling is a separate axis, and mixing the two is where teams get confused. MADR is a format, so it composes with whatever generator or linter you already run over Markdown. The repository itself uses markdownlint and ships .markdownlint.yml, and the README recommends the markdownlint extension for VS Code, which means the maintainers treat linting as part of the workflow rather than an add-on. If you want a tool that scaffolds and indexes records, that is a different project, and MADR can be the template such a tool emits.

Licence, releases and the real maintenance cost

The README states the work is dual-licensed under MIT and CC0, and you may choose either. package.json carries the SPDX expression MIT OR CC0-1.0, and the repository holds separate LICENSE, LICENSE.MIT and LICENSE.CC0-1.0 files. CC0 is a public domain dedication, so if you want no attribution obligation at all, that option exists. This is a description of what the files say, not legal advice; if your organisation has a policy on public domain dedications, run it past whoever handles that.

Upgrade cost is low but not zero, and it is mostly editorial. The release process described in the README includes updating the examples, updating the concrete decisions under docs/decisions to the new template, and copying the lint configuration into template/. For a consumer, a new MADR release can mean re-aligning your local template against the upstream one, which is a diff and a decision about whether the new fields are worth adopting. Version 4.0.0 was released on 2024-09-17, following 4.0.0-beta on 2024-09-02 and 3.0.0 on 2022-10-09, so major versions arrive years apart. The repository follows Semantic Versioning and keeps a CHANGELOG.md in the keep a changelog format, so you can read what changed before deciding. The last push to the repository was on 2026-08-28.

Editorial conclusion

Adopt MADR if your team already stores documentation in Git and wants a fixed section structure for decisions, and skip it if you need a CLI, an index, or supersession tracking, since the repository ships templates and a homepage, not a tool. Before committing, check the four template variants in template/ against your review process, confirm the dual MIT OR CC0-1.0 licence suits your redistribution, and decide whether the optional Consequences section should be mandatory for your team. The last push to the develop branch was on 2026-08-28, and the newest release is 4.0.0 from 2024-09-17.

Frequently asked questions

Official sources

1. adr/madr on GitHub
2. Issues
3. Project website
4. README
5. Releases