Коротко: Продакшн-ранбук — це єдиний, однозначний документ, який підказує черговому, як діагностувати, пом’якшувати та відновлювати ваш MVP під час збоїв. Якщо у вас прототип, зібраний vibecoding або за допомоги ШІ, продакшн-ранбук потрібен до приходу реальних користувачів. Ранбук робить інциденти «нудними», визначаючи власників, SLO, залежності, безпечні стани, відкат і плейбуки. Мінімальний продакшн-ранбук можна написати за один день і розвивати його разом із кодовою базою. Якісний ранбук скорочує час до відновлення, зменшує ескалації й перетворює хаос о 2‑й ночі на чекліст.
Ключові висновки
- Продакшн-ранбук перетворює невідомі на чеклісти, щоб черговий діяв швидко під стресом.
- Мінімальний ранбук для MVP вміщується в один файл, живе в репозиторії та покриває власників, SLO, відкат, залежності й топові плейбуки інцидентів.
- Автоматизуйте найвпливовіші кроки першими: health‑чеки, деплой/відкат, швидкі переходи по логах і метриках та безпечні фіче‑тогли.
- Тренування роблять ранбук реальним; плануйте короткі регулярні вправи з інцидентами й оновлюйте документ після кожного заняття.
Що таке продакшн-ранбук і чому ваш прототип його потребує
Продакшн-ранбук — це авторитетний набір інструкцій для діагностики, пом’якшення та відновлення сервісу під час інцидентів. Він існує, щоб людина на чергуванні зробила правильний перший крок без пошуків по дашбордах, Slack чи «племінній» пам’яті.
Код, написаний vibecoding або згенерований ШІ, часто бракує запобіжників і спільного контексту. Найшвидший спосіб додати надійність без переписування — задокументувати критичний шлях: хто володіє сервісом, як він має поводитись, де ламається та як безпечно відкотити. Ранбук централізує цей контекст і робить підтримку передбачуваною.
Для 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 і підв’яжіть алерт. Визначте «золотий шлях» (напр., успішність checkout або перцентиль латентності API). Створіть один алерт, що пейджить лише за реального впливу на користувачів; згадайте його в ранбуку й дайте лінк на дашборд. Наш дайджест SLOs for MVP допоможе.
- Занотуйте зовнішні залежності. Для кожного провайдера додайте лінки на консолі та URL сторінки статусу.
День: напишіть два топові плейбуки й зв’яжіть усе
- Обирайте дві поширені або лячні відмови. Приклади: стрибки CPU у БД, збої стороннього API, бэклоги черг або невдалий деплой.
- Напишіть короткі, дієві плейбуки. Для кожного: як виявити, куди дивитися спочатку, швидка мітигація (вимкнути фічу, масштабувати воркер), і коли відкочувати. Додайте команди для копіювання‑вставки.
- Задокументуйте health‑чеки. Додайте ендпоїнти, що можна викликати через curl, очікувані відповіді та однорядкову команду для tail логів застосунку з корисним фільтром.
- Опишіть місця секретів і конфігів. Назвіть vault або провайдера змінних середовища та зазначте відповідального за ротацію. Додайте посилання на ваш підхід із Secrets Management for MVP, якщо застосовано.
- Додайте шаблон постмортему. Тримайте його легким; мета — писати їх послідовно й призначати власників виправлень.
- Попросіть пір-рев’ю. Нехай людина, не знайома з системою, пройде відкат і один плейбук на стейджингу, тоді усуньте неоднозначності.
Постачайте ранбук із найближчим релізом. Згадайте його в он‑кол хендофі. Зробіть його першим результатом пошуку документації за назвою сервісу.
Що автоматизувати зараз, а що — пізніше у вашому ранбуку
Автоматизуйте кроки, що регулярно з’їдають час під час інцидентів. Повна платформа не потрібна; кілька скриптів швидко окупляться.
- Зараз: відкат однією командою, скрипт для вибірки останніх N рядків логів за correlation ID, раннер health‑проб і відкривач дашбордів із правильним часовим зсувом.
- Зараз: скрипт для вимкнення ризикових фіче‑флагів і перевірки, що система досягає відомого безпечного стану.
- Скоро: безпечний для даних гейт деплою, що перевіряє застосування міграцій і проходження синтетичного чеку до переключення трафіку.
- Пізніше: авто‑ремедіацію для гучних, але низькоризикових проблем; спершу доведіть безпечність і ідемпотентність. Для високого впливу поєднуйте автоматику з запобіжниками на кшталт фіче‑флагів та ідемпотентних операцій; див. наш підхід у Idempotency for Vibecoded Apps.
Зробіть автоматику помітною. Якщо скрипт існує — дайте посилання в плейбуці, покажіть приклад виклику й очікувані виводи та побічні ефекти.
Як тримати ранбук актуальним: власність, версіонування та рев’ю
Застарілі ранбуки створюють ручну працю. Рішення — проста «керованість»: тримайте ранбук під контролем версій, призначте явного власника і вимагайте оновлень разом із відповідними змінами в коді.
- Живе в репо: Зберігайте Runbook.md у корені сервісу. Віддавайте перевагу відносним лінкам на скрипти й діаграми, щоб рефакторинги не ламали посилання.
- Власність явна: Власник сервісу відповідає за ранбук як частину «definition of done».
- Інтегруйте в code review: Додайте пункт у PR‑чекліст: «Якщо поведінка змінилась — оновіть Runbook.md і дашборди». Блокуйте мерджі, що змінюють деплой, міграції чи критичні флоу без дифа ранбуку.
- Регулярні огляди: Заплануйте 15‑хвилинний щомісячний огляд ранбуку в календарі команди. Перегляньте SLO, деплой і топові плейбуки на предмет дрейфу.
- Закривайте цикл після інцидентів: Кожен постмортем містить завдання оновити плейбук або додати новий. Пов’яжіть зміну з інцидентом.
Ентропія документації — симптом неясної власності. Ставтесь до ранбуку як до коду. Часті малі правки зберігають довіру до нього.
Як тренуватися: вправи з інцидентами та game days для малих команд
Тренування перетворюють статичний документ на «м’язову пам’ять». Великих івентів не треба; короткі сфокусовані вправи виявляють прогалини й додають упевненості.
- Обрати сценарій. Реалістична відмова: неправильно сконфігурований секрет, збої залежності або завислий воркер.
- Ліміт — 45 хвилин. 5 хв — задати сцену, 25 — діагностувати й пом’якшити за ранбуком, 10 — рефлексія, 5 — оновлення документа.
- Проводьте в реальних умовах. Використовуйте стейджинг із даними й трафіком, подібними до продакшну. Якщо мусите тренуватись у продакшні — обирайте безпечний, зворотний тест із чітким правилом відміни.
- Міряйте базові метрики. Час до першої змістовної дії, час до мітигації та кількість ескалацій. Тренд важливіший за абсолютні значення.
- Фіксуйте покращення одразу. Якщо крок був неясним — виправте Runbook.md, перш ніж вийти з кімнати.
Game days не заміняють моніторинг чи SLO; вони перевіряють, що люди й документи вміють використовувати вже наявні сигнали.
Як зрозуміти, що ваш продакшн-ранбук працює
Робочий ранбук пришвидшує відновлення, знижує стрес і запобігає повторним інцидентам. Ви маєте бачити:
- Менший час до мітигації. Черговий швидше приводить систему у безпечний стан для того самого класу інциденту.
- Менше ескалацій. Перший реагувальник закриває більше інцидентів без виклику автора коду.
- Послідовні дії. Двоє різних реагувальників приймають однакові рішення за тих самих алертів і контексту.
- Кращі постмортеми. Дебріфи стають коротшими й предметнішими, бо хронологія та дії вже зрозумілі.
Якщо тренди не покращуються — додайте конкретики: команди для копіювання‑вставки, скріншоти або лінки, і дерева рішень там, де є розгалуження.
Типові плейбуки інцидентів для vibecoded‑застосунків (із чеклістами)
Команди, нові в продакшні, часто стикаються з тими самими збоями. Ці приклади показують, як чітко формулювати кроки.
Невдалий деплой спричиняє помилки
- Підтвердіть пейдж; надішліть в канал інциденту алерт і поточний рівень помилок.
- Перевірте час останнього деплою. Якщо сплеск почався в цьому вікні — переходьте до відкату.
- Запустіть команду відкату з ранбуку. Дочекайтесь очікуваного часу поширення.
- Перевірте відновлення на основному дашборді; опублікуйте новий рівень помилок.
- Створіть фоллоу‑ап: безпечно знайти корінну причину поза піком і додати переддеплойний чек, який би зловив цей клас проблем.
Насичення бази даних
- Підтвердіть насичення на дашборді БД (CPU, підключення, очікування блокувань).
- Визначте топ‑запити або ендпоїнти зі slow‑query логів.
- Застосуйте безпечний стан: вимкніть найважчу некритичну функцію через фіче‑тогл.
- Тимчасово масштабуйте репліки для читання або конкуренцію воркерів, якщо це задокументовано як безпечне.
- Створіть завдання на оптимізацію запитів і додайте примітку в ранбук із посиланням на винуватця.
Відмова стороннього API
- Перевірте сторінку статусу провайдера; надішліть посилання в канал інциденту.
- Увімкніть режим фолу‑беку або вимкніть залежні функції через тогли, якщо шкода користувачу висока.
- Тротуйте або ставте в чергу вихідні виклики; перевірте бюджети ретраїв і таймаути.
- Підтвердіть видимий для користувача вплив на SLO‑дашборді та прокомунікуйте очікувану поведінку.
- Після відновлення додайте тест або вимикач‑breaker, щоб зменшити майбутній бласт‑радіус.
Кожен плейбук має містити: перший дашборд для перевірки, перший лог‑запит, перемикач або команду для мітигації та критерії відміни.
Де зберігати і як структурувати ранбук
Зберігайте ранбук у тому ж репозиторії, що й сервіс, щоб зміни були поруч. Назвіть його Runbook.md. Згадайте про нього в README та гіді для он‑кол.
- Шапка: опис сервісу, власники, ескалація, SLO і лінки на дашборди.
- Операції: деплой, відкат, міграції, health‑чеки та безпечні стани.
- Плейбуки: топ 3–5 типів інцидентів із деревами рішень і командами.
- Довідки: залежності, секрети/конфіг, бекап/рестор і шаблон постмортему.
Якщо ви керуєте кількома сервісами, створіть кореневу сторінку Каталогу сервісів із посиланнями на кожен Runbook.md і вкажіть власника, SLO та дату останнього огляду.
Як Moai Team підходить до цього
Ми закриваємо розрив між vibecoding‑та‑продакшн, вбудовуючи forward‑deployed інженерів у ваш код і пишучи ранбук, поки зміцнюємо систему. Спершу приземляємо essentials: один SLO, прив’язаний до пейджингу, відкат однією командою і два плейбуки інцидентів. Налаштовуємо адекватні дефолти для секретів і конфігів, спираючись на наші патерни з Secrets Management for MVP, і полегшуємо розслідування інцидентів практиками з Audit Logging for Vibecoded Apps.
Ми тримаємо ранбук «живим»: він живе в репозиторії, змінюється в тих самих pull request, що й поведінка, і перевіряється короткими тренуваннями. Наша мета проста: коли спрацьовує пейджер, будь‑який компетентний інженер відновлює безпечний стан, користуючись документом перед очима.
Поширені запитання
Що таке продакшн-ранбук?
Продакшн-ранбук — це визначений набір інструкцій для діагностики, пом’якшення та відновлення сервісу під час інцидентів. У ньому вказані власники, посилання на дашборди, опис відкату і покрокові плейбуки типових відмов. Ранбук існує, щоб черговий діяв швидко, не шукаючи «племінні» знання.
Де має жити ранбук?
Тримайте ранбук у тому самому репозиторії, що й сервіс, зазвичай як Runbook.md у корені. Близькість до коду гарантує оновлення разом зі змінами поведінки та зручний пошук у коді. Додайте посилання з README і он‑кол документації.
Наскільки детальними мають бути інструкції з відкату?
Відкат має бути настільки точним, щоб команди можна було копіювати‑вставляти, із зазначенням таймінгів і кроків перевірки. Додайте точну команду, обсяг відкату, очікувані зміни логів/сигналів і критерії відміни, якщо відкат не вдався. Уявіть, що сонна людина виконує кроки під тиском часу.
Як часто проводити тренування інцидентів?
Короткі регулярні вправи кращі за рідкісні довгі. Щомісячне 45‑хвилинне тренування на реалістичному сценарії підтримує ранбук свіжим і додає впевненості. Після кожного заняття негайно оновіть ранбук за підсумками неясностей.
Хто володіє ранбуком?
Власник сервісу відповідає за ранбук як частину definition of done. Рев’юери коду мають вимагати оновлення ранбуку, коли змінюються деплой, міграції або критична поведінка. Після інцидентів власник постмортему забезпечує оновлення відповідного плейбуку.
Чи потрібен ранбук, якщо ми використовуємо serverless або повністю керовані сервіси?
Так, бо інциденти трапляються вище платформного шару. Ваш ранбук більше зосередиться на відмовах залежностей, помилках конфігурації, безпечних фіче‑тоглах і відкаті конфігурації чи коду. Керована інфраструктура зменшує рутину, але не прибирає потребу в операційній ясності.
Потрібен продакшн-ранбук, що витримує тиск? Поспілкуйтеся з forward‑deployed інженерами, які пишуть, тестують і постачають їх у вашому репозиторії. Зв’яжіться з Moai Team.