Why does my AI coding agent change files I didn't ask about?

An AI coding agent changes files you did not ask about for four common reasons: the task never said which files were in scope, the task was vague enough that the agent widened it, a formatter or code generator rewrote files as a side effect, or the agent drifted into refactoring code it passed on the way. Most of these are visible in one look at the change list, and each has a different fix. Reformatting is a tooling problem, drift is a task-writing problem and missing scope is a process problem. The goal is not to stop the agent ever touching a second file, since real changes often need one, but to make every touched file either expected or explained. This page shows how to sort the unexpected changes, what to do with each kind, and how to catch out-of-scope writes before they reach review. The broader question of limiting what an agent may do is in scope control for AI agents.

Check first: sort the changes

Start with the list, not the diff. git status shows modified and untracked files; git diff --stat shows how much each one changed. Then sort every unexpected file into one of four groups.

Formatting only. Run git diff -w on the file. If the whitespace-insensitive diff is empty or nearly so, a formatter, an editor setting or a line-ending change did it.

Generated or derived. Lockfiles, snapshots, compiled assets, migration files and generated clients. Ask what produced them: an install, a build, or a test run with snapshot updates switched on.

Related edits. Changes in a caller, a type definition or a test that the requested change genuinely needed. These are in scope in substance even if the task did not list them. Check that each one is necessary, not just convenient.

Unrelated edits. Renames, cleanups, rewritten comments or improvements in code the task did not concern. This is drift.

Count the groups. A dozen formatting-only files point to tooling; one large unrelated rewrite points to the task.

Fixes for each cause

Formatting. Configure the formatter to run on changed files only, or run it across the whole repository once in its own commit so later diffs stay clean. Make sure the agent's environment uses the same formatter version and settings as yours; a different version reformats files nobody edited.

Generated files. Decide which generated files belong in version control. If they do, regenerate them deliberately in a separate step. If snapshot tests updated themselves, treat that as a test change and review it as one.

Vague tasks. 'Clean up the export module' invites edits everywhere. Rewrite it with an area and a boundary: 'Change src/export/csv.py and its tests. Do not rename public functions.' Ask for a plan first when the area is unclear; planning before agent edits covers how.

Drift. Revert the unrelated hunks with git restore -p or git checkout -p, then, if the refactor was a good idea, write it up as its own task. Keeping it separate makes both changes reviewable and lets you reject one without the other.

Declaring scope in a way you can check

A scope is only useful if it can be compared with the result, so write it as paths and rules, not prose.

Allowed: src/export/ and tests/export/. Allowed with a stated reason: any caller of export_csv, if its signature changes. Not allowed: package manifests, CI configuration, migrations.

That is short enough to put in every task and specific enough to check mechanically. After the run, compare the changed path list with the allowed list. A small script that reads git diff --name-only against the base commit and flags anything outside the patterns is enough to start. Run it in a pre-commit hook or in CI so the check does not depend on someone remembering it.

When several agents work at once, scope also stops them colliding; preventing agents editing the same files covers locking and assignment. And when a cross-file change is legitimate, reviewing it as one unit is its own skill, described in reviewing cross-file AI changes.

Preventing the next one

Three habits stop unrequested edits from becoming routine.

Ask the agent to name the files it intends to change before it changes them. Tools with a planning or read-only mode make this cheap. If the list surprises you, adjust the task before any edits happen.

Make an out-of-scope change a reason to pause, not a footnote. If the agent finds it needs a file outside the scope, it should say so and wait, or record the need as a follow-up task, instead of editing first and explaining afterwards. Put that rule in your task template so it is present every time.

Keep formatting out of the agent's discretion. A shared formatter configuration, pinned to a version and run by a hook, means nobody, human or agent, reformats unrelated files by accident.

The result is a change list you can read in seconds: the files the task named, plus a short list of explained extras. Anything else becomes an exception worth a look rather than noise you have learned to ignore.

QUESTIONS

Why does my agent reformat files it did not edit?

Usually a formatter runs with different settings or a different version from the one the code was last formatted with, or it runs over the whole project instead of the changed files. Pin the formatter version, share its configuration, limit it to changed files, and reformat the repository once in a separate commit if it has drifted.

How do I undo only part of an agent's changes?

Use an interactive restore. git restore -p, or git checkout -p, walks through each changed hunk and lets you discard the ones you do not want while keeping the rest. Commit the part you keep first if you want a clean record, then write any worthwhile discarded refactor up as a separate task.

Is it wrong for an agent to edit files outside the task?

Not always. A signature change can require edits to callers and tests. The problem is unexplained edits. Ask the agent to name any file outside the declared scope before touching it and to say why. Necessary edits then arrive with a reason, and unnecessary ones get questioned before they are written.

RELATED GUIDES

• How to create a project card in BRAIN FLUID Desk
• How to preview work with the BRAIN FLUID harness CLI

RELATED HARNESS PAGES

• Keeping AI coding agents within scope Keeping AI coding agents within scope: declare paths, approve them separately with an expiry, check writes during the run and compare the diff after.
• Read-only first: planning sessions before an agent edits code Read-only first: planning sessions before an agent edits code, using Claude plan mode or a Codex read-only sandbox, then a scoped task.
• Preventing two AI agents from editing the same files Preventing two AI agents from editing the same files: separate scopes, separate worktrees, refusing stale writes, and where each layer stops.
• Reviewing cross-file changes made by AI agents Reviewing cross-file changes made by AI agents: check scope, read shared modules first, test interface changes and handle generated files apart.
• human review of agent output Human review of agent output: what to inspect before accepting AI changes, and how recorded outcomes make the review honest.