ЖУРНАЛ РЕШЕНИЙ · ПРАКТИКА

Как ввести практику журналирования решений в команде

Журнал решений - это не «ещё один документ для команды». Это конкретные правила: когда писать запись, а когда не нужно; как настроить так, чтобы AI-агент (Claude Code, Cursor, Codex) читал ваш контекст на старте сессии и не предлагал заново отвергнутые варианты; как выглядит день инженера, у которого журнал вписан в процесс - без перегруза и бюрократии.

Когда писать запись, а когда нет

Самая частая ошибка - пытаться записывать каждое решение. Это утомляет и быстро отбивает желание. Хорошее эмпирическое правило: запись стоит писать, если ответ «да» хотя бы на два из четырёх вопросов ниже.

Шкала глубины задачи - сколько и каких записей

Не все задачи требуют одинакового набора документов. Сложилась эмпирическая шкала из четырёх уровней - она хорошо коррелирует с риском и обратимостью задачи. На каждом уровне свой минимальный набор записей.

На практике быстрее всего определить уровень по двум вопросам: «легко откатить?» и «затронут ли другие команды?». Если оба ответа «нет» - тактический. Если первый «да», второй «нет» - стандартный. И так далее. Подробный калькулятор уровня (с интерактивными слайдерами) - в одном из дальнейших уроков серии.

Типичный день инженера с журналом в процессе

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

• 09:15 · УТРО · ВХОЖДЕНИЕ В КОНТЕКСТ
  Открываю каталог решений в проекте. Бегло смотрю активные записи и те, у которых приближается условие пересмотра. Это даёт картину «что сейчас в работе» и сигнал «вот это пора обсудить».
• 09:30 · НАЧАЛО ЗАДАЧИ
  Беру в работу тикет «оптимизировать обработку загрузки файлов». Прохожу два вопроса шкалы глубины (легко откатить? затронуты другие команды?) - получается стандартный уровень. Создаю заготовку документа продукта - это либо markdown по шаблону, либо запись в выбранном инструменте.
• 10:00 · ТРИ ВАРИАНТА · ПРОВЕРЯЕМЫЕ СЛЕДСТВИЯ
  Заполнил основные разделы. Выписываю три варианта реализации с проверяемыми следствиями (если выбираем вариант А, должно наблюдаться X; если Б - Y; если В - Z). Час уходит на прогон трёх прототипов, метрики записываются как доказательства. Эту работу я бы делал и без журнала - просто без фиксации.
• 14:00 · РЕАЛИЗАЦИЯ
  Запускаю AI-агента, у которого в инструкции прописано «прочитай активные решения проекта перед началом задачи». Агент не предлагает вариант, который мы вчера отвергли в обсуждении - потому что отвергнутые альтернативы записаны и агент их видит.
• 17:30 · ФИКСАЦИЯ РЕЗУЛЬТАТА
  Реализация готова, замер показал нужные числа. Создаю короткую запись доказательства (одна страница: что замерили, на каких данных, какой результат). Привязываю её к решению. Перевожу решение в статус «активное» - теперь файл не редактируется напрямую, только через создание новой версии, которая явно заменяет старую.
• 18:00 · ЗАКРЫТИЕ ДНЯ
  Открываю pull request. В описании ссылки на связанные записи. Ревьюер читает их перед код-ревью и приходит с правильным контекстом, а не «давайте вспомним, что мы тут хотели сделать».

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

Как AI-агент читает ваш контекст на старте сессии

Это самая важная часть для тех, кто кодит с AI-помощником. Без записей решений каждая новая сессия с Claude Code или Cursor начинается с пустого контекста: агент не знает, что у вас выбрана библиотека X, он каждый раз предлагает Y. С записями агент читает активные решения на старте и работает уже в правильных рамках.

Три способа подключения, от простого к продвинутому.

Способ 1 · Просто текстовые файлы в репозитории

