Всяка агентна система, която доставяме, има runbook. Шест страници, без диаграми освен flowchart, написани в тона на SRE документ от 2010 г. Скучен е нарочно.
Стигнахме до това да виждаме runbook-а като основен deliverable, не като документация. Ако не може да се напише runbook за агента, който току-що сме построили, агентът не е готов за production. Ето защо и какво всъщност има в него.
Защо runbook-ът е спецификацията
Runbook принуждава да отговорите на шест въпроса, които иначе бихте оставили отворени:
- Как изглежда „работещ правилно“? Не усещане — конкретна проверка. „p95 latency под X, eval pass rate над Y, цена за заявка между A и B.“
- Как изглежда „счупен“? Конкретни симптоми с прагове, не просто „потребители се оплакват“.
- Кой се вдига, когато се счупи? Име, ескалационна верига, телефонен номер.
- Какъв е playbook-ът за всеки известен failure? Стъпка по стъпка, включително „не правете нищо за 5 минути“, ако това е отговорът.
- Кога правим rollback? Не „ако стане лошо“. Конкретно условие, което тригерира rollback без да изисква среща.
- Какво състояние оцелява и какво не? Ако rollback-нем агента, какво се случва с in-flight workflows, частични завършвания, опашки със заявки?
Ако екипът не може да отговори на всичките шест писмено, агентът все още не е production-grade. Runbook-ът не е документация на това, което вече е вярно — писането му е това, което го прави вярно.
Структурата
Всеки runbook, който доставяме, има същите шест секции:
1. Резюме на услугата
Един параграф. Какво прави този агент, от какво зависи, какво зависи от него. Обновява се всеки път, когато отговорностите на агента се променят.
2. Здраве
Dashboard URL. Четирите или петте метрики, които дефинират „здрав“. Прагове за зелено / жълто / червено. Не повече от пет — ако имате десет, никой не ги гледа.
3. Чести failures
Всеки failure mode получава секция:
- Симптом — какво вижда оператор в dashboard-а.
- Диагноза — как да потвърдите, че това е реалната причина, а не двойник.
- Mitigation — стъпките, които да се вземат, по ред, с очаквани резултати.
- Resolution — как изглежда успех.
Целим документирани 6–10 failure modes. Повечето оператори ще се нуждаят само от три от тях, но дългата опашка е това, което ви спасява в 3 сутринта.
4. Ескалация
С кого да се свържете, в какъв ред, за какви видове проблеми. Телефонни номера, не Slack handles. Включете пътя за „това е извън обхвата на on-call — ескалирайте до инженеринг“.
5. Rollback
Конкретните условия, при които правим rollback, и процедурата. Критично: кой е оторизиран да решава за rollback без среща. Обикновено on-call.
Самата rollback процедура трябва да е една команда. Ако са три стъпки и координационно обаждане, това не е rollback процедура — това е план за проект.
6. Change log
Всяка промяна от последното ревю на runbook-а: prompt версия, model версия, retrieval index версия, dependency upgrades. Timeline, който позволява на on-call да види „какво се промени в последните 24 часа“, когато нещо започне да се държи неправилно.
Какво не е в него
Runbook-ът не е за обяснение как работи агентът. Има architecture doc за това. Runbook-ът е за оперирането му, когато спре да работи.
Също не е за onboarding на нови служители. Runbook-ът предполага, че познавате системата; той ви казва какво да правите, когато е счупена. Не го разреждайте с обяснителна проза.
Какво се променя, когато има runbook
Отношението на екипа към агента се променя. Без runbook всеки инцидент е неизвестно — инженерите импровизират, а post-mortem-ът е предимно изобретяване.
С runbook инцидентите стават изключения към документирано очакване. Post-mortem-ът става обновяване на runbook-а: „този failure не беше в секция 3; ето новия запис“. Всеки инцидент обучава runbook-а.
В рамките на шест месеца добре поддържан runbook покрива 90% от failures-те, които системата реално среща. Останалите 10% са интересните инциденти — тези, които изискват реален инженеринг, а не изпълнение на playbook.
Сигналът за handoff
Runbook-ът е също нашият handoff документ. Когато напускаме ангажимент, екипът на клиента притежава система и runbook, който им позволява да я оперират без нас. Видели сме твърде много handovers да се провалят, защото напускащият екип е запазил оперативното знание в главите си.
Скучен нарочно. Runbook-ът е това, което прави агента скучен за опериране. А скучен е как изглежда production-grade.