ЖУРНАЛ РЕШЕНИЙ · ФОРМАТ

Как выглядит хороший DDR - шаблон с примером

Хороший DDR должен читаться за две минуты. Если вы открыли запись и за две минуты не поняли, что было выбрано, почему и при каких условиях нужно пересмотреть - запись сделана неправильно. Разбираю формат по частям и показываю, как он выглядит на реальном примере.

Что такое DDR

DDR - Decision-Driven Record - это расширенная форма записи решения. Классический ADR (Architecture Decision Record) существует уже больше десяти лет и по сути - четыре поля: контекст, статус, решение, последствия. Для многих случаев этого хватает.

DDR появился, когда выяснилось, что в классическом ADR легко пропустить две вещи, из-за которых запись через год становится бесполезной. Первое - доказательства: на что именно опирались при выборе. Второе - условие пересмотра: при каком событии нужно вернуться к этому вопросу. Без доказательств запись выглядит как мнение. Без условия пересмотра запись превращается в памятник - её перестают трогать, даже когда контекст давно поменялся.

Соотношение форматов:

• ADR - контекст, решение, последствия. Быстро, минималистично. Хорошо для небольших технических выборов с коротким горизонтом.
• DDR - всё из ADR плюс явные доказательства и условия пересмотра. Чуть дольше писать, но запись остаётся живой через год и три года.

Различие не в объёме - в содержании. DDR из 250 слов лучше ADR из тех же 250 слов, если в нём есть доказательства и условие пересмотра.

Шесть обязательных полей

Если хотя бы одно поле пропущено - это не DDR, это заготовка. Именно обязательность полей отличает живую запись от свободного текста.

1. 01 · КОНТЕКСТ
   В какой ситуации принимали решение
   Что было известно, какие ограничения действовали, каков был масштаб. Без этого через год невозможно понять, применимо ли решение к новой ситуации или контекст полностью изменился.
2. 02 · ВАРИАНТЫ
   Что рассматривали
   Минимум три варианта, каждый с кратким плюсом и минусом. Если вариантов меньше двух - выбора не было, и запись это должна отражать явно.
3. 03 · ДОКАЗАТЕЛЬСТВА
   На что опирались при выборе
   Конкретные источники: замер на своих данных, документация поставщика, опыт коллеги из другой команды. Каждое доказательство - с коротким указанием на его применимость к вашему контексту.
4. 04 · РЕШЕНИЕ
   Один вариант, одна строка
   Точная формулировка выбранного варианта. Без «остановились на», без «решили попробовать». По этой строке через год можно однозначно проверить, выполняется ли решение.
5. 05 · ОТВЕРГНУТЫЕ
   Почему другие варианты не подошли
   Каждый отвергнутый вариант с конкретной причиной. Не «не подходит», а «не подходит, потому что X». Через год эта причина либо валидна, либо устарела - и это само по себе сигнал к пересмотру.
6. 06 · УСЛОВИЯ ПЕРЕСМОТРА
   Когда вернуться к этому вопросу
   Самая важная и чаще всего пропускаемая секция. Конкретное событие, метрика или дата, при достижении которой запись нужно открыть заново. Без этого поля запись мертва с первого дня.

Полный пример

Ниже - реальная структура DDR-файла для конкретного решения: выбор механизма авторизации в приложении для заметок небольшой команды. Три варианта: JWT-токены, серверные сессии, OAuth через стороннего провайдера. Поля заполнены так, как они выглядели бы в практике.

# DDR-007: Механизм авторизации - JWT vs сессии vs OAuth

Дата:       2025-11-14
Статус:     активен
Автор:      Михаил Д.
Пересмотреть: если DAU превысит 5 000 или появится требование SSO

## Контекст

Приложение для личных заметок - 4 разработчика, один бэкенд на Node.js,
планируемый DAU 200-800 человек. Единственный требуемый тип входа -
email + пароль. Нет требований к SSO, нет корпоративных клиентов.
Инфраструктура: один сервер без горизонтального масштабирования.

## Варианты

A. JWT-токены
   + Не требует серверного хранилища состояния.
   − Отзыв токена сложен: нужен blacklist или короткий TTL + refresh.

B. Серверные сессии (httpOnly cookie + session store)
   + Простой отзыв: удалить запись из store.
   + Зрелые библиотеки, минимум логики на клиенте.
   − Требует постоянного серверного хранилища (Redis или DB-таблица).

C. OAuth через стороннего провайдера (Google, GitHub)
   + Нет собственной логики паролей.
   − Зависимость от внешнего сервиса; требует домена и HTTPS с первого дня.
   − Усложняет онбординг: пользователи без Google/GitHub аккаунта.

## Доказательства

1. Бенчмарк внутри команды: серверная сессия с PostgreSQL store -
   p95 проверки сессии 4 мс на нашем железе (замер 14.11.2025,
   1 000 параллельных запросов). Для нашей нагрузки достаточно.

2. Документация express-session: поддержка pg-simple store,
   production-ready, последнее обновление ноябрь 2025.

3. Опыт команды Аркадия (схожий стек, схожий DAU): перешли с JWT
   на сессии, потому что blacklist JWT добавил больше сложности,
   чем сэкономило отсутствие state. Субъективно применимо к нашей ситуации.

## Решение

Используем серверные сессии: express-session + pg-simple store в той же
PostgreSQL БД, которая уже есть в проекте.

## Отвергнутые варианты

A (JWT): отвергнут, потому что без горизонтального масштабирования
выгода JWT перед сессиями отсутствует, а сложность отзыва токена выше.

C (OAuth): отвергнут, потому что добавляет зависимость от внешнего
сервиса и усложняет онбординг при нашей целевой аудитории.

## Условия пересмотра

1. DAU превышает 5 000 - проверить, не стал ли pg-simple store узким местом.
2. Появляется требование SSO от корпоративного клиента - переходить на OAuth/SAML.
3. Переход на горизонтальное масштабирование - пересмотреть store (Redis).

Обратите внимание на несколько вещей. Первое: доказательства - конкретные. Не «по нашему опыту», а «замер 14.11.2025, 1 000 запросов, 4 мс». Второе: в отвергнутых вариантах каждая причина относится именно к нашему контексту - не «JWT сложный», а «выгода JWT исчезает без горизонтального масштабирования». Третье: условия пересмотра привязаны к конкретным триггерам, а не к абстрактному «при необходимости».

Длина и читаемость

Хороший DDR умещается в 200-400 слов основного текста. Это одна экранная страница при стандартном шрифте. Если запись длиннее - скорее всего, одно из двух: либо в неё пытаются запихнуть несколько несвязанных решений (нужно разбить на отдельные), либо объяснение пишется там, где должна быть ссылка.

Три ориентира по длине полей:

Самая частая ошибка - огромный контекст (5-10 абзацев), в котором пишут всё, что знали, плюс цитаты из документации. Это не контекст, это черновик встречи. Контекст - это минимум, достаточный для того, чтобы через год понять, при каких ограничениях принималось решение.

Вторая ошибка - решение на три абзаца. Поле «Решение» - это одна формулировка. Аргументацию несут другие поля. Если хочется объяснить решение - смотрите поля «Доказательства» и «Отвергнутые».

Глубже

Две темы, которые дополняют этот формат с разных сторон: формальный цикл, в рамках которого живёт DDR, и то, что происходит с записью после того, как она активирована.