How to split a big request into clear steps

You ask Claude: "Add a list of locales, a search, a filter by country, and refresh the styling." The agent changes several files, reports that it's done, and at first glance the page looks fine. But once you type a query, the entry you need disappears. You clear the field. It doesn't come back.

So what broke? The search, the filter, or the list itself? Everything showed up at once, and you haven't yet seen any single part working on its own. You ask for a fix to the search, get another round of edits, and check the whole page again. Work is happening, but your confidence in the result keeps dropping.

To avoid untangling several changes at once, split the request into small steps you can check. First get the list and compare the entries. Then add the search and check it against that list. After that move on to the filter, and leave the restyling as a separate step. Mistakes are still possible, sure, but you'll have a starting state you already checked and a clear set of recent changes to look at. Let's go through how to pick those steps and how to hand them to the agent.

On the left are the changes made in a single pass. On the right is the shared symptom, which doesn't point to any particular cause yet. Check the parts one at a time and it gets easier to line a bug up with the most recent edit.

Pick the next outcome

Decomposition means breaking a task into parts. When you work with an agent, it helps to pick parts whose results you can check separately. For example: first display the list, then add a search over it, then the filter.

If the list already works, there's no need to build it again. Start from the next behavior that's missing. And if you're not sure whether it works, open the page and look first. The starting point depends on the state of the project. not on a tidy plan.

"First write the HTML, then the JavaScript" also splits the work, but it doesn't always help you check the result. A working search may need both an input field in HTML and a handler in JavaScript at the same time. That's one clear step, even though it touches two files.

Split the request by behavior

Our sample locale reference has four entries. The code, language, and country are listed below, and we'll check against this data later on.

Now each step can have a named outcome and a way to check it:

The arrow means you move on after a check. The search and the filter can swap places, but both of them need the list. We'll leave a full restyling as a separate step. Its result is easier to judge once the main actions already work.

Name the boundaries of the step

Say the list is ready. Ask Claude to add the search, and spell out what has to stay as it is. In our example the data and the page behavior live in app.js, the markup in index.html. In your own project, use your real paths.

Read @index.html and @app.js.
The list of four locales already works.
Add a search field for the locale code or the language name.

Keep the original entries, their fields, and the styling.
You may add the elements the search needs.
Don't build the country filter yet.

Check: German and de-DE find de-DE;
zzz finds no entries; an empty query returns all four.

First explain what you're going to change. Don't change the files yet.

Read the answer. If new data, a theme change, or the filter turned up in it, clarify the boundaries before anything runs. If it all matches your request, tell the agent to go ahead with this step. Spelling out the boundaries helps steer the work, but you still have to check the result to see whether they held.

Not every extra action is out of scope. The search needs an input field, of course. A full color change is already a separate request. Handy question to ask yourself: without this edit, do you still get the outcome you picked?

When it's not clear where to start

In someone else's project you may need to read first. There's no point asking for a search to be added if you don't yet know where the entries come from and which file renders the list. You'd just be guessing along with the agent.

Find where the page gets its entries and where it renders the list.
Read two or three key files, if that's enough.
Name the paths you found and suggest a first small step.
If that's not enough to go on, say what else you need to read.
Don't change the files yet.

The outcome of a step like this is the files it found and an explanation of what each one does. Compare the answer against the fragments it points to. "Two or three" here is a rough starting point, not a ban on reading whatever code is needed.

Check before the next step

"The search is ready" doesn't tell you what exactly was checked. Open the page and run the examples from your request: a match, no match, clearing the field. While you're there, make sure the original entries and their fields survived.

If clearing the field leaves only three rows, stick with the search. Tell the agent the action, the expected result, and the actual one: "Cleared the field. Expected four entries, I see three." Adding the filter now would only make the cause harder to find.

Sometimes a step has to get smaller. If no entries show up at all, for instance, restore the list first and check that. And that new idea about sorting? Write it down as a separate item, so it doesn't get lost and doesn't stretch the current edit.

The left branch sends you back to the search for as long as its behavior doesn't match the request. The right one opens after a successful check. Once you add the filter, check both it and how it works together with the search: a new step can affect behavior that already worked.

Working with Claude Code

Before each edit, state three things: what should come out of it now, what stays as it is, and how you'll see the result. Give the agent the files it needs, agree on the next step, and have it do that step. After the check, move on or refine the current edit.

One step can take several messages, and that's normal. What matters more is that at any moment you can say: "Right now we're adding the search. The list is already checked. The filter can wait."