Шаблон: архитектурное решение (ADR)

Запись об архитектурном решении (Architecture Decision Record, ADR) — короткий версионируемый документ, фиксирующий одно значимое архитектурное решение: контекст, выбор, последствия и статус. В линейке шаблонов аналитика ADR отвечает на вопрос «почему система устроена так», а не «что делает» (SRS, BRD) и не «как вызывать интерфейс» (REST, SOAP, Kafka spec). Этот шаблон — единый формат записи решений с явной связью с требованиями и последующими спецификациями; место ADR в SDLC — 00.03 Жизненный цикл ПО и место аналитика (SDLC, STLC); теория архитектуры — 03.01.01 Понятие архитектуры ИС и её виды (бизнес-, системная, техническая).

1. Назначение

Документ пишут системный аналитик и/или архитектор (00.01 Кто такой аналитик (роли BA, SA, FA)); его читают разработка, другие аналитики, DevOps/SRE, QA, владелец продукта и владельцы смежных систем на этапах проектирования, ревью и сопровождения.

Роли инициаторов. Технический ADR (стек, репликация, протокол) обычно ведёт SA или architect. Business analyst поднимает Proposed, когда зафиксирован компромисс между стейкхолдерами по scope или NFR (например, «eventual consistency до 30 s допустима для списка») — передаёт SA problem statement, Source requirements, ранжированные drivers и согласованные ограничения; SA/architect дополняет options, POC и доводит до Accepted. Эскалация при споре reviewers — 09.06 Ведение переговоров с техническими командами.

Шаблон закрывает четыре задачи:

• Сохранение контекста решения — через полгода видно, какие ограничения, NFR и альтернативы учитывались; без post-rationalization после релиза.
• Единая точка «почему» — User Story, API spec, схема БД и BPMN ссылаются на ADR-ID, не дублируя обоснование в каждом артефакте.
• Управляемый жизненный цикл — до принятия: Proposed → Accepted | Rejected | Withdrawn; после принятия: Accepted → Deprecated | Superseded by ADR-NNN. Смена решения = новый ADR, а не правка старого «задним числом».
• Трассировка требований → архитектура — BRD/SRS/NFR попадают в Context и Decision drivers; ADR объясняет, как архитектурный ответ закрывает требование и снимает конфликт между REQ — 02.05.01 Управление зависимостями между требованиями; структура связей — 10.01.15 Шаблон матрицы трассировки, концепция — 02.03.04 Трассировка требований (концепция).

ADR фиксирует архитектурный компромисс или выбор — технический, интеграционный или business-level (03.01.01 Понятие архитектуры ИС и её виды (бизнес-, системная, техническая)): граница bounded context, sync vs EDA, выбор паттерна (01.06 Принципы и паттерны проектирования решений). Не контракт API и не пошаговый сценарий. Детали эндпоинтов — в 10.01.04 Шаблон спецификации REST API; измеримые пороги качества — в 10.01.12 Шаблон нефункциональных требований (NFR).

Decision log — реестр всех ADR проекта; формат и правила ведения — §3.0.

Immutability. В статусе Proposed блоки Options, Decision и Consequences можно дорабатывать до ревью. После любого финального статуса (Accepted, Rejected, Withdrawn, Deprecated, Superseded) не меняйте Decision, Options, Consequences и Source requirements — только опечатки, уточнение reviewers, смена статуса и поля Superseded by. Date обновляется только при смене статуса, не при правках текста решения.

2. Когда использовать

Подходит, если:

• выбираете стек, паттерн интеграции, границу микросервиса или модель данных на уровне системы (03.01.03 Декомпозиция системы на подсистемы и модули, 03.06.02 Основы Domain-Driven Design);
• решаете sync REST vs async events для сквозного потока (03.05.06 Event-Driven Architecture);
• меняете контракт, затрагивающий несколько команд или внешних потребителей;
• явный компромисс по NFR (latency vs consistency, cost vs availability, security vs time-to-market);
• отклоняетесь от корпоративного reference architecture — нужно зафиксировать обоснование;
• перед gate «готовность к разработке» (10.04 Чеклист аналитика перед стартом разработки) спорный пункт в спецификации требует архитектурного якоря;
• в refinement или architecture review (05.02 Scrum и Kanban (аналитик в Agile)) команда не может согласовать «почему» без формальной записи; в масштабируемых фреймворках — согласование с architecture board (05.03 SAFe и LeSS — аналитик в масштабируемых фреймворках).

