ADR и design doc: context, decision, consequences
Тема дорожной карты · Английский для IT
🔊 Словарь терминов с произношением →
ADR (architecture decision record) — короткий документ, фиксирующий одно архитектурное решение: почему оно принято, какие были альтернативы и к чему оно приведёт. Формат придумал Майкл Найгард в 2011 году, и его классическая структура состоит из четырёх разделов: Title — заголовок с номером и сутью (ADR-004: Use SQLite instead of Postgres); Context — контекст: какая проблема, какие ограничения, какие силы действуют; Decision — решение, сформулированное в активном залоге (We will use SQLite for all persistence); Consequences — последствия, и хорошие, и плохие, включая то, что становится сложнее. Добавляют Status (Proposed, Accepted, Deprecated, Superseded by ADR-007), Alternatives considered — рассмотренные варианты с причинами отказа, Date, Deciders. ADR неизменяем: если решение меняется, пишут новый ADR и помечают старый как superseded. Design doc (design document, technical design, RFC во внутреннем смысле) — более длинный документ, описывающий проектируемую систему до написания кода: Overview / Summary, Goals и Non-goals — чего не делаем, Background / Motivation, Proposed design / Detailed design, Alternatives considered, Trade-offs, Risks / Open questions, Security considerations, Rollout plan / Migration, Testing strategy, Monitoring / Observability, Timeline / Milestones, Success metrics, Appendix. Ключевые слова: rationale — обоснование, constraint — ограничение, assumption — допущение, trade-off — компромисс, non-goal — намеренно не цель, out of scope, open question, decision driver — фактор решения, option / alternative, pros and cons — за и против, reversible / irreversible — обратимое / необратимое (one-way door, two-way door), lightweight — лёгкий (об ADR), supersede — заменить собой, deprecate, sign-off — утверждение, stakeholder, reviewer, approver, consensus, disagree and commit — не согласен, но выполняю.
Как произносится
ADR по буквам /ˌeɪ diː ˈɑːr/, architecture /ˈɑːrkɪtɛktʃər/, decision /dɪˈsɪʒən/, record /ˈrɛkɔːrd/, context /ˈkɒntɛkst/, consequences /ˈkɒnsɪkwənsɪz/ (ударение на первый слог, «кОнсиквенсиз»), rationale /ˌræʃəˈnɑːl/ («рэшэнАл», не «рэшнл»), constraint /kənˈstreɪnt/, assumption /əˈsʌmpʃən/, alternative /ɔːlˈtɜːrnətɪv/, trade-off /ˈtreɪd ɒf/, superseded /ˌsuːpərˈsiːdɪd/, deprecated /ˈdɛprəkeɪtɪd/, proposed /prəˈpoʊzd/, accepted /əkˈsɛptɪd/, design /dɪˈzaɪn/ (g немая), non-goal /ˌnɒn ˈɡoʊl/, scope /skoʊp/, stakeholder /ˈsteɪkhoʊldər/, reversible /rɪˈvɜːrsəbl/, milestone /ˈmaɪlstoʊn/, appendix /əˈpɛndɪks/, rollout /ˈroʊlaʊt/, consensus /kənˈsɛnsəs/.
Как употребляется
Компактный ADR:
# ADR-004: Use SQLite for all persistence Status: Accepted, 2026-05-12. Context: we run on Raspberry Pi hardware with no ops team. Postgres would add a second process to monitor, back up and upgrade. Expected load is under 50 writes per second. Decision: we will use SQLite via better-sqlite3 for all persistence, with WAL mode enabled. Consequences: simpler deployment and backups (one file); no network access to the DB from other hosts; horizontal scaling of writers is not possible without a redesign. If write load exceeds 500 per second, this decision should be revisited. Alternatives considered: Postgres (rejected: operational cost), embedded Postgres (rejected: immature tooling).
Фразы: Let's write an ADR before we commit to this. — Напишем ADR, прежде чем закладываться. What's the rationale for the non-goal? — Каково обоснование того, что это не цель? That's a one-way door; we need sign-off. — Это необратимое решение, нужно утверждение. I disagree, but I'll commit. — Не согласен, но выполню. This ADR supersedes ADR-002. — Этот ADR заменяет ADR-002.
Ловушки
Первая ловушка — писать ADR как документацию системы: ADR фиксирует решение и причины, а не описывает архитектуру целиком. Вторая — редактировать принятый ADR: пишите новый и помечайте старый superseded. Третья — consequences только положительные: раздел существует ради честного перечисления того, что станет хуже. Четвёртая — rationale произносить как rational: это «рэшэнАл», обоснование. Пятая — пропускать Non-goals в design doc: без них обсуждение расползается. Шестая — decision в пассиве (it was decided): пишите we will, чтобы было видно, кто решил. Седьмая — alternatives considered без причин отказа: «рассмотрели Postgres» бесполезно, нужно «отказались, потому что». Восьмая — путать ADR и RFC: RFC открыт для обсуждения до решения, ADR фиксирует принятое.