Sevk ettiğimiz her agentic sistemin bir runbook'u var. Altı sayfa, bir flowchart dışında diyagram yok, 2010 dönemi bir SRE doc tonunda yazılmış. Bilinçli olarak sıkıcı.
Runbook'u kağıt işi değil, birincil bir teslimat olarak görmeye başladık. Az önce inşa ettiğimiz ajan için bir runbook yazılamıyorsa, ajan production için hazır değildir. İşte nedeni ve içinde gerçekten ne var.
Runbook neden spec'tir
Bir runbook, aksi takdirde açık bırakacağınız altı soruyu yanıtlamaya zorlar:
- "Doğru çalışıyor" neye benzer? Vibe değil — somut bir kontrol. "p95 latency X altında, eval pass oranı Y üstünde, request başına maliyet A ile B arasında."
- "Bozuk" neye benzer? Sadece "kullanıcılar şikayet ediyor" değil, eşiklerle birlikte spesifik semptomlar.
- Bozulduğunda kime page atılır? Bir isim, bir eskalasyon zinciri, bir telefon numarası.
- Bilinen her hata için playbook nedir? Adım adım, cevap o ise "5 dakika hiçbir şey yapma" dahil.
- Ne zaman rollback yaparız? "Kötüleşirse" değil. Toplantı gerektirmeden rollback'i tetikleyen spesifik bir koşul.
- Hangi state hayatta kalır, hangisi kalmaz? Ajanı rollback edersek, in-flight workflow'lara, kısmi tamamlamalara, kuyruktaki isteklere ne olur?
Ekip altısının da cevabını yazılı olarak veremiyorsa, ajan henüz production-grade değildir. Runbook zaten doğru olanı dokümante etmez — onu yazmak, onu doğru yapan şeydir.
Yapı
Sevk ettiğimiz her runbook'un aynı altı bölümü var:
1. Servis özeti
Bir paragraf. Bu ajanın ne yaptığı, neye bağımlı olduğu, neyin ona bağımlı olduğu. Ajanın sorumlulukları değiştiğinde güncellenir.
2. Health
Dashboard URL'si. "Sağlıklı"yı tanımlayan dört ya da beş metrik. Yeşil / sarı / kırmızı için eşikler. Beşten fazla değil — onunuz varsa, kimse onları izlemiyor.
3. Yaygın hatalar
Her hata modu bir bölüm alır:
- Symptom — bir operatörün dashboard'da gördüğü şey.
- Diagnosis — bunun gerçek neden olduğunu, bir benzeri değil, nasıl onaylayacağınız.
- Mitigation — alınacak adımlar, sırasıyla, beklenen sonuçlarla.
- Resolution — başarı neye benzer.
6–10 hata modu dokümante etmeyi hedefliyoruz. Çoğu operatör sadece üçünü ihtiyaç duyacak, ama uzun kuyruk sizi sabahın 3'ünde kurtaran şey.
4. Eskalasyon
Kiminle iletişime geçileceği, hangi sırayla, ne tür sorunlar için. Slack handle'ları değil, telefon numaraları. "Bu on-call'un kapsamı dışında — mühendisliğe eskale et" yolunu dahil edin.
5. Rollback
Rollback yaptığımız spesifik koşullar ve prosedür. Kritik olarak: toplantı olmadan rollback yapmaya karar verme yetkisi olan kişi. Genellikle on-call.
Rollback prosedürünün kendisi tek bir komut olmalı. Üç adım ve bir koordinasyon call'u ise, bu bir rollback prosedürü değil — bir proje planı.
6. Change log
Son runbook review'undan bu yana her değişiklik: prompt sürümü, model sürümü, retrieval index sürümü, dependency upgrade'leri. Bir şey yanlış davranmaya başladığında on-call'un "son 24 saatte ne değişti" görmesini sağlayan bir timeline.
İçinde olmayan
Runbook, ajanın nasıl çalıştığını açıklamak için değildir. Bunun için bir mimari doc var. Runbook, ajan çalışmayı bıraktığında onu işletmek içindir.
Yeni işe alım onboarding'i için de değildir. Runbook sistemi bildiğinizi varsayar; bozulduğunda ne yapacağınızı söyler. Açıklayıcı nesirle sulandırmayın.
Bir runbook olduğunda ne değişir
Ekibin ajanla ilişkisi değişir. Runbook olmadan, her olay bir bilinmezdir — mühendisler doğaçlama yapar ve post-mortem çoğunlukla uydurmadır.
Runbook ile olaylar, dokümante edilmiş bir beklentinin istisnası haline gelir. Post-mortem bir runbook güncellemesi olur: "bu hata bölüm 3'te yoktu; işte yeni giriş." Her olay runbook'a öğretir.
Altı ay boyunca, iyi sürdürülen bir runbook, sistemin gerçekte karşılaştığı hataların %90'ını kapsar. Kalan %10, ilginç olaylardır — gerçek mühendislik gerektirenler, playbook execution değil.
Devir sinyali
Runbook ayrıca devir dokümanımız. Bir engagement'tan ayrıldığımızda, müşterinin ekibi bir sisteme ve onu bizsiz işletmelerini sağlayan bir runbook'a sahip olur. Ayrılan ekip işletme bilgisini kafalarında tuttuğu için kötü giden çok fazla devir gördük.
Bilinçli olarak sıkıcı. Runbook, ajanı işletmesi sıkıcı yapan şeydir. Ve sıkıcı, production-grade'in neye benzediğidir.