Replay Packs: простой способ исправлять cron-задачи без лишнего стресса

Проблема: зелёные скрипты и красные утра

Cron-задачи выглядят здоровыми, пока не сломаются. Бóльшую часть времени shell завершается с кодом 0, а в один прекрасный день API съезжает, шаблон меняется или контент-правило становится строже. Просыпаешься — сломанный пайплайн и полубесполезный лог. Самое обидное: задача выполнилась, но теперь уже не понять, как именно.

Чего обычно не хватает?

• точного контекста, который скрипт использовал на входе
• логики выбора: почему пошёл по одной ветке, а не по другой
• сгенерированного артефакта до того, как его тронул публикатор
• финального ответа от последнего шага

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

Что внутри replay pack

Мой стандартный набор нарочно скучный. Для каждого запуска храню:

• context.json (или эквивалент) — исходные входные данные
• plan.json — предполагаемый путь решений
• основной сгенерированный артефакт
• publish-result.json (или структурированный файл с ошибкой)

Этого хватает для большинства задач. Если воркфлоу трансформирует контент, сохраняю пре-публикационную версию ровно один раз. Если постит в API — сохраняю проверенную форму ответа, а не сырой текст терминала.

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

Вот крошечная ментальная модель:

inputs → plan → artifact → result

Каждая стрелка — место, куда просачивается энтропия. Если сохранять по файлу на каждом этапе, задачу становится гораздо проще осмыслить. Не идеально, но намного легче.

Маленький паттерн, который масштабируется

Никакой workflow-движок не нужен. Shell-скрипт и одна генерируемая директория на запуск — этого достаточно.

run_dir="generated/$RUN_ID" mkdir -p "$run_dir" write_context > "$run_dir/context.json" write_plan > "$run_dir/plan.json" write_article > "$run_dir/article.raw.md" publish_job "$run_dir" > "$run_dir/publish-result.json"

Важна дисциплина:

1. Пиши план до артефакта.
2. Генерируй основной артефакт один раз.
3. Публикуй из run-директории, а не из разбросанных временных файлов.
4. Никогда не «исправляй» упавший запуск, молча перезаписывая его историю.

Последнее особенно важно. Если задача упала и ты перегенерировал всё заново, ты можешь потерять точное состояние, которое вызвало проблему. Я делал эту ошибку не раз, и потом всегда терял время. Сохраняй сломанный запуск. Для повтора делай новый. Чуть многословнее, но зато правильная операционная привычка.

Временные почтовые адреса и их место

Этот паттерн особенно полезен, когда воркфлоу касается почтовых ящиков, ссылок для верификации или автоматизации регистрации. Временный email часто часть тестового потока, но хрупкость не только в почтовом ящике, а в координации между сгенерированными идентичностями, ожиданиями, повторными попытками и извлечёнными ссылками.

Если твоя задача использует tempmailso или любой хелпер для ящиков, сохраняй метаданные почтового ящика, политику повторных попыток и результат извлечения рядом с основным артефактом. Не закапывай эту деталь в длинный stdout. Если ссылка для верификации истекла или письмо пришло с опозданием — replay pack должен это показать без превращения в криминалистический проект.

Ещё я храню любые странные, но осмысленные поисковые фразы в виде данных в контексте запуска, а не как скрытое предположение в коде. Это делает поведение объяснимым, даже если формулировка немного корявая.

Q&A

Нужен ли replay pack для каждой cron-задачи?

Нет. Если скрипт крошечный, детерминированный и дёшево перезапускается — обычных логов хватит. Replay pack выручает, когда задача принимает решения, генерирует артефакты или общается с внешними системами.

Не будет ли слишком много файлов?

Немного будет, да. Но несколько маленьких структурированных файлов дешевле, чем час смутной отладки. Хранилище обычно не узкое место, время — да.

Какой файл добавить первым, если выбрать только один?

plan.json. Он заставляет задачу раскрыть намерения до выполнения. Когда намерения видны, сбои становятся гораздо менее расплывчатыми, и ревью — честнее.

Эта привычка с низкими усилиями постоянно окупается. Маленькие скрипты остаются маленькими, но перестают казаться одноразовыми. И когда cron будит тебя плохими новостями, у тебя есть что-то получше, чем догадки.