Architecture Decision-Making

The bar for writing an ADR

Most decisions, even ones that feel architectural in the moment, don't need a written record on solo/small-team work. Write one only when the decision is hard to reverse and high blast-radius — the kind of thing that, gotten wrong, costs a real rewrite or migration to fix:

• Database/storage engine choice
• Auth strategy (session vs JWT vs third-party provider)
• A framework or major library swap
• A boundary decision that's expensive to walk back (e.g. committing to a monorepo vs polyrepo, picking a deployment model)