Architecture Decision Records

Overview

Architectural decisions made in hallways, Slack threads, and "let's just go with X" moments vanish. Six months later nobody remembers why PostgreSQL over DynamoDB, why REST over gRPC, why that particular auth pattern. Engineers reverse-engineer intent from code that was never designed to explain itself.

Core principle: EVERY architectural decision gets written down with context, alternatives, and consequences. No exceptions.

If you didn't record it, you didn't decide it. You just happened to do something.

Announce at start: "I'm using the architecture-decision-records skill to document this decision."

Save ADRs to: docs/adr/NNNN-title-in-kebab-case.md

The Iron Law

EVERY ARCHITECTURAL DECISION GETS RECORDED WITH ALTERNATIVES AND RATIONALE