Architectural Decision Records Adoption in Growing Engineering Teams

Somebody asks why the catalog service runs on one database instead of another, and the honest answer is that nobody currently on the team knows. The engineer who made the call, now long gone from the company, left the company fourteen months ago, and the decision now survives only as folklore: a half-remembered Slack thread, a diagram in a deck nobody can locate, a strong opinion held by someone who wasn't even in the room when it happened. This scenario repeats across nearly every growing engineering organization, and it is not a sign of a careless team. Most engineering teams make a large number of architecture decisions over their lifetime and write down only a small fraction of them, leaving the rest distributed across scrollback, memory, and orphaned slide decks.

The pattern is structural. Decisions get made in the moment, under deadline pressure, in whatever channel the work is already happening in, and documentation competes with the next ticket for attention it rarely wins. AWS Prescriptive Guidance on architectural decision records identifies three anti-patterns that account for most of this loss: a decision never gets made at all because someone is afraid to commit to it; a decision gets made with no justification attached, so nobody downstream understands the reasoning; or a decision gets made and justified in conversation but never captured anywhere another engineer could later find it. Researchers call the long-run result of this pattern "architectural amnesia," a systematic erosion of the decisions, constraints, and team history that once made the engineering work coherent. It is the condition every growing team is already living in, whether or not anyone has named it yet.

What an ADR is

An architectural decision record is a short, dated document that captures exactly one architecturally significant decision: the context that made the decision necessary, the options that were weighed, the choice that was made, and the consequences that followed from it. It is not a design spec, a wiki page of general engineering guidance, or a retrospective summary written months after the fact for posterity. An ADR exists to answer one question precisely: why does this system look the way it does, and what did the team know when it decided that.

The defining property of an ADR is that it is immutable once accepted. The substance of a decision record does not get edited after the fact to reflect new information or a change of heart. When circumstances change enough to warrant a different choice, the team writes a new ADR that explicitly supersedes the original, and the resulting chain of supersessions becomes the architectural history of the system in a form anyone can trace. A Status field carries much of the practical weight of this system: Proposed, Accepted, Superseded by ADR-NNNN, Deprecated. An engineer scanning a directory of ADRs can tell at a glance which decisions still govern the system and which ones have been formally retired. That immutability is also where the discipline becomes most fragile in practice, because a record that can never be rewritten only works if someone chooses to write the superseding record when circumstances change, and that step is exactly where the habit tends to break down.

The costs that accumulate when architectural context is not preserved

The absence of durable architectural context does not cost a team once. It imposes a recurring tax on coordination, onboarding, and the quality of future decisions, and that tax grows faster than headcount does.

The most direct cost appears as repetition. Skan AI's Engineering Intelligence Guide found that nearly half of developers find themselves repeatedly answering the same questions from colleagues. That finding points to decisions being made and explained out loud, competently, and then evaporating the moment the conversation ends, because nothing about the explanation was recorded in a form that outlives the meeting it happened in. Every repeated answer taxes the time of whoever holds the knowledge, a cost paid repeatedly as the team grows and more people need the same explanation.

A second cost lands squarely on new hires. Without structured onboarding that includes a record of past decisions, new developers typically take several months to reach full productivity, largely because they have to reconstruct, through guesswork and informal questioning, the reasoning that existing team members take for granted. Teams that onboard new engineers with real decision history available to them tend to shorten that runway substantially, because the new hire can read why a choice was made.

Neither cost looks severe in isolation at small scale. A ten-person team can absorb a few repeated questions and a slightly slow onboarding ramp without much trouble. The damage compounds as the organization grows: headcount increases, repositories multiply, and the share of engineers who were actually present for the original decisions keeps shrinking. A five-year-old system with three remaining engineers from its founding team is a very different liability than the same system with thirty. The tax is not fixed. It scales with the exact factors, like team size and system age, that make a growing engineering organization valuable.

Why ADR adoption fails

Few engineering leaders need to be convinced that architectural decisions deserve a written record. Most have already tried to introduce ADRs at some point, often after a costly incident made the absence of documentation painful. The adoption usually fails anyway, and it fails for reasons that have little to do with whether anyone believes in the practice. The structural conditions required to write and maintain an ADR are almost never in place at the moment a decision actually gets made.

The first and most persistent failure mode is timing. Architectural decisions happen in Slack threads, in meetings, or inside one engineer's head while they're mid-implementation, and by the time anyone thinks to formalize the decision as an ADR, it has already shipped and the context behind it has partially evaporated. Research on GADR, presented at the Brazilian Symposium on Software Engineering, describes exactly this environment: architectural decisions emerge from informal, noisy meetings where the choices themselves are implicit, fragmented, and tangled up with off-topic conversation, conditions under which any after-the-fact documentation process tends to degrade. The decisions most in need of a written record are, perversely, the ones made fastest, under the most pressure, with the least slack in anyone's schedule to sit down and write about them.

