Κάθε agentic σύστημα που παραδίδουμε έχει ένα runbook. Έξι σελίδες, χωρίς διαγράμματα πέρα από ένα flowchart, γραμμένο στο ύφος ενός SRE doc του 2010. Είναι βαρετό επί τούτου.
Έχουμε καταλήξει να θεωρούμε το runbook ως κύριο παραδοτέο, όχι γραφειοκρατία. Αν δεν μπορεί να γραφτεί runbook για το agent που μόλις χτίσαμε, το agent δεν είναι έτοιμο για παραγωγή. Δείτε γιατί, και τι περιέχει στην πραγματικότητα.
Γιατί το runbook είναι η προδιαγραφή
Ένα runbook σας αναγκάζει να απαντήσετε σε έξι ερωτήσεις που αλλιώς θα αφήνατε ανοιχτές:
- Πώς μοιάζει το «δουλεύει σωστά»; Όχι vibes — ένας συγκεκριμένος έλεγχος. «p95 latency κάτω από X, eval pass rate πάνω από Y, κόστος ανά request μεταξύ A και B.»
- Πώς μοιάζει το «χαλασμένο»; Συγκεκριμένα συμπτώματα με κατώφλια, όχι απλώς «οι χρήστες παραπονιούνται».
- Ποιος ειδοποιείται όταν χαλάει; Ένα όνομα, μια αλυσίδα escalation, ένας αριθμός τηλεφώνου.
- Ποιο είναι το playbook για κάθε γνωστή αποτυχία; Βήμα-βήμα, συμπεριλαμβανομένου του «μην κάνεις τίποτα για 5 λεπτά» αν αυτή είναι η απάντηση.
- Πότε κάνουμε rollback; Όχι «αν χειροτερέψει». Μια συγκεκριμένη συνθήκη που ενεργοποιεί rollback χωρίς να απαιτεί σύσκεψη.
- Ποια κατάσταση επιβιώνει και ποια όχι; Αν κάνουμε rollback το agent, τι γίνεται με τα in-flight workflows, τις μερικές ολοκληρώσεις, τα requests σε ουρά;
Αν η ομάδα δεν μπορεί να απαντήσει και στις έξι γραπτώς, το agent δεν είναι ακόμη production-grade. Το runbook δεν είναι documentation αυτού που ισχύει ήδη — η συγγραφή του είναι αυτό που το κάνει αληθινό.
Η δομή
Κάθε runbook που παραδίδουμε έχει τις ίδιες έξι ενότητες:
1. Service summary
Μία παράγραφος. Τι κάνει αυτό το agent, από τι εξαρτάται, τι εξαρτάται από αυτό. Ενημερώνεται όποτε αλλάζουν οι ευθύνες του agent.
2. Health
Το URL του dashboard. Τα τέσσερα ή πέντε metrics που ορίζουν το «υγιές». Κατώφλια για πράσινο / κίτρινο / κόκκινο. Όχι περισσότερα από πέντε — αν έχετε δέκα, κανείς δεν τα παρακολουθεί.
3. Συνηθισμένες αποτυχίες
Κάθε failure mode παίρνει μια ενότητα:
- Σύμπτωμα — τι βλέπει ένας operator στο dashboard.
- Διάγνωση — πώς να επιβεβαιώσει ότι αυτή είναι η πραγματική αιτία, όχι μια παρόμοια.
- Mitigation — τα βήματα που πρέπει να ληφθούν, με σειρά, με αναμενόμενα αποτελέσματα.
- Επίλυση — πώς μοιάζει η επιτυχία.
Στοχεύουμε 6–10 failure modes τεκμηριωμένα. Οι περισσότεροι operators θα χρειαστούν μόνο τρία από αυτά, αλλά η μακριά ουρά είναι αυτή που σας σώζει στις 3 το πρωί.
4. Escalation
Ποιον να καλέσετε, με ποια σειρά, για ποια είδη ζητημάτων. Αριθμούς τηλεφώνου, όχι Slack handles. Συμπεριλάβετε τη διαδρομή για «αυτό ξεπερνά τον σκοπό του on-call — escalate στο engineering».
5. Rollback
Οι συγκεκριμένες συνθήκες υπό τις οποίες κάνουμε rollback, και η διαδικασία. Κρίσιμο: ποιος είναι εξουσιοδοτημένος να αποφασίσει rollback χωρίς σύσκεψη. Συνήθως ο on-call.
Η ίδια η διαδικασία rollback θα έπρεπε να είναι μία εντολή. Αν είναι τρία βήματα και μια κλήση συντονισμού, δεν είναι διαδικασία rollback — είναι σχέδιο έργου.
6. Change log
Κάθε αλλαγή από την τελευταία αναθεώρηση του runbook: prompt version, model version, retrieval index version, dependency upgrades. Ένα timeline που επιτρέπει στον on-call να δει «τι άλλαξε τις τελευταίες 24 ώρες» όταν κάτι αρχίζει να συμπεριφέρεται περίεργα.
Τι δεν είναι μέσα
Το runbook δεν είναι για να εξηγεί πώς το agent λειτουργεί. Υπάρχει architecture doc για αυτό. Το runbook είναι για να το λειτουργείτε όταν σταματά να δουλεύει.
Επίσης δεν είναι για onboarding νεοπροσληφθέντων. Το runbook υποθέτει ότι ξέρετε το σύστημα· σας λέει τι να κάνετε όταν είναι χαλασμένο. Μην το αραιώνετε με επεξηγηματική πρόζα.
Τι αλλάζει όταν υπάρχει runbook
Η σχέση της ομάδας με το agent αλλάζει. Χωρίς runbook, κάθε περιστατικό είναι ένα άγνωστο — οι μηχανικοί αυτοσχεδιάζουν, και το post-mortem είναι κυρίως επινόηση.
Με ένα runbook, τα περιστατικά γίνονται εξαιρέσεις σε μια τεκμηριωμένη προσδοκία. Το post-mortem γίνεται ενημέρωση του runbook: «αυτή η αποτυχία δεν ήταν στην ενότητα 3· εδώ είναι η νέα καταχώρηση». Κάθε περιστατικό διδάσκει το runbook.
Σε έξι μήνες, ένα καλά συντηρημένο runbook καλύπτει το 90% των αποτυχιών που το σύστημα συναντά πραγματικά. Το υπόλοιπο 10% είναι τα ενδιαφέροντα περιστατικά — αυτά που χρειάζονται πραγματικό engineering, όχι εκτέλεση playbook.
Το σήμα του handoff
Το runbook είναι επίσης το έγγραφο handoff μας. Όταν φεύγουμε από ένα engagement, η ομάδα του πελάτη κατέχει ένα σύστημα και ένα runbook που τους επιτρέπει να το λειτουργούν χωρίς εμάς. Έχουμε δει πολλά handovers να αποτυγχάνουν επειδή η αποχωρούσα ομάδα κρατούσε τη γνώση λειτουργίας στο κεφάλι της.
Βαρετό επί τούτου. Το runbook είναι αυτό που κάνει το agent βαρετό προς λειτουργία. Και το βαρετό είναι το πώς μοιάζει το production-grade.