Как подготовить runbook первичной проверки с помощью ИИ: соберите утверждённую процедуру, передайте её модели с явной границей разрешённых действий, получите черновик, сверьте каждый шаг с исходником и согласуйте владельца и дату пересмотра. Ниже — рабочий порядок, копируемый промпт и учебный пример.
Назначение документа и его границы
Runbook описывает повторяемую процедуру, которую оператор выполняет по заранее согласованным шагам. В документации PagerDuty runbook определён как подробное руководство «how-to» для повторяющейся задачи в IT-процессе: провижининг, обновления и развёртывания, изменения конфигурации, открытие портов. Там же сказано, что runbook даёт оператору стандартизированные детальные инструкции для быстрого и согласованного решения типовых задач.
Для первичной проверки это означает конкретную границу: документ собирает сведения и передаёт их дежурному. Устранение причины и восстановление сервиса остаются за пределами процедуры. В корпусе Google SRE дежурный инженер во время смены диагностирует, смягчает, исправляет или эскалирует инциденты — в этом перечне первичная проверка и действия по исправлению образуют разные задачи дежурства.
Разведите два жанра. PagerDuty прямо указывает, что playbook охватывает общую реакцию на крупные события и может включать несколько runbook и участников. Диагностический playbook ищет неизвестную причину; runbook выполняет уже заданную последовательность. В учебном артефакте RB-04 назначение сформулировано так: проверить статус и передать дежурному точные сведения, без обещания восстановления.
Практический вывод для промпта: перечислите разрешённые действия и запреты отдельными пунктами. Модель склонна дописывать «полезные» шаги вроде перезапуска задания или SQL-запроса. Если граница не задана текстом, черновик выйдет за рамки процедуры, и его придётся переписывать вручную.
Сбор и проверка исходных данных
Соберите входы до обращения к модели. Нужны: утверждённые шаги, условия запуска, наблюдаемые результаты, точки остановки и способ передачи сведений. В документации AWS Well-Architected для реестра runbook приведены поля Runbook ID, Description, Tools Used, Special Permissions, Runbook Author, Last Updated, Escalation POC. Эта таблица задаёт минимум сведений, которые должны существовать до написания текста: инструменты, особые права, автор, дата обновления и точка эскалации.
Проверьте каждый вход на принадлежность к вашей системе. Права доступа, имена заданий, коды ошибок и метки времени берутся из вашей документации и ваших интерфейсов. Модель не знает ваших идентификаторов, и любое число, которого нет во входных данных, в черновике окажется выдуманным.
Сверьте полноту по контрольному списку:
| Что проверить | Зачем это нужно | Источник |
|---|---|---|
| Условия запуска | Оператор понимает, когда процедура применима | Утверждённая процедура команды |
| Разрешённые действия | Граница между сбором сведений и исправлением | Регламент доступа |
| Наблюдаемые результаты | Проверка факта выполнения шага | Интерфейс системы |
| Точки остановки | Передача дежурному при неизвестном статусе | Соглашение команды |
| Владелец и дата пересмотра | Документ остаётся актуальным | AWS Well-Architected, поля реестра |
В документации Atlassian для шаблона DevOps runbook предлагается начать с общей картины: дать команде обзор архитектуры системы, чтобы она понимала, как хосты и сервисы работают вместе. Там же сказано назначить ответственных за поддержку и указать их контакты. Для первичной проверки это переводится в короткий блок «кто получает сведения» с точкой эскалации.
Отдельно проверьте, что входные данные не содержат персональных сведений и содержимого заявок. В учебном артефакте RB-04 это отдельный пункт: не помещать персональные данные и содержимое заявок в сообщение. Такой запрет попадает в промпт как явное требование.
Готовый учебный артефакт RB-04
Ниже — учебный пример процедуры первичной проверки задержки обновления. Все значения условные, они показывают структуру документа.
RB-04 «Первичная проверка задержки обновления»
Все данные учебные.
Назначение: проверить статус и передать дежурному точные сведения.
Процедура не обещает восстановление.
Входные условия:
- обновление дашборда должно происходить каждый час;
- сотруднику разрешён только просмотр;
- команда утвердила следующие шаги.
Шаги:
1. Прочитать метку «Данные обновлены» и записать время.
2. Открыть статус задания.
Если Running — не перезапускать, передать дежурному номер задания и время.
Если Failed — сохранить номер, время и код ошибки; передать их дежурному.
3. Не помещать персональные данные и содержимое заявок в сообщение.
4. Не повторять импорт и не перезаписывать таблицу.
5. После сообщения дежурного об успешном цикле повторно посмотреть метку времени.
Остановка: неизвестный статус, недостаточный доступ, невозможность прочитать номер.
Результат процедуры: дежурный получил необходимые сведения; это не доказательство
восстановления.
Владелец и дата пересмотра: команда должна назначить.
Разберите структуру. Назначение задаёт границу. Входные условия фиксируют, при каких обстоятельствах процедура применима. Шаги описывают действия и наблюдаемые результаты. Остановка перечисляет случаи, когда оператор прекращает работу и передаёт сведения. Результат этого runbook — переданные дежурному сведения. Состояние восстановления нужно подтвердить отдельно.
Учебный вход для этого примера: в 10:05 дашборд показывает последнее обновление 08:00, в задании 473 статус Failed и код IMPORT_TIMEOUT, повторять импорт сотруднику нельзя. Готовое сообщение дежурному: «Задание 473; в 10:05 последнее обновление 08:00; статус Failed; код IMPORT_TIMEOUT. Повторный импорт не выполнялся».
Обратите внимание на формулировку последней строки сообщения. Она фиксирует, что действие не выполнялось, и не содержит оценки состояния сервиса. Это соответствует границе процедуры: оператор передаёт наблюдения, устранение причины требует отдельной работы дежурного.
Копируемый промпт с указанными входами
Промпт, чтобы оформить утверждённые шаги RB-04 в структуру runbook:
Оформи только утверждённые шаги RB-04: назначение, условия, действие,
наблюдаемый результат, остановка, передача. Не добавляй перезапуск, SQL
или способ исправления. Не называй передачу сведений восстановлением.
Входные данные:
- назначение: [назначение процедуры];
- условия: [условия запуска];
- шаги: [утверждённые шаги по порядку];
- наблюдаемые результаты: [что видно после каждого шага];
- остановка: [случаи прекращения работы];
- передача: [кому и какие сведения передаются];
- запреты: [что оператору делать нельзя].
Требования к тексту:
- каждый шаг содержит действие и наблюдаемый результат;
- запреты вынесены отдельным блоком;
- результат процедуры сформулирован как передача сведений;
- владелец и дата пересмотра оставлены для заполнения командой.
Что менять под себя: подставьте свои значения вместо квадратных скобок, добавьте идентификатор процедуры и точку эскалации. Если в вашей системе есть особые права доступа, перечислите их в блоке запретов или в отдельном поле.
Вариации той же задачи:
- Оформить процедуру проверки доступности сервиса по метрике и передать сведения дежурному.
- Оформить процедуру проверки очереди заданий при задержке обработки.
- Оформить процедуру проверки сертификата и передачи сведений ответственному.
- Оформить процедуру проверки резервной копии по метке последнего успешного запуска.
- Оформить процедуру проверки прав доступа по журналу изменений.
В каждой вариации сохраняйте ту же рамку: назначение, условия, шаги с наблюдаемыми результатами, остановка, передача. Меняются предметная область и набор запретов.
Отрицательный пример и неизвестные данные
Разберите черновик, который нарушает границу. Модель может добавить шаг перезапустить задание 473 и проверить статус. Такой шаг выходит за рамки первичной проверки: он выполняет действие по исправлению, требует прав, которых у оператора может не быть, и меняет состояние системы до того, как дежурный получил сведения.
Второй типичный дефект — подмена результата. Формулировка «сервис восстановлен» появляется там, где процедура завершается передачей сведений. В учебном артефакте RB-04 результат описан прямо: дежурный получил необходимые сведения, и это не доказательство восстановления.
Третий дефект — выдуманные данные. Если во входных данных нет кода ошибки, модель может подставить правдоподобное значение. Проверяйте каждое число в черновике по исходнику: номер задания, время, код ошибки, идентификатор процедуры.
Отдельно обработайте неизвестные данные. В процедуре должны быть точки остановки для случаев, когда оператор не может прочитать статус, не имеет достаточного доступа или не видит номер задания. В RB-04 эти три случая перечислены как остановка. Если модель не получила их во входных данных, она либо пропустит блок, либо придумает свой перечень.
Сравнение двух подходов к черновику:
| Признак | Черновик в границах процедуры | Черновик за границами |
|---|---|---|
| Действия | Чтение метки, статуса, номера | Перезапуск, SQL, правка таблицы |
| Результат | Передача сведений дежурному | Заявление о восстановлении |
| Данные | Значения из входных данных | Правдоподобные подстановки |
| Остановка | Перечислены известные случаи | Блок отсутствует |
Ручная проверка результата по исходнику
Сверьте черновик с утверждённой процедурой построчно. Начните с назначения: оно должно совпадать по смыслу с исходной формулировкой. Затем пройдите шаги и отметьте для каждого наблюдаемый результат. Шаг без наблюдаемого результата оператор не сможет проверить.
Проверьте числа. Каждый номер задания, время, код ошибки и идентификатор сверяются с исходником. В учебном примере это задание 473, время 10:05 и 08:00, код IMPORT_TIMEOUT. Значения, которых нет во входных данных, из черновика удаляются.
Проверьте запреты. В RB-04 их два: не помещать персональные данные и содержимое заявок в сообщение, не повторять импорт и не перезаписывать таблицу. Убедитесь, что черновик не ослабил формулировки и не превратил запрет в рекомендацию.
Проверьте блок остановки и результат. Остановка должна перечислять случаи, при которых оператор прекращает работу. Результат формулируется как передача сведений. Если в тексте появилось утверждение о восстановлении, верните черновик на доработку.
Практическая проверка на исполнение: пройдите процедуру мысленно от первого шага до передачи и отметьте места, где не хватает сведений. В документации PagerDuty рекомендуется полевые испытания документированного процесса и обновление по итогам. Для первичной проверки это означает прогон на учебном входе и правку формулировок, которые вызвали вопросы.
Отдельно проверьте, что документ не смешивает runbook и playbook. Если в тексте появились ветвления для неизвестной причины, это признак диагностического сценария. Такой материал стоит вынести в отдельный документ, а в runbook оставить заданную последовательность.
Согласование, хранение и пересмотр
Согласуйте документ с командой до публикации. В документации AWS Well-Architected в реестре runbook предусмотрены поля автора, даты обновления и точки эскалации. Заполните их: без владельца документ быстро устаревает, и оператор следует шагам, которые уже не соответствуют системе.
Определите место хранения. В документации Atlassian шаблон DevOps runbook размещён в Confluence, где команда ведёт общие страницы и базы знаний. Подойдёт любой инструмент, который команда уже использует для документации, при условии единой структуры и одинаковых заголовков во всех процедурах. В документации PagerDuty отмечено, что runbook стоит держать согласованными по приложениям: одна структура, единые имена и заголовки.
Назначьте дату пересмотра. В документации PagerDuty шаги построения шаблона описаны как планирование, написание и проверка с течением времени. Пересмотр привязывайте к изменениям системы: новая версия интерфейса, смена прав доступа, изменение расписания обновлений.
Зафиксируйте порядок обновления. При изменении процедуры сначала правится утверждённый исходник, затем черновик runbook, затем документ проходит ту же ручную сверку. Обратный порядок приводит к расхождению между регламентом и инструкцией.
Передайте документ дежурному до первого использования. В корпусе Google SRE отмечено, что дежурство означает готовность отвечать на производственные инциденты в заданный период, а эскалации требуют живых контактных лиц. Runbook сокращает объём вопросов к дежурному, когда оператор передаёт точные сведения по установленной форме.
Частые вопросы
Как подготовить runbook первичной проверки с помощью ИИ?
Соберите утверждённую процедуру, передайте её модели с явной границей разрешённых действий, получите черновик, сверьте каждый шаг с исходником и согласуйте владельца и дату пересмотра. Модель оформляет структуру, содержание остаётся за командой.
Чем runbook отличается от playbook?
В документации PagerDuty playbook охватывает общую реакцию на крупные события и может включать несколько runbook и участников. Runbook выполняет заданную последовательность шагов для повторяемой задачи. Для первичной проверки используется runbook с фиксированными шагами.
Какие данные нельзя передавать модели?
Персональные данные и содержимое заявок. В учебном артефакте RB-04 это отдельный запрет. Передавайте идентификаторы, статусы, коды ошибок и метки времени, необходимые для оформления процедуры.
Что делать, если модель добавила лишние шаги?
Удалите шаги, выходящие за границу процедуры: перезапуск, SQL-запросы, правку таблиц. Если такие действия нужны, они описываются в отдельном документе и выполняются дежурным. В промпте перечислите запреты явным списком.
Как проверить готовый runbook?
Пройдите процедуру по шагам на учебном входе, сверьте числа с исходником, проверьте блоки остановки и результата. В документации PagerDuty рекомендуется полевые испытания документированного процесса и обновление по итогам.