We asked an agent to tidy up a pagination helper. It tidied up a different, similarly named helper in a payments module three directories away, and the diff looked confident enough that it nearly went to review as-is.
What actually happened
Two files shared a function name — pagination logic had been copy-pasted rather than shared, which was already a smell we should have caught earlier. The agent picked the first match its search returned, made a reasonable-looking improvement, and left the file we meant untouched. Nothing broke locally, because neither file had a test that exercised the change.
The near miss, not the failure
Nobody was hurt because a second engineer skimmed the file list before the code, a habit we've written about before and keep for exactly this reason. But it changed how we think about ambiguity in a codebase, not just in a ticket.
Duplicate names are a standing risk
- Search by name, not by path. Any tool that resolves "the pagination helper" by string match will occasionally resolve it wrong, agent or human.
- Merge the duplicates. We consolidated the two helpers into one, which removed the ambiguity permanently rather than training everyone to be careful.
- Reference the file path in the ticket, not just the function name, once we noticed how often this bit us.
An agent will resolve an ambiguous reference exactly as fast and exactly as wrong as a tired engineer at 5pm.
The instrumentation we added
We now log which files an agent session actually opened, not just which files it edited. When the list of opened files doesn't match the ticket's stated scope, that's a signal worth a look before the diff exists, not after.
What we'd tell a team starting this
Duplicate logic under similar names is a latent cost that used to surface as a confusing bug report months later. With agents doing more of the searching, it surfaces immediately, which is uncomfortable and better. Treat the first ambiguous resolution you catch as a prompt to clean up the codebase, not just the ticket.