Architecture Decision Records: Document Every 'Why' in the Codebase

A new engineer joined a TaaS squad three months into a healthcare platform build. The authentication module was the first thing she needed to extend — adding multi-factor authentication to an existing session management layer. The code was clean. Well-tested. Competently structured. And completely opaque about why it was built the way it was.

The session tokens used a non-standard rotation pattern instead of the more common sliding expiration approach. The OAuth integration bypassed the framework's built-in provider in favour of a custom implementation. The password hashing used a configuration that was deliberately more aggressive than the library's defaults, adding latency to every login request. Each of these choices looked intentional. None of them were documented. The original architect had left the engagement two months earlier.

The new engineer spent three weeks piecing together the reasoning. She dug through pull request comments, searched Slack archives, re-read compliance documents, and eventually scheduled calls with two engineers who'd overlapped with the original architect. The session rotation pattern existed because the compliance team had flagged a specific attack vector during a Production Readiness Review™. The custom OAuth implementation worked around a framework bug that had since been patched. The aggressive hashing configuration met a specific requirement from the client's security audit. Every decision was sound. Every decision was invisible.

Three weeks of an experienced engineer's time, on a staff augmentation engagement billed by the day, spent reconstructing knowledge that should have taken ten minutes to read. That's the cost of not having architecture decision records. Not the theoretical cost — the real, invoiced, relationship-straining cost of architectural knowledge that lives in people's heads instead of in the codebase.

Why Architecture Knowledge Disappears

Architecture decisions are the most valuable and most perishable knowledge in any codebase. Code tells you what the system does. Tests tell you what it should do. Architecture decision records — ADRs — tell you why it was built this way and not some other way. Without them, the reasoning behind every structural choice evaporates the moment the person who made it moves on.

This isn't a documentation problem in the traditional sense. Most teams have documentation. They have README files, wiki pages, Confluence spaces, architecture diagrams. What they almost never have is a record of the decision process: what alternatives were considered, what trade-offs were evaluated, what constraints drove the final choice, and what conditions would make it worth revisiting. That's what an ADR captures, and it's what makes the difference between documentation that exists and documentation that's actually useful when someone needs to understand or change the system.

The problem compounds in augmented teams. When a software development squad includes engineers who rotate in and out of engagements — which is the operational reality of staff augmentation — every transition is a potential knowledge loss event. The senior engineer who chose the event-driven architecture over request-response finishes their engagement. The architect who selected the specific database sharding strategy moves to another project. The tech lead who decided against microservices in favour of a modular monolith takes a new role. Each departure removes not just capability but context. ADRs are the mechanism that keeps the context in the codebase when the people leave.

What an ADR Actually Contains

An architecture decision record is a short document — typically one to two pages — that captures a single architectural decision. The format matters less than the content, but the most widely adopted structure follows a consistent pattern.

Title and date. A short, descriptive title that identifies the decision. "Use event sourcing for order management" is useful. "Architecture decision" is not. The date establishes when the decision was made, which matters when evaluating whether the constraints that drove it still apply.

Status. Whether the decision is proposed, accepted, deprecated, or superseded. This is critical for living codebases. An ADR with status "superseded by ADR-047" tells the reader that the reasoning is historically accurate but no longer current — and points them to the replacement decision. Without status tracking, engineers waste time understanding decisions that have already been reversed.

Context. The circumstances that prompted the decision. What problem needed solving? What constraints existed? What requirements — functional, non-functional, regulatory, contractual — shaped the options? Context is where the real value lives. Two years from now, when a new engineer asks "why didn't they just use the framework's built-in caching?", the context section answers: because the framework's caching couldn't handle the multi-tenancy isolation requirements the client's compliance team mandated.

Decision. The choice that was made, stated plainly. "We will use Redis Cluster for session storage with per-tenant key namespacing." One to three sentences. No ambiguity.

Alternatives considered. What other options were evaluated and why they were rejected. This section prevents the most common waste pattern in engineering: a new team member seeing the current approach, believing they've found a better one, investing time building a proof of concept, and then discovering the same constraints that ruled it out originally. The alternatives section short-circuits that cycle. It says: we considered that approach, here's why we didn't take it.

Consequences. What follows from the decision — both positive and negative. Every architectural choice creates trade-offs. Acknowledging them explicitly means the team knows what to watch for. "This approach increases write latency by approximately 15ms per transaction but eliminates the cross-tenant data leakage risk identified in the security audit." Future engineers who see the latency won't try to optimise it away without understanding what it protects.

How to Implement ADRs in Practice

The gap between knowing ADRs are valuable and actually writing them is where most teams fail. The implementation needs to be lightweight enough that engineers will do it and structured enough that the records are useful six months later.

Store ADRs in the repository. Not in Confluence. Not in a wiki. Not in a shared drive. In the code repository, in a dedicated directory — typically docs/adr/ or docs/decisions/. This is non-negotiable for one practical reason: ADRs that live outside the repository become orphaned. They don't travel with the code when it's forked, branched, or transferred. They aren't visible during code review. They aren't versioned alongside the code they describe. Keeping ADRs in the repo means they're subject to the same review process as the code itself, which is exactly what you want. The project delivery framework already defines review checkpoints — ADRs slot into those existing gates without adding ceremony.