Не подходит или требует дополнения, если:

• нужно описать что делает система для пользователя — 10.01.01 Шаблон User Story, 10.01.02 Шаблон Use Case;
• нужны поля, эндпоинты, схема сообщений — 10.01.04 Шаблон спецификации REST API, 10.01.05 Шаблон спецификации SOAP API, 10.01.06 Шаблон спецификации Producer (Kafka, RabbitMQ);
• нужна общая картина системы (компоненты, потоки, deployment) — HLD / C4 (06.03.05 C4-модель); ADR дополняет HLD точечными решениями, не заменяет его;
• нужен design doc / engineering spec с пошаговой реализацией, sequence diagram на уровне классов — отдельный артефакт; ADR фиксирует выбор, design doc — «как построить по выбранному»;
• нужен threat model, capacity plan, runbook или тест-план — отдельные артефакты; ADR может на них ссылаться;
• решение тривиально и не влияет на соседние команды — достаточно комментария в PR или meeting notes (критерий: «изменение затронет >1 артефакт 10.01 или >1 команду»).

Входные условия: границы scope согласованы (02.01.04 Определение границ решения (Scope Modelling)), релевантные FR/NFR из BRD/SRS известны. Для статуса Accepted — минимум две реальные альтернативы для сравнения; для Proposed достаточно problem statement и черновика options (см. §3.6).

Правило «одно решение — один ADR»: выбор REST vs gRPC — один ADR (03.05.02 Синхронные протоколы (REST, gRPC, GraphQL)); стратегия идемпотентности для конкретного API — другой. Смешение делает документ нечитаемым и ломает версионирование.

3. Структура документа

Скопируйте каркас из §3.0 в docs/adr/, Confluence или vault. Поля с пометкой обяз. для Accepted — см. §3.12; для Proposed — минимальный набор в §3.12. Лимит: 1–2 страницы; POC, диаграммы и протоколы встреч — в appendix или отдельных ссылках. Разделы §3.3–3.8 соответствуют классической тройке Nygard/MADR: Context → Options → Decision → Consequences (см. §7).

3.0. Бланк для копирования

Единый markdown-каркас; детали полей — в §3.1–3.11.

# ADR-NNNN: {Краткое название решения}
 
**Date:** YYYY-MM-DD · **Status:** Proposed | Accepted | Rejected | Withdrawn | Deprecated | Superseded
**Authors:** …
**Reviewers:** …
**Approvers:** … *(только для Accepted)*
**Supersedes:** ADR-… *(если заменяет прежнее решение)*
**Superseded by:** ADR-… *(заполняется при смене решения)*
 
## Summary
{2–4 предложения: проблема, выбор, главное последствие}
 
## Context
**Problem statement:** …
**Scope (in):** …
**Out of scope:** …
**Source requirements:** `BRD-…`, `SRS-REQ-…`, `US-…`
 
## Requirements и constraints
**NFR / constraints:** `NFR-…`, `CON-…` — по ID из NFR-реестра
**Functional drivers:** … *(опционально)*
 
## Decision drivers
1. … *(критерии сравнения options; не дублируйте числовые пороги из NFR)*
 
## Options considered
| Option | За | Против | Verdict |
|--------|-----|--------|---------|
| A. … | … | … | Rejected / Selected / TBD |
| B. … | … | … | … |
 
## Decision
**Принято:** … *(или «We will …» — один язык на весь ADR, см. §3.7)*
**Не делаем:** …
 
