В годовом отчёте появляется знакомая связка: команда выбрала решение, после него метрика изменилась, значит решение сработало. Через несколько месяцев такой вывод начинают повторять как рецепт. Симптом ошибки прост: в записи есть выбранный путь и хороший результат, но нет отвергнутых вариантов, цены выбора и границы сравнения. Цена ошибки — неверный выбор в следующем проекте. Команда переносит не проверенный механизм, а удачную последовательность событий.
\nТезис статьи: годовой инженерный вывод готов только тогда, когда он различает decision, observation и causal claim. Для этого нужно назвать доступную альтернативу, зафиксировать cost, сформулировать unknown и указать, какие состояния действительно сравнивались. Если хотя бы одного элемента нет, результатом должен быть запрос на исправление, а не уверенный итог.
\nПусть команда изменила лимит очереди в понедельник, а во вторник снизилась задержка. Запись подтверждает порядок событий. Она не показывает, что произошло бы без изменения. В этот же период могли измениться объём трафика, состав запросов, кэш, версия зависимости или нагрузка на соседний сервис.
\nНаблюдение отвечает на вопрос «что увидели». Причинное утверждение отвечает на другой вопрос: «что именно вызвало это изменение». Между ними нужен способ сравнения. Им может быть контрольное окно, сопоставимая группа, повторяемый эксперимент или другая методика, которую команда заранее описала. Если такого способа нет, нужно сохранить unknown, а не заменить его глаголом «улучшило».
\nКонтрфактический вопрос не требует придумывать альтернативную историю. Он проверяет границу утверждения: какой фактор мог дать тот же результат, какое состояние служит сравнением и что нельзя узнать из текущей записи. Такой вопрос делает текст менее эффектным, но более переносимым.
\nDecision описывает выбор в конкретный момент. В нём есть действие и контекст: например, «оставили один владелец повторных запросов для внешнего вызова». Фраза «сделали систему надёжнее» уже описывает предполагаемый результат и не подходит.
\nAlternatives перечисляет варианты, доступные тогда же. Нельзя добавлять идеальный вариант, появившийся только после инцидента. Если команда выбирала между локальным повтором и повтором на границе клиента, нужно назвать именно эти варианты и требования, по которым их сравнивали.
\nCost показывает, чем заплатили за выбор. Это может быть дополнительная задержка, сложность отката, неполное покрытие, расход памяти или ручная операция. Без cost решение выглядит бесплатным и неизбежным.
\nObservation фиксирует наблюдаемый факт: число попыток в учебном сценарии, значение поля, порядок событий или статус проверки. Не называйте его эффектом. Слово «снизило» уже содержит причинный вывод.
\nUnknown называет первый вопрос, на который запись не отвечает. Например: «неизвестно, как повёл бы себя тот же поток без изменения лимита». Unknown не является дефектом текста. Это честная граница знания.
\nComparison boundary уточняет набор сравнения: два фиксированных состояния, окно времени, тип нагрузки и исключённые факторы. Без границы нельзя понять, насколько широк вывод.
\n| Симптом | Причина | Проверка | Действие |
|---|---|---|---|
| После изменения появилась хорошая метрика | Порядок событий приняли за причинность | Найти контрольное состояние или явно записать его отсутствие | Заменить «изменение улучшило» на observation и добавить unknown |
| Выбранный путь выглядит единственным | Альтернативы вырезали при сокращении отчёта | Восстановить варианты, доступные в момент решения | Добавить alternatives и критерии выбора |
| Решение описано только как успех | Cost остался в рабочей переписке | Проверить задержку, сложность, покрытие и откат | Назвать принятый расход рядом с decision |
| Разные команды спорят о результате | Они сравнивают разные окна или нагрузки | Сопоставить период, входы, версии и исключения | Сузить comparison boundary до проверяемого набора |
| Reviewer пишет «не хватает контекста» | Не назван конкретный разрыв | Проверить шесть полей по одному | Вернуть один repair request с ожидаемым дополнением |
Ниже учебный пример. Он работает только с фиксированным объектом в памяти. В нём нет настоящих логов, метрик, тикетов, запросов или производственных данных. Код показывает порядок проверки записи, но не доказывает эффект решения.
\ntype ReviewCard = {\n decision: string;\n alternatives: string[];\n cost: string;\n observation: string;\n unknown: string;\n comparisonBoundary: string;\n};\n\nfunction inspect(card: ReviewCard) {\n const gaps = Object.entries(card)\n .filter(([, value]) => value.length === 0)\n .map(([field]) => field);\n\n if (gaps.length > 0) {\n return { status: 'stop-and-repair', gaps };\n }\n\n return {\n status: 'synthetic-review-handoff',\n note: 'Учебная запись не подтверждает production-эффект',\n };\n}\n\nconst card = {\n decision: 'Оставили один владелец retry',\n alternatives: ['retry на клиенте', 'retry на адаптере'],\n cost: 'Дополнительная задержка перед окончательной ошибкой',\n observation: 'В учебном прогоне выполнено не более двух попыток',\n unknown: 'Неизвестно поведение при другой нагрузке',\n comparisonBoundary: 'Фиксированный сценарий и два заданных входа',\n};\n\nconsole.log(inspect(card).status);\n// synthetic-review-handoffПоложительный статус означает только полноту учебной карточки. Он не означает, что один владелец retry уменьшил задержку или количество ошибок в настоящей системе. Для production понадобятся реальные входы, наблюдаемая телеметрия, план сравнения и владелец проверки.
\nСлабая проверка проходит только по заполненной карточке. Надёжная проверка должна остановиться на пустом поле и не превращать запуск без исключения в успех. Например, если unknown отсутствует, функция не должна подставлять «нет неизвестных». Это не знание, а потеря границы.
\nЕсть и другой отрицательный путь: reviewer не согласен с выбранной альтернативой, хотя все поля заполнены. Это не обязательно ошибка фактов. Сначала нужно проверить traceability записи. Затем можно отдельно обсуждать trade-off. Нельзя маскировать стратегическое несогласие под «неполный контекст» и нельзя исправлять пропуск данных спором о предпочтениях.
\nЕсли comparison boundary невозможно сформулировать, остановите итоговый вывод. Не расширяйте его словами «в целом», «обычно» или «для системы». Широкая формулировка не заменяет отсутствующее сравнение.
\nТакая карточка не восстанавливает прошлое идеально. Участники могут не помнить все варианты. Метрики могли собираться с другой семантикой. Внешние изменения могли совпасть по времени. Контрфактический вопрос выявляет эти ограничения, но сам по себе не создаёт контрольную группу.
\nПолный проход не нужен для каждого мелкого изменения. Он оправдан там, где запись предлагает повторить решение, объясняет заметное изменение или становится основанием для технического стандарта. Для локальной заметки может хватить decision и границы. Чем дороже ошибочный перенос рецепта, тем полнее должна быть карточка.
\nУчебный код также ограничен. Он не читает реальные источники, не проверяет качество метрик, не запускает эксперимент и не создаёт production-решение. Все значения в примере заданы вручную. Их нельзя выдавать за результат измерения.
\nЗапись готова к передаче на человеческое чтение, если она содержит конкретное decision, доступные alternatives, явный cost, наблюдаемый observation, один unknown и точную comparison boundary. Для каждого поля можно указать источник или честно отметить, что это фиксированный учебный литерал. Отсутствующее поле возвращает статус stop-and-repair. Ни один абзац не называет причиной то, что запись лишь наблюдала после изменения.
\n