How to write a change request for an AI coding agent

A change request an AI coding agent gets right points at one exact place (a file, a route, a screen state, a frame URL), says the change in terms you can observe, sets the scope (this instance, the component, or every screen), names what must not change, and says how you will check it is done. Send one change per message, with the reason when it is not obvious.

Agents rarely fail at writing the code. They fail at guessing what you meant. The rest of this article is about removing the guesses.

Where change requests go wrong

Most bad results come from a handful of gaps:

• An ambiguous reference. “Fix the button on the settings page” when the page has four buttons.
• An unstated scope. “Make the button blue”: this one, every primary button, or the brand color itself?
• An activity instead of an outcome. “Clean up the header” is an activity. “The header is 56 px tall, logo on the left, avatar on the right” is a result.
• Stacked requests. Five changes in one message, where the agent does four and quietly skips the fifth.
• No reason. Without “because users miss the Save button”, the agent cannot choose between two valid fixes.

Each gap has the same cost: you only discover it after the change is made, when reviewing and redoing it takes longer than a precise request would have.

The anatomy of a good request

Part	Weak	Strong
Where	“the form”	“CheckoutForm on /checkout, error state”
What	“better errors”	“Show each field error under its field and keep the summary at the top”
Scope	(unsaid)	“Only this form; the other forms keep their current behavior”
Keep	(unsaid)	“Do not change the validation rules or the API calls”
Done when	“looks good”	“An empty email shows ‘Enter your email’ under the field; tests pass”
Why	(unsaid)	“On mobile, users do not see the summary”

Assembled into one message:

In CheckoutForm (src/checkout/CheckoutForm.tsx), error state: show
each field error directly under its field, in the error color, and
keep the summary at the top. Only this form. Do not change the
validation rules or the API calls. Done when submitting with an
empty email shows "Enter your email" under the email field on a
390 px wide screen, and npm test passes. Why: on mobile, users do
not scroll up to the summary.

The reason is the part people skip most, and the one that helps most when the agent meets a choice you did not foresee. “Users do not see the summary on mobile” tells it to check a narrow screen and to keep the fix visible there.

Point at the place instead of describing it

The most reliable way to say where is to hand over an identifier the agent can resolve: a file path (in Claude Code, an @ reference puts the file in the conversation), a route, a component name, a test name, or a screenshot with the element circled. Descriptions such as “the second card on the left” break as soon as the layout changes.

For UI, name the state too. “The invoice list” has an empty state, a loading state, a filtered state and an error state. “The invoice list, empty state” can only mean one thing.

Say the scope out loud

Scope is where agents most often do too much or too little. The same words, “make this button darker”, can mean three different changes:

1. This instance: one style or class on one element.
2. The component: every place that uses the primary button.
3. The token: the primary color everywhere, links and focus rings included.

Pick one and write it down. When you are not sure, ask the agent what each option would affect before it edits anything. A careful agent asks when the scope is ambiguous, but a request that states it saves the round trip.

Name what must stay the same

An agent asked to change one thing may improve others it sees as related: renaming a prop, reformatting a file, updating a dependency. Each is reasonable alone, and each adds to your review. One sentence prevents most of it: “Do not change the API calls, the validation rules or any other screen.” List the things closest to your change, because those are the ones the agent is most tempted to touch.

Define done in checkable terms

“Done” should be something both you and the agent can verify without debate:

• a behavior: “pressing Enter in the search field submits the search”;
• a visible result at a given size: “at 390 px wide, the Save button is visible without scrolling”;
• a command that passes: “npm run lint and npm test pass”;
• states to show you: “tell me how to reach the empty, filled and error states”.

A clear definition of done also tells the agent when to stop. Without one, it may keep polishing, or declare the work finished after the first check passes.

If your project has standard checks, write them in the project CLAUDE.md so you do not repeat them in every request: Claude Code loads that file at the start of each session.

Templates you can copy

A visual tweak:

In <component or file>, <state>: change <property> from <current>
to <target>. Scope: <this instance | the component | the token>.
Keep everything else as is. Done when <visible result at a size>.

A behavior change:

When the user <action> on <screen>, <what happens now>. It should
<new behavior> instead, because <reason>. Do not change <boundary>.
Done when <test or manual check>, and <command> passes.

A missing state:

<Screen> has no <empty | error | loading> state. Add one with
<texts> and <actions>. Reuse <component>. Show me the state before
you wire it to real data.

When the agent gets it wrong

Do not pile corrections on a wrong result: each fix builds on the misunderstanding. Undo, then ask again. In Claude Code, /rewind (or Esc twice with an empty prompt) restores the code, the conversation or both to an earlier prompt, for edits made with its file editing tools. The checkpointing documentation lists what it does not cover, such as files changed by shell commands. Then rewrite the request with the misread part made explicit.

If you are not sure what you want yet, do not write a change request. Ask for two or three variants, choose one, then request it. How to review AI generated UI changes covers checking the result once it arrives.

Change requests on a prototype canvas

agentappbuilder turns “where” into a link. Each state of each screen is a frame with its own URL, so a change request is the URL plus the change:

https://app.agentappbuilder.com/f/<token> Make the Save button full width and show the error message above the form.

Your agent adds a new version of that frame with a note of what changed, and records which version it started from. For small visual changes (a color, a padding, a corner radius), you can edit the frame yourself on the canvas instead of describing it, then say “Implement my edits.” Your agent receives the exact list of properties you changed, applies each one where it belongs (a design token, a component or that one instance), and asks you when the scope is not clear. Working with your agent lists the prompts, and the canvas explains how to edit a frame. For first requests, before there is anything to change, see Claude Code prompts for UI.

Where, what, scope, what to keep, done when, and why: six short answers that save a second attempt.