AI 智能體新增檔案而非修改現有檔案，導致程式碼庫出現重複驗證器

The PR diff looks fine. You asked the agent to add a phone-number validator. It added a file called validation-helpers.ts with a clean, well-tested validatePhone() function. CI is green. The code is correct.

It is also wrong.

Because utils/validators.ts already exists. It has been there for two years. It already exports validateEmail(), validatePostalCode(), and a dozen other validators. The agent didn't find it, so it made a new one. Now the repo has two validator files, two naming conventions, and two places to update when the country-code rules change.

Why it happens

Three reasons stack up. First, the agent's file search is shallow. It looks at the root directory, maybe src/, and gives up. It doesn't grep for existing function names, doesn't check utils/, lib/, helpers/, or the half-dozen places a real project stashes shared code.

Second, creating a new file is the path of least resistance. Editing an existing file requires finding it, reading it, matching its style, and not breaking the other exports. Creating a new file means writing fresh code in a style the model is comfortable with. No search cost, no compatibility risk.

Third, and this is the subtle one: nothing in the task asks the agent to check whether the functionality already exists. "Add a phone validator" sounds like a greenfield task. The agent treats it as one. It doesn't think to ask "is there already a validator?" because the prompt didn't tell it to look.

Why it's worse than a wrong file

When an agent edits the wrong file, you catch it in review. The diff is in wrong-place.ts and you say "this should be in right-place.ts." Easy.

When an agent creates a new file, the diff looks clean. It's adding new code, not touching existing code. No one has to move anything. The code is correct, tested, and green. It just duplicates something that already existed, and you won't notice until three months later when you fix a bug in one validator and the other one still has the bug.

This is the kind of failure that accumulates. Each PR adds one small new file. None of them are wrong. A year later, the repo has utils/validators.ts, validation-helpers.ts, lib/phone-utils.ts, and a src/utils/validation/ directory you forgot about.

The one rule

You don't need a complex file-discovery system. You need one instruction:

Before writing any new shared utility, grep the codebase for the closest existing function. If it exists, edit that file. If it doesn't, create a new one but explain why the existing structure didn't fit.

This forces the agent to search first. It doesn't have to be a perfect search — a single grep for validat or phone across src/ is usually enough to surface the existing file. The point is to make the agent pause and consider "does this already exist?" before it writes.

A second cheap guard: when you ask for a new utility, name the file you expect it to live in. "Add this to utils/validators.ts" removes the ambiguity entirely. The agent can't create a parallel file if you told it which file to edit.

The deeper habit

The bigger issue is that agents are optimized for producing code, not for fitting into an existing system. "Add a validator" produces a validator. It doesn't ask "where does this belong?" or "does this already exist?" Those are questions a human would ask out of habit. An agent has to be told to ask them.

Next time you review a PR that adds a new utils/ or helpers/ file, spend ten seconds grepping for the closest existing thing. You'll be surprised how often the new file is a duplicate of something that was already there.