Armin Ronacher dug into Claude Code’s plan mode as an interested bystander.
However today I had two interesting conversations with people who really like plan mode. As a non-user of plan mode, I wanted to understand how it works. So I specifically looked at the Claude Code implementation to understand what it does, how it prompts the agent, and how it steers the client. I wanted to use the tool loop just to get a better understanding of what I’m missing out on.
This post is basically just what I found out about how it works, and maybe it’s useful to someone who also does not use plan mode and wants to know what it actually does.
This one took me a few days to get around to, but it turned out to be an interesting reflection on how I work with Claude. In essence, like Ronacher, I’ve unknowingly recreated many key aspects of plan mode!
Over the last month, I’ve started most agentic coding sessions with a prompt along the lines of: “generate a plan, in markdown format, include a timestamp, with a task checklist, and write it into a plans folder.” Then I review the plan, typically only making minor changes. I commit these plans to the working repository.
With a plan in place, I’ll kick the agent into implementation action. If the plan is fairly complex, with multiple phases, and might hit usage limits, I often ask the agent to complete only the first couple of phases, then pause so I can review.
Here’s more from Armin:
Plan mode as it exists in Claude has this sort of weirdness in my mind where it doesn’t come quite natural to me. It might come natural to others! But why can I not just ask the model to plan with me? Why do I have to switch the user interface into a different mode? Plan mode is just one of many examples where I think that because we are already so used to writing or talking to machines, bringing in more complexity in the user interface takes away some of the magic. I always want to look into whether just working with the model can accomplish something similar enough that I don’t actually need to have another user interaction or a user interface that replicates something that natural language could potentially do.
This is particularly true because my workflow involves wanting to double check what these plans are, to edit them, and to manipulate them. I feel like I’m more in control of that experience if I have a file on disk somewhere that I can see, that I can read, that I can review, that I can edit before actually acting on it. The Claude integrated user experience is just a little bit too far away from me to feel natural. I understand that other people might have different opinions on this, but for me that experience really was triggered by the thought that if people have such a great experience with plan mode, I want to understand what I’m missing out on.
And now I know: I’m mostly a custom prompt to give it structure, and some system reminders and a handful of examples.
Emphasis mine on that last line.
The other nice thing about making plans into explicit documentation is that:
- Work can be handed off to another agentic system.
- You can try the same plan with multiple different agents.
- Resets and restarts are easy.
YMMV.
Built using