Ogni sistema con agenti IA che rilasciamo ha un runbook. Sei pagine, nessun diagramma oltre un flowchart, scritto nel tono di un documento SRE dell'era 2010. È noioso di proposito.
Siamo arrivati a vedere il runbook come un deliverable primario, non come carta da firmare. Se non si può scrivere un runbook per l'agente che abbiamo appena costruito, l'agente non è pronto per la produzione. Ecco perché, e cosa contiene davvero.
Perché il runbook è la spec
Un runbook la costringe a rispondere a sei domande che altrimenti resterebbero aperte:
- Come si presenta il "funziona correttamente"? Niente sensazioni — un controllo concreto. "Latenza p95 sotto X, pass rate degli eval sopra Y, costo per richiesta tra A e B."
- Come si presenta il "rotto"? Sintomi specifici con soglie, non solo "gli utenti si lamentano."
- Chi viene svegliato quando è rotto? Un nome, una catena di escalation, un numero di telefono.
- Qual è il playbook per ciascun fallimento noto? Passo passo, incluso "non faccia nulla per 5 minuti" se è quella la risposta.
- Quando facciamo rollback? Non "se va male." Una condizione specifica che innesca il rollback senza richiedere una riunione.
- Quale stato sopravvive, e quale no? Se facciamo rollback dell'agente, cosa succede ai workflow in-flight, ai completamenti parziali, alle richieste in coda?
Se il team non sa rispondere a tutte e sei per iscritto, l'agente non è ancora production-grade. Il runbook non è la documentazione di ciò che è già vero — scriverlo è ciò che lo rende vero.
La struttura
Ogni runbook che rilasciamo ha le stesse sei sezioni:
1. Riepilogo del servizio
Un paragrafo. Cosa fa questo agente, da cosa dipende, cosa dipende da lui. Aggiornato ogni volta che cambiano le responsabilità dell'agente.
2. Salute
L'URL della dashboard. Le quattro o cinque metriche che definiscono "in salute." Soglie per verde / giallo / rosso. Non più di cinque — se ne ha dieci, nessuno le guarda.
3. Fallimenti comuni
Ogni modalità di fallimento ha una sua sezione:
- Sintomo — cosa vede un operatore nella dashboard.
- Diagnosi — come confermare che sia la causa vera, e non un sosia.
- Mitigazione — i passi da fare, in ordine, con gli esiti attesi.
- Risoluzione — come si presenta il successo.
Puntiamo a 6–10 modalità di fallimento documentate. La maggior parte degli operatori ne userà solo tre, ma la coda lunga è ciò che la salva alle 3 di notte.
4. Escalation
Chi contattare, in che ordine, per quali tipi di problemi. Numeri di telefono, non handle Slack. Includa il percorso per "questo è oltre lo scope dell'on-call — escali all'engineering."
5. Rollback
Le condizioni specifiche in cui si fa rollback, e la procedura. Soprattutto: chi è autorizzato a decidere il rollback senza una riunione. Di solito l'on-call.
La procedura di rollback stessa dovrebbe essere un comando. Se sono tre passi e una call di coordinamento, non è una procedura di rollback — è un piano di progetto.
6. Change log
Ogni modifica dall'ultima review del runbook: versione del prompt, versione del modello, versione dell'indice di retrieval, upgrade di dipendenze. Una timeline che permette all'on-call di vedere "cosa è cambiato nelle ultime 24 ore" quando qualcosa inizia a comportarsi male.
Cosa non c'è dentro
Il runbook non serve a spiegare come l'agente funziona. Per quello c'è il documento di architettura. Il runbook serve a operarlo quando smette di funzionare.
Non serve nemmeno per l'onboarding di nuovi assunti. Il runbook presuppone che lei conosca il sistema; le dice cosa fare quando è rotto. Non lo diluisca con prosa esplicativa.
Cosa cambia quando c'è un runbook
Il rapporto del team con l'agente cambia. Senza runbook, ogni incident è un'incognita — gli ingegneri improvvisano, e il post-mortem è in gran parte invenzione.
Con un runbook, gli incident diventano eccezioni a un'aspettativa documentata. Il post-mortem diventa un aggiornamento del runbook: "questo fallimento non era nella sezione 3; ecco la nuova voce." Ogni incident insegna qualcosa al runbook.
Nell'arco di sei mesi, un runbook ben mantenuto copre il 90% dei fallimenti che il sistema incontra davvero. Il restante 10% sono gli incident interessanti — quelli che richiedono ingegneria vera, non esecuzione di playbook.
Il segnale di handoff
Il runbook è anche il nostro documento di handoff. Quando lasciamo un engagement, il team del cliente possiede un sistema e un runbook che gli permette di operarlo senza di noi. Abbiamo visto troppi passaggi di consegne andare male perché il team uscente teneva la conoscenza operativa nelle proprie teste.
Noioso di proposito. Il runbook è ciò che rende noioso operare l'agente. E noioso è esattamente come deve apparire il production-grade.