Design documentation

NNNN. Short title of the decision

Context

The forces at play: the problem, the constraints, and what makes this a genuine decision rather than an obvious one. State the situation neutrally — what is true regardless of the choice. Reference related decisions by number (e.g. ADR-0015) in prose, not as links.

Decision

The decision, in active voice — "We will …". Be specific about what is chosen and what is rejected. Use RFC-2119 keywords (MUST / SHOULD / MAY) only when this records a normative requirement an implementation must honour.

Consequences

What becomes easier and what becomes harder as a result. The trade-offs accepted, the follow-on work created, and what this commits the project to or forecloses — including the cost of reversing it later.