Журнал технических решений: зачем записывать «почему»

Коротко. Код фиксирует, что сделано, но не сохраняет, почему выбрано именно это. Через полгода причина забывается, и команда либо повторяет обсуждение с нуля, либо меняет решение, не зная о причине, по которой оно было принято. Журнал технических решений — короткие записи по одной странице: контекст, варианты, выбор и его последствия. В инженерной практике такой формат известен как ADR (architecture decision record). Ключевая часть записи — не решение, а отвергнутые варианты и причина отказа: именно они не восстанавливаются потом никакими усилиями и именно из-за их отсутствия начинаются повторные споры.

Код помнит, что выбрано. Причину выбора не помнит ничто, кроме записи

Какую проблему это решает

Четыре знакомые ситуации:

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

Повторные обсуждения. Один и тот же спор возвращается каждые несколько месяцев, потому что аргументы нигде не зафиксированы.

Онбординг. Новому человеку приходится реконструировать логику системы по коду. Журнал решений сокращает это радикально: онбординг нового сотрудника.

Смена контекста. Условия изменились, и решение стоит пересмотреть — но чтобы понять, изменились ли именно те условия, нужна исходная причина.

Что записывать

Минимальный состав записи — четыре блока:

Контекст. Какая задача стояла и какие ограничения действовали на тот момент: сроки, объём, доступные технологии, размер команды.
Рассмотренные варианты. Два-три реальных, а не формальные «варианты для галочки».
Решение. Что выбрано.
Причина и последствия. Почему выбрано и что мы теперь принимаем как плату за это: чего не сможем, что усложнится, что придётся делать вручную.

Самый ценный блок — второй вместе с четвёртым. Записанное «мы отказались от X, потому что Y» экономит месяцы: когда через год кто-то предложит X, разговор начнётся с проверки, изменилось ли Y, а не с нуля.

Шаблон записи

Дата, автор
Статус: предложено / принято / заменено на #N

Контекст
Что решаем и какие ограничения действуют.

Варианты
1. Вариант A — плюсы, минусы.
2. Вариант B — плюсы, минусы.
3. Вариант C — плюсы, минусы.

Решение
Выбран вариант B.

Причина
Почему именно он — 2-3 предложения по существу.

Последствия
Что усложняется, чем платим, что придётся пересмотреть при изменении условий.

Одна страница — верхний предел. Запись на десять страниц не будет ни написана, ни прочитана.

Какие решения стоит записывать

Стоит:

выбор технологии, библиотеки, протокола, формата данных;
решения, которые трудно отменить: схема данных, границы сервисов, публичные интерфейсы;
отказ от очевидного решения — особенно важно, потому что вызывает больше всего вопросов потом;
компромиссы под сроки: «сделали быстро и знаем, чем платим»;
решения, вызвавшие спор в команде;
всё, что нарушает принятые в проекте соглашения (и причина, почему).

Не стоит:

рутинные решения внутри одной задачи;
то, что очевидно из кода;
вкусовые предпочтения по форматированию — для этого есть соглашения;
решения, которые легко и дёшево отменить.

Практичный критерий: если через год кто-то спросит «почему так?», запись нужна.

Где хранить

Три рабочих варианта, по убыванию надёжности:

в репозитории рядом с кодом (например каталог docs/decisions с файлами по номеру). Плюс: живёт вместе с кодом, версионируется, видно в ревью. Это стандартная практика для ADR;
в вики проекта. Удобнее для чтения не-разработчиками, легче теряется при смене инструмента;
в трекере задач. Ближе к контексту, но плохо ищется через год.

Главное правило — одно место и понятная навигация. Журнал, разбросанный по чатам и почте, не существует.

Как не превратить в бюрократию

Самая частая причина смерти такой практики — она становится обязанностью без пользы. Что помогает:

писать после решения, а не до. Журнал не заменяет обсуждение и не должен его тормозить;
10 минут на запись. Не идеальный документ, а понятный текст;
записывать выборочно. Пять записей в год лучше, чем пятьдесят никем не читаемых;
включать в ревью. Если запись проходит вместе с кодом, она не забывается;
не требовать формальностей. Никаких обязательных согласований и шаблонов на десять полей;
не использовать как отчётность. Как только журнал становится инструментом контроля, содержание в нём вымывается — тот же эффект, что и с личным журналом работы и вообще с любым показателем: закон Гудхарта.

Что делать с устаревшими записями

Записи не удаляются — они получают статус.

«принято» — действует;
«заменено на #N» — решение пересмотрено, ссылка на новую запись;
«отменено» — от подхода отказались, причина указана.

Так сохраняется история изменений мышления команды, а это отдельно полезная вещь: по ней видно, какие предположения регулярно оказываются неверными.

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

Чек-лист

Запись содержит контекст, варианты, решение, причину и последствия.
Отвергнутые варианты записаны с причиной отказа.
Объём — одна страница, время на запись — около 10 минут.
Записываются только решения, которые трудно отменить или вызвали спор.
Хранение в одном месте, желательно в репозитории рядом с кодом.
Запись проходит вместе с кодом в ревью.
Устаревшие записи получают статус, а не удаляются.
Журнал не используется как отчётность перед руководством.

FAQ

Что такое журнал технических решений? Набор коротких записей о принятых решениях: контекст, рассмотренные варианты, выбор, причина и последствия. В инженерной практике такой формат известен как ADR — architecture decision record.

Зачем записывать, если решение видно в коде? Код показывает, что сделано, но не сохраняет, почему выбрано именно это и от чего отказались. Именно причина не восстанавливается потом и вызывает повторные споры.

Какой длины должна быть запись? Одна страница максимум, около 10 минут на написание. Более объёмные документы не пишут и не читают.

Какие решения записывать? Те, которые трудно отменить (схема данных, границы сервисов, публичные интерфейсы), выбор технологий, отказ от очевидного варианта, компромиссы под сроки и всё, что вызвало спор.

Где лучше хранить журнал? В репозитории рядом с кодом: он версионируется, попадает в ревью и не теряется при смене инструментов. Вики и трекер тоже подходят, но менее надёжны.

Что делать, если решение устарело? Не удалять запись, а поставить статус «заменено на #N» со ссылкой на новую. История пересмотров сама по себе полезна.

Как заставить команду вести журнал? Не заставлять, а встроить: писать только по важным решениям, тратить на запись десять минут и включать её в ревью вместе с кодом. Обязательность без пользы убивает практику.

Опубликовано: 12 августа 2026 г.