Architecture Decision Records: A Practical ADR Guide for Developers

An architecture decision record is a short written record of a significant technical decision. Martin Fowler describes an ADR as a short document that captures and explains a single decision relevant to a product or ecosystem. Microsoft frames an ADR as a record of how and why a system came to its current shape. The GitHub ADR community defines it around one architectural decision, its rationale, tradeoffs, and consequences.

Those definitions all point at the same idea: an ADR is not a design document. It is not a requirements document. It is not a meeting transcript. It is the decision log for your architecture.

A good ADR answers five questions:

• What problem were we solving? The context that made the decision necessary.
• What did we decide? The actual choice, stated plainly.
• What alternatives did we consider? Serious options, not straw men.
• Why did we choose this path? The rationale and tradeoffs.
• What happens now? Consequences, follow-up work, and signals that might trigger reconsideration.

That last part matters. Technical decisions are rarely perfect. Most are bets under uncertainty. You choose PostgreSQL over DynamoDB because query flexibility matters more than extreme write scale right now. You choose a modular monolith over microservices because the team is small and coordination cost would kill delivery. You choose GraphQL because frontend teams need flexible reads, even though caching and authorization get more complicated.

The ADR does not need to prove you were right forever. It needs to explain what you believed at the time, what constraints mattered, and what price you knowingly paid. Future developers can respect a tradeoff even when they would not make the same choice today.

The obvious benefit of architecture decision records is documentation. The deeper benefit is decision quality. Writing forces vague opinions to become specific. When a team has to write down the problem, options, tradeoffs, and expected consequences, weak reasoning becomes visible fast.

This is why ADRs are useful before the decision is final, not only afterward. A draft ADR gives the team something concrete to review. Instead of arguing in circles about whether a technology "feels scalable," people can comment on the actual constraints: traffic shape, team experience, operational maturity, hiring plans, compliance needs, latency requirements, cost limits, and migration risk.

AWS published guidance in 2025 based on more than 200 ADRs across projects ranging from small teams to programs with more than 100 contributors. Their experience points to a practical problem every growing engineering org recognizes: coordination cost. Teams spend real time aligning with other teams, preserving nonfunctional requirements, adapting to changing business goals, and transferring knowledge to new people. ADRs reduce that tax by making decisions discoverable.

For developers, this has career value too. A well-written ADR is evidence that you can think above the ticket level. It shows you can compare options, communicate risk, and make tradeoffs instead of just arguing for your favorite tool. If you want to move from mid-level to senior, senior to tech lead, or tech lead to staff engineer, ADRs are one of the cleanest ways to practice technical leadership without waiting for a new title.

For managers, ADRs reduce dependency on memory. The team no longer needs the same two senior engineers in every conversation because only they remember the original reasoning. New hires ramp faster. Product partners understand why certain requests are expensive. Incident reviews can trace whether a failure came from a known tradeoff or a decision that needs to be superseded.

The best teams do not use ADRs to make themselves look sophisticated. They use them to stop wasting time.

The fastest way to ruin ADRs is to document everything. If every dependency upgrade, component name, and CSS convention gets an ADR, the team will ignore the whole folder within two weeks. ADRs are for decisions that shape the system, affect quality attributes, create long-lived constraints, or would be expensive to reverse.

Write an ADR when the decision changes architecture boundaries, data ownership, deployment strategy, integration patterns, security posture, scalability characteristics, or the way multiple teams work together. Write one when the decision answers a question future developers are likely to ask. Write one when the decision has meaningful tradeoffs and reasonable people could disagree.

Common ADR topics include choosing a database, introducing an event bus, splitting a service, keeping a monolith, selecting an API style, adopting a cloud provider, changing authentication strategy, standardizing observability, defining tenant isolation, choosing build tooling, or deciding how to handle background jobs. These are not just implementation details. They create paths the team will walk for months or years.

Do not write an ADR for tiny local choices unless they represent a broader standard. "Use this helper function" does not need an ADR. "All new services use OpenTelemetry tracing with this naming convention" might. "Add a new endpoint" does not need one. "Expose partner integrations through versioned public APIs instead of direct database access" probably does.

A simple test helps: if a new engineer joins in six months and asks "why is it this way?" would the honest answer require context that is not obvious from the code? If yes, consider an ADR.

Another test: would changing this decision require coordination, migration, or risk management? If yes, document it. The more expensive the reversal, the more useful the record.

Templates matter because consistency lowers friction. Microsoft recommends a consistent anatomy for every record, including problem statement, options considered, outcome, tradeoffs, confidence level, and status. Fowler emphasizes brevity, status, rationale, alternatives, and consequences. You do not need a complicated template. You need one your team will actually complete.

Use this structure:

1. Title: A numbered, readable decision name, such as "0007 Use PostgreSQL for billing data."
2. Status: Proposed, accepted, superseded, or rejected.
3. Date: When the decision was proposed or accepted.
4. Context: The problem, constraints, and forces acting on the decision.
5. Decision: The choice in direct language.
6. Options considered: The serious alternatives and their pros and cons.
7. Consequences: What gets easier, what gets harder, and what follow-up work exists.
8. Confidence and review triggers: How confident the team is and what would make the decision worth revisiting.

