Короткий ответ: продакшен‑ранбук — это единый, явный документ, который подсказывает он‑коллу, как диагностировать, смягчать и восстанавливать ваш MVP при сбоях. Если у вас прототип, собранный vibecoding или с помощью ИИ, продакшен‑ранбук нужен до прихода реальных пользователей. Ранбук делает инциденты скучными: определяет владельцев, SLO, зависимости, безопасные состояния, откат и плейбуки. Минимальный продакшен‑ранбук можно написать за один день и развивать его вместе с кодовой базой. Хороший ранбук сокращает время до восстановления, снижает число эскалаций и превращает хаос в 2 ночи в чек‑лист.
Главные выводы
- Продакшен‑ранбук превращает неизвестность в чек‑листы, чтобы он‑колл действовал быстро под стрессом.
- Минимальный ранбук для MVP умещается в один файл, живёт в репозитории и покрывает владение, SLO, откат, зависимости и топовые плейбуки инцидентов.
- Автоматизируйте самые выгодные шаги: health‑чеки, деплой/откат, полезные срезы логов и метрик, безопасные фича‑флаги.
- Учения делают ранбук реальным: планируйте короткие регулярные тренировки по инцидентам и обновляйте документ после каждого упражнения.
Что такое продакшен‑ранбук и почему он нужен вашему прототипу
Продакшен‑ранбук — это авторитетный набор инструкций по диагностике, смягчению и восстановлению сервиса во время инцидентов. Он существует, чтобы дежурный мог сделать правильный первый шаг без поисков по дашбордам, Slack или «памяти племени».
Vibecoded‑ и ИИ‑сгенерированный код часто лишён ограничителей и общего контекста. Самый быстрый способ добавить надёжности без переписывания — задокументировать критический путь: кто владелец сервиса, как он должен себя вести, где он ломается и как безопасно откатываться. Ранбук централизует этот контекст и делает поддержку предсказуемой.
Для MVP ранбук может быть одним файлом Runbook.md в репозитории. Держите его лаконичным. Ссылайтесь на живые дашборды и скрипты. Предпочитайте чек‑листы прозе. Меняете поведение системы — меняйте ранбук в том же pull request.
Что должно быть в продакшен‑ранбуке для MVP
Хороший ранбук сначала даёт ответы, затем — контекст. Ниже — минимальные разделы, которые мы ожидаем увидеть у только что выпущенного продукта:
- Краткое описание сервиса: Один абзац о том, что делает сервис, критические пользовательские пути и известные не‑цели.
- Владельцы и эскалация: Основная команда, ссылка на ротацию и одноступенчатый путь эскалации с ожиданиями по отклику.
- SLO и политика пейджинга: Пользовательский опыт, на который вы подписываетесь, и когда будить человека. Если явных SLO нет — определите один для «золотого пути» и привяжите к нему алерты; см. наш гид SLOs for MVP.
- Эскиз архитектуры: Простой диаграммой или списком компонентов и потоков данных. Укажите сетевые границы и места хранения.
- Внешние зависимости: Сторонние API, очереди, email/SMS‑провайдеры, платёжные шлюзы и где смотреть их статус.
- Конфигурация и секреты: Как загружается конфигурация, где живут секреты и как их ротировать. Для минимальной гигиены возьмите паттерны из Secrets Management for MVP.
- Деплой и откат: Точные команды, ожидаемые тайминги и как проверить здоровье релиза. Включите безопасный откат одной командой и чек‑лист для изменений в базе.
- База данных и миграции: Как применять миграции, как откатить неудачную миграцию и где лежат бэкапы.
- Безопасные состояния и фича‑флаги: Какие функции можно отключить, чтобы сбросить нагрузку или изолировать сбой, и какие переключатели для этого есть.
- Health‑чеки и наблюдаемость: URL или команды для health/readiness‑проверок, основной дашборд и какие метрики/логи смотреть сначала.
- Плейбуки инцидентов: Пошаговые инструкции для ваших трёх главных отказов с развилками решений и известными скриптами‑обходами.
- Аудит и учёт изменений: Как просматривать пользовательские и системные изменения во время расследования. Минимальный, стойкий к подделке след окупается; см. Audit Logging for Vibecoded Apps.
- Бэкапы и быстрый рестор: Где живут бэкапы, как проверять целостность и короткий план учения по восстановлению.
- Шаблон постмортема: Одна страница: причина, влияние, таймлайн, ремедиация и владельцы.
Если ваш MVP состоит из нескольких сервисов, добавьте краткий каталог сервисов сверху с ссылками на раздел каждого компонента. Остальное держите плоским и удобным для сканирования.
Как написать продакшен‑ранбук за один день
Рабочий ранбук можно накидать за один рабочий день. Начните с самых рычажных разделов, которые разблокируют он‑колл: владение, ссылки на SLO‑алерты, откат и топовые плейбуки инцидентов. Остальное добавляйте по мере обучения.
Утро: собрать необходимое
- Откройте Runbook.md в репозитории. Добавьте заголовки по чек‑листу. Создайте плейсхолдеры ссылок на дашборды и скрипты.
- Определите владельцев и эскалацию. Укажите ротацию он‑колла и один контакт эскалации с ожидаемым временем ответа.
- Пропишите шаги деплоя/отката. Скопируйте точные команды, которые используете сейчас. Проверьте откат на стейджинге или во временной среде.
- Выберите один SLO и привяжите алерт. Выберите «золотой путь» (например, доля успешных оформлений заказа или перцентиль латентности API). Создайте один алерт, который пейджит только при влиянии на пользователей; упомяните его в ранбуке и дайте ссылку на дашборд. Наш ликбез SLOs for MVP поможет в этом шаге.
- Составьте список внешних зависимостей. Для каждого провайдера добавьте ссылки на консоль и страницу статуса.
День: напишите два топовых плейбука и сведите всё
- Выберите два частых или самых страшных сбоя. Примеры: всплески CPU базы, отказы сторонних API, заторы в очередях или неудачный деплой.
- Сделайте короткие, действенные плейбуки. Для каждого: как обнаружить, куда смотреть сначала, быстрая мера (выключить фичу, масштабировать воркер) и когда откатываться. Включите команды для копирования и вставки.
- Задокументируйте health‑чеки. Добавьте curl‑доступные эндпоинты, ожидаемые ответы и однострочник для просмотра логов приложения с полезным фильтром.
- Зафиксируйте места секретов и конфигурации. Назовите хранилище (vault) или провайдера окружения и укажите ответственного за ротацию. Если вы приняли наш подход, дайте ссылку на Secrets Management for MVP.
- Добавьте шаблон постмортема. Держите его лёгким; цель — писать их последовательно и назначать владельцев исправлений.
- Попросите peer‑review. Пусть человек, не знакомый с системой, выполнит откат и один плейбук на стейджинге — затем устраните неоднозначности.
Отправьте ранбук вместе со следующим релизом. Сошлитесь на него в он‑колл‑хэндовере. Сделайте так, чтобы при поиске названия сервиса в вашей документации это был первый результат.
Что автоматизировать сейчас, а что позже в ранбуке
Автоматизируйте шаги, которые раз за разом съедают время во время инцидентов. Вам не нужна целая платформа, чтобы получить отдачу: нескольких скриптов уже достаточно.
- Сейчас: откат одной командой, скрипт для выборки последних N строк логов по correlation ID, запускающий health‑пробу раннер и «открывашка» дашборда с нужным таймфреймом.
- Сейчас: скрипт, который выключает высокорисковые фича‑флаги и проверяет достижение известного безопасного состояния.
- Скоро: защитный гейт деплоя, который убеждается, что миграции применены и синтетическая проверка проходит до переключения трафика.
- Позже: автоисправление шумных, но низкорисковых проблем; сначала требуйте доказанной безопасности и идемпотентности. Для эффектов большого импакта сочетайте автоматизацию с предохранителями вроде фича‑флагов и идемпотентных операций; см. наш взгляд на Idempotency for Vibecoded Apps.
Делайте автоматизацию обнаружимой. Если скрипт существует — дайте на него ссылку в плейбуке, покажите пример запуска и ожидаемые выводы/побочные эффекты.
Как поддерживать ранбук актуальным: владение, версии и ревью
Протухшие ранбуки создают лишнюю работу. Лекарство — простое управление: держите ранбук под версионированием, назначьте явного владельца и требуйте обновлений вместе с релевантными изменениями кода.
- Живите в репозитории: храните Runbook.md в корне сервиса. Предпочитайте относительные ссылки на скрипты и диаграммы, чтобы рефакторинги не ломали референсы.
- Сделайте владение явным: владелец сервиса отвечает за ранбук как часть определения «готово».
- Встройте в code review: добавьте пункт чек‑листа pull request: «Если поведение изменилось — обнови Runbook.md и дашборды». Блокируйте слияния, которые меняют деплой, миграции или критические потоки без диффа ранбука.
- Регулярные обзоры: запланируйте ежемесячный 15‑минутный обзор ранбука в календаре команды. Просмотрите SLO, деплой и топовые плейбуки на предмет дрейфа.
- Замыкайте цикл после инцидентов: каждый постмортем включает задачу обновить плейбук или добавить новый. Свяжите изменение с инцидентом.
Энтропия документации — симптом неясного владения. Относитесь к ранбуку как к коду. Частые мелкие правки поддерживают доверие к нему.
Как практиковаться: учения по инцидентам и «игровые дни» для малых команд
Учения превращают статичный документ в мышечную память. Большое мероприятие не нужно: короткие, сфокусированные упражнения выявляют пробелы и укрепляют уверенность.
- Выберите сценарий. Возьмите реалистичный сбой: неверно сконфигурированный секрет, отказ зависимости или «зависший» воркер.
- Таймбокс до 45 минут. 5 минут на вводную, 25 — на диагностику и смягчение по ранбуку, 10 — на рефлексию, 5 — на обновление документа.
- Проводите в реалистичных условиях. Используйте стейджинг с данными и трафиком, похожими на прод. Если нужно тренироваться в проде — выберите безопасный, обратимый тест с явным правилом остановки.
- Измеряйте базовые метрики. Время до первого осмысленного действия, время до смягчения и число эскалаций. Динамика важнее абсолютов.
- Фиксируйте улучшения сразу. Если шаг был неясен — поправьте Runbook.md, не выходя из комнаты.
«Игровые дни» не заменяют мониторинг и SLO; они проверяют, что люди и документы умеют использовать уже имеющиеся сигналы.
Как понять, что ваш продакшен‑ранбук работает
Рабочий ранбук сокращает восстановление, снижает стресс и предотвращает повторы инцидентов. Вы увидите:
- Меньше времени до купирования. Он‑колл быстрее приводит систему в безопасное состояние для того же класса инцидентов.
- Меньше эскалаций. Первый реагирующий закрывает больше инцидентов без вызова автора кода.
- Последовательные действия. Двое разных реагирующих принимают одни и те же решения при одинаковом алерте и контексте.
- Лучшие постмортемы. Разборы становятся короче и предметнее, потому что таймлайн и действия уже ясны.
Если эти тренды не улучшаются — повысьте конкретику: добавьте команды для копирования и вставки, скриншоты или ссылки и деревья решений там, где важны развилки.
Типовые плейбуки инцидентов для vibecoded‑приложений (с чек‑листами)
Команды, новые в проде, часто сталкиваются с одними и теми же сбоями. Эти примеры показывают, как формулировать шаги чётко.
Неудачный деплой вызывает ошибки
- Подтвердите оповещение; опубликуйте алерт и текущую ошибко‑частоту в инцидентный канал.
- Проверьте время последнего деплоя. Если всплеск начался в этот интервал — переходите к откату.
- Выполните команду отката из ранбука. Подождите ожидаемое время распространения.
- Проверьте восстановление на основном дашборде; опубликуйте новую ошибко‑частоту.
- Заведите задачу: безопасно выяснить корневую причину вне рабочего времени и добавить преддеплойную проверку, которая бы ловила такой класс проблем.
Перегрузка базы данных
- Подтвердите перегрузку на дашборде БД (CPU, соединения, ожидания блокировок).
- Найдите топ‑запросы или эндпоинты по slow‑query логам.
- Примените безопасное состояние: отключите самую тяжёлую некритичную фичу через фича‑флаг.
- Временно увеличьте число реплик для чтения или конкурентность воркеров, если это задокументировано как безопасно.
- Откройте задачу на оптимизацию запросов и добавьте в ранбук примечание со ссылкой на виновника.
Аутедж стороннего API
- Проверьте страницу статуса провайдера; дайте ссылку в инцидентном канале.
- Включите режим фолбэка или отключите зависимые фичи через флаги, если вред пользователям высок.
- Ограничьте или поставьте исходящие вызовы в очередь; убедитесь, что бюджеты повторов и таймауты разумны.
- Проверьте пользовательский импакт на SLO‑дашборде и сообщите ожидаемое поведение.
- После восстановления добавьте тест или «предохранитель» (circuit breaker), чтобы уменьшить будущий блэст‑радиус.
Каждый плейбук должен включать: первый дашборд для проверки, первый лог‑запрос, переключатель или команду для смягчения и критерии остановки.
Где хранить и как структурировать ранбук
Храните ранбук в том же репозитории, что и сервис, чтобы быть ближе к изменениям. Назовите его Runbook.md. Сошлитесь на него из README и гайда по он‑коллу.
- Шапка: описание сервиса, владельцы, эскалация, SLO и ссылки на дашборды.
- Операции: деплой, откат, миграции, health‑чеки и безопасные состояния.
- Плейбуки: топ‑3–5 типов инцидентов с деревьями решений и командами.
- Справка: зависимости, секреты/конфиг, бэкап/восстановление и шаблон постмортема.
Если у вас несколько сервисов, создайте корневую страницу каталога сервисов со ссылками на каждый Runbook.md и указанием владельца, SLO и даты последнего обзора.
Как к этому подходит Moai Team
Мы закрываем разрыв между vibecoding и продом, внедряя forward‑deployed инженеров в ваш код и пишем ранбук по мере «закалки» системы. Сначала приземляем основы: один SLO, связанный с пейджингом, откат одной командой и два плейбука инцидентов. Настраиваем здравые дефолты для секретов и конфига, опираясь на наши паттерны из Secrets Management for MVP, и упрощаем расследование инцидентов практиками из Audit Logging for Vibecoded Apps.
Мы держим ранбук живым: он живёт в репозитории, меняется в тех же pull request, что и поведение, и регулярно проверяется на коротких учениях. Наша цель проста: когда срабатывает пейдж, любой компетентный инженер может вернуть систему в безопасное состояние, пользуясь документом перед собой.
Часто задаваемые вопросы
Что такое продакшен‑ранбук?
Продакшен‑ранбук — это исчерпывающий набор инструкций по диагностике, смягчению и восстановлению сервиса во время инцидентов. В нём указаны владельцы, ссылки на дашборды, описан откат и приведены пошаговые плейбуки для частых отказов. Ранбук существует, чтобы он‑колл действовал быстро, не разыскивая «племенные знания».
Где должен жить ранбук?
Держите ранбук в том же репозитории, что и сервис, обычно как Runbook.md в корне. Близость к коду гарантирует его обновление вместе с изменениями поведения и находимость через поиск по коду. Дайте ссылки на него в README и документации по он‑коллу.
Насколько детальными должны быть инструкции по откату?
Откат должен быть точным до «скопировал‑вставил» с ожидаемыми таймингами и шагами проверки. Укажите точную команду, область отката, ожидаемые изменения логов или сигналов и критерии остановки, если откат не удался. Предполагайте, что сонный человек выполняет шаги под давлением времени.
Как часто проводить учения по инцидентам?
Короткие регулярные учения лучше редких длинных. Ежемесячное 45‑минутное упражнение на реалистичном сбое поддерживает ранбук свежим и укрепляет уверенность. После каждого учения сразу обновляйте ранбук по неясным местам.
Кто владеет ранбуком?
Владелец сервиса отвечает за ранбук как за часть определения «готово». Ревьюеры кода должны требовать обновления ранбука при изменениях деплоя, миграций или критического поведения. После инцидентов владелец постмортема обеспечивает обновление соответствующего плейбука.
Нужен ли ранбук, если мы используем serverless или полностью управляемые сервисы?
Да, потому что инциденты происходят и выше уровня платформы. Ваш ранбук будет больше фокусироваться на отказах зависимостей, ошибках конфигурации, безопасных фича‑флагах и откате конфигурации или кода. Управляемая инфраструктура снижает «рутину», но не отменяет потребность в операционной ясности.
Нужен продакшен‑ранбук, который выдерживает давление? Поговорите с forward‑deployed инженерами, которые пишут, тестируют и внедряют их прямо в вашем репозитории. Свяжитесь с Moai Team.