Architecture Decision Record Generator

An Architecture Decision Record (ADR) is a short document that captures an important architectural decision made during a project. It records what was decided, why it was decided (context, forces, options considered), and what the consequences are. ADRs create a decision log that helps future team members understand why the system is built the way it is — not just what was built.

MADR stands for Markdown Architectural Decision Records. It is a lightweight ADR template that uses standard Markdown, making it easy to store alongside code in version control. MADR structures each record with: title, status, context/problem statement, decision drivers, considered options (with pros and cons), the decision outcome, and consequences. It is designed to be readable on GitHub/GitLab and kept in a dedicated docs/decisions/ folder.

Write an ADR when making a decision that: (1) is hard to reverse or expensive to change later, (2) affects multiple teams or system boundaries, (3) involves significant trade-offs between competing options, (4) solves a recurring debate — once written, the ADR closes the debate. Common triggers: choosing a database, selecting a framework, deciding on an API style, defining a caching strategy, or adopting a deployment architecture.

The context section explains the situation that led to this decision. Describe the problem you are solving, the forces at play (performance requirements, team skill set, operational constraints, compliance needs), and any relevant background. Avoid proposing solutions here — just describe the landscape clearly so a reader with no prior context understands why a decision was needed.

Consider at least two options — 'do nothing' (status quo) should almost always be one of them. Three to four options is a practical sweet spot: enough to show you explored the space without becoming an exhaustive research paper. For each option, note the key pros and cons (two to four points each). The goal is to show your reasoning, not to be comprehensive — readers should be able to follow your logic quickly.