documenting runbooks agents actually follow
Explains how to write runbooks that agents actually follow: linear steps, expected outputs, and decision points, instead of prose documentation. Use when agents execute operational procedures; not for human-only runbooks or high-level architecture docs.
TL;DR
Agents follow checklists, not essays: a runbook that reads like a procedure gets executed; one that reads like a blog post gets skimmed. Every step needs a success check the agent can verify. Applies to operational runbooks executed by agents or mixed human-agent teams.
The query
documenting runbooks agents actually followUse this when
- Agents execute your operational procedures.
- Prose docs get skimmed; checklists get followed.
- Every step needs a verifiable success check.
Not for
- Humans alone execute the procedure (write for humans, with judgment calls spelled out).
- The procedure changes every run (automate it instead of documenting it).
- You need a design doc (different document, different audience).
Steps
- Write the procedure as numbered steps, each with one action and one expected output.
Expected output: A linear checklist an agent can walk through.
- Add decision points as explicit branches: if X, do Y; else do Z.
Expected output: No ambiguity at the points where runs usually stall.
- Include the rollback or abort step for when things go wrong.
Expected output: A safe exit the agent can take without improvising.
- Have an agent execute the runbook once and fix every step it stumbles on.
Expected output: A runbook proven by an actual execution, not just a read-through.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_fKy98AFi5JRBhuLu5xJ5iw
Maintainer review
No maintainer verification is recorded for this version.
This records the version a maintainer checked. It does not assert that the version is the latest upstream release.