ADR generator

An architecture decision record (ADR) is a short document that captures one important decision: the situation, the options, what you chose and what it costs. Kept next to your code, ADRs answer the question every new team member asks: why is it built like this?

Fill in the form and the Markdown on the right updates as you type. Copy it into your repository, for example as docs/adr/0007-use-a-modular-monolith.md. Your draft stays in this browser only.

TitleNumber

DateDecision makers

ContextWhat is the situation, and what forces or constraints matter?Options consideredOne per line. Add a short note after a colon, for example “Microservices: too much operational overhead for one team”.DecisionWhat did you choose, and why?

Good consequencesOne per line.Costs and risksOne per line.

Revisit whenWhat would make you change this decision?

Fill in an exampleClear the form

Your ADR in Markdown

Copy MarkdownDownload .md

Tips for good ADRs

• One decision per record. If you’re tempted to write “and”, it’s probably two ADRs.
• Write the context for a stranger. Someone reading it in two years won’t know today’s constraints.
• List the options you rejected, and why. That’s the part people most often need later.
• Be honest about costs. Every real decision has some.
• Never edit an accepted ADR’s decision. Write a new one that supersedes it, and link the two.

The format follows Michael Nygard’s original proposal for decision records (opens in a new tab), with a section for the options considered.