Судья пишет, какие доказательства рассмотрены, какие отвергнуты и почему. Через год дело можно пересмотреть. Тот же приём нужен архитектурному решению - иначе через два квартала оно становится памятником. Разбираю шесть секций DDR, особенно последнюю - условия пересмотра.
Аналогия суда
Судья не говорит просто «виновен». Он пишет мотивировочную часть: какие доказательства рассмотрены, какие отвергнуты и почему, на каком основании сделан вывод.
Это не формальность. Через год, если появятся новые обстоятельства, дело можно пересмотреть. И у следующего судьи будет полная картина: что было решено тогда, почему именно так, какие альтернативы рассматривались и при каких условиях это решение могло бы быть другим.
Если бы судья писал «после рассмотрения остановились на этом приговоре», правовая система не работала бы. Невозможно было бы апеллировать, невозможно было бы создавать прецеденты, невозможно было бы понять, какой принцип лежит в основе решения.
В разработке мы пишем именно так: «после обсуждения остановились на JWT». Через полгода у команды нет ни мотивировки, ни рассмотренных альтернатив, ни условий пересмотра. Запись формально есть, но она бесполезна.
Первая статья серии в третьем посте уже намекнула на формат записи с условием пересмотра. Сегодня разберу его подробно - какие шесть секций, какая из них самая важная и почему её чаще всего пропускают.
Шесть секций DDR
DDR - короткая запись, которая ведёт команду к решению, а не описывает его постфактум. Шесть секций. Каждая закрывает один класс ошибок, который иначе всплывает через год.
Контекст. Один-два абзаца: какая ситуация на момент решения, какие ограничения, какие требования. Без этого через год невозможно понять, насколько решение применимо к новой ситуации. «Выбрали JWT» без контекста бесполезно. «Выбрали JWT, потому что у нас был единственный поставщик аутентификации и нужно было запустить интеграцию за две недели» - даёт через год возможность сказать «у нас сейчас три поставщика и нет дефицита времени, контекст другой».
Рассмотренные варианты. Минимум три. Не «выбор между JWT и сессиями», а «JWT с ротацией refresh-токенов, классические сессии в Redis, делегирование к внешнему OAuth-поставщику». Три варианта - эмпирический порог, ниже которого выбор почти всегда оказывается ложным.
Доказательства. На что опирались при выборе. Не «обсудили», а конкретные ссылки: «замер на наших данных», «документация поставщика», «опыт коллеги». Каждое доказательство с оценкой надёжности по логике из предыдущего поста серии: F/G/R и уровень контекстного соответствия.
Принятое решение. Одно предложение. «Выбираем JWT с ротацией refresh-токенов с TTL 7 дней».
Отвергнутые альтернативы. Каждая - с конкретной причиной отказа. Не «не подошло», а «Redis потребовал бы выделенного DevOps на поддержку, а у нас один на всё». Через год эта причина либо валидна - и решение остаётся, либо устарела - и пора пересмотреть.
Условия пересмотра. Самая важная секция, которую пропускают чаще всех других. При каком событии, метрике или дате это решение нужно открыть заново. Что-то, что сработает само, без подвига памяти команды.
Почему шестая секция самая важная
Возьмём типичный сценарий: год назад команда приняла решение «не запускать бесплатный тариф». Причины записаны: «команда поддержки на 4 человека, нагрузка от бесплатных пользователей задавит». Через год: автоматизация поддержки выросла, обращений меньше. Поддержка готова, но никто не понимает, что решение пора пересматривать, потому что в записи нет триггера.
Решение остаётся в силе по инерции. Через ещё полгода кто-то на встрече по результатам квартала говорит «а почему мы не делаем фримиум, как все конкуренты?». Команда садится, обсуждает, заново перебирает все аргументы. Тратит две недели на то, что в исходной записи могло бы быть одной строкой.
С условием пересмотра: «вернуться, если поддержка автоматизирует 80% обращений или конверсия в платный поднимется выше 12%». Через полгода метрика поддержки достигла 78%, конверсия - 14%. Решение само себя открывает на пересмотр, без чьего-то героизма. Команда садится, читает старую запись с альтернативами, принимает новое решение за 30 минут.
Эта одна секция превращает запись из памятника в живой документ. Без неё любая фиксация решения становится «так решили тогда, не трогаем».
Условие может быть разным:
- метрика: «пересмотреть, если время верификации JWT превысит 5 мс»
- срок: «пересмотреть через год, в любом случае»
- событие: «пересмотреть, если откроется европейский рынок»
- релиз: «пересмотреть, когда выйдет следующая major-версия библиотеки»
Главное - событие должно быть наблюдаемым автоматически. «Пересмотреть, когда станет проблемой» - не работает, потому что никто не следит. «Пересмотреть, когда метрика X превысит Y» - работает, потому что метрику можно поставить под алёрт.
Срок годности доказательств
С условием пересмотра связана вторая идея: доказательства, на которые опиралось решение, тоже имеют срок годности.
Бенчмарк прошлого года для одной версии библиотеки уже не валиден для новой. Производственное наблюдение на 50 запросах в секунду не применимо к 500. Опыт коллеги в проекте на Postgres 12 не переносится напрямую на Postgres 16.
Хорошая запись это признаёт заранее. У каждого доказательства - пометка «валидно при условиях X, перепроверить, если изменилось Y». Когда нагрузка вырастает в десять раз - система автоматически помечает доказательство как «устарело», и связанное с ним решение попадает в очередь на пересмотр.
Это вторая защита от ситуации «у нас же есть запись про кэш». Запись есть, но доказательства, на которых она держалась, - нет. И никто не заметил, потому что никто не проверял.
Длина записи
Когда я первый раз показал шесть секций в команде, реакция была: «У нас нет времени на такие документы».
Эта реакция основана на неправильной картинке. Люди представляют, что DDR - это документ на двадцать страниц с подписью DevOps-директора.
В реальности - 200-400 слов в одном markdown-файле. Одна экранная страница. Пять-десять минут на заполнение шести секций. Никаких новых инструментов: достаточно каталога docs/decisions/ в репозитории и одного правила команды.
Если получается две тысячи слов - никто к этому не вернётся через месяц. Запись должна читаться за две минуты, иначе её роль не выполняется. Длинный документ - это лекция, а DDR должен быть справкой.
Жёсткое ограничение: одна экранная страница, без «уточняющих приложений». Если что-то не помещается - значит, это не «контекст для одного решения», а отдельное решение, которому нужна своя запись.
Конкретный пример: решение, которое само себя открывает
Расскажу один кейс, изменю детали.
Команда B2B-продукта два квартала назад приняла решение «не запускать бесплатный тариф». Записали в DDR. Все шесть секций:
- Контекст: команда поддержки 4 человека, при текущем потоке клиентов справляется едва. Конверсия в платный - 8%. Прогноз: бесплатный тариф приведёт в десять раз больше обращений, поддержка лопнет.
- Рассмотренные варианты: запуск полноценного бесплатного тарифа без ограничений; ограниченный бесплатный (без поддержки, только документация); пилот для двадцати компаний-партнёров.
- Доказательства: замер обращений в поддержку от существующих платных пользователей (8 обращений на пользователя в год); оценка времени работы на обращение (40 минут); расчёт нагрузки при росте пользователей в 10 раз; опыт двух знакомых SaaS-команд с похожей моделью.
- Принятое решение: не запускаем бесплатный тариф до улучшения автоматизации поддержки.
- Отвергнутые альтернативы: полноценный бесплатный - задавит поддержку; ограниченный без поддержки - портит репутацию (пользователи не отличают «бесплатно без поддержки» от «бесплатно с плохой поддержкой»); пилот для партнёров - рискуем испортить отношения, если перестанем тянуть.
- Условия пересмотра: вернуться, если поддержка автоматизирует 80% обращений ИЛИ если конверсия в платный поднимется выше 12% ИЛИ через год в любом случае.
Через шесть месяцев менеджер по поддержке выкладывает квартальный отчёт: автоматизировано 78% обращений (бот закрывает большую часть стандартных запросов). Метрика автоматически попадает в дашборд DDR - система видит «триггер пересмотра DDR-014 близок». Через ещё две недели метрика переваливает 80%. Команда садится за DDR-014, читает старые альтернативы. Сейчас они выглядят иначе:
- Полноценный бесплатный - нагрузка с автоматизацией уже не страшна. Лучше.
- Ограниченный без поддержки - больше не нужно, поддержка теперь справляется. Лучше.
- Пилот для партнёров - потеряло актуальность, прошёл этап взросления.
Решение пересматривается за 30 минут. Запускают ограниченный бесплатный тариф (быстрее всего и проверяет гипотезу спроса). Через квартал - если работает - расширяют до полного.
В этом весь смысл DDR. Не «зафиксировать что было сказано», а «сделать так, чтобы через полгода команда без подвига памяти знала, когда вернуться к вопросу».
Что отдать AI-агенту, что - себе
AI-агент хорошо делает первый черновик DDR: собирает контекст из обсуждения в чате или из pull request, выписывает альтернативы (если в обсуждении они звучали - даже мельком), предлагает условия пересмотра по шаблону «при достижении метрики X порога Y».
Финальная секция, которую стоит писать рукой, - отвергнутые альтернативы с причиной. Агент не знает, что вы отвергли альтернативу не из-за функциональности, а потому что генеральный директор того поставщика недавно публично поссорился с вашим инвестором. Эта причина не появится в публичной документации, но именно она - настоящая мотивировка. Только человек её записывает.
Базовое правило: агент - черновик и шаблон, человек - настоящие причины. Если AI пишет 100% DDR - у вас не запись решения, у вас красивая отписка.
Что почитать дальше
Это четвёртый пост в серии. Предыдущие:
- Кладбище решений - почему запись без формата не спасает
- Перед тем как чинить - выпишите три версии - приём диагностики
- Среднее обманывает - как оценивать доказательства
Дальше:
- Как маленькое сообщение из чата превращается в продуктовый документ из 13 разделов без расползания рамок.
- Как отличить намерение от поведения, когда документируете требования.
К этому посту прилагается интерактивный шаблон DDR: можно ввести своё решение по шести секциям и получить готовую запись с автоматическими триггерами пересмотра. Лежит в /guides.