architecture-decision-records

Structure the ADR with a decision-focused title, a status (Proposed, Approved, Replaced, Deprecated), the relevant context and constraints, the decision in direct language, consequences split into benefits, costs, and accepted risks, and references to related PRDs, HLDs, and prior ADRs.

Create an ADR when a change affects the approved stack, module boundaries, multi-tenancy or persistence strategy, cross-cutting patterns like queues or auditing, or deployment and runtime operations. Skip ADRs for local refactors, renames, or isolated test adjustments without structural impact.

Review the repository's AGENTS.md, the current PRD for the system or module, the module's HLD if it exists, previously approved related ADRs, the approved technology stack document, and any active plan or report driving the decision.

Avoid generic ADRs disconnected from the actual project stack, inflated context with irrelevant history, ambiguous decisions that never state what is adopted, and documenting technologies outside the approved baseline without escalation or approval.

An ADR can document a stack exception, but it must explicitly justify the deviation against the baseline constraints and require escalation or approval. Introducing tools like MongoDB or microservices by default contradicts the current baseline and should not be assumed.