Español

Tell Your Agent to Note, Not Fix, Out-of-Scope Issues

Your AI's helpful cleanup is sabotaging your pull request. You ask it to fix one bug, and it comes back having also renamed three variables, modernized an import it only read, and reformatted a file it happened to open. The bug is fixed — but now the diff is 400 lines across nine files, and the reviewer can't tell the one-line fix from the noise around it.

The instinct behind this is good. The agent sees dead code, an old pattern, a typo in a comment, and it wants to leave the campsite cleaner than it found it. The problem is when. Every unrelated improvement folded into a task mixes concerns and inflates the change under review.

Why scope discipline wins

Google's engineering-practices guide is blunt about it: a good changelist "makes a minimal change that addresses just one thing." Small, single-purpose diffs get reviewed faster, get reviewed more thoroughly, are less likely to hide a bug, and are far easier to merge and to revert. The same guide says outright that "it's usually best to do refactorings in a separate CL from feature changes or bug fixes" — moving a class and fixing a bug in that class are two reviews, not one.

A bloated diff quietly steals all of those benefits. The reviewer now has to reverse-engineer intent: which lines are the fix, and which are the agent freelancing? That's the exact cognitive load small diffs exist to remove.

The one rule

Give your agent a single instruction and put it where it reads it every session — for Claude Code, that's CLAUDE.md:

## Scope discipline
- Touch only what the task requires. Do not clean up, reformat, or
  modernize code that is adjacent to — or merely read by — the task.
- If you notice something worth improving that is out of scope, NOTE it,
  do not fix it. Add it to a "Things I didn't touch" list at the end of
  your summary and offer it as a follow-up.

Now the agent's cleanup instinct has somewhere to go that isn't your diff. It still surfaces the dead code and the stale pattern — as a list of follow-ups you can triage — while the pull request stays one logical change.

Note vs. fix: a quick rule of thumb

The line is simple: fix only what the task cannot be completed without. Everything else is a note.

Power-user moves

• Make the follow-up list a deliverable. Ask for a FOLLOWUPS.md or a bulleted "Things I didn't touch" block in every summary. Those notes become a ready-made backlog of small, scoped clean-up PRs — the good kind.
• Keep the rule short and high in CLAUDE.md. Anthropic's own guidance is to keep these files concise; frontier models reliably follow only a couple hundred instructions, so a scope rule buried under 300 lines gets ignored. One tight paragraph near the top beats a paragraph on page three.
• Split when the agent already over-reached. If a diff came back too big, ask the agent to move the incidental changes into a second commit or a separate branch — one PR per logical change, exactly as the code-review guides prescribe.
• Name the scope in the task, too. "Fix the null check in auth.ts; change nothing else" reinforces the standing rule at request time and gives the model a concrete boundary to respect.

Resources

• Small CLs — Google Engineering Practices
• Writing good CL descriptions — Google Engineering Practices
• Best practices for Claude Code — Anthropic