## Consequences
- *Positive:* …
- *Negative / risks:* …
- *Migration / rollout:* … *(если нужно)*
 
## Impact on artifacts
| Артефакт | ID / действие |
|----------|---------------|
| API spec | `API-…` — … |
| NFR | `NFR-…` — … |
 
## Open questions / Follow-up ADRs
…
 
## References
…

Decision log (минимум): README.md или index.md в каталоге ADR — колонки: ID, Title, Status, Date, Epic/Release, Authors. Один ADR = один файл; поиск по ID и статусу обязателен. Хранение в Git — 07.05 Системы контроля версий (Git) для документации. При Superseded цепочка читается по полю Superseded by: последний Accepted в цепочке = актуальное решение.

При конфликте двух Accepted ADR — эскалация approver + новый ADR; один из конфликтующих → Superseded или Deprecated. Просроченный Proposed без SLA ревью → Withdrawn или доработка.

На ревью ADR проверяйте: одно решение на документ; минимум две options; drivers согласованы с NFR-ID; Impact перечисляет затронутые spec; двусторонняя трассировка REQ ↔ ADR. Чеклист перед разработкой — 10.04 Чеклист аналитика перед стартом разработки; формальные техники ревью — 08.04 Рецензирование и инспекции (техники Фейгана).

3.1. Метаданные

3.2. Summary

3.3. Context и scope

3.4. Requirements и constraints

3.5. Decision drivers

3.6. Options considered

3.7. Decision

3.8. Consequences

3.9. Impact on artifacts

3.10. Open questions и follow-up

3.11. References

3.12. Чеклисты качества

Минимум для Proposed:

• Problem statement и Scope заполнены.
• Source requirements указаны (хотя бы черновые REQ/Epic).
• Reviewers назначены; статус и Date (= дата подачи на ревью) зафиксированы.
• Есть черновик options или явный TBD с планом доработки.

Перед Accepted (дополнительно к Proposed):

• Один ADR = одно архитектурное решение.
• Минимум две альтернативы с критериями отказа.
• Decision outcome и anti-decisions заполнены.
• Блок Consequences содержит negative paths и риски.
• Нет дублирования OpenAPI / DDL — только ссылки на spec.
• Impact on artifacts перечисляет затронутые шаблоны 10.01.
• Approvers зафиксированы; index decision log обновлён.
• При смене решения — новый ADR + старый → Superseded, не правка Decision.

Для Rejected:

• Options и Rejected because заполнены для каждого отвергнутого варианта.
• Decision outcome = явный отказ («ни один вариант не принят») или зафиксирован preferred path вне scope ADR.
• Date = дата решения о Rejected; содержимое Decision/Options после Rejected не меняется (immutability).

4. Пример заполнения

Сокращённый технический ADR для HR Portal — сервис leave-service (данные условны). Для интеграционного ADR (sync REST vs Kafka для уведомлений) или business-level (граница сервиса Leave vs Payroll) тот же каркас §3.0; options и Impact другие, без Redis/replica.

ID: глобальный счётчик 0014 в decision log продукта HR Portal; HR — навигационный префикс. Supersedes показывает замену прежнего решения; Follow-up — отложенный ADR, который позже получит Supersedes: ADR-HR-0014.

В репозитории продукта в Impact указывайте API-LEAVE-001, NFR-PERF-001 — без wiki. Ниже wiki-ссылки только для навигации в KB.

ADR-HR-0014 · Async read path через read replica и cache
Date: 2026-03-12 · Status: Accepted
Authors: SA Иванова, Architect Петров
Reviewers: Tech Lead leave-team, SRE Козлов
Approvers: Architect Петров
Supersedes: ADR-HR-0008 (read path только с primary + индексы; p95 не достигнут на POC)

Summary. Список заявок на отпуск при росте БД не укладывается в NFR-PERF-001 (p95 ≤ 300 ms). Принято: чтение списка — с read replica PostgreSQL + Redis cache invalidation по событиям; запись — только primary.