Number them sequentially. 0001-use-event-sourcing-for-orders.md, 0002-redis-cluster-for-sessions.md. Sequential numbering creates a chronological record of architectural evolution. When you read ADR-0023 and it references constraints from ADR-0008, you can trace the decision lineage. This matters because architectural decisions are rarely independent — they build on, constrain, and sometimes contradict each other, and the sequence makes those relationships visible.

Write them during the decision, not after. The most common failure mode is treating ADRs as retrospective documentation — something you write after the architecture is built. By then, the reasoning is already fading. The alternatives you considered are blurring together. The constraints feel obvious in hindsight. Write the ADR when the decision is being made, as part of the decision process. Use the act of writing to sharpen the thinking. If you can't articulate the context and alternatives clearly, the decision isn't ready to be made.

Make them a pull request requirement. Any pull request that introduces a significant architectural change should include an ADR or reference an existing one. "Significant" doesn't mean "large" — a small change to the authentication flow that reflects a deliberate architectural choice is significant. A large refactoring that moves files around without changing the architecture isn't. The trigger is whether someone looking at this change six months from now would ask "why was it done this way?" If yes, write an ADR.

Keep them short. A good ADR is one to two pages. If it's longer, you're either documenting multiple decisions (split it) or including implementation detail that belongs in code comments or technical specifications. The ADR captures the decision and its reasoning — not the implementation plan, not the detailed design, not the migration steps. Brevity encourages writing. Nobody procrastinates on a one-page document.

The Squad That Built a Decision Trail

A TaaS squad was eighteen months into a fintech platform build when the client's CTO raised a concern during a quarterly review. The platform had grown to fourteen microservices, and new engineers — both on the client side and within the augmented squad — were taking weeks to become productive. The CTO's question was pointed: "Why do we have fourteen services? Why not ten, or three, or one?" Nobody in the room could answer with confidence. The architect who'd made the initial decomposition decisions had rotated off the engagement a year earlier.

The squad lead proposed introducing ADRs — not retroactively documenting every past decision, but starting from that point forward and backfilling the critical ones. Over four weeks, the squad produced twenty-three ADRs. Twelve were retrospective, capturing the reasoning behind the most-questioned architectural choices: why the service boundaries were drawn where they were, why certain services used synchronous communication while others used event-driven patterns, why the authentication service was separate from the user service despite the apparent overlap.

The remaining eleven captured decisions made during that same month — including two decisions to consolidate services where the original reasoning no longer applied. The ADR process itself surfaced those opportunities: when the squad tried to write the context and rationale for keeping two services separate, they discovered the original constraint (a regulatory requirement that had since been relaxed) no longer justified the operational overhead.

Within two months, onboarding time for new engineers dropped measurably. New squad members could read the ADR directory chronologically and understand not just the current architecture but how it evolved — which decisions were foundational, which were tactical responses to specific constraints, and which had been superseded. The concept-to-launch pipeline became traceable, and the answer to "why is it built this way?" stopped being "ask someone who was there" and started being "read ADR-0007."

When ADRs Matter Most

ADRs deliver value in any codebase, but certain conditions make them critical rather than merely useful.

Staff augmentation engagements. When engineers rotate through a codebase — joining for six months, twelve months, then moving on — architectural knowledge has a half-life measured in employment tenure. ADRs convert that knowledge from volatile (stored in people) to durable (stored in the repository). For any team considering augmented engineering resources, ADRs should be a delivery standard, not an optional practice.

Regulated industries. Healthcare, finance, government. When an auditor asks why patient data is stored in a specific geographic region, or why payment processing follows a particular flow, the answer needs to be documented and traceable. ADRs provide exactly the audit trail regulators expect — dated, authored, reviewed, and versioned.

Long-lived products. If the product will be maintained for years, the team that built it will not be the team that maintains it. Every year that passes without ADRs increases the cost of the next architectural change, because each change requires re-discovering the reasoning behind the current state. The compounding effect is real: a codebase with three years of undocumented decisions is not three times harder to modify than one with one year. It's dramatically harder, because the decisions interact and the missing context multiplies.

Multi-team codebases. When multiple squads contribute to the same platform, ADRs prevent redundant investigation and conflicting architectural choices. Squad A's decision to use a specific caching strategy affects Squad B's options for data consistency. Without ADRs, Squad B discovers this through a production incident. With ADRs, Squad B reads ADR-0015 and designs accordingly. This is especially relevant as development practices evolve and codebases become more distributed across teams and services.

What to Do Next

Open your repository and create a docs/adr/ directory. Write one ADR today — pick the architectural decision that new engineers ask about most frequently. Use the structure outlined above: title, status, context, decision, alternatives considered, consequences. Keep it under two pages. Put it in a pull request and have it reviewed like code.

Then make it a habit. Every architectural decision gets an ADR. Every pull request that changes the architecture references one. Every new squad member reads the ADR directory in their first week. The answer to "why is it built this way?" should be in the codebase, not in someone's memory. That principle, applied consistently across our delivery engagements with 1400+ businesses — and backed by ISO 9001 and ISO 27001 processes — is what separates architecture that survives team transitions from architecture that has to be re-discovered every time someone new arrives.

Frequently Asked Questions