The function looked wrong.
It returned an object with a key that started with a dollar sign, it did a network call inside a loop, and it mapped one enum value to a string that didn't match the enum's other values. None of it was elegant.
There was a three-line comment above it that explained all of this. A legacy integration expected the dollar prefix. The network call was a cache fill that had to be synchronous because of a downstream order-of-operations constraint. The enum string mismatch was a fix from 2021 that some external client still parsed by exact match.
You asked the agent to "clean up this module" and it did.
It renamed the function. It pulled the network call into a helper. It added a type for the return value. It deleted the comment.
The code was now shorter, more consistent, and slightly wrong in a way that surfaced three weeks later when a customer integration started failing at 2 a.m.
What the agent optimized for
Agents optimize for what they can see. They see code they can reformat, rename, extract, and type. They see comments as prose attached to code, and they treat them the way a junior engineer treats old comments: if the comment doesn't explain the current code, it looks stale and gets deleted.
That heuristic is wrong in one specific, expensive way. The most valuable comments in a codebase are not the ones that describe what the code does. The code does that. The valuable comments are the ones that explain what the code cannot tell you:
- Why the weird shape exists and who depends on it.
- What you will break if you "fix" it.
- Which incident taught us this the hard way.
- Why we are not doing the obvious refactor.
These comments are load-bearing. They are the reason the code looks wrong on purpose. When an agent deletes them, it is not tidying up. It is erasing the memory that prevents the next refactor from shipping an outage.
Why tests don't catch this
You might assume tests would catch the regression. They don't, usually, because the tests were written at the same time as the workaround and they encode the weird shape as expected behavior. The agent's refactor passes the tests because the tests still assert the old shape. The bug is not in the code behavior; it is in the loss of the explanation that told the next engineer not to generalize the shape away.
The failure mode is slower and quieter than a red test. Someone reads the refactored function, thinks "this is cleaner now," and starts changing the return type to match the rest of the codebase. The customer who depended on the dollar prefix finds out.
The cheap guard
We started doing one thing that costs almost nothing: before accepting a refactor, ask the agent to list the comments it deleted and the reason for each. If a deleted comment contained a "because," a "don't," a "legacy," or a date, it goes back in. Not verbatim — rewritten against the new code — but the reason survives.
This is the same reason we keep descriptions and deprecation notes inside the OpenAPI file itself rather than in a separate doc. When the note lives next to the thing it explains, a refactor that touches the thing is forced to touch the note too. When the note lives somewhere else, it drifts the moment someone cleans up the code.
The comment is not decoration. It is the only record of why the code looks wrong on purpose. Treat it like a test: if a change removes it, the change should explain why the reason no longer applies.
If the agent can't explain that, the comment stays.