Context. GET /leave-requests на primary при 500k записей даёт p95 ~800 ms (POC LT-2026-02). Scope: leave-service, web UI модуля Leave. Out of scope: mobile app v1, полнотекстовый поиск. Source: BRD-GOAL-011, SRS-HR-LEAVE-v2 REQ-012, NFR-PERF-001, US-0247.

NFR / constraints. NFR-PERF-001 (p95 ≤ 300 ms @ 200 RPS); CON-TECH-001 (PostgreSQL 15, без смены СУБД); CON-DATA-001 (ПДн в контуре РФ).

Decision drivers (по убыванию): 1) latency p95; 2) time-to-market (релиз v2.1 через 6 нед.); 3) operational cost; 4) consistency для списка (eventual допустима до 30 s).

Options considered:

Decision. Принято: маршрутизировать GET /leave-requests на read replica; Redis cache TTL 60 s с invalidation по domain events при create/update/delete. Запись — только primary. Не делаем: Elasticsearch в v2.1.

Consequences.

• Positive: p95 ~220 ms на stage POC; разгрузка primary.
• Negative: eventual consistency до 30 s; мониторинг replication lag; runbook cache stampede.
• Risks: replica lag > 30 s нарушает UX — alert pg-replica-lag-leave.
• Migration / rollout: v2.1 — feature flag read-from-replica; неделя dual-read на stage; rollback — flag off.

Impact on artifacts:

Open questions: стратегия cache warming при cold start — owner SRE, до 2026-03-20.

Follow-up ADR: ADR-HR-0015 (полнотекстовый поиск) — отложено post v2.1. При принятии 0015: Supersedes: ADR-HR-0014, у 0014 → Superseded by: ADR-HR-0015, Date обновляется на дату supersede.

5. Связанные артефакты

На входе (upstream)

На выходе (downstream)

Как пользоваться шаблоном (кратко)

1. Спорный пункт в refinement (05.02 Scrum и Kanban (аналитик в Agile)) → ADR Proposed; BA передаёт context/drivers, SA — options и POC.
2. Ревью reviewers (09.06 Ведение переговоров с техническими командами при эскалации); после согласования — Accepted.
3. Обновить spec по Impact; трассировка в 10.01.15 Шаблон матрицы трассировки.
4. Смена принятого решения — новый ADR, старый → Superseded.
5. Формальное согласование изменения scope/контракта через CCB — 02.05.02 Управление изменениями (Change Control Board). Reprioritization backlog без смены архитектуры — 02.05.02 Управление приоритетами в условиях изменчивости (не путать с CCB).
6. Rejected — обсудили, не приняли; Withdrawn — сняли до решения.

6. Связи с другими разделами базы

Только то, что не разобрано выше:

• Паттерны распределённых систем — 03.06.01 Архитектурные паттерны распределённых систем
• Интеграции — 03.01.04 Интерфейсы и интеграционные взаимодействия, 03.05.02 Синхронные протоколы (REST, gRPC, GraphQL), 03.05.06 Event-Driven Architecture
• Жизненный цикл требования после ADR — 02.05.05 Жизненный цикл требования

7. Источники и дополнительные материалы

Структура §3.3–3.8 следует канону Context / Options / Decision / Consequences (Nygard, MADR); теория «зачем ADR» — 03.01.01 Понятие архитектуры ИС и её виды (бизнес-, системная, техническая).

Статьи и практики

• Michael Nygard — Documenting Architecture Decisions (классическая тройка Context / Decision / Consequences) — https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
• Architecture Decision Records (adr.github.io) — каталог форматов и decision log — https://adr.github.io/
• Markdown ADR (MADR) — расширенный шаблон полей (drivers, options, consequences) — https://adr.github.io/madr/
• MADR (репозиторий шаблона) — https://github.com/adr/madr
• AWS Prescriptive Guidance — Architecture decision records — https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/
• Joel Parker Henderson — Architecture decision record (коллекция шаблонов и примеров) — https://github.com/joelparkerhenderson/architecture-decision-record