How to Get an AI Coding Agent to Write a Rollback Plan

Before an AI coding agent touches anything risky, a schema migration, an authentication check, a payment path, add one line to the task: a rollback plan is part of the deliverable, not an afterthought written later by whoever gets paged. The plan names exactly what changed, the specific signal that tells you it broke something, the exact commands to undo it, and what data or state a plain revert will not fix on its own. Written before the change ships and read by a human in under a minute, it turns a risky merge into something you can undo in minutes instead of an afternoon of forensic work.

This is deliberately the opposite moment from how to roll back a bad AI coding agent change, which covers what to do once a bad change is already live. That post is triage. This one is prevention: the same agent that writes the risky code also writes the plan for undoing it, before either one reaches production.

Why a normal code review misses this

A code review checks whether the change does what it claims. It rarely checks whether the change can be cheaply undone if it turns out to be wrong, and an AI agent's diff makes that gap worse, not better. The agent will happily generate a migration that adds a NOT NULL column, backfills it from three other tables, and drops an old column in the same commit, all correct, all reviewable line by line, and all essentially unrevertible once the drop has run against production data. Nobody caught anything because there was nothing wrong to catch. The risk was never in the code. It was in the fact that undoing it required information nobody wrote down.

Asking for a rollback plan up front is a pre-mortem for AI code changes, not a second review pass. A review asks whether this is correct. A pre-mortem asks what you would need to know at 2am if it turns out not to be.

What a rollback plan actually needs to cover

A useful plan is short and specific. Five things, in this order:

1. What changed, precisely. The tables, endpoints, config keys, feature flags, and background jobs touched, not a restatement of the ticket.

2. The detection signal. The exact metric, error type, failed job name, or customer-facing symptom that would tell a human this specific change is the cause, not a generic "if something looks wrong."

3. The exact revert steps, in order. Commands to run, migrations to reverse, flags to flip, and the order that matters between them.

4. What a revert alone will not fix. Rows already backfilled, emails already sent, charges already made, cache entries already poisoned, anything a git revert cannot touch because it already happened in the outside world.

5. Whether the revert is safe to run instantly or needs a maintenance window, and who needs to be told either way.

Point four is where most agent-written rollback plans earn their keep, because it is the part a rushed human skips under pressure. An agent asked for it explicitly will actually enumerate the side effects, because listing things is what it is good at.

The prompt pattern

The trick is sequencing: ask for the plan before the implementation, as a gate the agent has to pass through, not a summary it writes after the fact once it has already forgotten which line did what.

Task: add idempotency keys to the payment charge endpoint so retried
requests never double-charge a customer.

Before writing any implementation code, write ROLLBACK.md covering:

1. Exact files, tables, config keys, and feature flags this change
   will touch.
2. The specific signal that would tell us in production that this
   change is broken (error type, metric name and threshold, log
   line, or customer-facing symptom). Not "monitor closely."
3. The exact revert steps, in the order they must run, including how
   to reverse any migration and how to disable any new flag.
4. Any data or external state this change creates that a plain
   revert will not undo (rows written, calls made to the payment
   provider, emails sent), and what a human needs to do about each
   one.
5. Whether reverting is safe to run immediately or needs a
   maintenance window, and who should be notified either way.

Do not begin the implementation until ROLLBACK.md is drafted. If any
part of the change cannot be safely reverted, say so explicitly in
the plan instead of writing revert steps that would not actually
work.

What a real rollback plan looks like coming back

For that same idempotency-key migration, a rollback plan worth reading looks close to this:

# ROLLBACK.md - idempotency keys on /charge

## What changed
- New column `idempotency_key` (unique, nullable) on `charges`.
- New table `charge_idempotency_locks`.
- `charge_service.py`: checks the lock table before calling the
  payment provider; writes a lock row before charging.
- Feature flag: `payments.idempotency_keys_enabled` (default: off).

## Detection signal
- Alert if `charge_service.duplicate_charge_blocked` fires more than
  0 times per hour under normal traffic (should never happen; a
  nonzero rate means the lock logic itself is wrong).
- Alert if p99 latency on POST /charge rises above 800ms (lock
  lookup added a query in the hot path).

