Why Does My Agent Keep Editing the Wrong File?

Quick answer
The usual cause is ambiguity: two files with similar names, a generated copy, or a barrel file that re-exports the real implementation.
Agents search by name and content, so a stale build artefact or a vendored copy competes with the source of truth.
Name the exact path in the task, and state which directories are generated and off limits.
Check that the runtime uses the file it edited; editing a component that no route imports changes nothing.
Delete or exclude duplicates rather than explaining them, because every duplicate is a future wrong edit.

Why does the agent pick the wrong file?

Because the repository contains more than one plausible answer. A component may exist in the source tree and in a built output directory; a helper may exist in two packages; a file may be re-exported from an index that hides where the implementation lives. Search finds all of them.

Naming contributes. utils.ts, helpers.ts, api.ts, and server.ts appear in every project, so a search for a function name can return the wrong module with high confidence.

How do you tell the agent which file to use?

In the task, give the path, not the concept: “edit src/server/routes/webhooks.ts”, not “the webhook handler”. If the path is long, put the mapping in AGENTS.md: webhooks live here, the worker lives there, generated files live in dist.

Then say what is generated. A directory listing with an exclusion rule is more useful than a warning about being careful, because the agent can check it.

How do you confirm the right file was edited?

Trace the runtime path from the entry point. If the route imports a controller that calls a service, the edit must be in the file that path reaches. A change in an unimported sibling file will not appear when you test.

After the change, verify the behaviour, not the diff. If the behaviour is unchanged, the edit was in the wrong place regardless of how correct the code looks.

How do you prevent it structurally?

Remove duplicate sources of truth. A generated directory should be gitignored and excluded from search where the tooling allows it. A vendored copy should be clearly marked. A file that exists in two places will eventually be edited in the wrong one.

Improve names where the ambiguity is systemic. A component named after its feature is easier to pick than one named after its shape. This is a codebase-quality investment that pays off for humans and agents alike.

Where this bites vibecoders
The classic case is a built copy under dist/ or .next/ that the agent edits because the class name matched. The change is real, the tests pass, and the site does nothing different. Exclude build output from search before blaming the model.

Where AI coding assistants get this wrong

Describing the file by role instead of path.
Leaving generated directories searchable.
Assuming a change in a sibling module is imported anywhere.
Having two files that export the same symbol.
Verifying with a test that mocks the module under change.
Accepting a passing test as proof the right file was edited.

Checklist

Name the exact path in the task.
List generated directories as off limits.
Exclude build output from search.
Trace the import path from the entry point.
Verify the behaviour, not just the diff.
Remove duplicate implementations.

FAQ

Why did the tests pass if it edited the wrong file?

Because the test probably imports the file directly, or mocks the layer that should have changed. A unit test can pass against an implementation no route uses. The behaviour check has to go through the real entry point.

Can I make the agent ask before editing?

Yes. Plan mode or an explicit instruction to list the files it intends to change before writing gives you a checkpoint. Review that list against the runtime path; it is cheaper than reviewing a diff in the wrong place.

What if the repository genuinely has two implementations?

Then it needs a decision, not a better prompt. Either consolidate, or document which one is live and in what context. An agent cannot resolve an architectural ambiguity that the team has not resolved.

Does a larger context window help?

It gives the agent more candidates, which can make the choice harder. Precision comes from naming the path and removing duplicates, not from loading more of the repository into the prompt.