Architecture Decision Records: The One-Page Habit That Stops Your Team Relitigating Old Technical Decisions

Every engineering team has lived this moment: a new senior engineer joins, opens the codebase, and asks, "Why on earth did we build it this way?" Nobody remembers. The person who made the call left eighteen months ago, the Slack thread was archived, and the pull request description says "refactor." So the team either reverses a decision that had a good reason, or defends one that no longer has any. At AEGONTECH LLC, we have seen this pattern across dozens of client codebases, and the fix is one of the cheapest practices in software engineering: the Architecture Decision Record.

Key Takeaways

• An Architecture Decision Record (ADR) is a short, dated document that captures one significant technical decision, the context behind it, and its consequences.
• ADRs cut onboarding time and stop teams from relitigating settled decisions every quarter.
• The best ADRs are a page long, live in the repository next to the code, and are reviewed like any other change.
• Record decisions that are costly to reverse, not every library choice.
• A decision log is also the clearest evidence of engineering maturity when you evaluate or hand over to a software partner.

What Is an Architecture Decision Record and Why Does It Matter?

An Architecture Decision Record is a lightweight document, typically one page of Markdown, that records a single architecturally significant decision: what was decided, why, which alternatives were rejected, and what trade-offs the team accepted. The format was popularized by Michael Nygard in 2011 and is now used by teams at companies of every size, and cloud providers such as AWS and Azure publish guidance recommending it.

It matters because code records what a system does, never why it does it that way. Stripe's Developer Coefficient report estimated that developers spend roughly 17 hours a week on maintenance and bad code, including deciphering existing systems. A meaningful slice of that time is archaeology: reconstructing reasoning that was obvious to someone once and is now lost.

Code tells you how a system works. Only a written decision tells you why it was allowed to work that way.

What Should an ADR Actually Contain?

A useful ADR has five short parts, and it should fit on one screen or two. The structure below is the one we use at AEGONTECH, adapted from the original Nygard template:

1. Title and status. A numbered, verb-led title ("ADR-014: Use PostgreSQL row-level security for tenant isolation") plus a status: proposed, accepted, deprecated, or superseded by another ADR.
2. Context. The forces at play: the business goal, the constraints (budget, team skills, compliance such as SOC 2), and the facts known on the day of the decision.
3. Decision. One or two sentences in active voice: "We will use..."
4. Alternatives considered. The options you rejected and the specific reason each lost. This section is the most valuable one, because it prevents the same debate from restarting.
5. Consequences. The good, the bad, and the follow-up work. An honest ADR names the downside you are accepting.

Notice what is missing: long diagrams, exhaustive research, and approval committees. If writing an ADR takes more than an hour, the template is too heavy or the decision is not yet ready to be made.

Which Decisions Deserve an ADR?

Write an ADR when a decision is expensive to reverse, affects more than one team, or will be questioned later. As a rule of thumb, if undoing the choice would cost more than two engineer-weeks, it belongs in the log.

Good candidates include:

• Choosing a primary datastore, for example PostgreSQL vs MongoDB for a given workload.
• Adopting or rejecting microservices vs a modular monolith.
• Selecting an authentication provider or an event bus.
• Deciding on a deployment model, such as serverless vs containers on Kubernetes.
• Setting a data retention or privacy policy that shapes the schema.

Poor candidates include formatting rules, minor library upgrades, and anything a linter can enforce. An ADR log of 400 entries is as useless as no log at all. In our experience, a healthy product produces roughly one to three ADRs per month, and the count rises sharply around major migrations.

Where Should ADRs Live?

ADRs belong in the same repository as the code, in a folder such as docs/adr, versioned with Git. This is the single most important logistical choice, and it is where many teams go wrong by parking decisions in a wiki.

Wikis drift. They have no review process, no history tied to the code, and nobody gets a notification when a page goes stale. A Markdown file in the repository, by contrast, is proposed through a pull request, reviewed by the people affected, merged with a timestamp, and found by anyone who clones the project. Tools such as adr-tools or Log4brains can generate an index, but plain numbered files work perfectly well.

