Plan mode versus direct execution

What each mode is for

Plan mode suits large-scale change: multi-file modifications, architectural decisions, and situations where several approaches are genuinely viable. It allows exploration and design before anything is committed to, which is what prevents expensive rework.

Direct execution suits well-scoped, well-understood change — a single validation check, a one-file bug fix with a clear stack trace.

Decide based on the cost of choosing the wrong approach

Ask: Could choosing the wrong approach cause significant rework?

A migration touching forty-five files may need little planning when the approach is already clear. A two-file change may need more planning when the available integration strategies have different infrastructure consequences.

"Two approaches look viable" isn't on its own a reason to plan, either. Sometimes only one is really available and nobody has checked — whether the upstream service supports batching, say. Planning cannot choose between an approach that works and one that cannot exist, so check the fact first.

Use Explore for broad investigation

A discovery phase produces a lot of output that matters only in aggregate. The Explore subagent isolates that verbose work and returns a summary, preserving main-conversation context — which is what prevents context exhaustion partway through a multi-phase task.

Use an Explore subagent when many files must be examined to reach one conclusion. Look up a single fact directly.

Combining them

The modes can be used in the same task. You can plan a library migration and then switch to direct execution to implement the approved approach.

Do not use Plan mode in unattended runs

Plan mode ends by presenting a plan and waiting for a person to approve it. A non-interactive run — a pipeline job, a scheduled task — has nobody attached, so nothing can approve the plan. The run waits until it times out and may delay other changes in the queue.

The investigation is still worth doing; what changes is how the run ends. Let it weigh the alternatives and finish by reporting its recommended approach as output, for a person to read afterward — same deliberation, no wait. Shortening the timeout only shortens the blockage, and still discards the plan unread.