Every software system is made of decisions. Hundreds of them. Thousands, for anything substantial.
Which database? Which authentication approach? Monolith or microservices? REST or GraphQL? How do we handle file uploads? What's our caching strategy? How do we structure the data model?
Most teams make these decisions in Slack threads, standup meetings, or casual conversations. The decision gets made. The code gets written. Six months later, a new engineer joins and asks: "Why is the database structured this way?"
Nobody remembers.
The Institutional Memory Problem
This is the most expensive problem in software engineering that nobody talks about. Institutional knowledge — the why behind the what — lives in people's heads. When those people leave, the knowledge leaves with them.
The code tells you what the system does. It doesn't tell you why it does it that way. And the "why" is what matters when you need to change it.
Without the "why," every modification becomes a guessing game. Is this structure intentional or accidental? Was this approach chosen for performance reasons, or was it just what the developer knew best? Can we safely change this, or will it break something non-obvious?
Engineers facing these questions have two options: guess (risky) or reverse-engineer the context from the code (time-consuming). Both are expensive. Both are avoidable.
What an ADR Actually Looks Like
An Architecture Decision Record is a short document — usually one page — that captures four things:
Context. What situation prompted this decision? What problem are we solving? What constraints exist?
Decision. What did we decide? State it clearly and specifically.
Alternatives considered. What other options were on the table? Why were they rejected? This is the most valuable section, because it prevents future engineers from re-exploring paths that were already evaluated.
Consequences. What are the trade-offs? What does this decision make easier? What does it make harder? What follow-up decisions will this force?
Here's a real example from a multi-tenant platform we built:
ADR-007: Use row-level security for tenant isolation
Context: The product is a multi-tenant property management platform. Each customer's data must be completely isolated from other customers. We need to choose between application-level isolation (filtering in code), schema-level isolation (separate database schemas per tenant), and row-level isolation (shared tables with security policies).
Decision: Use PostgreSQL row-level security (RLS) policies to enforce tenant isolation at the database level.
Alternatives: Application-level filtering is simpler but relies on every query being written correctly — one missed filter exposes cross-tenant data. Schema-per-tenant provides strong isolation but creates operational complexity at scale (migrations must run against every schema).
Consequences: RLS provides defense-in-depth — even if application code has a bug, the database enforces isolation. Trade-off: RLS policies add complexity to database migrations and require careful testing. All queries must include tenant context.
That took fifteen minutes to write. It will save dozens of hours over the life of the project.
Why Most Teams Don't Write ADRs
Three reasons, all fixable.
"We don't have time." An ADR takes 10-15 minutes. The decision itself took hours or days of discussion. Spending fifteen minutes documenting the outcome is not a meaningful time investment — it's a rounding error on the time already spent.
"Everyone on the team already knows." Today they do. Will they in six months? Will the engineer you hire next quarter? Will the team that takes over maintenance? Institutional knowledge decays. Documentation doesn't.
"It feels like bureaucracy." ADRs aren't bureaucracy because they don't require approval, review boards, or sign-off processes. They're a written record of a decision that was already made. The overhead is nearly zero.
How to Start
If your engineering team doesn't write ADRs, here's how to start without it feeling like a mandate:
Step 1: Pick a format. The four-section format above (Context, Decision, Alternatives, Consequences) is simple and sufficient. Don't overthink the template.
Step 2: Start with the next decision. Don't try to retroactively document every past decision. Just start with the next one. "We're choosing between X and Y. Let's write down what we decide and why."
Step 3: Store them with the code. ADRs should live in the repository, in a /docs/adr/ directory. They're version-controlled, searchable, and travel with the codebase. They're not in Confluence, not in Google Docs, not in someone's Notion. In the repo.
Step 4: Number them sequentially. ADR-001-use-postgresql-for-primary-database.md. The numbering creates a chronological record of how the architecture evolved.
Step 5: Never delete them. When a decision is superseded, mark it as superseded and link to the new ADR. The history of why decisions changed is as valuable as the decisions themselves.
What ADRs Signal to Founders
If you're a non-technical founder evaluating engineering partners, ask to see their ADRs from a past project.
A team that writes ADRs is a team that:
- Thinks systematically about architecture
- Considers alternatives before committing
- Cares about the long-term maintainability of the system
- Builds for handoff, not dependency
A team that doesn't write ADRs might still be excellent engineers. But their knowledge will leave when they do.
At Perizer Labs, ADRs are non-negotiable. Every platform we build has a complete ADR history. When a new engineer joins any of these projects, they can read the ADRs and understand not just what the system does, but why it's built the way it is.
That's not documentation for documentation's sake. That's building a system that outlives any individual engineer.
Architecture Decision Records are part of the Blueprint phase in The Perizer Protocol. Download the full book for ADR templates, domain modeling guides, and the complete five-phase framework.