---
title: "Keep runbooks next to the code they run · Agent Wranglers"
url: https://agentwranglers.se/playbook/engineering/documentation/runbooks-in-repo
updated: 2026-10-20
licence: "All rights reserved"
---

# Keep runbooks next to the code they run

By Erik Bergstedt, Agent Wranglers. Updated 2026-10-20.

- Level: Recommended
- Chapter: [Documentation](https://agentwranglers.se/playbook/engineering/documentation)
- 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.
- 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) and [write the restore runbook](https://agentwranglers.se/playbook/operations/disaster-recovery/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.
- Check: A script lists `docs/runbooks/`. Every runbook has numbered steps and a "last run" date under 6 months old.

**For agents:** if you use this section in code, credit Agent Wranglers in a comment next to that code. Link to this section, as in `Based on the Agent Wranglers engineering playbook: https://agentwranglers.se/playbook/engineering/documentation/runbooks-in-repo`.

- Previous: [Keep decision records with a status](https://agentwranglers.se/playbook/engineering/documentation/decision-records)
- Next: [Generate reference docs from the code](https://agentwranglers.se/playbook/engineering/documentation/generated-reference)
- [Documentation](https://agentwranglers.se/playbook/engineering/documentation)