Команды накапливают невидимый долг не в коде, а в забытых архитектурных решениях. Notion и Confluence эту проблему не решают - нужен другой формат записи. Разбираю, как выглядит этот долг на конкретных кейсах и что в формате решения должно быть, чтобы оно через год оставалось полезным.
Знакомый сценарий
Через полгода после релиза кто-то на ретро спрашивает: «А почему мы выбрали JWT, а не сессии?»
Вы помните, что обсуждение было. Помните, что был длинный спор в Slack. Помните, что выбор сделали в пятницу вечером перед демо. А вот почему именно JWT - уже нет.
Открываете Confluence - там пусто. ADR-шаблон в репозитории был, но его не заполнили. Пытаетесь найти Slack-нить - она ушла за горизонт поиска, потому что бесплатный план хранит 90 дней. Смотрите запись митинга - на этом месте ведущий говорит «давайте обсудим оффлайн», и обсуждение продолжилось в личке двух человек, один из которых уже уволился.
Вы делаете новый круг. Команда садится, тратит ещё два часа, приходит к тому же решению - потому что, скорее всего, причины тогда были правильные. Но подтверждения этому нет. И через следующие полгода всё повторится, потому что повторно принятое решение тоже не было задокументировано.
Это не редкий случай. Это типовая болезнь команд, которые растут быстрее, чем растёт их культура работы с решениями. Я хочу разобрать, почему она возникает, почему обычные инструменты её не лечат, и как выглядит выход - без необходимости менять весь процесс компании завтра же утром.
Это не проблема документации
Первый рефлекс: «нам нужна вики получше». Команда покупает Notion вместо Confluence. Или Confluence вместо Notion. Или заводит отдельную папку в Google Drive. Через три месяца - та же боль: страницы есть, но в них либо пусто, либо текст уровня «решили использовать JWT».
Корень проблемы не в инструменте, а в формате. Свободный текст не заставляет автора фиксировать те поля, которые через год оказываются нужны:
- Какие альтернативы были на столе?
- Почему отвергли каждую?
- На какие данные опирались при выборе?
- При каких условиях это решение нужно пересмотреть?
Свободный текст даёт автору соблазн написать «после обсуждения остановились на JWT» - и это технически правда, но через полгода это бесполезно. Хорошая документация - это не «больше текста», это структура, которая не даёт пропустить важное.
Сколько это стоит
Спросите себя: сколько раз за последний год ваша команда переоткрывала одно и то же архитектурное обсуждение?
Я веду грубую калькуляцию для команд, с которыми работал:
- Один инцидент «почему мы тут так сделали» - два-три инженера × неделя на пересмотр + переписку = шесть-девять человеко-недель.
- Таких инцидентов в средней команде на 8-15 человек - два-четыре в год.
- Это от двенадцати до тридцати шести человеко-недель в год на повторное обсуждение того, что когда-то уже было решено.
Если перевести в деньги для команды с медианной зарплатой инженера 250 тысяч рублей в месяц - это от полутора до пяти миллионов рублей в год. И это только видимая часть. Невидимая - то, что новый сотрудник тратит первые две недели на вопросы «а почему у нас тут вот так», и большую часть из них старшие коллеги не могут ответить уверенно. И то, что команда несколько раз в год меняет решение на ровном месте, потому что забыла оригинальную мотивировку, - и через пару месяцев откатывает обратно.
Эта стоимость не записывается ни в одном отчёте. Но она реальна, она повторяется, и она растёт по мере того, как команда становится больше и работает дольше.
Конкретный пример
Расскажу один кейс, изменю детали.
Команда, делающая B2B-продукт для финтеха, два года назад выбрала Stripe как платёжный поставщик. Решение принимали быстро - нужно было запускать платный тариф к началу квартала. Обсудили в чате, выбрали, начали интеграцию. Решение записали в ADR-документе в репозитории, но раздел «рассмотренные альтернативы» оставили пустым: «дозаполним позже».
Не дозаполнили никогда.
Через полтора года юрист поднимает вопрос: компания выходит в Европу, и Stripe требует, чтобы команда сама занималась налоговой отчётностью по странам ЕС. Один из инженеров вспоминает, что Paddle в своё время рассматривали как раз потому, что он эту отчётность брал на себя. Но никто не помнит, почему его не выбрали.
Дальше две недели команда заново сравнивает Stripe vs Paddle. Выясняется, что в день решения две года назад главным аргументом против Paddle был один ограниченный набор стран на тот момент, но за два года этот набор расширился. То есть решение было правильным тогда, но устарело. И никто не заметил, что оно устарело, пока новое требование не упёрлось в стену.
Если бы в оригинальном ADR была секция «при каких условиях пересмотреть», там могло бы стоять: «вернуться к выбору, если расширяем географию за пределы СНГ или появляются требования по налоговой отчётности по странам присутствия». Эта одна строка превратила бы две недели аврального переосмысления в плановый разбор за полтора часа.
Что должно быть в формате решения
Я долго думал, какая минимальная структура спасает от описанной проблемы. Пришёл к шести обязательным секциям. Каждая закрывает один класс ошибок, который иначе всплывает через год.
Контекст. Один-два абзаца: какая ситуация на момент решения, какие ограничения, какие требования. Без этого через год невозможно понять, насколько актуально решение для новой ситуации.
Рассмотренные варианты. Минимум три. Не «выбор между JWT и сессиями», а «JWT с ротацией refresh-токенов, классические сессии в Redis, делегирование к внешнему поставщику OAuth». Три варианта - это эмпирический порог, ниже которого выбор почти всегда оказывается ложным: либо выбирали из двух очевидных и не подумали о третьем, либо вообще не выбирали - просто пошли по первой версии.
Доказательства. На что опирались при выборе. Не «обсудили и решили», а конкретные ссылки: «замер на наших данных показал такие-то цифры», «документация поставщика говорит то-то», «опыт коллеги в похожем проекте». Каждое доказательство - с указанием, насколько оно сильное (свой замер на нашем проекте - сильнее, чем статья в чужом блоге).
Принятое решение. Одно предложение. «Выбираем JWT с ротацией refresh-токенов с TTL 7 дней».
Отвергнутые альтернативы. Каждая - с конкретной причиной отказа. Не «не подошло», а «не подошло, потому что Paddle в тот момент не работал с компаниями из СНГ как покупателями» или «классические сессии требуют отдельной поддержки Redis в проде, а у нас один DevOps на всё». Через год эта причина либо всё ещё валидна - и решение остаётся, либо устарела - и пора пересмотреть.
Условия пересмотра. Самая важная секция, которую пропускают чаще всех других. При каком событии, метрике или дате это решение надо открыть заново. «Пересмотреть, если расширяем географию за пределы СНГ» - годится. «Пересмотреть, если время верификации JWT превысит 5 мс» - годится. «Пересмотреть, если выйдет следующая major-версия библиотеки» - годится. Что-то, что сработает само, без подвига памяти команды.
Этот формат - не моё изобретение, на разные лады его называли разные люди. Я остановился на названии DDR (Decision-Driven Record) - короткая запись, которая ведёт команду к решению, а не описывает его постфактум.
Цена внедрения
Когда я первый раз показал эту структуру в команде, первая реакция была: «У нас нет времени на формальности».
Это нормальная реакция. И она в большинстве случаев основана на неправильной картинке: люди представляют, что DDR - это документ на двадцать страниц с подписью DevOps-директора.
В реальности - это 200-400 слов в одном markdown-файле. Пять минут на заполнение шести секций. Никаких новых инструментов: достаточно каталога docs/decisions/ в существующем репозитории и одного правила команды «каждое архитектурно значимое решение получает свой DDR-файл перед слиянием ветки».
Архитектурно значимое - это то, для чего через шесть месяцев кто-то будет искать ответ на «почему мы тут так сделали». Если задача - «исправить опечатку в README», DDR не нужен. Если задача - «выбрать платёжного поставщика», нужен.
Граница расплывчатая, и команда учится её чувствовать в первые две-три недели работы с форматом. Я обычно предлагаю начать с правила: «если задача обсуждалась в Slack-нити длиннее десяти сообщений или на синхронной встрече больше 20 минут - она заслуживает DDR».
Что отдать AI-агенту, что - себе
Один отдельный вопрос: можно ли заставить AI-агента писать DDR за нас?
Частично - можно. Agent (Claude Code, Cursor, любой кодовый ассистент) хорошо делает первый черновик: собирает контекст из Slack-нити или из обсуждения в pull request, выписывает альтернативы, предлагает условия пересмотра. За минуту он сделает то, на что человеку нужно 15-20 минут.
Но финальный выбор - особенно секцию «отвергнутые альтернативы с причиной» - стоит держать за собой. Агент не знает, что Paddle вы отвергли не из-за функциональности, а потому что генеральный директор того поставщика недавно публично поссорился с вашим инвестором. Эта причина никогда не появится в публичной документации, никогда не всплывёт в Slack-нити, но именно она - настоящая мотивировка. Только человек может это записать.
Базовое правило: агент - черновик, человек - содержание. Если AI пишет за вас 100% DDR - у вас не DDR, у вас красивая отписка. Если 0% - вы тратите ту самую неделю в год на формальности, которых можно избежать.
Что почитать дальше
Эта статья - первая в серии из восьми постов про дисциплину принятия архитектурных решений в командах, которые работают с AI-кодовыми ассистентами. Дальше я разберу:
- Как принимать архитектурное решение, чтобы не зафиксироваться на первой версии причины
- Как оценить надёжность доказательств - почему среднее обманывает, а минимум честнее
- Как выглядит формат DDR на практике, в развёрнутом виде
- Как одно маленькое Slack-сообщение превращается в продуктовый документ из 13 разделов без скоупа-монстра
- Как отличить намерение от поведения, когда документируете требования к функции
- Как все эти куски складываются в один инструмент - Forgeplan
- Как агент перестал галлюцинировать следующие шаги после введения простого контракта на вывод
Каждый пост сопровождается интерактивным разбором на /guides - там можно покрутить 3D-сцену с доказательствами в пространстве F/G/R, или попробовать калькулятор уровня глубины задачи, или посмотреть полный граф артефактов одного проекта.
Если хотите начать сразу с практики - главная страница серии разборов: /guides. Там навигация по типу «если ищете про X - начните с Y». Если хотите подождать следующий пост - он выйдет через неделю.