Your AI agent needs a runbook, not a vibe

A developer argues that AI coding agents need explicit runbooks, not general rules files, to handle risky operations like deployments safely. The post provides a template with preconditions, STOP conditions, verification steps, and exact commands, and recommends storing runbooks in the repo and referencing them from rules files.

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. 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: 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. 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 . 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. 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 https://kitforgedev.itch.io/agentic-coding-kit - $19, one-time, free v1.x updates.