Fiecare sistem agentic pe care îl livrăm are un runbook. Șase pagini, fără diagrame dincolo de un flowchart, scris în tonul unui doc SRE din 2010. E plictisitor intenționat.
Am ajuns să vedem runbook-ul ca pe un livrabil principal, nu paperwork. Dacă nu se poate scrie un runbook pentru agentul pe care tocmai l-am construit, agentul nu e gata de producție. Iată de ce și ce conține efectiv.
De ce runbook-ul e specificația
Un runbook te forțează să răspunzi la șase întrebări pe care altfel le-ai lăsa deschise:
- Cum arată „funcționează corect"? Nu vibe-uri — un check concret. „Latența p95 sub X, rata de pass pe evals peste Y, costul pe request între A și B."
- Cum arată „stricat"? Simptome specifice cu praguri, nu doar „utilizatorii se plâng."
- Cine e trezit când e stricat? Un nume, un lanț de escaladare, un număr de telefon.
- Care e playbook-ul pentru fiecare eșec cunoscut? Pas cu pas, inclusiv „nu face nimic timp de 5 minute" dacă ăsta e răspunsul.
- Când facem rollback? Nu „dacă se înrăutățește." O condiție specifică care declanșează rollback fără a necesita o ședință.
- Ce stare supraviețuiește și ce nu? Dacă facem rollback la agent, ce se întâmplă cu workflow-urile în zbor, finalizările parțiale, request-urile din coadă?
Dacă echipa nu poate răspunde la toate șase în scris, agentul nu e încă production-grade. Runbook-ul nu e documentația a ce e deja adevărat — scrierea lui e ce îl face adevărat.
Structura
Fiecare runbook pe care îl livrăm are aceleași șase secțiuni:
1. Rezumat de serviciu
Un paragraf. Ce face acest agent, de ce depinde, ce depinde de el. Actualizat oricând se schimbă responsabilitățile agentului.
2. Sănătate
URL-ul dashboard-ului. Cele patru sau cinci metrici care definesc „sănătos". Praguri pentru verde / galben / roșu. Nu mai mult de cinci — dacă ai zece, nu le urmărește nimeni.
3. Eșecuri comune
Fiecare mod de eșec primește o secțiune:
- Simptom — ce vede un operator în dashboard.
- Diagnoză — cum confirmi că asta e cauza reală, nu un look-alike.
- Mitigare — pașii de făcut, în ordine, cu rezultatele așteptate.
- Rezolvare — cum arată succesul.
Țintim 6–10 moduri de eșec documentate. Majoritatea operatorilor vor avea nevoie doar de trei dintre ele, dar coada lungă te salvează la 3 dimineața.
4. Escaladare
Pe cine să contactezi, în ce ordine, pentru ce tipuri de probleme. Numere de telefon, nu handle-uri de Slack. Include calea pentru „asta depășește scope-ul de on-call — escaladează la inginerie."
5. Rollback
Condițiile specifice în care facem rollback și procedura. Crucial: cine e autorizat să decidă rollback fără ședință. De obicei on-call-ul.
Procedura de rollback în sine ar trebui să fie o singură comandă. Dacă sunt trei pași și un apel de coordonare, nu e o procedură de rollback — e un plan de proiect.
6. Change log
Fiecare schimbare de la ultimul review de runbook: versiunea de prompt, versiunea de model, versiunea indexului de retrieval, upgrade-urile de dependențe. O cronologie care îi lasă pe on-call să vadă „ce s-a schimbat în ultimele 24 de ore" când ceva începe să se comporte aiurea.
Ce nu e în el
Runbook-ul nu e pentru a explica cum funcționează agentul. Există un doc de arhitectură pentru asta. Runbook-ul e pentru a-l opera când nu mai funcționează.
Nu e nici pentru onboarding-ul noilor angajați. Runbook-ul presupune că știi sistemul; îți spune ce să faci când e stricat. Nu-l dilua cu proză explicativă.
Ce se schimbă când există un runbook
Relația echipei cu agentul se schimbă. Fără runbook, fiecare incident e un necunoscut — inginerii improvizează, iar post-mortem-ul e mai mult invenție.
Cu runbook, incidentele devin excepții la o așteptare documentată. Post-mortem-ul devine un update de runbook: „acest eșec nu era în secțiunea 3; iată noua intrare." Fiecare incident învață runbook-ul.
În șase luni, un runbook bine întreținut acoperă 90% din eșecurile pe care sistemul le întâlnește efectiv. Restul de 10% sunt incidentele interesante — cele care au nevoie de inginerie reală, nu de execuție de playbook.
Semnalul de handoff
Runbook-ul e și documentul nostru de handoff. Când plecăm dintr-un engagement, echipa clientului deține un sistem și un runbook care îi lasă să-l opereze fără noi. Am văzut prea multe handover-uri eșuate pentru că echipa care pleacă păstra cunoștințele operaționale în capetele lor.
Plictisitor intenționat. Runbook-ul e ce face agentul plictisitor de operat. Iar plictisitor e cum arată production-grade.