Chaque système à base d'agents IA que nous livrons a un runbook. Six pages, aucun diagramme au-delà d'un flowchart, écrit dans le ton d'un doc SRE de 2010. C'est ennuyeux exprès.
Nous en sommes venus à voir le runbook comme un livrable primaire, pas comme de la paperasse. Si on ne peut pas écrire un runbook pour l'agent qu'on vient de construire, l'agent n'est pas prêt pour la production. Voici pourquoi, et ce qu'il contient vraiment.
Pourquoi le runbook est la spec
Un runbook vous force à répondre à six questions que vous laisseriez sinon ouvertes :
- À quoi ressemble « ça marche correctement » ? Pas au feeling — un contrôle concret. « Latence p95 sous X, taux de réussite eval au-dessus de Y, coût par requête entre A et B. »
- À quoi ressemble « cassé » ? Des symptômes spécifiques avec des seuils, pas juste « les utilisateurs se plaignent ».
- Qui est pagé quand c'est cassé ? Un nom, une chaîne d'escalade, un numéro de téléphone.
- Quel est le playbook pour chaque défaillance connue ? Pas-à-pas, y compris « ne rien faire pendant 5 minutes » si c'est la réponse.
- Quand fait-on un rollback ? Pas « si ça devient mauvais ». Une condition spécifique qui déclenche le rollback sans nécessiter une réunion.
- Quel état survit, et lequel non ? Si on rollback l'agent, qu'arrive-t-il aux workflows en cours, aux complétions partielles, aux requêtes en file d'attente ?
Si l'équipe ne peut pas répondre par écrit aux six, l'agent n'est pas encore production-grade. Le runbook n'est pas la documentation de ce qui est déjà vrai — l'écrire est ce qui le rend vrai.
La structure
Chaque runbook que nous livrons a les mêmes six sections :
1. Résumé du service
Un paragraphe. Ce que fait cet agent, ce dont il dépend, ce qui dépend de lui. Mis à jour à chaque changement des responsabilités de l'agent.
2. Santé
L'URL du tableau de bord. Les quatre ou cinq métriques qui définissent « en bonne santé ». Les seuils vert / jaune / rouge. Pas plus de cinq — si vous en avez dix, personne ne les regarde.
3. Défaillances courantes
Chaque mode de défaillance a sa section :
- Symptôme — ce qu'un opérateur voit dans le tableau de bord.
- Diagnostic — comment confirmer que c'est la vraie cause, et non un sosie.
- Mitigation — les étapes à suivre, dans l'ordre, avec les résultats attendus.
- Résolution — à quoi ressemble la réussite.
Nous visons 6 à 10 modes de défaillance documentés. La plupart des opérateurs n'en auront besoin que de trois, mais c'est la longue traîne qui vous sauve à 3 h du matin.
4. Escalade
Qui contacter, dans quel ordre, pour quels types de problèmes. Des numéros de téléphone, pas des handles Slack. Incluez le chemin pour « ceci dépasse le périmètre de l'on-call — escalader à l'ingénierie ».
5. Rollback
Les conditions spécifiques sous lesquelles on rollback, et la procédure. Surtout : qui est autorisé à décider de rollback sans réunion. Généralement l'on-call.
La procédure de rollback elle-même doit tenir en une commande. Si c'est trois étapes et un appel de coordination, ce n'est pas une procédure de rollback — c'est un plan de projet.
6. Journal des changements
Chaque changement depuis la dernière revue du runbook : version du prompt, version du modèle, version de l'index de retrieval, montées de version de dépendances. Une chronologie qui permet à l'on-call de voir « qu'est-ce qui a changé dans les 24 dernières heures » quand quelque chose commence à mal se comporter.
Ce qui n'y est pas
Le runbook n'est pas là pour expliquer comment l'agent fonctionne. Il y a un doc d'architecture pour ça. Le runbook est là pour l'opérer quand il cesse de fonctionner.
Ce n'est pas non plus pour l'onboarding des nouvelles recrues. Le runbook suppose que vous connaissez le système ; il vous dit quoi faire quand c'est cassé. Ne le diluez pas avec de la prose explicative.
Ce qui change quand il y a un runbook
La relation de l'équipe à l'agent change. Sans runbook, chaque incident est une inconnue — les ingénieurs improvisent, et le post-mortem est largement de l'invention.
Avec un runbook, les incidents deviennent des exceptions à une attente documentée. Le post-mortem devient une mise à jour du runbook : « cette défaillance n'était pas en section 3 ; voici la nouvelle entrée. » Chaque incident enseigne le runbook.
Sur six mois, un runbook bien entretenu couvre 90 % des défaillances que le système rencontre réellement. Les 10 % restants sont les incidents intéressants — ceux qui demandent de la vraie ingénierie, pas de l'exécution de playbook.
Le signal de handoff
Le runbook est aussi notre document de handoff. Quand nous quittons une mission, l'équipe du client possède un système et un runbook qui lui permet de l'opérer sans nous. Nous avons vu trop de transferts mal tourner parce que l'équipe qui partait gardait le savoir opérationnel dans sa tête.
Ennuyeux exprès. Le runbook est ce qui rend l'agent ennuyeux à opérer. Et l'ennuyeux, c'est à quoi ressemble le production-grade.