---
title: "Keep runbooks next to the code they run · Agent Wranglers"
url: https://agentwranglers.se/playbook/documentation/docs-for-coding-agents/runbooks-in-repo
id: DOC-44
level: Recommended
updated: 2026-10-27
build: a2a6bdfed830
tokens: 876
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Keep runbooks next to the code they run

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Docs for coding agents](https://agentwranglers.se/playbook/documentation/docs-for-coding-agents.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-27.

- ID: DOC-44
- Level: Recommended
- Chapter: [Docs for coding agents](https://agentwranglers.se/playbook/documentation/docs-for-coding-agents.md)
- Rule: 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.
- Check: A script lists `docs/runbooks/`. Every runbook has numbered steps and a "last run" date under 6 months old.
- How: 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](https://agentwranglers.se/playbook/operations/alerts-and-on-call/actionable-alerts.md) and [write the restore runbook](https://agentwranglers.se/playbook/operations/disaster-recovery/restore-runbook.md). 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.

## Related rules

- TST-53 [Run load tests from a written runbook](https://agentwranglers.se/playbook/testing/performance-tests/load-test-runbook.md) in Testing
- OPS-69 [Keep manual operations work under half the time](https://agentwranglers.se/playbook/operations/running-the-service/limit-toil.md) in Operations and observability
- TKO-41 [Record handover sessions before the old team leaves](https://agentwranglers.se/playbook/codebase-takeover/triage/record-handover-sessions.md) in Codebase takeover
- DOC-2 [Write how-to guides as numbered steps toward one goal](https://agentwranglers.se/playbook/documentation/kinds-of-docs/how-to-steps.md) in Documentation
- OPS-19 [Make every alert actionable](https://agentwranglers.se/playbook/operations/alerts-and-on-call/actionable-alerts.md) in Operations and observability
- OPS-47 [Write the restore runbook](https://agentwranglers.se/playbook/operations/disaster-recovery/restore-runbook.md) in Operations and observability
- DOC-18 [Put a stop before every destructive step in a runbook](https://agentwranglers.se/playbook/documentation/docs-for-coding-agents/destructive-step-stops.md) in Documentation
- TDD-9 [Ask the team to explain the critical paths without AI](https://agentwranglers.se/playbook/due-diligence/code-and-ownership/explain-without-ai.md) in Technical due diligence

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/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.

- Previous: [Publish the docs in a form agents can fetch](https://agentwranglers.se/playbook/documentation/docs-for-coding-agents/agent-readable-docs.md)
- Next: [Put a stop before every destructive step in a runbook](https://agentwranglers.se/playbook/documentation/docs-for-coding-agents/destructive-step-stops.md)
- [Docs for coding agents](https://agentwranglers.se/playbook/documentation/docs-for-coding-agents.md)