Here is the tone you want: plain, assertive, and factual. Not academic. Not defensive. Not stuffed with buzzwords. An ADR should feel like a senior engineer explaining the choice to another competent engineer who was not in the room.

Bad decision wording sounds like this: "After evaluating multiple industry-leading options, we will use Kafka to enable scalable event-driven architecture across the platform." That is brochure language. It hides the actual reasoning.

Better wording sounds like this: "We will use Kafka for order lifecycle events because three downstream systems need independent consumption, event replay matters for audit recovery, and the platform team already operates Kafka in production. This increases operational coupling to the platform team and adds schema governance work." That is useful. It names the upside and the price.

Keep the record short. One to two pages is enough for most decisions. If the analysis needs twenty pages, write a separate design document and link it from the ADR. The ADR should still stand alone as the decision record.

The easiest way to write a good ADR is to start before the meeting. Draft the context and options while the question is still open. That draft becomes the discussion artifact. People can point at sentences, challenge assumptions, add missing constraints, and suggest alternatives. The ADR improves because the team can see the thinking.

AWS recommends short, focused ADR meetings, often 30 to 45 minutes, with a readout style where people spend part of the meeting reading and commenting on the document. That works because it shifts the conversation from whoever talks fastest to what the document actually says. It also gives quieter engineers a way to contribute through written comments.

The participant list should be lean but cross-functional. Invite people who own affected systems, security or operations stakeholders when relevant, and the product partner if the decision changes customer outcomes or delivery risk. Do not invite twenty observers because the word "architecture" sounds important. Large rooms create performance. Small rooms create decisions.

Separate exploration from decision. If the team needs a spike, benchmark, prototype, or lengthy design proposal, do that work before accepting the ADR. The ADR is not where you dump every experiment. It is where you summarize the important findings and record the final choice.

Be honest about consequences. Many ADRs fail because they read like sales pitches for the chosen option. That destroys trust. Every meaningful technical choice makes something worse. Microservices improve independent deployment and ownership, but they add network boundaries, observability burden, deployment coordination, and local development complexity. A monolith improves simplicity and flow, but it can concentrate ownership and create scaling pressure later. If your ADR does not admit the downside, it is not a decision record. It is propaganda.

Finally, write for future readers. Future readers will not remember the Slack debate, the urgent customer deadline, the hiring constraint, or the production incident that shaped the decision. Include enough context for them to understand why the choice made sense when it was made.

The common developer-friendly default is to store ADRs in the same repository as the code they affect, often under docs/adr or doc/adr. Fowler recommends keeping them close to the codebase so they can be read, searched, reviewed, and diffed like code. That is usually the right starting point.

Use one file per ADR. Number files in a monotonic sequence so directory order tells a story: 0001-use-postgresql.md, 0002-adopt-openapi-for-public-apis.md, 0003-supersede-session-storage-choice.md. The number matters less than consistency. The readable title matters a lot.

For decisions that span multiple repositories, choose a higher-level documentation repository or engineering handbook. The rule is simple: store the ADR where the affected people will naturally look. If a platform standard affects every service, hiding it in one service repo is a mistake. If a decision affects only the checkout service, putting it in a company-wide wiki may make it harder for checkout developers to find.

Git works well for engineering-owned ADRs because review history is valuable. Pull requests create an audit trail of comments and approval. Search works. Links from code reviews, issues, and design docs are easy. The drawback is that non-engineering stakeholders may find Git awkward. If product, security, or compliance needs frequent access, publish ADRs to a docs site or mirror accepted decisions into a more accessible location.

Do not let storage debates block the habit. A simple folder in the repo beats a perfect knowledge platform nobody updates. Start with the least fancy place that keeps records visible.

An ADR needs status because decisions move. A proposed ADR is still under discussion. An accepted ADR governs the current direction. A rejected ADR records an option the team decided not to take. A superseded ADR has been replaced by a newer decision.

The most important rule is this: accepted ADRs are append-only. Do not rewrite history when the decision changes. Write a new ADR that supersedes the old one and link them together. Microsoft explicitly recommends this approach because it preserves the history of thinking and makes it clear when direction shifted. Fowler makes the same point: once accepted, the record should not be reopened and edited to pretend the past was cleaner than it was.

This matters because architecture is path-dependent. The old decision may have been correct under old constraints. A year later, traffic changed, the team doubled, compliance requirements appeared, or a vendor relationship shifted. Superseding the ADR lets the team say, "This was the right decision then. This is the right decision now. Here is why the conditions changed." That is mature engineering.

Review triggers help keep ADRs alive without creating calendar bureaucracy. Add a sentence like: "Revisit this decision if write volume exceeds 10,000 events per second, if the platform team stops supporting Kafka, or if audit replay becomes unnecessary." Now future teams know what evidence would justify reopening the question.