The second failure mode is the sheer effort the task demands. The background research behind GADR identifies two primary obstacles to ADR adoption: the effort required to capture architectural knowledge in writing, and a lack of clarity about which decisions are even significant enough to warrant a record. Decision-makers consistently carry tacit knowledge that never surfaces in the decision itself. Writing a strong Context section requires reconstructing a frame of mind, a set of constraints, and a state of the world that may have existed weeks or months earlier, and that reconstruction is cognitively expensive in a way that writing code rarely is.

A related failure mode concerns what gets left out of the record once someone finally sits down to write it. An ADR that lists only the positives of the chosen option is a broken record, because it produces a document future engineers will trust and then be actively misled by when the unlisted tradeoffs eventually surface in production. Less experienced engineers compound this problem in a specific way: research on GADR notes that novice architects frequently reach for approaches they already know rather than genuinely exploring alternatives, and the project meetings in which these choices get made tend to be unstructured enough that the decision stays implicit even to the people in the room making it.

A fourth failure mode is where the record lives. ADRs stored in Confluence or a general-purpose wiki become write-only documents, updated once with enthusiasm and then abandoned at the same rate as every other page in that wiki. The fix for this is not a better wiki or a more organized folder structure. It requires a different mental model entirely, one that treats decisions as artifacts that belong in the repository itself, versioned alongside the code they govern, reviewed through the same pull request process as everything else the team ships.

A fifth failure mode is the absence of any enforcement or review cycle. ADRs written once and never revisited go stale, and a stale decision record hands a confident, specific, wrong answer to the next engineer who reads it, which is worse than an honest absence of information.

None of these five failure modes gets fixed by asking engineers to care more or document better. Telling a team to improve its documentation habits, without changing where and how that documentation gets produced, generates a fresh batch of well-intentioned Confluence pages that decay at the same rate as the last batch did. The fix has to change the structure the decision gets made inside of, not the motivation of the people making it.

The structural conditions that make ADRs stick

ADRs stick when writing one is the easiest available path at the exact moment a decision gets made, and when the resulting record lives somewhere the team is already looking.

The first condition is timing the record to the moment the decision is made. AWS Prescriptive Guidance, drawing on experience across more than 200 architectural decision records, treats the ADR review process as a gate inside the development workflow itself, not a retrospective artifact produced after the system is already live. Practically, this means a pull request that introduces a new data store, a new service boundary, or a new third-party dependency includes the ADR as part of the change being reviewed, not as a follow-up task assigned to someone's backlog.

The second condition is a clear, enforced threshold for what counts as architecturally significant. Teams that attempt to document every decision end up documenting almost none of them, because the volume overwhelms anyone's willingness to keep up. Teams that instead define significance narrowly, limiting ADRs to changes that affect nonfunctional requirements, cross team boundaries, or are difficult to reverse once shipped, tend to produce records consistently, because the bar is clear enough that engineers can apply it themselves without asking a manager for a ruling.

The third condition concerns who writes the records. Assigning new hires to write or refine ADRs by their third month of onboarding turns a passive reading exercise into an active knowledge-building one. A new engineer's fresh perspective is a reliable detector of gaps in what the team assumes is common knowledge, precisely because that engineer doesn't yet share the assumptions everyone else has stopped noticing. Having them draft or revise the record, rather than merely read it, exposes the places where the existing documentation quietly assumes context the new hire doesn't have.

Lowering the cost of capturing decisions with AI-assisted development

The single largest barrier to ADR adoption, the effort required to capture a decision at the moment it happens, is now directly addressable by large language model tooling, with humans still reviewing and approving what the tooling produces. This matters because effort was never a motivational problem. It was a cost problem, and cost problems respond to tools in a way that willpower problems do not.

GADR, presented at a software engineering symposium in 2026, demonstrates one version of what that tooling looks like in practice: a multi-agent, self-correcting workflow that extracts architectural decisions directly from raw, unstructured meeting transcriptions and generates ADR drafts in a standard format. What distinguishes this approach from earlier LLM-based attempts at ADR generation is that it is built for noisy, implicit conversational data rather than input that has already been structured by a human editor. Earlier approaches assumed something closer to a clean decision summary as a starting point. GADR instead works from the actual condition decisions are made in: a meeting where the choice is implicit, scattered across several minutes of conversation, and tangled up with unrelated discussion, which is precisely the condition that the earlier failure-mode research identified as the hardest for any documentation process to survive.

The implication for growing engineering teams is specific. If a tool can sit on top of an engineering team's existing meetings and standups and produce a draft ADR without requiring anyone to stop and write one by hand, the effort barrier that has sunk most ADR adoption attempts stops being the determining factor. Human reviewers still need to confirm the draft is accurate, fill in the consequences the model couldn't infer, and decide whether the decision clears the bar for architectural significance. That review step keeps the record trustworthy in exactly the way immutability was designed to protect. The tooling changes what it costs to get a first draft in front of a human, which is the step every failure mode described above has been breaking on.