Architecture Decision Records
Templates, examples, and a generator for Markdown ADRs—what ADRs are, Nygard and other shapes, and ready-to-save .md output in the browser.
What is an ADR?
An Architecture Decision Record captures a single, meaningful choice: the context, the decision, and the consequences. It lives in version control, usually as Markdown, so history stays with the code.
ADRs are not specs for the whole system. They answer “What did we decide, and why?” for a point in time—so future you (and the next team) can revisit the reasoning without another architecture review.
Generator preview
Fill in a few fields; the panel updates in real time. The full page adds download and filename hints.
Nygard is the default classic ADR. MADR adds structured sections. Y-Statement is a single sentence. ISO 42010–inspired is for architecture description vocabulary—not a “fourth ADR spec,” but a view/concern–aligned record.
Open the full generator to copy or download the file.
# ADR-0001: Use PostgreSQL for new services
## Status
Proposed
## Context
We need a default relational store for new backend services. MySQL 8 and PostgreSQL 15 are both available on our internal cloud.
## Decision
We adopt PostgreSQL 15+ as the default for new stateful services unless a team documents a different ADR for their bounded context.
## Consequences
Existing MySQL services stay on MySQL until migrated. SRE can standardize backup and HA playbooks on fewer engines.Default (Nygard) template
Drop this in docs/adr/ and adjust. Other shapes (MADR, Y-Statement, ISO 42010–inspired) live in templates and the generator above.
# ADR-0001: <short title in Title Case>
## Status
Proposed
## Context
Describe the situation: constraints, options considered briefly, and why a decision is needed.
## Decision
State the decision in plain language. Link to ADRs that this supersedes or extends.
## Consequences
- Positive: …
- Negative: …
- Neutral / follow-ups: …
Realistic examples
Two end-to-end ADRs you can use as a tone and structure reference.
Where this fits
ADRs sit alongside whatever you already use: pull requests, internal wikis, RFCs, or diagrams. This site only gives you structure and copy-paste Markdown—the rest is your team’s process.