системный анализ · 7 минут
Decision Log для аналитика: журнал решений, которые вы приняли молча
Спросите себя, почему в вашей системе суммы хранятся именно так, как хранятся. Скорее всего, вы это решили. Скорее всего, за пять секунд. Скорее всего, нигде не записали и через месяц не вспомните критерий, по которому выбрали.
Такой выбор мы называем молчаливым решением: вы его сделали, никуда не записали и не заметили, что сделали. «Дубли схлопываем по email, а не по телефону». «Берём последнюю версию, а не актуальную на дату». «Отмену после оплаты в первой версии не поддерживаем». В момент принятия каждое выглядит очевидным. Через месяц оно не очевидно ни для кого.
Почему это перестало сходить с рук
Раньше сходило. Спецификацию читал человек, и часть молчаливых решений он восстанавливал сам: по интонации, по истории переписки, по тому, что «мы же обсуждали на созвоне».
Агент не восстанавливает ничего. Он берёт написанное, достраивает недостающее и выдаёт результат. Каждый раз достраивает по-своему. Отсюда та невоспроизводимость, на которую жалуются все, кто отдал агенту кусок работы: два прогона одной спецификации дают два разных результата, оба выглядят правдоподобно, и выбирать между ними приходится вам.
Тут же лежит ответ на вопрос, за что аналитику платят, когда код пишет агент. Не за текст спецификации: текст агент напишет быстрее и ровнее. Платят за владение решениями, которых в тексте не видно.
Шаблон
Журнал устроен вокруг одного ограничения: на строку уходит минута. Всё, что дороже минуты, заполняют первую неделю и бросают.
Девять полей, обязательны четыре.
| Поле | Обяз. | Что писать |
|---|---|---|
| id | да | DL-001, сквозная нумерация |
| дата | да | когда приняли, не когда записали |
| решение | да | одна фраза в утвердительной форме: «Дубли схлопываем по ИНН» |
| почему | да | критерий, по которому выбрали |
| контекст | нет | задача или артефакт, к которому относится |
| отвергнуто | нет | что рассматривали и не взяли |
| обратимость | нет | дёшево или дорого — сколько стоит откатить |
| кто | нет | вы, команда, заказчик |
| ломается_если_изменить | нет | какие артефакты станут неверными |
Поле «почему» — единственное, где все срезают углы, и единственное, ради которого журнал заводят. Правило простое: если в графе «почему» написано то же, что в графе «решение», строка не заполнена.
Поле «обратимость» попало в шаблон намеренно. Оно сортирует записи по цене ошибки и отвечает на вопрос, что стоит выносить на обсуждение. Не всякое молчаливое решение плохо. Плохи незаписанные необратимые.
Как выглядит заполненный
Восемь записей на учебном кейсе Acme Pay, приём платежей для маркетплейса. Три строки для примера:
| id | решение | почему | обратимость | кто |
|---|---|---|---|---|
| DL-001 | Суммы храним целым числом в копейках | дробные типы дают расхождение в отчёте на третьем знаке | дорого | принял сам, никто не спросил |
| DL-003 | Курс валюты фиксируем на момент авторизации | между авторизацией и списанием до трёх суток, продавец должен видеть подтверждённую им сумму | дорого | обсудил с заказчиком |
| DL-008 | Статус «в обработке» отдаём сразу, не дожидаясь банка | ответ банка идёт до 40 секунд, покупатель уходит и платит второй раз | дорого | принял сам, никто не спросил |
Пять записей из восьми в полном примере приняты в одиночку. Пять помечены как необратимые. Ни одна не восстанавливается из спецификации: там написано «система хранит сумму платежа».
Журнал нужен не только вам
Это и делает шаблон рабочим инструментом, а не бланком для порядка.
Журнал вы кладёте в контекст агента как файл и ссылаетесь на него из спецификации номерами: «поведение при дублях, см. DL-004». Работает с любым инструментом, который принимает файлы контекста: ChatGPT, Claude, Подмастерье аналитика (AnalystCraft Coworker). Подмастерье держит журнал в том же слое контекста, что и Source map, и подтягивает его к каждому артефакту без ручного напоминания.
Проверить пользу можно за вечер, не веря никому на слово. Прогоните одну спецификацию дважды: с журналом в контексте и без. Если агент принимает разные решения, запись работает. Если результат тот же, запись лишняя, удаляйте.
«Это же ADR»
Возражение приходит сразу, и оно справедливое наполовину.
ADR фиксирует архитектурные решения для людей. Decision Log фиксирует аналитические решения для людей и для агентов. Разница в цене заполнения: ADR пишут полчаса и заводят на «выбрали Kafka», строку журнала пишут минуту и заводят на «дубли схлопываем по ИНН». Второе в ADR не попадает никогда — слишком мелко для документа на полстраницы, но ровно на этом слое агент и додумывает за вас.
С чего начать
Прошлое не переписывайте. Восстановление полугодовой истории решений — работа на неделю, которую никто не доводит до конца. Начните с сегодняшнего дня, четыре обязательных поля, минута на строку. Через две недели посмотрите на колонку «обратимость»: строки с пометкой «дорого», принятые в одиночку, стоит проговорить с командой.
Забрать шаблон
Markdown и YAML, README и заполненный пример на Acme Pay. Лицензия Apache 2.0, берите в командные wiki.
Если нужен архив письмом, оставьте адрес — пришлю пак одним архивом и напишу, когда выйдет сквозной разбор, где Source map, чек-лист и журнал работают на одном кейсе.
Связанные материалы
Часто спрашивают
Чем Decision Log отличается от ADR?
ADR фиксирует крупные архитектурные решения. Decision Log фиксирует аналитические решения на уровне требований, дублей, дат, статусов, границ и исключений.
Когда заводить запись?
Когда вы приняли решение, которое не следует напрямую из источника, влияет на поведение системы и будет дорого восстановить через месяц.
Сколько времени это должно занимать?
Около минуты на строку. Если запись требует полчаса, это уже не строка журнала, а отдельное обсуждение или ADR.