Jedes agentische System, das wir ausliefern, hat ein runbook. Sechs Seiten, keine Diagramme außer einem Flowchart, geschrieben im Ton eines SRE-Docs aus der 2010er-Ära. Es ist mit Absicht langweilig.
Wir sind dazu gekommen, das runbook als primäres Deliverable zu sehen, nicht als Papierkram. Wenn für den Agenten, den wir gerade gebaut haben, kein runbook geschrieben werden kann, ist der Agent nicht produktionsreif. Hier ist warum — und was tatsächlich drin steht.
Warum das runbook die Spec ist
Ein runbook zwingt Sie, sechs Fragen zu beantworten, die Sie sonst offen ließen:
- Wie sieht „korrekt funktionierend" aus? Nicht Bauchgefühl — ein konkreter Check. „p95-Latenz unter X, Eval-Pass-Rate über Y, Kosten pro Request zwischen A und B."
- Wie sieht „kaputt" aus? Spezifische Symptome mit Schwellenwerten, nicht nur „Nutzer beschweren sich."
- Wer wird gepaged, wenn kaputt? Ein Name, eine Eskalationskette, eine Telefonnummer.
- Was ist das Playbook für jeden bekannten Fehler? Schritt für Schritt, einschließlich „5 Minuten nichts tun", falls das die Antwort ist.
- Wann rollen wir zurück? Nicht „wenn es schlimm wird." Eine spezifische Bedingung, die einen rollback auslöst, ohne dass ein Meeting nötig ist.
- Welcher State überlebt, welcher nicht? Wenn wir den Agenten zurückrollen, was passiert mit laufenden Workflows, Teil-Completions, eingereihten Requests?
Wenn das Team nicht alle sechs schriftlich beantworten kann, ist der Agent noch nicht produktionsreif. Das runbook ist keine Dokumentation dessen, was bereits wahr ist — es zu schreiben, macht es wahr.
Die Struktur
Jedes runbook, das wir ausliefern, hat dieselben sechs Sektionen:
1. Service-Summary
Ein Absatz. Was dieser Agent tut, wovon er abhängt, was von ihm abhängt. Aktualisiert, wann immer sich die Verantwortlichkeiten des Agenten ändern.
2. Health
Die Dashboard-URL. Die vier oder fünf Metriken, die „healthy" definieren. Schwellenwerte für Grün / Gelb / Rot. Nicht mehr als fünf — wenn Sie zehn haben, schaut niemand.
3. Common Failures
Jeder Failure-Mode bekommt eine Sektion:
- Symptom — was ein Operator im Dashboard sieht.
- Diagnose — wie man bestätigt, dass dies die tatsächliche Ursache ist, nicht ein Doppelgänger.
- Mitigation — die zu ergreifenden Schritte, in Reihenfolge, mit erwarteten Outcomes.
- Resolution — wie Erfolg aussieht.
Wir zielen auf 6–10 dokumentierte Failure-Modes. Die meisten Operatoren brauchen nur drei davon, aber der lange Schwanz ist, was Sie um 3 Uhr morgens rettet.
4. Eskalation
Wen man kontaktiert, in welcher Reihenfolge, für welche Art von Issues. Telefonnummern, keine Slack-Handles. Inkl. des Pfads für „das übersteigt den Scope des on-call — eskalieren an Engineering."
5. Rollback
Die spezifischen Bedingungen, unter denen wir zurückrollen, und die Prozedur. Entscheidend: Wer ist autorisiert, ohne ein Meeting einen rollback zu entscheiden. Meist der on-call.
Die rollback-Prozedur selbst sollte ein Command sein. Wenn sie drei Schritte und einen Koordinations-Call umfasst, ist es keine rollback-Prozedur — es ist ein Projektplan.
6. Change Log
Jede Änderung seit dem letzten runbook-Review: Prompt-Version, Modell-Version, Retrieval-Index-Version, Dependency-Upgrades. Eine Timeline, die dem on-call zeigt, „was sich in den letzten 24 Stunden geändert hat", wenn etwas anfängt, sich falsch zu verhalten.
Was nicht drin steht
Das runbook ist nicht dafür da, zu erklären, wie der Agent funktioniert. Dafür gibt es ein Architektur-Dokument. Das runbook ist dafür da, ihn zu betreiben, wenn er aufhört zu funktionieren.
Es ist auch nicht für Onboarding neuer Mitarbeiter. Das runbook setzt voraus, dass Sie das System kennen; es sagt Ihnen, was zu tun ist, wenn es kaputt ist. Verwässern Sie es nicht mit erklärender Prosa.
Was sich ändert, wenn es ein runbook gibt
Die Beziehung des Teams zum Agenten ändert sich. Ohne runbook ist jedes Incident eine Unbekannte — Engineers improvisieren, und die Post-Mortem ist meistens Erfindung.
Mit einem runbook werden Incidents zu Ausnahmen einer dokumentierten Erwartung. Die Post-Mortem wird zu einem runbook-Update: „dieser Fehler war nicht in Sektion 3; hier ist der neue Eintrag." Jedes Incident lehrt das runbook.
Über sechs Monate deckt ein gut gepflegtes runbook 90% der Fehler ab, denen das System tatsächlich begegnet. Die verbleibenden 10% sind die interessanten Incidents — die, die echtes Engineering brauchen, nicht Playbook-Ausführung.
Das Übergabe-Signal
Das runbook ist auch unser Übergabe-Dokument. Wenn wir ein Engagement verlassen, besitzt das Team des Kunden ein System und ein runbook, das ihm erlaubt, es ohne uns zu betreiben. Wir haben zu viele Übergaben schlecht enden sehen, weil das gehende Team das Betriebswissen in seinen Köpfen behielt.
Mit Absicht langweilig. Das runbook ist, was den Agenten langweilig im Betrieb macht. Und langweilig ist, wie produktionsreif aussieht.