Agent Runbooks

A convention for externalizing step-by-step procedures from AI agent instruction files (CLAUDE.md, AGENTS.md, .cursorrules, etc.) into on-demand runbook files.

The Problem

AI agent instruction files serve two purposes in tension:

1. Policy — conventions, architecture decisions, rules that apply to every interaction
2. Procedure — step-by-step instructions that apply to specific workflows

Policy is always-on context and belongs in the instruction file. Procedure is on-demand context — it should be loaded when needed and absent when not.

Inlining procedures into your instruction file means paying the full token cost on every interaction, even when the procedure is irrelevant.

The Convention

Place runbooks in a runbooks/ directory under whichever agent config directory you use:

your-project/
├── .agent/runbooks/            # or .agents/runbooks/, .ai/runbooks/
│   ├── precommit.md
│   ├── prerelease.md
│   ├── deploy.md
│   └── incident-response.md
├── CLAUDE.md                  # (or AGENTS.md, .cursorrules, etc.)
└── ...

The parent directory name is an emerging convention — .agent/, .agents/, .ai/, and tool-specific directories (.claude/, .cursor/) all work. What matters is the pattern: externalize procedures into on-demand files.

Each runbook is a standalone markdown file with a clear title, description, and procedural steps. Your instruction file references them with a single line:

Before committing, follow `.agent/runbooks/precommit.md`.

25 lines of inline procedure replaced by 1 line of reference. The agent reads the runbook on demand when it actually needs the procedure.

Emerging directory conventions

Pick whichever aligns with your existing setup. The runbooks pattern works with any of them.

Runbook Format

Runbooks are plain markdown. No special syntax required. Recommended structure:

# Procedure Name

One-line description of when this procedure applies.

## Steps

1. First step
   - Sub-step detail
   - Commands: `make check`

2. Second step
   ...

Runbooks vs Rules

AI coding tools use "rules" (.cursor/rules/, .windsurf/rules/, .rules) for declarative policy — conventions, coding standards, and architectural guidelines that shape agent behavior. Rules are typically always-loaded or conditionally attached.

Runbooks are different: they contain imperative procedures — step-by-step instructions for specific tasks. The distinction matters because it tells the agent what to expect:

• Rules = "use snake_case for Python functions" (policy, always relevant)
• Runbooks = "step 1: run make check, step 2: verify output, step 3: stage files..." (procedure, relevant only during that task)

Loading mode (eager/lazy) is orthogonal — both rules and runbooks can be loaded on demand. The content type is what differs.

Design Principles

1. One procedure per file. Each runbook covers exactly one workflow.
2. Runbooks are imperative, instruction files are declarative. The instruction file says what (conventions, rules). Runbooks say how (step-by-step procedures).
3. Reference, don't duplicate. One-line pointer in the instruction file; full procedure in the runbook.
4. Self-contained. A runbook should make sense without reading the instruction file first.
5. Version-controlled. Runbooks are code. They belong in the repo.

Cross-Harness Compatibility

This convention works with any AI coding assistant that can read project files:

Examples

See the examples/ directory for real-world runbooks:

• precommit.md — Pre-commit checklist (test, lint, audit, review)
• prerelease.md — Multi-target release procedure

Related Work

• AGENTS.md — Universal instruction file spec (Linux Foundation)
• Claude Code Skills — Progressive disclosure for agent procedures
• AgentInfra — .ai/ directory with three-layer loading
• dotagent — Universal parser/converter for AI rules across IDEs
• ACS — Agentic Collaboration Standard proposing .agents/

License

CC0 1.0 — Public domain. Use this convention however you like.