You can also use lightweight periodic review. Once a quarter, a tech lead or staff engineer scans accepted ADRs for decisions that look outdated, risky, or contradicted by current practice. The goal is not to rewrite everything. The goal is to identify which decisions need a superseding ADR or cleanup work.

Imagine a team deciding whether to move user notifications from synchronous API calls to an event-driven workflow. A weak ADR says, "We decided to use events because event-driven architecture is scalable." That tells future developers almost nothing.

A useful ADR says the current checkout path waits on email, SMS, and webhook notification calls. External provider latency is increasing p95 checkout response time by 430 milliseconds. The team considered keeping synchronous calls with tighter timeouts, moving notifications to a background job table, and publishing notification events to the existing message broker. The decision is to publish notification events because checkout should not depend on provider latency, three consumers need the same lifecycle signal, and the company already runs the broker. The consequences are eventual consistency, duplicate delivery handling, schema versioning, and new monitoring requirements.

That record is not long, but it changes the quality of future conversations. If a developer later asks why notifications are async, the answer is there. If duplicate emails happen, the ADR already warned that idempotency matters. If the broker becomes unreliable, the team can decide whether the original tradeoff still holds.

Here is another example. A startup decides to keep a modular monolith instead of splitting into microservices. A useful ADR would name the constraints: six engineers, one product line, high uncertainty in domain boundaries, no dedicated platform team, and a need for fast refactoring. It would acknowledge the downsides: deploys remain coupled, ownership boundaries need discipline, and future extraction may require migration work. It might include a review trigger: revisit service extraction when two or more teams need independent deploy schedules around clearly separated domains.

Notice the pattern. Good ADRs do not glorify the decision. They create a map of the tradeoff. That is what future teams need.

The first mistake is writing ADRs after the fact as fake justification. If the decision is already politically locked and the ADR merely decorates it, engineers will smell it immediately. Use ADRs to clarify decisions, not launder them.

The second mistake is making records too long. Developers will not read a ten-page ADR for a normal architectural choice. Put details in supporting docs. Keep the decision record brief.

The third mistake is documenting trivial choices. When everything is an ADR, nothing is. Protect the format for decisions that matter.

The fourth mistake is hiding rejected alternatives. Future teams need to know what you considered and why you rejected it. Otherwise they will rediscover the same tempting wrong option and reopen the debate.

The fifth mistake is letting ADRs drift away from implementation. If the team accepted an ADR but the code took a different path, either fix the implementation, write a superseding ADR, or mark the decision abandoned. A stale decision log is worse than no log because it gives false confidence.

The sixth mistake is treating ADRs as architect-only artifacts. Developers closest to the work should write many of them. A tech lead, staff engineer, or architect can coach the shape, but the person doing the investigation often has the freshest context. Writing ADRs is a skill builders should practice.

The seventh mistake is using ADRs to avoid conversation. Written records do not replace human alignment. They improve it. If a decision affects people, talk to them. Then capture the outcome so nobody has to reconstruct the conversation from memory.

Do not announce a grand documentation initiative. Developers have survived too many of those. Start with one painful recurring decision and write one useful ADR.

Pick a decision the team already cares about: database choice for a new feature, API versioning, queue strategy, deployment ownership, or whether to split a service. Draft a one-page ADR and bring it to the team. Ask for comments. Keep the meeting short. Accept the decision. Store it somewhere obvious. Then reference it the next time the question comes up.

That last step is the hook. When someone asks, "Why did we choose this?" and you can send a link instead of restarting a meeting, the team feels the value. Process adoption works better when people experience relief.

After two or three useful ADRs, define the lightweight rule: any architecturally significant decision needs an ADR before it is considered done. Not before exploration. Not before conversation. Before done. That gives teams flexibility while still preserving the record.

Create a template and examples. Developers hate blank pages. Put the template in the repo. Add a short README explaining when to write an ADR, what statuses mean, and how to supersede a decision. Keep it under a page.

If the team resists, do not argue abstractly about documentation maturity. Ask what repeated decision, onboarding confusion, or production surprise they would like to stop reliving. ADRs are not about looking professional. They are about preventing expensive amnesia.

Architecture decision records are not glamorous. Nobody gets into software because they dream of creating a folder full of small decision documents. But mature engineering often looks like boring habits done consistently. ADRs are one of those habits.

They make decisions clearer before the team commits. They preserve context after people leave. They help new developers understand the system without interrupting the same senior engineer every afternoon. They give managers and product partners a better way to understand why technical tradeoffs exist. They create a career-building practice for developers who want to show judgment, not just output.

The key is keeping them small. One decision. Clear status. Honest tradeoffs. Real consequences. Easy to find. Easy to supersede.

If your team has never used ADRs, do not boil the ocean. Write one this week. Pick a decision people keep debating. Capture the context, alternatives, decision, and consequences. Share it. Improve it. Accept it. Then the next time the same question comes up, send the link.

That is how architecture gets less mysterious. Not through perfect diagrams or heroic memory, but through a trail of decisions that lets future developers understand the path you took and decide whether it is still the right one.