AI Architecture Decision Record Generator

An ADR is a short document that captures a significant architectural decision along with its context, rationale, and consequences. ADRs create an immutable log of why decisions were made, preventing the common problem where teams revisit settled decisions because no one remembers the original reasoning. They are typically stored alongside the code in an adr/ directory.

We support the Michael Nygard format with Status, Context, Decision, and Consequences sections. The MADR format adds Considered Options with detailed pros and cons for each. Y-Statements provide a compact single-sentence decision format. The Lightweight format is a minimal template for smaller decisions. Each format follows its respective community convention.

Create an ADR for decisions that are hard to reverse, affect multiple team members, involve trade-offs between competing concerns, or will be questioned by future developers. Examples include choosing a database, selecting an authentication approach, deciding on an API versioning strategy, or picking a deployment architecture. If you considered alternatives, it is worth recording.

Each alternative should include a brief description, its key advantages, its main drawbacks, and why it was ultimately not chosen. This prevents future team members from re-proposing the same alternatives and shows that the decision was made thoughtfully. Include quantitative comparisons like benchmark results or cost estimates when available.

ADRs are immutable — you never edit a past ADR. Instead, create a new ADR that supersedes the old one, referencing it and explaining what changed in the context that requires a new decision. The old ADR's status changes to Superseded with a link to the replacement. This preserves the full history of your architecture's evolution.