The AI Coding Agent Runbook: A Practical Checklist for Reliable Changes

AI coding agents are most useful when the work around them is boring.

The less ambiguity there is about the task, the code boundaries, the verification steps, and the definition of done, the more likely the agent is to produce a change you can actually merge. The opposite is also true. If you drop an agent into a repo with a vague instruction like "clean this up" or "fix the dashboard," you should expect wandering edits, missed edge cases, and a review that takes longer than writing the code yourself.

This article gives you a practical runbook you can reuse for real engineering work. It is not tied to one model or one tool. It works with Claude Code, Codex, Cursor agents, Aider, and most terminal-based coding agents.

Use it when you want an agent to make a change that matters.

The Core Idea

An agent runbook is a short operating procedure for a single task.

It answers five questions before the agent starts editing:

• What exactly should change?
• What must not change?
• Which files or areas are in scope?
• How will we prove the result works?
• What should the agent report back at the end?

That sounds simple, but it prevents most expensive agent mistakes. The model no longer has to infer the success criteria from vibes. It has a target, boundaries, and a feedback loop.

When to Use a Runbook

You do not need a full runbook for every tiny prompt. If you are asking an agent to rename a variable or explain a function, keep it lightweight.

Use a runbook when the task has any of these traits:

• It touches production code.
• It spans more than one file.
• It changes behavior users rely on.
• It involves tests, migrations, or release notes.
• It could conflict with another person or another agent.
• It might be interrupted and resumed later.

The more expensive a bad diff would be, the more useful the runbook becomes.

The Copy-Paste Runbook

Here is the short version. Paste this into a new agent session and fill in the blanks.

# Agent task runbook

Goal:
<One sentence describing the user-visible or developer-visible outcome.>

Scope:
- In scope: <files, directories, modules, behaviors>
- Out of scope: <things the agent must not change>

Context:
- <Relevant architecture notes>
- <Known constraints>
- <Recent failures or related bugs>

Rules:
- Prefer the smallest correct change.
- Do not introduce new dependencies unless explicitly approved.
- Do not rewrite unrelated code.
- Preserve public APIs unless the goal says otherwise.
- Ask before touching files outside scope.

Verification:
- First run: <focused command or check>
- Then run: <wider command or check>
- If tests cannot run, explain exactly why and what was checked instead.

Expected final report:
- Files changed
- Behavior changed
- Tests/checks run and results
- Risks or follow-up work

This template is intentionally plain. The value is not in fancy formatting. The value is in forcing the work to become specific.

Step 1: Write a Goal That Cannot Be Misread

Bad goal:

Improve the file viewer.

Better goal:

Add stream-follow support for growing text files without changing existing PDF, image, or CSV viewer behavior.

The better goal defines the outcome and protects adjacent behavior. It gives the agent something to optimize for and something to avoid breaking.

A strong goal usually includes:

• the feature or bug being addressed
• the affected user flow
• a constraint on what should remain unchanged

Examples:

• Fix duplicate checkout polling requests after tab visibility changes without changing the checkout hook signature.
• Add a keyboard shortcut for closing the active terminal pane while preserving existing browser-tab shortcuts.
• Move XLSX parsing off the main UI thread without changing the workbook display format.

If you cannot write the goal in one sentence, the task is probably too broad.

Step 2: Define Scope Before the Agent Finds Extra Work

Agents are good at finding adjacent problems. That can be useful during review. It is dangerous during implementation.

Scope tells the agent where to operate.

Example:

Scope:
- In scope: src/viewers/text/, src/viewers/shared/streaming.ts, related tests
- Out of scope: PDF rendering, image viewer, file explorer redesign, theme changes

This prevents the common pattern where a small bug fix turns into a broad cleanup. It also makes review easier because you can compare the final diff against the agreed boundary.

For large repos, scope should include both paths and behaviors:

Scope:
- In scope: token propagation for MCP server startup and agent process launch
- In scope: tests that prove Codex and Claude sessions receive the token
- Out of scope: changing the MCP protocol shape
- Out of scope: changing user-facing auth settings

Paths alone are sometimes too narrow. Behaviors alone are sometimes too vague. Use both when the task is important.

Step 3: Add Constraints That Protect the System

Most agent regressions are not caused by bad syntax. They are caused by violating hidden constraints.

Write those constraints down.

Useful constraints include:

• No new dependencies.
• Do not change public APIs.
• Preserve existing file permissions.
• Keep backward compatibility with old saved state.
• Do not modify migrations.
• Do not change copy or visual layout outside the requested area.
• Do not touch generated files manually.
• Keep the fix local to the failing flow.

The best constraints are concrete. "Be careful" is not a constraint. "Preserve existing JSON save format" is.

If the repo has project-level instructions, the runbook should not repeat everything. It should add task-specific constraints the agent needs right now.

Step 4: Start With a Focused Verification Command

Every agent task should have a first check.

For a bug, the first check should reproduce the failure. For a feature, the first check should validate the narrowest behavior. For UI work, the first check might be a screenshot or a small manual flow.

Examples:

pnpm test src/viewers/text/stream-follow.test.ts

cargo test ssh_control_master_reuses_live_socket

npm run build

playwright screenshot http://127.0.0.1:4173/ /tmp/home.png

Do not start with the biggest possible check unless the repo is small. A full suite that takes 20 minutes is not a useful inner loop. Start focused, then widen.

A good verification section looks like this:

Verification:
- First run the focused text viewer tests.
- Then run the viewer package test target.
- Then run typecheck.
- If a command fails because dependencies are missing, report the exact failure and do not guess.

