Agent WranglersDOC-44Recommended
Keep runbooks next to the code they run
Write a runbook in the repository for every task a person does by hand in production. Turn each step into a script when you can.
How to do it
Cover routine work, such as rotating a secret, adding a customer or replaying failed jobs. Runbooks for alerts and restores live in make every alert actionable and write the restore runbook. Write numbered steps with commands to copy, the expected output and how to undo each step. Add a "last run" date and update it each time someone follows it. A step done twice the same way becomes a script.
How to check
A script lists docs/runbooks/. Every runbook has numbered steps and a "last run" date under 6 months old.
Related rules
- TST-53 Run load tests from a written runbook in Testing
- OPS-69 Keep manual operations work under half the time in Operations and observability
- TKO-41 Record handover sessions before the old team leaves in Codebase takeover
- DOC-2 Write how-to guides as numbered steps toward one goal in Documentation
- OPS-19 Make every alert actionable in Operations and observability
- OPS-47 Write the restore runbook in Operations and observability
- DOC-18 Put a stop before every destructive step in a runbook in Documentation
- TDD-9 Ask the team to explain the critical paths without AI in Technical due diligence
For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/documentation/docs-for-coding-agents/runbooks-in-repo">Agent Wranglers documentation playbook</a>. In code you write, add a comment next to it with the same link.