## Revert steps, in order
1. Set `payments.idempotency_keys_enabled` to false. This alone
   stops new lock checks; charges continue on the old path.
2. Redeploy the previous `charge_service.py` if the flag alone does
   not fully bypass the new code path.
3. Leave the schema in place; do not drop `idempotency_key` or the
   lock table immediately, they are additive and harmless if unused.

## What a revert will not fix
- Any charge that was blocked as a false-positive duplicate while
  the bug was live needs to be manually re-run through the payment
  provider and reconciled against the customer's order.
- Lock rows written during the incident window should be reviewed,
  not bulk-deleted, in case they reveal which charges were affected.

## Maintenance window
- Not required. The flag flip and redeploy are both safe to run
  live; no customer-visible downtime.

Where this pattern is worth the extra step

Not every change needs this. A copy fix or a new UI component does not. This is for the category of change where being wrong is expensive to discover late: an AI coding agent risky change safety net, in practical terms, for anything touching

• Schema migrations, especially ones that drop, rename, or backfill columns.

• Authentication and authorization logic, session handling, or permission checks.

• Payment code, billing logic, or anything that calls a payment provider.

• Background jobs and queues, where a bad change keeps processing quietly for hours before anyone notices.

• Third-party integrations where the other side has no undo button of its own.

For everything else, asking for a rollback plan is friction with no payoff. Reserve it for the changes where the cost of skipping it is a multi-hour incident, not a five-minute git revert.

Making it a habit instead of a one-off prompt

AI agent deployment safety holds up better as a standing rule than as something you remember to type each time. Two places to anchor it:

First, tie it to the paths an agent is allowed to touch unsupervised. If your team already scopes agent permissions by directory or change type, as covered in how to set permissions for AI coding agents on a team, make a rollback plan a condition attached to the same risky categories: migrations, auth, and payments require ROLLBACK.md before the agent can open a pull request at all.

Second, enforce it mechanically rather than trusting memory. If the agent runs inside a pipeline, as described in how to run an AI coding agent in CI, add a check that fails the build when a diff touches a migrations or payments path without a matching ROLLBACK.md in the same commit. A missing file is trivial to catch in CI and easy for a human to miss in review.

It is also a natural moment to widen the lens past reversibility. When a human reviewer opens the rollback plan for a risky change, that is a good point to also apply the checks from how to catch an AI coding agent introducing a vulnerability, since both reviews are looking at the same high-stakes diff for different reasons.

This pattern sits inside the broader discipline covered in AI coding tools: agents are fast enough to ship a bad change before anyone reads it closely, so the safety has to be built into how you prompt and gate them, not bolted on after something breaks.

Frequently asked questions

Is a rollback plan the same thing as a runbook?

No. A runbook is general operational documentation for a system. A rollback plan here is scoped to one specific change, written at the moment that change is proposed, and thrown away or archived once the change has been stable for a while. It answers one question: how do we undo exactly this, right now.

Can the agent actually verify its own revert steps work?

Not fully, and do not treat the plan as tested just because it reads convincingly. Treat it as a draft a human confirms in minutes rather than reconstructs from scratch under pressure. For anything touching a migration, the safest check is running the down-migration against a staging copy of production-shaped data before merging, not just trusting the written steps.

Should the rollback plan live in the same pull request as the code?

Yes. If it lives anywhere else, wiki page, ticket description, someone's memory, it will not be there when the change actually needs undoing. Commit ROLLBACK.md alongside the diff it describes, so the two never drift apart.

What if the agent says the change cannot be safely rolled back?

That answer is the whole point of asking early. It is far cheaper to hear "this cannot be cleanly reverted" before the change ships than to discover it during an incident. Use that flag to either redesign the change into reversible steps, such as an additive migration followed by a separate cleanup later, or to accept the risk with eyes open and a maintenance window planned.

How is this different from just asking the agent to roll back after something breaks?

Timing and authorship. Asking after the fact means writing the plan under pressure, from a codebase that has already moved on, possibly with the person who understands the change no longer in the room. Asking before the change ships means the plan is written by the same agent with full context of exactly what it did, while the diff is still fresh and nothing has gone wrong yet.