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