Записи лежат в выделенном каталоге проекта как обычные markdown-файлы. Любой AI-агент, у которого есть доступ к файлам, может их прочитать. Достаточно одной строки в системной инструкции (типа CLAUDE.md, .cursorrules или эквивалент):

# CLAUDE.md или .cursorrules
Перед началом любой задачи прочитай файлы в каталоге docs/decisions/
со статусом active. Это активные архитектурные решения проекта.
Не предлагай варианты, которые явно записаны как отвергнутые.

Этого достаточно для 80% случаев. Не нужен ни плагин, ни специальная интеграция - агент сам подгрузит контекст из текстовых файлов.

Способ 2 · Через тулинг вашего агента

У современных агентов есть свои механизмы подключения внешнего контекста - Cursor Rules для Cursor, slash-commands и подключаемые инструменты в Claude Code, custom GPTs у OpenAI. Каждый из них может забирать записи решений по своей схеме: целиком, по запросу, по seman­ti­че­ско­му поиску. Если у инструмента есть свой механизм подключения данных - используйте его, он будет эффективнее, чем каждый раз читать файлы целиком.

Способ 3 · Гейты в процессе непрерывной интеграции

Самый строгий вариант: pull request не сливается, если затронуты файлы, для которых нет активного решения. Это не «бюрократия» - это защита от случайного обхода уже принятых ограничений. Реализуется обычным шагом в CI (GitHub Actions, GitLab CI, Buildkite - что используете), который сравнивает diff с каталогом решений и блокирует merge, если найдено расхождение.

Пять способов работы агента с записями

После подключения агент может делать одно из пяти. Конкретные сценарии - что вы можете попросить и что произойдёт.

Что показать новому члену команды в первый день

Если у команды уже есть журнал решений, новый человек должен пройти четыре шага в первый день, чтобы войти в курс. Это занимает суммарно час.

1. Открыть каталог решений и посмотреть структуру. Это покажет, какие типы записей живут в проекте.
2. Бегло просмотреть активные записи - отсортировать по дате, прочитать 10-15 самых свежих. Не вчитываться, просто понять «о чём команда вообще принимает решения».
3. Открыть граф связей (если у вас есть визуализация) или просто посмотреть, какие решения ссылаются друг на друга. Это покажет, как устроена «карта» проекта.
4. Попробовать создать одну тестовую запись (например, заметку о наблюдении первого дня). Это снимает страх «а вдруг что-то сломаю».

После этих четырёх шагов человек знает: где живут решения, как их читать, как создавать новые, как они связаны. Дальше обучение происходит органически - на конкретных задачах.

Антипаттерны: чего не делать

Шесть типовых ошибок, которые я видел в командах, начавших вести журнал решений. Каждая снижает доверие к процессу и приводит к отказу от практики через 2-3 месяца.

С чем интегрируется и что не заменяет

Чтобы было понятно, во что встаёт журнал решений и что от него нужно оставить отдельным инструментам.

Хорошо интегрируется

• git - записи живут рядом с кодом, в том же репозитории. История правок видна через git log.
• AI-агенты (Claude Code, Cursor, Codex и другие) - через прямое чтение файлов или через специализированные протоколы.
• CI/CD (GitHub Actions, GitLab CI, Buildkite) - гейты перед слиянием, проверка соответствия pull request активным решениям.
• Slack / Telegram - уведомления о приближающихся условиях пересмотра через простой скрипт.
• Системы мониторинга (Grafana, Datadog, Prometheus) - метрики из панелей мониторинга как триггер пересмотра.

Не заменяет

• Jira / Linear / Trello - управление задачами и сроками. Журнал решений не знает, кто что делает прямо сейчас и когда дедлайн.
• Notion / Confluence - общие документы, дизайн-системы, заметки со встреч. Не для пересказа митингов.
• Slack / Discord - коммуникация. Решения записываются после обсуждения в чате, не вместо него.

Куда дальше

После двух нулевых уроков - серия из двенадцати разборов конкретных частей процесса. Выбор зависит от того, что для вас сейчас актуальнее.