Write runbooks for humans and AI agents

Operational docs used to have one primary reader: a person in a hurry. Now they may also be read by an AI agent trying to help that person. The best runbooks work for both.

That does not mean adding magical formatting. It means being explicit about context, safety boundaries, expected outputs, and verification.

Make the first screen do more work

A good runbook starts with the boring facts an operator needs before taking action:

• Purpose: what problem this fixes.
• Scope: what systems or files are safe to touch.
• Do not do: actions that are risky, noisy, or out of bounds.
• Success signal: the exact check that proves the fix worked.
• Rollback: how to undo the change, or where to stop and ask.

Add an AI-friendly prompt block

Humans can skim prose and infer missing context. Agents are better when the instruction is explicit. A small prompt block can help a human delegate safely:

Prompt to use with an AI assistant:
Read this runbook first. Perform only read-only diagnostics until you can name the likely failure layer. Do not restart services, publish data, or edit credentials. Report: observed state, likely cause, proposed next action, and exact verification command.

Separate diagnosis from action

For both humans and agents, mark the difference between checks and state changes. A read-only command is safe to run during triage. A restart, deletion, migration, or publish step needs a higher bar.

This distinction also improves search snippets and AI retrieval. A future reader can quickly find the diagnostic path without accidentally copying a destructive command.

Use stable phrases for SEO and retrieval

Search engines and AI systems both benefit from clear language. Prefer phrases people actually search for: debug stuck worker queue, agent runbook template, safe service restart checklist, AI operations documentation.