Claude Code keeps stopping to ask: give it an example of finished work

TL;DR Before a long task, hand Claude the way a similar job was finished (a six-line write-up, a PR or its commits) and tell it "run it like this". On the same migration, "bite off bigger chunks" ended 3 out of 3 times with no tests, no commits and a question; with the example, 3 out of 3 times with everything done and no question.

This isn't about the permission prompt before each command: permission modes fix that, and it's covered in Stop Claude Code asking for permission. This is the other thing: Claude makes a couple of changes, ends its turn with a summary and a question, and the task sits there until you answer.

Why it stops, and why "go bigger" doesn't help

Two documented behaviors add up:

• It reads your request at the low end. The Claude Code best practices put it plainly: Claude tends to build the smallest thing that satisfies the request, because it can't see how much you were hoping for.
• It reports mid-task. The Opus 5.5 prompting guide says that on long tasks with several parts, some of its progress updates end the turn with text instead of another tool call. Among the stops it lists: offering to carry on unless you'd prefer otherwise, and a list of decisions that block nothing.

"Bite off bigger chunks" is an adjective. It doesn't say what done means: whether the tests must pass, whether it's one commit per module, whether the old code goes, when a stop is actually worth it.

A job someone already finished says all of that at once.

That's what Andrew Edstrom, an engineer at Anthropic, shared in the October 3 Claude Code newsletter: his long-running session kept making small changes and stopping for input, asking for bigger pieces didn't help, so he had it read a colleague's write-up of a big migration they had shipped. The next morning he woke up to 133 PRs.

The test: the same migration, with and without an example

A repo with five modules on oldlog, a new logger.js and a test.js. The same request, "migrate the modules in src/ from oldlog to logger", with three different endings. Claude Code v2.1.316 in -p, one run per row, prompts in Spanish (translated here):

Without the example, all four runs claimed the repo had no tests, with test.js sitting at the root, and all of them ended the same way. A Sonnet run closed with (translated):

I left `src/oldlog.js` untouched, and no module imports it anymore. Should I delete it?

And the Opus 5.5 run:

I haven't deleted `src/oldlog.js` (nothing uses it) or made a commit. Tell me if you want either.

With the example, the same request ended on the list of commits, and Sonnet explained why it hadn't asked:

- **Deleting `src/oldlog.js`:** before deleting it I searched the whole repo for `oldlog` and no reference was left. So there was no need to stop and ask, as the date migration did for the file another team imported.

How to give it the example

1. Find a finished job that looks like this one

Anything that shows the whole project start to finish works: a migration write-up, a merged PR or a run of commits. Commits are enough: the last row of the table had no document at all, just a git log.

2. If none exists, write it in six lines

This is the one from the test, in full (in English here):

# How we migrated from moment to date-fns (closed)

- Scope: the 7 modules that imported moment. None was left half done.
- One commit per module, with the message `migrate <module>: moment -> date-fns`.
- After each module, `node test.js`. If it failed, it was fixed before moving on.
- Nobody asked anything between modules: style questions were settled by copying what the first migrated module did.
- At the end: `src/moment-shim.js` was deleted, `node test.js` ran one last time and a summary listed the commits.
- It stopped only once, to ask whether to delete a file another team imported.

Each line answers a question Claude would otherwise have asked you: how far it goes, what the unit of work is, what the check is, how to settle doubts, how it wraps up and when it does stop.

3. Ask it to run it the same way

Migrate the modules in src/ from oldlog to logger (src/logger.js). Run it the way the migration described in @docs/date-migration.md ran.

It works just as well in a session that's been going for hours: the example is one more message, and that's exactly how Edstrom used it.

4. If the task runs for hours, add a stop condition too

The example shows how to work. To keep the session from handing control back before it's finished, add /goal with a condition that can be checked, such as "every module migrated and node test.js passes".

The cases you'll run into

• It copies the stops too. The example's only stop became the only question Claude weighed. If you want it to stop before something, write it into the example as a stop that already happened.
• It copies the details, not just the scale. The commit messages came out in the example's format, migrate auth: oldlog -> logger. If the reference job has a habit you don't want, remove it or say so.
• It fills in what the example leaves out. Opus 5.5 created a branch on its own, migrate-oldlog-to-logger, because it was on master. The example said nothing about branches.
• It takes more turns. On Opus 5.5, the run with the example took 27 turns and the "bigger chunks" one 16. That's the work you used to ask for in three messages.
• An example at another scale brings its scale. Edstrom's example was a big migration and he woke up to 133 PRs. For a three-file fix, hand it a three-file job.

Official docs: Best practices for Claude Code · Prompting Claude Opus 5.5: unattended agentic runs