Runbook для поддержки проекта помогает передать систему в поддержку без сюрпризов: шаблоны инцидентов, восстановление, ручные операции и контакты.
Фраза «да там всё просто» почти всегда звучит днём, когда разработчик рядом и можно уточнить детали. Проблемы начинаются ночью, в выходные или в тот редкий момент, когда ошибка повторяется впервые за полгода. Поддержка остаётся один на один с системой, а время уходит на догадки вместо действий.
Обычно «в голове» остаются вещи, которые автору кажутся очевидными: где смотреть логи, какой сигнал считать аварией, как отличить «норму» от отклонения, какие шаги безопасны, а какие могут усугубить ситуацию. Туда же попадают мелкие, но критичные детали: какая команда перезапуска не ломает очередь, в каком порядке обновлять сертификат, где лежат бэкапы и как проверить, что восстановление прошло правильно.
Runbook - это не «документация вообще» и не требования. Документация объясняет архитектуру и устройство модулей, требования описывают, что система должна делать. Runbook отвечает на другой вопрос: что делать прямо сейчас, когда сервис ведёт себя плохо или нужна операция руками. Это короткие, проверяемые шаги с ожидаемым результатом и понятным условием остановки (когда пора эскалировать).
Без понятных инструкций бизнес теряет время и деньги. Растёт простой, увеличиваются штрафы по SLA, ухудшается опыт пользователей. Появляются лишние риски: поддержка «чинит» наугад и случайно делает хуже, потому что не знает ограничений. Самое неприятное - после инцидента знания снова остаются в переписке, а не превращаются в устойчивый процесс.
Передача проекта в поддержку ломается не из-за «плохой поддержки», а из-за тумана в договорённостях. Прежде чем писать runbook для поддержки проекта, зафиксируйте три вещи: что именно поддерживаем, кто что делает и кто принимает решения в спорных ситуациях.
Сначала определите, какие системы и команды участвуют. Это не только приложение, но и база данных, очереди, платежи, почта, домены, хостинг, мониторинг, а также внешние подрядчики. Если продукт собран на платформе вроде TakProsto (типичный стек: React фронт, Go бэкенд, PostgreSQL, иногда Flutter), отдельно запишите, какие части в зоне вашей команды, а какие завязаны на инфраструктуру или сторонние сервисы.
Дальше нужны границы ответственности. Поддержка обычно принимает обращения, проверяет метрики, выполняет стандартные действия по инструкции и общается с пользователями. Разработка чинит баги в коде, выпускает патчи, меняет архитектуру и схемы данных. Важно прямо написать, какие операции поддержка делать не имеет права (например, ручные правки в базе без согласования).
Определите уровни инцидентов и кто решает. Например: P1 - сервис недоступен, решение о деградации, отключении функций или откате принимает дежурный инженер вместе с ответственным за продукт. P2 - частичная деградация, решение можно принять в рамках поддержки по шаблону. P3 - единичные ошибки, уходят в план работ.
Зафиксируйте метрики: время реакции (когда мы впервые ответили и начали диагностику) и время восстановления (когда сервис снова работает для пользователя). Без этого невозможно честно оценить, хорошо ли работает поддержка и где именно «течёт» процесс.
«Готово к поддержке» означает: известен список компонентов и владельцев, определены SLO по реакции и восстановлению, есть понятные критерии приоритета инцидентов, а поддержка имеет доступы и инструкции для типовых действий, не держа знания в голове.
Хороший runbook для поддержки проекта читается за минуты и даёт понятный следующий шаг. Его цель не «описать всё», а помочь дежурному быстро понять, что происходит, что проверить и как безопасно действовать.
Минимальный набор разделов, без которых почти всегда больно:
Для частых инцидентов держите правило «один кейс - одна секция» объёмом в 1-2 экрана. Например: «Ошибка 500 после релиза», «Очередь не разгребается», «Время ответа выросло в 3 раза». Редкие, но критичные события (компрометация ключей, повреждение данных, массовые таймауты у провайдера) лучше выносить в отдельные аварийные инструкции: они не нужны каждый день, но должны быть под рукой и без двусмысленностей.
Формат шагов важнее красоты. Рабочее правило: один шаг - одно действие - один ожидаемый результат. Формулировка «перезапусти сервис X» слишком общая. Лучше так: «перезапусти сервис X и убедись, что код ответа на /health стал 200 за 30 секунд».
Чтобы инструкции не устаревали, ведите версию и актуальность прямо вверху: дата обновления, автор, на каком окружении проверено. Полезная пометка - «проверено на практике» рядом с шагами, которые реально прогоняли.
Runbook на инцидент нужен, чтобы дежурный не гадал и не вспоминал «как мы это чинили в прошлый раз». Хороший шаблон помогает быстро подтвердить, что это именно тот случай, и безопасно перейти к действиям.
Опишите признаки так, как их видит поддержка: что говорит мониторинг, что пишет пользователь, что видно в логах. Добавьте 2-3 типичных «не это»: похожие симптомы, но другая причина. Пример: «500 на /api/login в течение 5 минут, рост ошибок в Go-сервисе, фронт на React грузится, но авторизация падает».
Сделайте короткий набор проверок, которые занимают до 2 минут каждая. Проверки должны быть безопасными и повторяемыми. Обычно хватает такого минимума:
Пишите шаги как инструкцию: «сделай X, ожидай Y». После каждого шага добавляйте критерий успеха. Например: «перезапусти сервис. Успех: ошибки 500 падают до нормы за 3-5 минут». Если не помогло, добавьте ветку: «если нет, откати на снимок или предыдущую версию. Успех: восстановилась авторизация, новые ошибки не растут».
Эскалацию зафиксируйте явно: когда прекращать попытки (например, 15 минут без прогресса или риск потери данных) и кого подключать (дежурный разработки, владелец продукта, администратор БД), с временем доступности и каналом связи.
Runbook на восстановление нужен не только для «падений». Он спасает и при тихой порче данных, и при неудачном релизе, и когда сервис вроде бы жив, но работает с ошибками. Главная цель - чтобы дежурный мог вернуть рабочее состояние быстро и одинаково, без догадок.
Сначала зафиксируйте, где именно лежат бэкапы и как к ним попасть. В runbook должно быть написано: типы бэкапов (БД, файлы, конфиги, секреты), периодичность, срок хранения и кто имеет доступ. Отдельно укажите запасной путь, если основной недоступен (например, второй бакет или копия на другом хранилище). Если доступ выдаётся по заявке, опишите, кому писать и какой шаблон запроса использовать.
Процедуру восстановления делайте пошаговой и с оценкой времени на каждый этап. Это помогает принять решение: восстанавливаемся или откатываемся на снимок или предыдущую версию.
Важно описать, что делать при частичном восстановлении и деградации. Например: БД поднялась, но часть таблиц пустая, или сервис отвечает медленно. В runbook должны быть явные ветки: когда повторять восстановление, когда переключаться на откат версии, когда вводить временные ограничения (отключить тяжёлую функцию, закрыть регистрацию, перевести сервис в read-only режим).
После восстановления нужны проверки целостности. Перечислите конкретные проверки: количество записей в ключевых таблицах, успешный логин, создание заказа или заявки, корректность фоновых задач, отсутствие всплеска 5xx и таймаутов. Лучше 5 простых проверок, которые реально делают каждый раз, чем 30 «на всякий случай».
Не забудьте про коммуникации: кого уведомить (поддержка, владелец продукта, дежурный админ), что писать (время начала, причина, точка восстановления, потери данных, статус), и что обязательно зафиксировать в постмортеме: какие шаги сработали, сколько заняло, что было непонятно в инструкции.
Ручные операции нужны даже в аккуратном проекте. Они появляются из жизни: что-то «подвисло», очередь не разгреблась, письмо не ушло, или нужно выполнить плановые действия вне релиза. Чтобы runbook для поддержки проекта работал, заранее решите: какие операции поддержка может делать сама, а какие только после подтверждения владельца сервиса.
Сначала составьте короткий список того, что реально происходит на проекте (а не «может пригодиться»). Обычно это перезапуск сервиса или воркера после зависания, повторный запуск упавшей джобы, очистка кэша или временных файлов по понятному признаку, включение или выключение фичи через флаг, ручной прогон скрипта обслуживания (например, пересчёт данных).
Для каждой операции фиксируйте предусловия: какие доступы нужны (и где они хранятся), есть ли окно работ, сколько времени операция должна занимать, и что делать, если лимит времени вышел. Добавьте точки контроля: что должно измениться в метриках или логах, чтобы считать операцию успешной.
Самое важное место в таком runbook - ограничения и риски. Прямо напишите, что нельзя делать без подтверждения: любые действия, которые могут привести к потере данных, простоям, откату схемы базы, удалению файлов, массовой рассылке или изменению прав доступа.
Шаги выполнения держите короткими и проверяемыми: «сделай действие», «проверь признак успеха», «если не так, остановись и эскалируй». Хорошо работает правило: если шаг нельзя проверить, его надо переписать.
После ручной операции поддержка должна оставить короткий отчёт. Удобно держать шаблон прямо в конце runbook:
Поддержка не может быстро реагировать, если непонятно, кому звонить, куда смотреть и что можно делать. Даже когда сервис «простой», эти три вещи чаще всего решают исход инцидента.
Соберите короткую матрицу контактов и держите её рядом с runbook-ами. Важно указать не только «кого», но и «когда» и «кто вместо него». Обычно достаточно: владелец сервиса (технический), владелец со стороны бизнеса, дежурная линия поддержки (основная смена и резерв), эксперты второй линии (БД, инфраструктура, фронтенд или мобайл), внешние подрядчики (хостинг, платежи, SMS или email).
Отдельно отметьте, кто имеет право говорить «останавливаем сервис», «делаем откат», «отключаем фичу».
Опишите, какие доступы должны быть выданы заранее (и кому), и как их отзывать. Хорошее правило: поддержка получает минимум прав для диагностики и типовых действий, а рискованные операции остаются владельцу сервиса.
Зафиксируйте точки наблюдения: где смотреть состояние (мониторинг), где искать причины (логи), где видны последствия (алерты, очередь задач, ошибки в клиенте). Пример: при жалобах «не проходит оплата» поддержка сначала проверяет дашборд ошибок, затем логи платежного сервиса, затем статус внешнего провайдера.
Чтобы не сочинять тексты в стрессе, добавьте короткие шаблоны сообщений:
Начинайте не с шаблонов, а с фактов. Поднимите историю инцидентов и запросов за последние 3-6 месяцев: тикеты, чат дежурных, алерты, постмортемы. Это даст реальную картину того, что чаще всего ломается и что поддержка будет делать руками.
Дальше выберите 5-10 самых частых или самых дорогих по времени случаев и оформите их одинаково. Поддержка должна видеть не только «что делать», но и «как понять, что это именно оно»: симптомы, быстрые проверки, критерий успеха, когда нужно звать разработчика.
Последовательность, которую реально пройти за 1-2 дня на небольшом проекте:
В финале назначьте владельца runbook (не «команду», а конкретного человека) и поставьте календарный пересмотр: например, раз в месяц и после каждого серьёзного инцидента. Тогда знания не будут жить только в голове и не устареют после первого же изменения в сервисе.
Частая проблема в том, что runbook выглядит как «памятка для автора», а не как инструкция для дежурного. В момент инцидента мозг занят не чтением между строк, а поиском простых ответов: что проверить, что сделать, как понять, что стало лучше.
Первая ловушка - слишком общие слова вместо конкретики. «Проверь логи», «перезапусти сервис», «проверь базу» не помогают, если не указано, где именно смотреть, какой командой, какой ожидаемый результат и что делать, если результата нет.
Чаще всего runbook для поддержки проекта ломается по таким причинам:
Отдельная боль - инструкции, которые невозможно выполнить безопасно. Например, «удалить зависшие записи» без фильтра, примера запроса и предупреждения, что именно нельзя трогать. Или «откатить релиз» без указания, какой артефакт считать последним стабильным и как проверить, что откат не сломал миграции.
Рабочий runbook живёт вместе с инцидентами. Если после сбоя не было короткого постмортема и правки документа, он устаревает за пару недель. Практичный подход: после каждого реального случая добавлять два пункта - что было неожиданным и какую проверку нужно сделать в первые 5 минут (например, статус внешних зависимостей, заполнение диска, свежие ошибки в метриках).
Перед тем как считать передачу завершённой, проверьте не документы «в целом», а готовность к первому реальному ночному инциденту. Хороший runbook для поддержки проекта заметен тем, что по нему можно действовать без автора рядом.
Чеклист, который обычно ловит самые болезненные пробелы:
Если по любому пункту ответ «где-то было», значит знаний всё ещё слишком много в голове, а не в поддержке.
02:17. Пользователь пишет: «Сайт не открывается, вместо списка проектов пустой экран». Дежурный видит всплеск ошибок 500 в панели метрик и рост времени ответа API. По runbook первым делом фиксируется время начала, затронутые функции и пример запроса, который падает.
Дальше идут быстрые проверки, чтобы не гадать:
В этом сценарии runbook быстро исключает сеть и фронтенд: статические страницы грузятся, но API падает на запросе списка проектов. В логах видно: «relation does not exist», и это совпадает с недавней миграцией.
Решение по runbook состоит из двух частей. Временный обход: включить режим деградации, чтобы пользователи видели понятное сообщение и могли хотя бы зайти в аккаунт. Полное восстановление: откат на последний стабильный снимок или откат релиза, затем повторная проверка ключевых сценариев (логин, список проектов, создание черновика).
Коммуникация тоже по инструкции: дежурный пишет в канал инцидента, уведомляет ответственного инженера и владельца продукта, фиксирует таймлайн и действия в тикете. После стабилизации добавляют постфактум: почему миграция не применилась, какие команды и проверки сработали.
Runbook обновляют сразу: добавляют явную проверку «миграции применены», критерии включения режима деградации и шаблон сообщения пользователям, чтобы в следующий раз не сочинять текст ночью.
Runbook начинает работать по-настоящему только после передачи. Иначе он быстро превращается в файл, который «где-то лежит», но в момент сбоя никто не уверен, что в нём актуально.
Соберите все runbook в одном месте и договоритесь о простом правиле обновлений: кто правит, кто подтверждает, и за сколько часов после изменения системы документ должен обновиться. Практичный ориентир - один владелец от разработки и один от поддержки.
Попросите поддержку пройти 2-3 самых частых сценария без реального инцидента. Это занимает около 30 минут, но сразу показывает дырки: где не хватает прав, где непонятно, что считать нормой, где шаги слишком общие.
Удобный формат прогона:
Если вы ведёте разработку на TakProsto, удобно оформлять процедуры прямо в Planning Mode, а для аварийных откатов заранее держать под рукой снимки и механизм rollback. В таких случаях поддержке проще действовать по инструкции, потому что ключевые операции подкреплены инструментами платформы takprosto.ai.
Если в runbook много действий руками (почистить очередь, перезапустить воркер, переключить флаг), это кандидат на автоматизацию. Начните с того, что случается чаще раза в месяц или занимает больше 10 минут в стрессовой ситуации.
Пример: ночью сервис начал отдавать 500, причина не ясна. По runbook поддержка проверяет статус зависимых компонентов, видит переполненную очередь, выполняет безопасную очистку по инструкции и поднимает сервис. Утром команда добавляет метрику на рост очереди и автоматическое оповещение, а в runbook остаётся короткий шаг «проверь алерт и подтверди».
После каждого заметного инцидента делайте короткий пересмотр. Не переписывайте всё, достаточно добавить 2-3 строки: что было новым, что не сработало, какие проверки сэкономили время.
Runbook отвечает на вопрос «что делать прямо сейчас», когда что-то сломалось или нужна операция руками. В нём должны быть конкретные шаги, ожидаемый результат после каждого шага и понятный момент остановки, когда пора эскалировать.
Обычная документация описывает устройство системы, но редко помогает принять решение в стрессовой ситуации и не гарантирует, что действия безопасны.
Когда разработчик рядом, можно уточнить детали и «додумать» недостающее. Ночью или в выходные поддержка остаётся без контекста и тратит время на догадки вместо действий.
Без runbook растёт простой, риски случайно ухудшить ситуацию и шанс повторять одни и те же ошибки, потому что знания остаются в переписках, а не в процессе.
Зафиксируйте три вещи: что именно поддерживаем (компоненты и зависимости), кто за что отвечает (границы поддержки и разработки) и кто принимает решения в спорных случаях.
Если этого нет, любой инцидент превращается в спор «кто должен чинить», и время восстановления улетает на согласования.
Минимум — короткое описание сервиса, точки наблюдения (метрики, логи, алерты), типовые инциденты отдельными секциями, восстановление и откат, а также ручные операции с запретами.
Главное, чтобы дежурный мог прочитать нужный раздел за пару минут и сразу понять следующий шаг.
Делайте формат «один шаг — одно действие — один ожидаемый результат». Вместо «перезапусти сервис» пишите, что именно перезапустить и по какому признаку считать, что стало лучше.
Если результат нельзя проверить, шаг считается плохим и его лучше переписать.
Эскалация должна быть явной: сколько времени вы пробуете стандартные шаги и при каких признаках прекращаете, чтобы не навредить. Типичный стоп-сигнал — отсутствие прогресса в течение заранее оговорённого времени или риск потери данных.
В runbook также полезно указать, кого именно подключать: дежурного разработки, администратора БД, владельца продукта, и какие данные нужно собрать перед передачей.
Runbook на восстановление должен отвечать на практические вопросы: где лежат бэкапы, кто имеет доступ, какую точку восстановления выбрать и как проверить результат.
После восстановления обязателен короткий набор проверок ключевых сценариев и метрик, чтобы не считать «поднялось» равным «работает».
Опишите, что поддержка может делать сама, и отдельно — что запрещено без согласования. По умолчанию безопаснее разрешить только действия, которые можно быстро проверить и откатить.
Любые операции с риском потери данных, массовых изменений или неожиданных побочных эффектов лучше явно пометить как «только через владельца сервиса».
Проведите «сухой прогон»: один человек читает runbook, другой выполняет шаги в тестовой среде или на безопасных данных, не задавая вопросов. Всё, что вызывает вопрос или упирается в доступы, сразу дописывайте.
Дальше держите простое правило: после каждого серьёзного инцидента добавляйте в runbook новые проверки и уточняйте неочевидные шаги.
Да, если эти возможности у вас реально используются и поддержке нужно уметь ими пользоваться. В runbook полезно описать, как делать откат и как проверять, что после rollback сервис вернулся в норму.
Если проект собран на TakProsto, отдельно уточните, какие операции делаются через механизмы платформы (например, snapshots, rollback, planning mode), а какие остаются на стороне инфраструктуры или внешних сервисов.
