Architecture Decision Records: context, decision and consequences over time

ADR сохраняет мотивацию одной architecturally significant decision. Nygard’s original format uses Title, Context, Decision, Status и Consequences; proposed/accepted/deprecated/superseded are useful states. Markdown в Git и one-to-two pages — решения его проекта, а не обязательный стандарт для всех команд.

Что утверждает паттерн — и чего он не гарантирует

• Nygard’s ADR captures one architecturally significant decision and its forces, response and consequences.
• Original proposed/accepted/deprecated/superseded states preserve history; reversing a decision should reference its replacement.
• Markdown, repository path, sequential numbering and one-to-two-page length are Nygard’s project decisions/examples, not universal ADR conformance rules.
• An ADR records a decision; it does not prove the decision is correct, implemented or still valid.

Границы и компоненты

Сценарии

Propose a significant decision

Author records facts/forces neutrally, alternatives and measurable assumptions before a decision is accepted. The ADR can be written before, during or after discovery as long as status and evidence are honest.

Проверяемый исход: Readers can distinguish facts, assumptions, options and the proposed response.

Accept with all consequences

Review checks decision scope, positive/negative/neutral consequences, owner and verification plan. Acceptance means stakeholders chose it, not that technology guarantees the outcome.

Проверяемый исход: The accepted record names success/failure signals and known trade-offs.

Verify assumptions in operation

A queue/broker decision uses measured workload, latency, durability and recovery tests. No fixed RabbitMQ ceiling is copied into the ADR as a universal product fact.

Проверяемый исход: Fitness checks detect when assumptions or consequences diverge from reality.

Supersede without erasing history

Changed forces lead to a new ADR. It links the old record, marks it superseded and preserves why the old decision was reasonable then.

Проверяемый исход: Search resolves the current decision while historical context remains auditable.

Failure, concurrency и evolution checklist

• Link decision to implementation/configuration and observable verification.
• Record negative and neutral consequences, not only benefits.
• Time-stamp evidence and re-evaluate assumptions when workload/context changes.
• Never delete or rewrite accepted history to hide a reversal; supersede with links and access controls appropriate to the repository.

Метрики, units и допущения

• Capacity claims cite benchmark workload, payload, durability, concurrency, hardware and confidence range; no broker has a universal messages/s ceiling.
• Review age = current time − last evidence time; teams choose thresholds based on volatility/risk.
• ADR size/page count is an editing heuristic, not a correctness metric.

Числа здесь — размерностные формулы или явно помеченные учебные inputs. Паттерн архитектуры сам по себе не задаёт SLA, throughput, latency или fault tolerance.

Связанные темы

[CONCEPT]c4-model

[CONCEPT]evolutionary-architecture

Первичные источники

• https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
• https://adr.github.io/

Scope note

ADR discipline improves traceability. It does not guarantee consensus, implementation conformance, current evidence, good architecture or any vendor performance number.