# Your AI agent needs a runbook, not a vibe

> Source: <https://dev.to/kitforge/your-ai-agent-needs-a-runbook-not-a-vibe-372i>
> Published: 2026-09-09 07:20:00+00:00

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.*