ЖУРНАЛ РЕШЕНИЙ · БАЗА

Что такое журнал решений и зачем он нужен команде

Каждые полгода в любой команде звучит один и тот же вопрос: «а почему мы тут так сделали». Иногда находится человек, который помнит. Чаще - нет. Из этой повторяющейся боли выросла отдельная инженерная практика - журналирование решений. Конкретные форматы (ADR, DDR), шесть обязательных полей записи, причина почему «среднее» обманывает при оценке доказательств, и зачем у каждой записи должно быть условие пересмотра.

Что такое журнал решений

Журнал решений - это инженерная практика записи каждого архитектурного и продуктового выбора в едином структурированном формате. Цель - чтобы через год кто угодно мог открыть запись и понять: что было решено, почему именно так, и при каких условиях нужно вернуться к вопросу.

Аналогия из мира программирования: git хранит историю изменений кода. Кто, когда и что поменял; легко вернуться к любой версии. Журнал решений делает то же самое для решений: кто, когда и почему выбрал один из вариантов.

Аналогия для тех, кто не работает с git: представьте журнал бортовых решений капитана корабля. Туда заносится каждое серьёзное решение - почему отклонились от курса, почему изменили скорость, какие условия были на момент решения, при каких условиях нужно вернуться к первоначальному плану. Через полгода капитан или его сменщик могут открыть журнал и увидеть полную картину.

У практики есть устоявшиеся имена форматов. Они выработаны разными инженерными командами за последние 10 лет - не наше изобретение:

• ADR (Architecture Decision Record) - короткая запись архитектурного решения. Минимум: контекст, решение, последствия.
• DDR (Decision-Driven Record) - расширенная форма, где явно фиксируются доказательства и условия пересмотра. Это то, что разбираем дальше.
• Journal Entry - простой формат для команд, где архитектура меняется часто: только дата, событие и причина.

Знакомый сценарий

Понедельник, рабочий чат. Новый разработчик задаёт вопрос: «А почему у нас тут используется библиотека X, а не Y? Я вижу в коде X, но в документации проекта почти ничего нет».

Тишина в чате на десять минут. Кто-то наконец отвечает: «Мы это обсуждали полгода назад. Был длинный спор, выбрали X. Причины уже не помню - кажется, что-то про производительность. Или про лицензию. Точно скажет Алексей, но он сейчас в отпуске».

Знакомо? Это типовой сценарий, который повторяется в большинстве команд. Не потому что команда плохая, а потому что нет места, куда решения обязаны ложиться. Чат прокручивается. Вики забывается. Файл «meeting-notes-2025-03-12.docx» лежит в общей папке и никто его не открывает, потому что никто не знает что в нём.

Журнал решений - это попытка дать решениям конкретное место. Не «ещё один инструмент с подпиской», а файл рядом с кодом, в чёткой структуре, с обязательными полями. Когда новый разработчик через полгода спросит «почему X», ему отвечают одной ссылкой на файл - не «помню что обсуждали».

Это для меня?

Четыре типичных читателя, которым практика журналирования решений приносит ощутимую отдачу. Возможно, узнаете кого-то - себя или коллегу.

Что значит «решение» в этом подходе

Когда говорю «решение», я имею в виду конкретную структуру из шести обязательных полей. Если хотя бы одно поле пропущено - это не решение, это запись с дырой. Эти шесть полей - не наше изобретение, они выработаны практикой формата DDR (Decision-Driven Record).

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

Почему артефакты, а не чаты или вики

Главное возражение, которое я слышу: «Мы уже всё пишем в Slack, Notion или Confluence. Зачем ещё один формат?» Ответ: дело не в количестве, а в формате. Свободный текст не заставляет фиксировать то, что через год оказывается нужно.

Вот реальный замер: для одной и той же типовой команды я сравнил, у какого процента решений через шесть месяцев осталась читаемая мотивировка. Различия огромные, и не связаны с тем, насколько «правильно» работают с инструментом - только с тем, насколько формат заставляет фиксировать главное.

До и после: один день из жизни команды

Чтобы не оставаться в теории - вот сравнение двух команд, работающих над одной типовой задачей: «выбрать платёжного поставщика для нового европейского рынка».

Use-cases в разных сферах

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

Почему это важно именно сейчас, в мире AI

Один отдельный поворот, который заставил меня в это вложиться: AI меняет то, как мы принимаем решения, не в лучшую сторону по умолчанию.

Когда разработчик пишет код вместе с агентом (Claude Code, Cursor, Codex), каждая новая сессия начинается с чистого листа. Агент не помнит, что у вас уже выбрана библиотека X. Он каждый раз ищет «как принято в индустрии» и предлагает Y. Если у вас нет места, где живут решения - агент будет каждую сессию пытаться ввести то, что вы уже один раз отвергли.

Решение этой проблемы не в более умной модели. Решение в том, чтобы модели было что прочитать на старте. Файл с записями решений рядом с кодом - это и есть «контекст», который агент подгружает автоматически. Без такого файла каждая сессия будет начинаться со спора, который у вас уже был.

Для инженера автоматизации та же логика: когда автоматизирующий агент выполняет процесс, он должен прочитать на старте, какие правила действуют. «Сначала проверь дубли, потом отправь уведомление, не отправляй после 22:00» - это правила процесса, записанные как решения. Без них агент будет делать «как обычно», а не «как у вас принято».

Что разбирается дальше

Карточки ниже ведут к следующим разборам. Можно идти подряд - по одному в день. Можно открыть тот, который ближе к вашей текущей задаче.