Keep a Decision Log That Prevents Repeated Arguments

A decision log (a.k.a. ADR — Architecture Decision Record) is a dated, immutable list of "what we decided and why." Keep one file per project, e.g. docs/decisions.md. WHICH DECISIONS BELONG IN IT - Anything that was debated, had alternatives, and will cost money to reverse: architecture, tech stack, libraries, data model, API contracts, process rules, security choices. - Exclude trivial calls (naming a variable) and one-off fixes. - Rule of thumb: if someone could reasonably ask "why did we do this?" six months from now, it belongs in the log. COMPACT TEMPLATE (one entry) --- Date: YYYY-MM-DD Decision: <one sentence, imperative> Context: <the problem/constraint that forced the choice> Options: <alternatives considered, one line each> Chosen: <why this one won> Status: Accepted | Superseded by #N --- FILLED EXAMPLE --- Date: 2026-08-26 Decision: Use PostgreSQL as the primary datastore. Context: Need ACID transactions, JSON querying, and managed hosting; team knows SQL. Options: - MongoDB: flexible schema, but no strong transactions and team unfamiliar. - DynamoDB: cheap and scalable, but weak joins and vendor lock-in. - PostgreSQL: ACID, JSONB covers semi-structured needs, team expertise exists. Chosen: PostgreSQL — meets all three constraints with lowest migration risk. Status: Accepted --- HOW IT PREVENTS REOPENING SETTLED QUESTIONS - The "Chosen" line preserves the original reasoning, so a newcomer asking "why Postgres?" gets the answer instantly instead of re-litigating it in a meeting. - A decision is only reopened by explicit act: write a new entry and mark the old one "Superseded by #N." That forces the challenger to show what changed (new requirement, new data), not just restate a preference. - It creates social friction against churn: reopening a logged decision looks like wasting the team's time unless the challenger brings new evidence. - It stops "we never decided anything" amnesia. Without a log, every team member carries a private version of history and argues from it; with a log there is one shared, dated record everyone treats as the baseline. - Review cadence (e.g. "decisions stand unless superseded at a quarterly review") gives a safe, scheduled outlet for real changes, so urgent-feeling objections don get a venue without derailing the current work. Practical tips: keep entries short (the template's ~5 lines), never edit a past entry (append "Superseded by #N" instead — edits destroy the audit trail), and require a decision log entry as part of any design review or PR that changes architecture.