architecture-decision-records

To document architecture decisions so the rationale stays accessible, capture architectural choices in structured Architecture Decision Records (ADRs) that log context, alternatives considered, and why specific options were rejected for future traceability.

You should create an architecture decision record during coding sessions and planning discussions when the team compares alternatives for frameworks, libraries, patterns, data models, security approaches, or infrastructure choices and agrees on a meaningful trade-off.

To track the status of architecture decision records as requirements change, manage the ADR lifecycle through proposed, accepted, deprecated, and superseded states while updating the ADR index for discoverability.

The best way to structure architectural rationale for technical onboarding is to format decisions into numbered ADR documents with explicit Context and Decision sections, then maintain a navigable ADR index under the docs directory.

Yes, you can retrieve the rationale for a past framework or infrastructure choice by reading existing ADRs on demand, which presents the relevant Context and Decision sections to answer why a specific choice was made without manual searching.

No, you do not need to manually initialize a directory before recording your first ADR, as the system can detect decision moments and optionally initialize the docs/adr directory with your consent during the workflow.