Ask an AI coding agent to deploy your service and watch what happens. It will improvise: guess the deploy command, skip the health check, forget to warm the cache, and announce success before the rollback window even opens.
Now ask a senior engineer the same thing. They don't improvise. They follow the runbook — the boring, written-down, step-by-step procedure that exists precisely so nobody has to think during a risky operation.
Your agent needs that document too. Not a paragraph of encouragement in a rules file. An actual runbook.
Vibes don't survive contact with production
Rules files tell agents how to behave in general. Runbooks tell them exactly what to do in a specific, dangerous situation. The difference matters most when the stakes are highest:
- Deploys. Order of operations, health checks, rollback triggers.
- Migrations. Backup first, run in a transaction, verify row counts, have the reverse migration ready.
- Incident response. What to check first, who to page, what never to touch.
When you skip the runbook, the agent pattern-matches from training data — which means it runs the deploy procedure from a 2021 Medium post about a stack you don't use.
Anatomy of a runbook an agent can execute
A good agent runbook is not the wiki page you wrote for humans. Humans tolerate ambiguity, infer context, and know which steps are skippable. Agents execute literally and confidently. Write accordingly:
1. Preconditions as checks, not prose.
Bad: "Make sure the migration is reversible."
Good: ls migrations/down/ | grep <migration_name> must return a file. If not, STOP and ask.
2. Explicit STOP conditions.
Agents default to forward progress. Every runbook needs a list of states where the correct action is to halt and report: "If the health check fails twice, do NOT retry a third time. Revert and report."
3. Verification after every mutating step.
Not "deploy the service" but "deploy, then curl /healthz expecting 200, then check the error rate for 2 minutes." An agent that verifies catches its own mistakes. An agent that doesn't, ships them.
4. Named commands, never described commands.
"Run the test suite" gets you pytest on a repo that uses make test. Write the exact command. If the exact command varies, write how to discover it (cat Makefile | grep -A2 test).
A minimal example
## Deploy: api-service
Preconditions (check ALL, stop if any fail):
- `git status` clean on main
- `make test` passes
- No active incident: `curl -s status.internal/health | grep OK`
Steps:
1. `make build && make deploy-staging`
2. Verify: `curl -s staging.api/healthz` returns 200
3. Run smoke suite: `make smoke-staging`
4. `make deploy-prod`
5. Watch error rate for 120s: `make watch-errors`
STOP and rollback (`make rollback`) if:
- Any health check returns non-200
- Error rate exceeds 0.5% at any point
- Any step hangs longer than 5 minutes
Six lines of structure, and the agent goes from improvising theater to executing a procedure.
Where runbooks live
Keep them in the repo, in a runbooks/ directory, referenced from your rules file by path: "Before any deploy, read runbooks/deploy-api.md and follow it exactly." The rules file points; the runbook executes.
This also fixes the context-window problem from my last post: the agent loads the runbook when it needs it, instead of carrying 400 lines of deploy lore in every session.
The kit I sell includes ready-to-adapt runbook templates for deploys, migrations, and incident response, alongside the CLAUDE.md templates and git hook suite: The Agentic Coding Kit - $19, one-time, free v1.x updates.
Top comments (0)