That last line matters. Agents sometimes explain around failed verification. Make the expected behavior explicit: report the failure honestly.

Step 5: Give the Agent an Editing Strategy

For production code, the safest default is the smallest correct change.

Tell the agent that directly:

Editing strategy:
- Reproduce or inspect the failure before editing.
- Make the smallest patch that satisfies the goal.
- Keep unrelated cleanup out of the diff.
- Prefer existing helpers and local patterns.
- Add tests near the behavior being changed.

This does not prevent larger changes when they are needed. It just makes the agent justify them. If the small patch is impossible, the agent can say why and propose a broader plan.

For refactors, change the strategy:

Editing strategy:
- Do not change behavior.
- Move code in mechanical steps.
- Keep commits or checkpoints small.
- Run tests after each meaningful step.

The runbook should match the work. A bug fix and a refactor need different guardrails.

Step 6: Require a Useful Final Report

The final response is part of the artifact. It should help you review the work quickly.

Ask for this:

Expected final report:
- Summary of behavior changed
- Files changed
- Tests/checks run, with pass/fail results
- Any commands that could not run
- Remaining risks

Avoid final reports that only say "done." You need evidence.

A useful final report sounds like:

Added stream-follow support for local text files by extending the text viewer stream state and watcher path. Changed TextViewer.tsx, useFileStream.ts, and text-stream.test.ts. Ran the focused stream tests and typecheck. Did not run the full app test suite because it is not available in this workspace. Remaining risk: SSH polling path still needs manual verification.

That is reviewable. It tells you what changed, what was proven, and what still needs attention.

A Complete Example

Here is a full runbook for a realistic bug fix.

# Agent task runbook

Goal:
Fix file explorer scroll jumps after rename/delete actions without changing the explorer layout or selection model.

Scope:
- In scope: file explorer scroll restoration and context menu action handling
- In scope: tests for rename/delete preserving scroll position
- Out of scope: redesigning the explorer, changing icons, changing SSH file APIs

Context:
- Users lose their place in large directories after mutating a file.
- The bug appears after the directory listing refreshes.
- Existing selection behavior should remain unchanged.

Rules:
- Prefer the smallest correct change.
- Reuse existing explorer state helpers if available.
- Do not introduce a new state library or dependency.
- Do not modify unrelated viewer code.

Verification:
- Run the focused file explorer tests first.
- Run frontend typecheck after the focused tests pass.
- If tests are missing, add a targeted regression test near the explorer component.

Expected final report:
- Files changed
- Explanation of how scroll position is preserved
- Tests/checks run and results
- Any remaining edge cases

Notice what this does. It does not tell the agent how to implement the fix. It tells the agent how to stay inside the right problem.

The Review Checklist

After the agent finishes, review the diff against the runbook.

Ask these questions:

• Did the diff satisfy the stated goal?
• Did it stay inside scope?
• Did it violate any constraints?
• Is there a focused test or check for the behavior?
• Are unrelated cleanups mixed into the change?
• Did the final report match the actual diff?
• Are there hidden compatibility risks?

This checklist catches many failures quickly. If the goal was "preserve permissions during atomic save" and the diff never checks file mode, you know where to focus. If the task was scoped to text files and the diff modifies PDF rendering, you know to push back.

The Handoff Version

Sometimes the first agent should not finish the task. It might investigate, isolate the issue, and hand off to a stronger model or a human.

Use a shorter handoff runbook:

# Handoff

Goal:
<Original goal>

What I found:
- <Important facts>
- <Files inspected>
- <Failure reproduced or not>

Current state:
- <Files changed, if any>
- <Tests run>
- <Known failures>

Next step:
<One concrete action for the next session>

Risks:
- <Anything the next person should not miss>

This keeps work from being rediscovered. It also makes multi-agent workflows less chaotic, because each session produces a clean checkpoint instead of a long transcript.

Common Mistakes

The biggest mistake is giving the agent a goal without a verification step. That produces plausible code, not proven code.

The second biggest mistake is asking for too much at once. "Refactor auth, fix tests, improve error handling, and update docs" is four tasks. Split it.

The third mistake is leaving scope implicit. If you do not say what is out of scope, the agent may decide that nearby cleanup is helpful.

The fourth mistake is accepting a final report without checking it against the diff. Agents can miss files, overstate test coverage, or forget to mention a skipped check. Treat the report as a starting point for review, not proof by itself.

A Lightweight Version for Small Tasks

For small tasks, use this compact prompt:

Make this change: <goal>.

Stay within: <files or area>.
Do not change: <protected behavior>.
Verify with: <command or manual check>.
Report back with: files changed, checks run, and any risk.

That is enough for many day-to-day changes.

Example:

Make this change: update the changelog for v0.9.0.

Stay within: public changelog and visible release links.
Do not change: historical entries except marking the new latest release.
Verify with: search for stale v0.8.7 current-release references.
Report back with: files changed, checks run, and any risk.

Small tasks still benefit from boundaries. They just do not need a full page of process.

Why This Works

An agent runbook turns a fuzzy coding request into an engineering contract.

It gives the model:

• a target
• a boundary
• constraints
• a feedback loop
• a reporting format

It gives you:

• a faster review
• a smaller diff
• fewer surprise changes
• a handoff artifact if the work continues later

The point is not to micromanage the agent. The point is to remove ambiguity from the parts of the work where ambiguity is expensive.

When agents have clear operating conditions, they become much more useful. They can still explore, reason, and implement, but they do it inside a frame that protects the codebase.

That is the difference between using an AI coding agent as a chat box and using it as part of a real development workflow.