How Do You Keep ADRs From Becoming Bureaucracy?

Keep them short, keep them immutable, and keep them honest. The two most common failure modes are the ADR that nobody writes because the process feels heavy, and the ADR that nobody reads because it reads like a legal memo.

Three habits prevent both outcomes:

• Treat ADRs as append-only. Never edit an accepted decision. When circumstances change, write a new ADR that supersedes the old one and link the two. The history of changed minds is itself valuable information.
• Write the ADR before or during implementation, not after. A retroactive ADR written months later is fiction. A draft written while the debate is live captures the real alternatives.
• Make the pull request the discussion forum. Comments on the ADR pull request become the record of dissent, and a decision that survived a challenge is more durable than one that was never questioned.

A practical rule we apply at AEGONTECH: a pull request that introduces a new infrastructure dependency without an ADR link does not merge. It takes thirty seconds to check and removes an entire category of "why do we have this" questions later.

Are ADRs Worth It for Small Teams and Startups?

Yes, and arguably more so, because small teams have the highest turnover of context. A five-person startup that loses one engineer loses 20 percent of its institutional memory overnight. Founders also face a second audience: investors and acquirers. During technical due diligence, a decision log shows that architecture was chosen deliberately rather than by accident, which reduces perceived risk and shortens review cycles.

The same logic applies to outsourcing. When AEGONTECH builds products for clients, and for our own platforms such as Dolfy.ai, Dialable.world, Maximus IPTV Player, and Mimicall.app, the ADR log is part of the handover. A client who inherits a codebase with forty clear decision records can switch vendors or hire in-house with confidence; one who inherits code without them is effectively locked in by ignorance. That is the difference between a partner and a dependency.

A team that cannot explain its past decisions is condemned to either repeat them or reverse them blindly.

What Does a Good ADR Look Like in Practice?

Consider a short example. A team building a multi-tenant SaaS product must decide how to isolate customer data.

ADR-007: Isolate tenants with PostgreSQL row-level security. Status: accepted.

Context: We expect 200 tenants in year one, a three-person platform team, and a SOC 2 audit in nine months. Separate databases per tenant would raise infrastructure cost by an estimated 4x and complicate migrations.

Decision: We will use a shared schema with a tenant_id column enforced by PostgreSQL row-level security policies.

Alternatives: Database-per-tenant (rejected: cost and migration overhead). Application-level filtering only (rejected: one missed WHERE clause leaks data).

Consequences: Lower cost and simple migrations. We accept noisy-neighbor risk and must add per-tenant query monitoring. Revisit if any single tenant exceeds 25 percent of total load.

That is under 150 words, and it answers the question two years later in seconds. It also contains a trigger for revisiting the decision, which turns the ADR into a living safeguard rather than a historical artifact.

Frequently Asked Questions

How long should an ADR be?

One page is the target, and two pages is the ceiling. If the document needs more, the extra material is research and should be linked rather than embedded.

Who is allowed to approve an ADR?

The people who will live with the consequences. For most teams that means a tech lead plus one reviewer from each affected team. Avoid a central architecture board for routine decisions, because it turns a one-day decision into a three-week queue.

What if we already have years of undocumented decisions?

Do not try to document the past in bulk. Start recording new decisions today, and write a retroactive ADR only when someone asks "why" about an existing choice. Within six months you will have covered the decisions that actually matter.

Do ADRs replace architecture diagrams or design docs?

No. A design doc explores how to build something, a diagram shows structure, and an ADR records the choice and its reasoning. They complement each other, and the ADR is usually the only one that stays accurate, because it never claims to describe the present.

Conclusion: Write the Decision Down While You Still Remember Why

Architecture Decision Records are not about process for its own sake. They are a small, cheap investment that turns tribal knowledge into a durable asset, speeds up onboarding, calms recurring debates, and gives every future engineer, in-house or external, a map of how the system got here. The best time to start is with the next significant decision your team makes.

If you are weighing an architecture choice, inheriting a codebase, or evaluating a development partner, AEGONTECH LLC can help you make the decision and document it properly. Visit AEGONTECH LLC to book a consultation.