Ask a question Share knowledge Edit the page
Register of architectural solutions
Architecture Decision Record (ADR) It’s a short record of one architecturally significant decision: what the team chose, why it chose this, what options it rejected, and what consequences it has. Architecture Decision Log (ADL)ADR doesn’t replace architecture, RFC, or design doc, but its mission is to keep the context of choice so that in six months time, a new developer, team leader, or AI assistant doesn’t know why the system works that way.
ADR is useful where the cost of forgetting is higher than the cost of writing, for example, the team chose a message broker, banned direct access to the base of another service, left a modular monolith instead of microservices, introduced an API versioning rule, or decided to store architectural knowledge next to the code, in each case it is important to preserve not only the outcome, but also the circumstances: constraints, conflicting requirements, alternatives considered, consequences and revision conditions.
The idea of lightweight ADR popularized by Michael Nygard in an article Documenting Architecture DecisionsHis main argument is still relevant: large architectural documents quickly become obsolete, and small modular records have a chance to live with the project.
What problem does ADR solve?
The code says, now implementedThe diagram shows, How do the components connect now?But neither the code nor the chart usually explains why the team gave up the other option, what risks they thought were acceptable, and under what conditions the decision should be reconsidered.
ADR turns this knowledge into an accessible artifact:
-
Reduces the reliance on the memory of a particular architect or senior developer
-
accelerates onboarding of new team members;
-
It prevents repeated arguments of the kind “why didn’t we do otherwise?”
-
assists in reviewing, transferring system ownership and planning migrations;
-
Links architectural solutions to code, tasks, incidents, and other documents
-
It makes knowledge more useful for search and RAG systems because the solution has clear boundaries, status and links.
This doesn’t mean that ADR replaces live discussion. Some of the expertise is still implicit: in people’s experience, diagnostic skills, domain understanding. But ADR captures a solid core: facts, tradeoffs and consequences that are then hard to repair.
When writing ADR
ADR is not needed for every line of code, nor for every library, but is justified if the solution answers at least partially yes to one of the questions:
-
The decision affects the structure of the system, the boundaries of modules or services.
-
Changes important quality attributes: reliability, safety, performance, and maintenance.
-
introduces a long-lived dependency, platform, framework or infrastructure standard;
-
defines a public API, integration contract, data model, or versioning method;
-
It affects multiple commands or repositories.
-
It’s expensive to roll back;
-
It has been repeatedly argued or it raises questions from new people.
-
This can be expected in future pull requests.
Don’t write ADRs in local implementation detail that can be replaced in one PR without affecting others, and if the solution isn’t interesting to the future team, it’s not architecturally significant.
Spotify Engineering in the Material When Should I Write an Architecture Decision Record ADR is written when the decision is meaningfully influenced, and the team needs to agree on what is meaningful in its context.
ADR, RFC, design doc and decision log
| Artifact | Main question | When is created | How is it related to ADR |
|---|---|---|---|
ADR |
What did you decide, why, under what restrictions and with what consequences? |
During or immediately after the decision is made |
Records a stable result and rationale of one significant fork. |
RFC |
What change is proposed and do the parties concerned agree? |
Before decision and until substantial implementation |
RFC organizes a discussion. The RFC output can be compressed into ADR. In large open-source projects like Rust, RFC is a separate governance process. |
Design doc |
How will the implementation be arranged? |
Before or at the beginning of a major initiative |
Design doc can contain APIs, migration plans, diagrams and multiple solutions, and ADR pulls a long-lived architectural solution out of it. |
Decision log / ADL |
What solutions exist, what are their statuses and where can they be found? |
Updated as ADRs become available |
This is an index: id, title, status, scope and a link to a full ADR. Microsoft describes this approach as a design decision log. |
Architectural documentation |
How is the system now? |
Lives with the system |
ADR explains the origin of the current device and limitations that are not visible from the diagram. |
The main thing is not the file name, but the function distribution. Where does the team discuss the proposal? Where does the decision go? Where does the current architecture show? Where does the list of all solutions look? If these questions are not separated, ADR quickly turns into either too long a design doc or a table without context.
Minimum workflow
The workflow should be easier than the decision itself:
-
Any team member can suggest ADR if they see an architecturally significant fork.
-
The record has an owner: a person who collects context and brings the record to status.
-
Chernivka gets status
proposedand discussed in a pull request, design review or short session. -
After the agreement, the record receives
acceptedorrejected. -
If the context has changed, the old ADR is not rewritten silently, but is created with a new ADR.
supersedes.
AWS in ADR process It recommends starting the review with a short silent reading: 10-15 minutes for reading and commenting, then discussion. This is a good antidote against presentations where decisions are made on the speaker’s charisma, not on the content.
Where to store ADRs
For an engineering team, the best default is to store ADRs next to the code: docs/adr/, doc/adr/ or architecture/decisions/. So the record goes through a pull request, has a history of changes, and is easily linked to the code. Backstage ADR and GOV.UK GDS Way.
But the Git-only approach isn’t always enough. If a solution works on dozens of repositories, you need a central index: id, title, status, area, command-owner, reference to the original. The full text can be left next to the system, and the index can be published on a wiki, Backstage, documentation portal or knowledge base.
A practical compromise:
-
Local solutions – in the system repository;
-
Intercommand standards – in a central catalog or a separate architecture repository
-
In all cases, stable ids, statuses, and links between solutions.
ADR template
Don’t start with the fullest template. Start with the Nygard kernel: title, context, decision, status, consequences. If the solution is complex, add fields from MADR: drivers, alternatives, participants, compliance verification and revision terms. Markdown Architectural Decision Records.
---
id: ADR-0042
title: Summary of the decision taken
status: proposed
date-created: 2026-08-01
date-decided:
owners:
- team-or-person
decision-makers: []
consulted: []
informed: []
scope:
systems: []
components: []
repositories: []
tags: []
supersedes: []
superseded-by: []
related-adrs: []
related-rfcs: []
related-design-docs: []
related-issues: []
related-code: []
review-or-revisit:
---
# ADR-0042: Summary of the decision
## Context and problem
What problem are we solving?
What are the facts, limitations, and contradictory forces?
What is outside the scope of the solution?
## Decision drivers
- What quality or limitation is most important?
- What conditions are mandatory?
- What criteria allow you to compare the options?
## Options considered
1. Option A.
2. Option B.
3. Don't change anything.
## Decision
We'll be...
Why does the chosen option fit the drivers better?
## Effects of consequences
Positive:
- ...
Negative:
- ...
Operational:
- ...
## Compliance verification
How do you make sure that the implementation is in line with the solution?
What tests, metrics, reviews, or architectural rules do you test for?
## Conditions for review
What changes in load, requirements, cost, commands
Or should the regulatory framework be revised?
## Supplementary material
References to RFC, design docs, tasks, code, incidents, and related ADRs.
Mandatory fields: id, title, status, context, decision, `consequences`The rest is only added if it’s used. Too complete a template easily turns ADR into a bureaucratic questionnaire.
Example 1. Selection of a database
---
id: ADR-0012
title: Use relational database as the main storage of order service
status: accepted
date-created: 2026-08-03
date-decided: 2026-08-07
owners: [orders-team]
scope:
systems: [order-management]
components: [order-service]
tags: [database, consistency, orders]
related-issues: [ORD-418]
review-or-revisit: 2027-02-01
---
# ADR-0012: Use relational database as the primary order service repository
## Context and problem
The service must store the order, positions, payment status and history
One order requires atomic change of the associated
to the entity and to unambiguously restore the condition.
They are on order, customer or time range.
The solution does not define analytical storage and full-text search.
## Decision drivers
- Transactional integrity.
- A clear migration model of the scheme.
- Operational experience of the team.
- Reproduced integration tests.
- Predictable backups.
## Options considered
1. Relational database as a system of record.
2. Documentary database as a system of record.
3. Event store is the only source of wealth.
## Decision
We will use a controlled relational database as the main one.
order-service storage. Events for other systems are published
through transactional outbox.
## Effects of consequences
Positive:
- Order invariants can be provided in a transaction.
- The team uses familiar migrations and diagnostics.
Negative:
- Online migration of large tables requires a separate discipline.
- Complex analytics cannot be transferred to operational DB.
## Compliance verification
- Integration tests check the atomicity of order changes and outbox.
- Code review checks for the absence of dual writers.
- The architectural test prohibits entry in order-service tables from other services.
## Conditions for review
Revise if the load profile requires data separation
Or transactional boundaries will change.
Example 2: Integration with an external system
---
id: ADR-0021
title: Isolate integration with the partner system through an asynchronous adapter
status: accepted
date-created: 2026-08-10
date-decided: 2026-08-14
owners: [integration-team]
scope:
systems: [partner-fulfilment-integration]
tags: [integration, resilience, idempotency]
related-rfcs: [RFC-007]
review-or-revisit: 2026-11-01
---
# ADR-0021: Isolate integration with the partner system through an asynchronous adapter
## Context and problem
After confirming the order, you need to transfer the application for execution to the partner.
External APIs have their own availability window, timeout responses are not always available.
The partner’s model is different from ours.
User checkout should not be dependent on the instant availability of the partner.
## Decision drivers
- Do not lose confirmed applications.
- Maintain idempotent repetitions.
- See the state of integration.
- Do not drag an external data model into checkout.
## Options considered
1. Synchronous call of the partner from checkout.
2. Asynchronous queue and dedicated adapter component.
3. Periodic packet unloading.
## Decision
We will record local integration intent within the transaction.
order and asynchronously transfer its adapter component.
idempotency key, transforms the data model and manages retry policy.
Checkout returns the result after saving the order without waiting
external confirmation.
## Effects of consequences
Positive:
- Unavailability of the partner does not block the order.
- The external contract is isolated in one component.
Negative:
- It's eventual consistency.
- Reconciliation job, dead-letter queue and support interface.
## Compliance verification
- Direct calls to the partner API from the checkout package are prohibited.
- Contract tests check the data conversion.
- Metrics track queue age, repeats and DLQ.
## Conditions for review
Review if the partner gives guaranteed transactional messaging integration
or the product will require synchronous confirmation.
Example 3: Modular monolith
---
id: ADR-0030
title: Develop the product as a modular monolith with clear domain boundaries
status: accepted
date-created: 2026-08-17
date-decided: 2026-08-21
owners: [platform-team]
scope:
systems: [core-product]
tags: [architecture-style, modularity, deployment]
review-or-revisit: 2027-02-01
---
# ADR-0030: Develop the product as a modular monolith with explicit domain boundaries
## Context and problem
The product is changing rapidly, domain boundaries are still being clarified, and several
Teams are regularly changing the same user scenarios.
A platform for the operation of a large number of services has not yet been created.
This should prevent the growth of unstructured monoliths.
## Decision drivers
- The speed of change of cross-cutting scenarios.
- Low operational complexity.
- Clear boundaries of ownership.
- Possibility of future module allocation.
- Unified deployment for transactional changes.
## Options considered
1. Microservices for the proposed domain areas.
2. Unstructured monolith.
3. A modular monolith with controlled dependencies.
## Decision
We will use a single deployable, divided into domain modules.
Each module has a public application interface and does not address the application.
to the internal packages or tables of another module.
A separate service requires a new ADR.
## Effects of consequences
Positive:
- End-to-end changes do not require coordination of multiple deployments.
- The boundaries can be clarified as the domain is studied.
Negative:
- Independent scaling is limited.
- Border discipline should be ensured by tests and revisions, not by arrangements.
## Compliance verification
- Architecture tests check the permissible directions of dependencies.
- The modules do not import each other’s internal packages.
- Direct access to other people's tables is prohibited by review checklist and test.
## Conditions for review
Allocate a module to the service if it needs an independent lifecycle
isolated scaling or autonomous command with a stable boundary.
ADR and AI Assistants/RAG
AI assistants add value to ADR, but only if records are structured, and people often understand from context that "it’s a billing solution," and a metadata-free RAG system can apply it to the entire monorepository.
For AI-ready ADR, it is important:
-
stable
idfor citation and deduplication; -
short-cut
title; -
`status`so that retrieval does not post outdated or rejected solutions as valid;
-
scope: system, component, repository, catalog; -
supersedesandsuperseded-by; -
references to code, tests, tasks, RFC and design docs;
-
`confirmation`How to check that the decision is being followed.
You don’t have to upload the entire ADR log to a prompt AI agent, but you have to split the knowledge into two layers.
-
ADR stores history and explanation: context, options, decision, consequences.
-
AGENTS.md,CLAUDE.mdor.github/copilot-instructions.mdKeep a short operating rules for the agent.
For example, ADR explains why checkout should not directly call the partner API. checkout/ Don’t add direct partner API calls; use integration adapter. A test or architectural linter checks that the rule is not broken.
This is in line with the modern tools approach: GitHub describes repository-level and path-specific. custom instructions for Copilotand Anthropic in the documentation Claude Code memory It explicitly states that these files are contextual, not enforceable, requiring tests, hooks, linters, or policy-as-code.
In RAG piping, a short ADR can be indexed as a whole, and a long ADR can be chunked by semantic partitions, keeping the metadata for each chunk: adr_id, status, scope, date, `tags`Microsoft Azure Architecture Center in Guidelines RAG chunking and chunk enrichment It also highlights the role of document structure and metadata for search.
What could go wrong
| Anti-pattern | What is dangerous | How to fix |
|---|---|---|
ADR on 20 pages |
It’s not read, the solution is sinking in detail |
Leave a summary, rationale and consequences; benchmarks and migration plan to be referenced. |
Only the name of the technology |
It’s unclear why the choice was reasonable |
Add context, drivers, options and implications. |
ADR is written by an architect only |
A queue arises, the team doesn’t feel ownership |
Allow any participant to initiate ADR; the owner is responsible for the process. |
No statuses |
It is unclear whether the decision is valid |
Use |
Accepted ADR edited silently |
History is lost |
Significant change to issue new ADR with reference |
ADR is not associated with the code |
He’s not remembered when the system changes |
Refer to ADRs from PR, issues, tests and review checklist. |
Consider the amount of ADR the main KPI |
The team writes records for volume |
Measure usage: links from PR, onboarding, search, reduce repeated disputes. |
How to start 2-4 weeks
-
Choose one pilot area: service, platform standard, or active architecture fork.
-
Consistent with trigger criteria: When a decision is considered significant.
-
Create.
docs/adr/shortdecision-log.md. -
Write ADR-0001: “We use ADR to fix architectural solutions.”
-
In the real-life solution, spend 60-90 minutes in a session: context, drivers, alternatives, decision, consequences.
-
Over the next two weeks, create another 2-4 ADRs with only real solutions.
-
Add links to ADRs in PR and tasks.
-
After a month, do a retrospective: which fields are not filled, what is not, where the record helped.
Don’t start with backfill of the entire system history.Research Using Architecture Decision Records in Open Source Projects It shows that the mere presence of multiple ADRs does not mean sustainable practice, but stronger signaling is multiple authors, continued practice over time, and actual use of records.
Utility metrics
Minimum dashboard for pilot:
-
The proportion of significant solutions for which there are ADRs;
-
median time from the appearance of the fork to the recording;
-
Number of active authors and reviewers;
-
ADR share with references to code, issue, test or design doc
-
Number of ADR references from PR, onboarding, incident review or architectural discussions
-
Repeated disputes over an already made decision without a new context
-
The proportion of questions where a person or RAG system quickly finds the correct ADR working
Don’t use "ADR" as your primary metric. It’s vanity metric. The value of ADR is when writing helps you make your next decision faster and more consciously.
FAQ
Do I need to write an ADR for each library?
No. ADR is needed if a library becomes a long-lived dependency, defines a public contract, affects security, data, operation, or becomes an organizational standard. A utility that can be replaced in one PR doesn’t usually need to be documented as ADR.
Who should write ADR?
The one who is closest to the problem and can put the context together: developer, tech lead, SRE, security specialist, product engineer. It’s more important to assign the owner and reviewers than to assign the authorship only to the architect.
When to write ADR: before or after the decision?
It is useful to start the draft at the moment of fork. Proposed ADR structured the discussion. Accepted ADR captures the result. For a major change, it can be an RFC or a design doc first, and the ADR will appear as a compact record of the decision made.
Can old decisions be documented?
Yes, if they continue to affect work and raise questions, but such an ADR should be marked as retrospective/backfilled, the date of recovery, and separate known facts from reconstruction.
Can I change the accepted ADR?
Typographical errors, broken links and formatting refinement — yes. Change of meaning is better to make a new ADR and link it through the new ADR. `supersedes`So the story stays honest.
Git or wiki?
For code-related solutions, Git is usually better: pull requests, history, implementation links. Wiki is more convenient for non-engineered audiences and cross-repositor search. Practically, Git is the source of truth and a published directory in the wiki/portal.
How is ADR different from RFC?
RFC helps to discuss a proposal and gather consent before a decision is made. ADR stores the decision and the reasons. In a small team, one document can perform both functions, but the status and canonical outcome must be clear.
How is ADR different from Design Doc?
Design doc describes a future implementation and can contain APIs, migration plans, diagrams and multiple solutions. ADR is atomic: one meaningful solution, its context and consequences.
How do you avoid bureaucracy?
Limit ADR to meaningful solutions, leave a short template core, build a review into an existing pull request or design review, and regularly delete fields that no one uses.
How to use ADR with AI coding agent?
Index only the accepted ADRs with metadata scope, status Transfer the current restrictions into short scoped instructions for the agent, and fix critical rules with tests or architectural checks.
Sources
architecture, decisions, documentation, adr, architecture-knowledge-management