How to Get Started with ADRs

Any team member can create an ADR using templates to ensure all relevant information is captured.

ADRs capture a set of forces and the single decision that responds to them. The decision is central, meaning specific forces may appear in many ADRs. Keep these documents in a project repository with a simple structure e.g. doc/arch/adr-NNN.md, using a lightweight text formatting language like Markdown or Textile. Each ADR is numbered and has a short noun phrase title.

The Context section of each ADR describes the forces at play, including technological, political, social, and project local.

The Decision section outlines the response to these forces, which may be marked as “proposed” or “accepted.” If a later ADR changes or reverses a decision, it may be marked as “deprecated” or “superseded” on its replacement. The Consequences section describes the resulting context after applying the decision, including all positive, negative, or neutral consequences. We aim to keep each ADR to one or two pages, with complete sentences organized into paragraphs. Bullets are acceptable only for visual style, not to excuse sentence fragments. Each ADR should describe one significant decision for a specific project that will affect how the rest of the project runs.

The consequences of each ADR will likely become the context for the next ADRs.

During a team meeting, the ADR is either accepted, requested for rework, or rejected. Otherwise, the ADR status changes to “accepted” or “rejected,” and it becomes immutable. Suppose the team needs to update the decision. In that case, they propose a new ADR which supersedes the previous one

A new team member coming to a project must understand the motivation behind certain decisions. If the decision is still valid, they must understand the rationale or consequences of having two choices.