adr

Architectural decision records capture context, alternatives, trade-offs, and rationale to preserve institutional memory. You create structured ADR files with Context, Decision, and Consequences sections to document technology choices and service boundaries.

An architectural decision record is a structured, traceable document capturing context, alternatives, and consequences for critical architecture choices. You need ADRs for technology choices, service boundaries, and deployment patterns to prevent decisions from drifting over time.

Create an ADR file in docs/adr/ with a clear title like 0001-use-architecture.md. Include Context, Decision, and Consequences sections, then reference it in relevant pull requests to link the architectural decision record to implementation artifacts.

You can track architectural decision lifecycles using statuses like proposed, accepted, superseded, or deprecated. This creates living documentation that evolves with the project as new architectural decisions supersede previous ones.

When documenting alternatives and trade-offs in an ADR, include the alternatives considered, associated risks, mitigations, and the rationale for the final decision. This ensures the consequences and constraints are fully traceable.