architecture-decision-records

Document architectural decisions by creating structured Architecture Decision Records that capture context, alternatives, rationale, and consequences. This approach preserves the reasoning behind significant engineering choices so future work does not depend on scattered chat logs or memory.

An Architecture Decision Record is a structured document that captures the context, decision, alternatives, and consequences of a significant technical choice. You should write one during planning discussions for technology selection, API design, data modeling, or infrastructure choices.

Maintain an architecture decision log by reading existing ADR indexes, numbering new records sequentially, and preserving the full decision history alongside your codebase without writing files until the proposed decision is explicitly approved.

Yes, you can use Architecture Decision Records to document technology selection choices like choosing PostgreSQL over MongoDB. The ADR captures the durable rationale, trade-offs, and rejected alternatives so the team understands why a specific framework was chosen.

Architecture Decision Records apply directly to API design, data modeling, infrastructure choices, and other significant codebase trade-offs. They turn significant choices into structured documents with context, decision, alternatives, and consequences.

Relying on PR comments or chat logs for architectural rationale limits future teams because context fades over time. Structured ADRs solve this by preserving the decision history and reasoning durably alongside the codebase.