Why agents make stale comments expensive
An agent refactor changed 83 files and 10 carried the logic. Most of the rest were file paths in comments, which no tool checks and the next agent reads as fact.
An agent refactored the identity module in our API worker this week. The goal was narrow: move flows that coordinate several modules out of the route files.
The pull request merged with 83 changed files. Ten carry the logic. Most of the rest changed because a comment or a doc named a file path.
- Move the implementationImports break and the compiler finds them.
- Leave an old path commentText references can remain stale without a failing check.
- Next agent reads itAn outdated comment becomes misleading context.
Where the other 73 came from
The agent wrote five commits. Three move the agent, org and /me flows. The fourth splits the feature into domain folders, so agents-pg.ts becomes agents/data.ts.
That move was checked for free. Every import still pointing at an old path failed to compile, and TypeScript listed each one.
The fifth commit fixes paths in comments and docs: 181 lines across 51 files. Nothing listed those. One of them, from a dashboard component:
charge (recordUsage in api-key-pg.ts) — a key used solely forcharge (recordUsage in identity/keys/data.ts) — a key used solely forBy file, 75 of the 83 got a path edit in a comment or doc. For 39 that was the whole change, and 37 of those sit outside the identity module: dashboard, billing, admin tests, wrangler.toml.
The next agent reads the comment as fact
A person who follows a stale path finds the file missing and goes looking. For an agent, the comment is context. It sits beside the code, and nothing marks it as older than the code.
Often it is the only place the reason is written down, so it gets used. Had the dashboard edit been missed, the next agent would go looking for api-key-pg.ts, which no longer exists.
Cheap to write, hard to check
A missed path in a comment breaks nothing, so the only check is a search for the old names. The search only finds the names someone thinks to try.
Short names make that worse. routes.ts and middleware.ts exist in many folders, so an old path like identity/middleware.ts is easy to miss in grep output.
Writing those edits cost the agent little. Checking them fell to review: one-line edits across dozens of files, with no build behind them. I could list the paths the fifth commit fixed. I could not show that none were left.
Taking paths out of comments
The fix is to stop writing file locations in code comments. In the worker, 231 files open with a comment that repeats their own path. A follow-up, not merged yet, deletes those lines.
About 600 more lines point at another file by location. They will name the symbol instead: recordUsage, not api-key-pg.ts, or {@link recordUsage}, which the TypeScript language service resolves and renames.
A comment saying a test fake “mirrors ApiKeyPgRow” becomes a satisfies constraint, so the compiler checks the mirror.
Docs keep their paths, because a docs map exists to say where files are. They get a link check that fails on a missing path. A CI check that rejects paths in code comments keeps the rule in place.
Before a folder move, grep the comments for the paths you are about to change. If there are many, take the paths out first, in their own PR. The move that follows then changes only files and imports.