Runbooks make repeatable work easier to supervise
A good AI coding agent runbook is a short, practical document for one recurring class of work. It tells Claude Code or Codex what the task is, where it should happen, what it is not allowed to change, and how you will know the work is done.
That is different from a full product spec and different from a long prompt. A runbook is what you reach for when the same kind of task keeps showing up and you want the next run to start with fewer questions.
Junction fits this style because the daemon runs on your machine, the agent works in the same repository as the runbook, and the browser or phone gives you a control surface for output, approval, and review.
What belongs in a runbook
A runbook should answer five questions:
- What class of work is this?
- What files or areas are in scope?
- What commands should verify it?
- What should stop the agent immediately?
- What should the reviewer look for?
If it does not help with one of those questions, it probably belongs somewhere else.
Useful runbook sections are:
- the task name,
- the allowed file areas,
- setup or branch assumptions,
- validation commands,
- high-risk boundaries,
- and the final review checklist.
That is enough structure to keep the document useful without making it fragile.
What a runbook is not
A runbook is not:
- a long architectural essay,
- a copy of the README,
- a ticket dump,
- or a hidden place for secrets.
It should not try to hold every exception the project has ever seen. The more general the document gets, the less likely anyone is to use it on the next task.
The best runbooks are small enough to read before a run starts and specific enough to be worth keeping around.
A useful template
Here is a simple template for a recurring bug-fix run:
## Task
Fix one user-visible bug in the pricing or settings flow.
## Scope
- Only edit the site package.
- Do not change daemon code.
- Do not change pricing numbers unless the task says so.
## Verification
- Run the focused package test.
- Run typecheck if the diff touches shared components.
## Stop conditions
- The fix requires schema changes.
- The task expands into multiple unrelated screens.
- The agent cannot explain the failing path from the output.
## Review
- Confirm the diff is limited to the task area.
- Confirm the final state matches the expected user path.This template is intentionally boring. That is a feature.
Runbooks work best for repeated task classes
Not every task deserves a runbook. The best candidates are the ones that happen often enough that you keep re-explaining them:
- a small copy update with a predictable review path,
- a recurring test fix,
- a branch cleanup after an agent run,
- a doc update that should not touch app logic,
- or a narrow hotfix flow.
If a task happens once a year, a note in the issue may be enough. If it happens every week, a runbook usually pays off.
Keep the boundaries sharp
The most useful runbook detail is the boundary.
For example:
- what file types are safe to edit,
- what packages are out of scope,
- which commands are known-good,
- and which changes need human review before they continue.
That boundary is what prevents the agent from turning a focused task into a repo-wide exploration.
If the runbook says "fix the settings copy only," the agent should not wander into auth, pricing, or build system code unless the task explicitly expands.
A concrete example
Imagine a runbook for "update empty states in the app."
It might say:
- scope the work to
packages/site, - keep the copy accessible and concise,
- verify with the site tests,
- and stop if the fix requires a data model change.
That runbook lets a future Claude Code or Codex session start with the right assumptions without carrying a full prompt history from the last time the task appeared.
You can make the example more specific if a task repeats enough:
- empty-state copy,
- error-state copy,
- mobile button labels,
- or review prompts for permission prompts.
The more often the pattern repeats, the more valuable the runbook becomes.
How to keep them current
Runbooks rot when nobody revisits them after the workflow changes.
Review a runbook when:
- the test command changes,
- a package moves,
- the branching model changes,
- or the same mistake keeps recurring.
Do not update the document for every tiny change. Update it when the lesson is durable.
If a runbook keeps growing, split it. One runbook for setup, one for verification, one for cleanup is often better than one giant checklist.
How runbooks and repo instructions work together
Runbooks and repo instruction files solve different problems.
Repository instructions explain the stable project facts that every agent should know. Runbooks explain the recurring task you want to perform today.
That means you can keep the instructions broad and the runbook narrow:
CLAUDE.mdorAGENTS.mdfor repo rules,- a runbook for the repeated action,
- and Junction for live supervision, approvals, and diff review.
For the instruction side, read Use CLAUDE.md and AGENTS.md to Steer Local Agent Runs. For the local-control side, start with the setup guide.
Tradeoffs
Runbooks introduce one more file to maintain. That is the cost of reuse.
The upside is that you stop retyping the same constraints every time a task class returns. You also reduce the chance that the agent re-discovers a boundary that already caused trouble last week.
The only real failure mode is over-documenting. If the runbook is longer than the work, it will not be used. Keep it short enough that the next person can read it before a run starts.
Where Junction fits
Junction does not replace the runbook. It makes the runbook visible where the work happens. The daemon runs locally, the agent stays attached to the repo, and you can inspect the session state as the runbook is being followed or violated.
If you are deciding whether this workflow should stay in a simple setup or move into a paid plan, compare pricing. If you want more context on the instruction layer, pair this post with Use Branch Suggestions to Keep Agent Runs Reviewable.