Implementation worksheet · 6 min read
How to Scope an AI App Change Without Rewriting Working Features
Bound every change three ways before asking for it: name the specific behaviour to change, name the flows that must keep working unchanged, and name the files or areas that are in scope if you know them. Then review the diff by size before reading it — a request to change a button's validation that returns a forty-file diff is telling you something regardless of how good the code is. The instruction that causes the most damage is a broad improvement request ('clean this up', 'tighten up the auth') because it has no boundary, so any change is technically compliant and you have no basis to reject one.
Asking an agent to change a working application is different from asking it to build one. In a new build, broad latitude is useful. In an existing app, latitude means the parts that already work are in scope for modification, and a rewrite of something functional is expensive precisely because it looks like progress.
Put it into practice
1. Describe the change as a behaviour delta
'Today the form accepts an empty email; it should show an inline error and not submit.' Before and after, one behaviour. Compare with 'fix the form validation', which does not say what is wrong or what correct looks like and invites a general improvement pass.
2. Name the invariants explicitly
The flows that must behave identically afterwards: login, checkout, the export, the admin view. This is the single most effective sentence you can add, and it is almost never included. Without it, 'do not break anything' is the instruction, which is not a constraint anyone can act on.
3. Scope by area when you can
If you know the change belongs in one component or route, say so. This is a hint rather than a rule — sometimes the right fix is elsewhere — but it converts an unbounded search into a bounded one and makes an out-of-scope change visible as a deviation you can ask about.
4. Refuse the broad improvement request
'Tidy this up', 'clean this up', 'improve error handling' have no completion criterion, so any change satisfies them. If the codebase genuinely needs that work, break it into named changes with named invariants and do them one at a time.
5. Review diff size before diff content
Files touched and lines changed, against what you asked for. A small behavioural change producing a large diff means something unrequested happened — a reformat, a refactor, a dependency change. Reading the code first means evaluating each change on its merits and losing the signal that the set as a whole is too big.
6. Test the invariants, not just the change
The change was requested, so it will get tested. The invariants are what nobody re-checks. Walk the flows you named, in the deployed build, before accepting. This is where the collateral damage surfaces, and it is a five-minute job that saves a much longer one.
Scoping a change
Copy this structure into your review document and record your observed result for each row.
| Element | Your entry | Set |
|---|---|---|
| Behaviour today | ||
| Behaviour wanted | ||
| Invariant flow 1 | ||
| Invariant flow 2 | ||
| Invariant flow 3 | ||
| Areas in scope (if known) | ||
| Explicitly out of scope | ||
| Expected diff size | small / medium / large | |
| Actual files touched | ||
| Invariants re-tested in the deployed build |
A failure worth checking
The improvement nobody asked for. The request was to fix one validation message. The diff also renames variables for consistency, extracts a helper, updates a dependency and reformats two files — all defensible individually, none requested. Review becomes archaeology, the real change is buried, and if something breaks next week the bisect surface is four times larger than it needed to be. Reviewing size before content catches this in ten seconds.
Common questions
Is it wrong to let an agent refactor?
No, but it should be its own request with its own review, not a passenger on a bug fix. Mixing a behavioural change with a structural one means neither can be reverted independently, which is the property you want most when something turns out to be wrong.
What if the fix genuinely requires broad changes?
Then that is the finding, and it should be surfaced before the work rather than discovered in the diff. Ask for the explanation first, decide whether to accept the scope, and then request it deliberately.
Basis and scope
This is a proposed implementation method using illustrative examples, not a measured benchmark or a customer case study. Prepared with AI assistance. Validate product-specific behavior against current documentation and your own test environment.