ADR vs NFR: Architecture Decisions and System Quality Are Not the Same Thing

An non-functional requirement (NFR) describes a quality, constraint, or operating condition the system is expected to satisfy. An architecture decision record (ADR) records an architecturally significant choice made in response to requirements, constraints, risks, and trade-offs. They are connected, but they are not interchangeable: an NFR states what must be true; an ADR explains what was decided, why, and with what consequences.

What is the difference between an NFR and an ADR?

The simplest distinction is grammatical. A requirement describes a condition the system must satisfy. A decision record describes a choice the team made.

For example, “The API must return 95% of read requests within 300 ms under the agreed reference load” is a quality requirement. “Use a read-through cache for this workload because the measured database-only path cannot meet the latency target without unacceptable cost” is an architecture decision.

The first statement remains valid even if the implementation changes. The second statement can later be superseded by another decision if the workload, technology, cost model, or evidence changes.

What is an NFR in precise architectural terms?

“Non-functional requirement” is a convenient industry label, but it can hide several different kinds of statements. In architecture work, the useful distinction is between functional behavior, quality requirements, and constraints.

ISO/IEC 25010:2023 provides a product-quality model with nine characteristics and subcharacteristics that can be used when specifying and evaluating ICT and software product quality. SEI architecture work similarly treats quality attribute requirements as major drivers of software architecture.

A useful NFR is therefore not “the system should be fast” or “the platform must be secure.” Those statements name aspirations. An architecture-driving requirement should make the expected property testable enough that design alternatives and later evidence can be evaluated against it.

What is an Architecture Decision Record?

An Architecture Decision Record is a compact record of an important architecture decision. Michael Nygard’s original ADR formulation emphasizes the context, the decision, its status, and the resulting consequences.

The important object is the decision, not the template. Different teams use different ADR formats. A richer record can also preserve alternatives, decision criteria, trade-offs, evidence, links to requirements, and the date or version from which the decision applies.

ISO/IEC/IEEE 42010:2022 is broader than ADR practice: it specifies requirements for architecture descriptions and their concepts, while explicitly not prescribing one process, notation, tool, format, or medium for recording an architecture description. An ADR is therefore a practical decision-recording technique, not a format mandated by ISO 42010.

The simplest example: latency requirement → architecture decision

Suppose a product owner and engineering team agree that a search endpoint must return the first page of results within 400 ms at the 95th percentile under a defined reference workload.

That target is not an ADR. It is a quality requirement. Architecture work begins by asking what design can satisfy it under the system’s other constraints.

NFRs and ADRs usually have a many-to-many relationship

One quality requirement can drive several architecture decisions. A tenant-isolation requirement, for example, can influence identity propagation, database scoping, background-job design, cache keys, audit logging, and administrative tooling.

One architecture decision can also respond to several requirements at once. Choosing an asynchronous processing boundary might improve responsiveness and failure isolation while introducing consistency, complexity, observability, and operational trade-offs.

A technology choice is not automatically a requirement

A recurring architecture error is to write a preferred technology into the requirements layer and then treat the resulting design as inevitable.

“The system must use PostgreSQL” can be a legitimate constraint if a contract, platform policy, compatibility requirement, licensing rule, organizational standard, or existing operational boundary actually mandates PostgreSQL. But if the real need is transactional consistency, structured querying, operational familiarity, or a specific recovery objective, the requirement should state that need and the technology selection should be recorded as a decision.

An ADR is not proof that an NFR has been satisfied

Decision documentation and system validation answer different questions. An ADR can show that performance, security, resilience, or maintainability were considered. It cannot by itself demonstrate that the delivered system actually achieves those properties.

The proof must come from the validation method appropriate to the requirement: benchmark, load test, failure test, security test, architecture analysis, audit, inspection, operational telemetry, recovery exercise, user study, or another form of evidence.

When does an NFR become architecturally significant?

Not every non-functional requirement deserves an architecture decision. The important subset is the requirements that materially shape the architecture or force trade-offs across the system.

SEI literature uses the concept of architecturally significant requirements for requirements with far-reaching architectural effect. Quality attributes such as performance, reliability, security, and modifiability are frequent sources of such drivers, especially when they carry high business or mission value.

A stronger architecture model: requirement → decision → implementation → validation

