Previewing changes before applying them: diffs, previews and review

Previewing an AI agent's changes means reviewing them before they happen. What a diff should show, how to handle non-text actions and when a summary is enough.

info Quick Definition
Previewing changes before applying them means showing a person what an AI agent is about to modify before the change happens, usually as a diff or a list of effects. It lets them approve, correct or reject with information, instead of discovering the result afterwards.

What problem does a preview solve?

An agent that writes code or text produces changes the person has to understand. If they only see the final result, they do not know what was lost, what was rewritten by mistake or what changed more than expected. If they see the change first, they can review the intent and the scope in seconds.

A preview also separates two moments that often get mixed: deciding whether the change is correct and applying it. When the system merges them, the person approves what they think will happen, not what will happen.

What should a good diff show?

A diff, the comparison between the previous state and the proposed one, is the classic form for code and text. To work for someone who does not program, show:

  1. Which files or elements change. A short list first, with the number of lines or changes for each.
  2. Before and after. Only the modified parts, with enough context to understand the line, not the whole file.
  3. The reason. One sentence from the agent about why it made that change, attached to the block.
  4. What does not change. Sometimes it matters to know that the rest of the file stayed the same.

Order matters. A person who opens a 600-line diff with no summary takes a long time to find what matters. A summary such as “three files, two text changes, one new dependency” orients them before the detail.

What to do with actions that have no text?

A payment, an email send, a status change in a third-party system or a record in a database have no natural diff. For those, the preview must describe the effect in plain language:

  • What will be done, in one sentence. “Send an email to 42 customers with the subject X”.
  • Who or what it affects. Recipients, accounts, amounts, dates.
  • What cannot be undone. Said plainly.
  • A real example. A sample email with one person’s data, or the charge for one specific case, to validate the text before a mass send.

That view is part of human-controlled design: the person sees the effect, not only the agent’s intention.

When is a summary enough?

If changes are repetitive and low risk, a full diff of each one exhausts the person. For example, renaming fifty files with the same pattern. In that case, show the pattern (from what to what), the list of affected items and three or four sample cases. If the samples are right, the batch is approved. If a sample surprises, open the detail.

There is a trap here: the summary must say how many changes there are. A batch described as “some files” that is really three hundred is not a preview.

How do real tools handle it, and how does it connect to undo?

A preview reduces the need to undo, but does not remove it: an approved change can still turn out to be bad. So an approved change should also leave a restore point or a commit. The page on undoing what an agent did describes that second line of defense, and Git for designers explains the commit.

Two tools show how review gets split:

  • Claude Code. According to its documentation, the permission prompt shows what Claude is about to do, followed by the options to approve or reject. In accept-edits mode (acceptEdits), Claude creates and edits files in the working directory without asking; the documentation recommends it when you would rather review the changes afterwards, in your editor or with git diff, than approve each edit. Plan mode is another kind of preview: Claude researches and proposes changes without editing your files, and edits stay blocked until you approve the plan (more in plan mode). Its checkpoints only track edits made with its file-editing tools: changes made through terminal commands or by other sessions are normally not recorded, and the documentation states they are not a replacement for version control.
  • Replit Agent. According to its documentation, each background task runs in an isolated copy of the project and does not change the main version until you review its work log, test results and live preview, and decide to apply or dismiss it.

The difference between them is exactly what the design must explain: what is reviewed beforehand and what is accepted on trust. The rules that decide when each prompt appears are in permissions UX for agents, and the concrete approval question is in action approval.

Example

Illustrative example: an agent proposes changing the text of a payment button on the checkout page. The person receives a diff with two modified lines, the reason “the current text is confused with the test plan” and a note: “It does not change the billing logic”.

They approve the text, but reject a second change the agent added in the same batch: an adjustment to the tax value. The diff showed it with its reason, and the person saw it because the summary said “two text changes, one value change”. Without that summary line, the tax change would have passed hidden among the text changes.

When should you NOT show a full preview?

  • When the action is reversible, internal and low impact. Reviewing every line of a draft nobody will use wastes time.
  • When the preview is so long nobody reads it. A summary with the option to see the detail is better.
  • When the person cannot judge the content. Then the preview must come with an explanation or with someone who can.

Common mistakes

  • Showing a large diff without a summary.
  • Showing the final result without the before.
  • Calling changes “minor” when they change a value, a price or a recipient.
  • Applying a whole batch after approving a sample that was not representative.
  • Presenting a code diff to someone who needs to understand the effect on their business.

Sources

Frequently asked questions

What does previewing changes in an AI agent mean?
It means showing the person what the agent is about to modify before the change is applied, usually as a diff or a list of effects, so they can approve, correct or reject it.
What should a change preview show?
The affected files or records, the content before and after, the reason for the change and, where relevant, the external effect it will have, such as an email that will go out or an amount that will be charged.
Is a diff always the best way to preview?
For code and text, it usually is. For actions without text, such as a payment or a send, a diff does not help; the effect must be shown in plain language.
When is a summary view enough?
When changes are repetitive and low risk, for example renaming fifty files with the same pattern. Then show the pattern, the list of affected items and a sample.