Dev
Architecture Decision Record Generator
Six months after a major architectural decision, a new engineer asks why. Without a record, the answer lives only in the heads of whoever was in the meeting. An Architecture Decision Record (ADR) captures the context, the choice, the consequences, and the alternatives in a short document committed alongside the code. One input drives the output: the Decision field — adopt PostgreSQL over MongoDB, use event sourcing for the order service. The generator returns a Markdown ADR with the decision as the title, a Status field defaulting to Proposed, and four sections: Context, Decision, Consequences (positive and negative), and Alternatives considered. Fill the Context section with the real problem and constraints. List consequences honestly — the negatives matter as much as the positives. Commit the file to docs/decisions/ or adr/, named with a sequence number and a short slug.
How to use
- Choose your options above
- Click Generate
- Copy your result
Detailed instructions
- Enter the architecture decision.
- Click Generate to produce the ADR template.
- Fill in the context, consequences, and alternatives.
- Commit the ADR alongside your code.
Use Cases
- •Documenting an important architecture decision
- •Recording why a technology or pattern was chosen
- •Forcing a clear look at trade-offs before committing
- •Preserving reasoning for future teammates
- •Standardising how a team records decisions
Tips
- →Record the why and the trade-offs, not just the decision.
- →List the alternatives you rejected and why.
- →Keep ADRs short — one decision per record.
- →Store them in the repo so reasoning lives with the code.
FAQ
what is an ADR and what does it contain
An Architecture Decision Record is a short document capturing one significant technical decision. The generated template includes a title, a Status field, and four sections: Context (what drove the decision), Decision (the choice), Consequences (positive and negative trade-offs), and Alternatives considered with reasons.
when should I write an ADR
For decisions that are hard to reverse, affect many parts of the system, or will cause future developers to ask "why did we do it this way?" — choosing a database, an architecture pattern, or a major external dependency. Routine implementation choices do not need one.
where should I store the ADR file
In the repository, typically in a docs/decisions/ or adr/ directory, named with a sequence number and a short slug — 0001-adopt-postgresql.md. Keeping it in the repo means it is reviewed alongside the code changes it describes.
why record the consequences and alternatives
The decision alone is rarely the useful part — the context and trade-offs explain why it made sense at the time. Future engineers who ask whether to revisit the choice need to know what problem it solved, what it cost, and what was rejected.
You might also like
Popular tools from other categories that share themes with this one.
Try these next
More free tools from other corners of the catalog, picked by shared themes.