adr-writing

An architecture decision record is needed when introducing structural changes like new recurring patterns, runtime dependencies, convention departures, or non-obvious schema choices. It deliberately skips micro-style or file-layout decisions to focus on significant architecture choices.

To format an ADR template, use a short ≤25-line structure containing Context, Decision, Consequences, and Alternatives sections. This ensures architecture decision rationales are captured concisely for future maintainers without excessive documentation overhead.

To avoid numbering conflicts in parallel workstreams, name ADR files using a ticket-id namespaced path format like ADR-TASK-XXX-<slug>.md. This collision-safe naming convention prevents duplicate-number conflicts when multiple developers work concurrently.

To link architecture decision records to source code, include a single representative in-code reference comment and ensure a matching documentation commit message. This allows reviewers to find the rationale alongside the actual code change.

No, this ADR format does not work for documenting micro-style or file-layout decisions. It specifically applies to structural decisions like new dependencies and convention departures, deliberately skipping minor file organization choices.