The most useful connection between NFRs and ADRs is traceability. A requirement should be able to point to the architecture decisions that address it; an ADR should identify the drivers it responds to; implementation work should realize the decision; validation should return to the original requirement.

Implementation evidence: how I separate requirements and decisions in SenseFlow

In SenseFlow, the project Source of Truth explicitly places non-functional requirements inside the requirements structure together with dependencies, risks, assumptions, acceptance criteria, and a validation method. The documentation model separately defines decision integrity for significant decisions.

For significant SenseFlow decisions, the recorded fields are Decision, Reason, Alternatives, Trade-offs, Status, and Date / Version. Major architecture and product decisions are intended to remain historically traceable rather than being overwritten when the project evolves.

SenseFlow also assigns different operational roles to Confluence and Jira. Confluence is the structured knowledge and decision environment; Jira manages actionable delivery work. Major Jira Epics should link back to the relevant product or requirements documentation. This preserves the chain from product intent through requirements and decisions into implementation rather than turning the backlog into the architecture Source of Truth.

Enterprise project context: requirements should precede architecture choices

The same separation is useful in enterprise-oriented project work. Architecture decisions made before requirements, risks, constraints, and acceptance conditions are sufficiently understood can turn preferences into false necessities.

For Enterprise Aaasaasa 0.1, the relevant lesson is methodological rather than a claim about one particular ADR: requirements, architecture, validation, milestones, risk management, and acceptance belong to a connected delivery system. An architecture choice should remain traceable to the requirement or constraint it is intended to address.

Common failure modes when ADRs and NFRs are mixed

The ADR–NFR decision framework

When a team encounters a new architecture concern, the following sequence helps determine what belongs in requirements, what belongs in an ADR, and what belongs in evidence.

What ADR and NFR are not

What would change this answer?

The terminology can evolve. ISO/IEC/IEEE 29148:2018 remains the current published requirements-engineering standard as of 8 October 2026, but ISO lists a Draft International Standard intended to replace it. If the new edition changes relevant terminology or requirements guidance, the version-specific references in this article should be updated.

ADR templates can also evolve without changing the central distinction. Michael Nygard’s minimal template, MADR, organization-specific templates, architecture knowledge tools, or structured decision databases can all record decisions. The durable question is whether the record preserves enough context and rationale to understand an architecturally significant choice.

The distinction would only collapse if an organization deliberately chose a combined artifact that stores both requirement and decision data in one document. Even then, the semantic roles remain different: one field states the required outcome or constraint; another records the chosen response.

Limitations

This article uses NFR as practical shorthand. Some engineering methods prefer terms such as quality attribute requirement, quality requirement, system quality, constraint, service-level objective, or architecturally significant requirement. Those terms are not perfectly interchangeable, and project terminology should be explicit.

Not every requirement can be reduced to a single numeric threshold. Security, safety, maintainability, interoperability, usability, explainability, portability, and governance can require combinations of scenarios, structural rules, analyses, process controls, and qualitative evidence. “Measurable” should mean verifiable enough for the decision, not artificially numeric.

Not every architecture decision needs a formal ADR. The documentation cost should be proportional to architectural significance, longevity, uncertainty, trade-off complexity, and the cost of losing the rationale.

Conclusion

ADR and NFR belong to different layers of architecture work. The NFR defines a quality target, constraint, or operating condition. The ADR records a significant architectural response to one or more drivers.

Keeping those layers separate makes architecture easier to reason about. Requirements can be validated independently of technology. Decisions can be superseded without rewriting history. Alternatives and trade-offs remain visible. Delivery work can be traced back to architectural intent. Evidence can show whether the resulting system actually satisfies the requirement.

The strongest chain is therefore not “NFR → ADR → done.” It is need → requirement → architectural drivers → options → decision → implementation → validation → change. That chain turns architecture documentation from static paperwork into a testable record of why the system has the shape it has.

FAQ

Glossary

Primary sources and implementation evidence

This article separates current standards from project implementation evidence. ISO/IEC/IEEE 29148:2018 remains current as of 8 October 2026 but is marked for revision; ISO/IEC 25010:2023 and ISO/IEC/IEEE 42010:2022 are current published editions. SenseFlow is original project evidence for the traceability and decision-integrity model described above.