すべてのエージェントに同梱する runbook。

我々が出荷するすべてのエージェントシステムには runbook が付いてきます。6ページ、フローチャート以上の図はなし、2010年代の SRE ドキュメントのトーンで書かれます。意図的に退屈です。

runbook は事務作業ではなく主要な納品物だ、と考えるようになりました。たった今構築したエージェントに runbook が書けないなら、そのエージェントは本番には未到達です。理由と中身を説明します。

なぜ runbook が仕様なのか

runbook は、放置していたら開いたままだったはずの6つの質問への回答を強制します。

「正しく動いている」とはどういう状態か? 雰囲気ではなく、具体的なチェック。「p95 レイテンシが X 未満、eval pass 率が Y 以上、リクエスト単価が A〜B」。
「壊れている」とはどういう状態か? 「ユーザーが文句を言う」ではなく、閾値付きの具体的症状。
壊れたら誰がページされるか? 名前、エスカレーションチェーン、電話番号。
既知の各失敗に対するプレイブックは? ステップバイステップ。答えが「5分何もしない」ならそれも含める。
いつ rollback するか? 「ひどくなったら」ではない。ミーティングなしで rollback をトリガーする具体的条件。
どの状態が生き残り、どれが残らないのか? エージェントを rollback したら、in-flight ワークフロー、部分完了、キューに溜まったリクエストはどうなるか?

チームが6つすべてに書面で答えられないなら、エージェントは本番グレードに到達していません。runbook はすでに真であることのドキュメントではありません。書くことが真にする行為そのものです。

我々が出荷するすべての runbook は同じ6セクションを持ちます。

1段落。このエージェントが何をするか、何に依存し、何が依存しているか。エージェントの責務が変わるたびに更新。

ダッシュボード URL。「健全」を定義する4〜5のメトリクス。緑/黄/赤の閾値。5を超えないこと。10あったら誰も見ません。

各失敗モードに1セクション。

ドキュメント化する失敗モードは6〜10を目指します。ほとんどのオペレータは3つしか使いませんが、ロングテールが午前3時にあなたを救います。

誰に、どの順序で、どんな問題で連絡するか。Slack ハンドルではなく電話番号。「これは on-call のスコープを超える — エンジニアリングにエスカレートする」経路も含めます。

rollback する具体的条件と、その手順。重要なのは、ミーティングなしで rollback の判断 を下す権限を持つのは誰か。通常は on-call。

rollback 手順そのものは1コマンドであるべきです。3ステップと調整通話を要するなら、それは rollback 手順ではなくプロジェクト計画です。

前回の runbook レビュー以降のすべての変更: プロンプトバージョン、モデルバージョン、retrieval インデックスバージョン、依存関係アップグレード。何かが挙動を崩したとき、on-call が「過去24時間で何が変わったか」を見られるタイムライン。

runbook はエージェントが どう動くか を説明するためのものではありません。それにはアーキテクチャドキュメントがあります。runbook は、動かなくなったときに運用するためのものです。

新規入社者のオンボーディング用でもありません。runbook はシステムを知っていることを前提とし、壊れたときに何をするかを伝えます。説明的散文で薄めないでください。

チームのエージェントとの関係が変わります。runbook がないと、すべてのインシデントが未知で、エンジニアは即興で対応し、ポストモーテムはほぼ作り話になります。

runbook があると、インシデントは文書化された期待からの例外になります。ポストモーテムは runbook の更新になります。「この失敗はセクション3になかった。新しいエントリはこれだ」。各インシデントが runbook を教育します。

6か月で、よくメンテされた runbook はシステムが実際に遭遇する失敗の90%をカバーします。残りの10%が興味深いインシデントです。プレイブック実行ではなく、本物のエンジニアリングが必要なものです。

runbook は我々のハンドオフドキュメントでもあります。エンゲージメントを終えるとき、クライアントのチームはシステムとそれを我々なしで運用できる runbook を引き継ぎます。運用知識を頭の中に留めたまま離脱したチームが原因で、悪化したハンドオーバーを我々は何度も見てきました。

意図的に退屈に。runbook がエージェントを退屈に運用可能にします。そして退屈こそが本番グレードの姿です。