How Do You Design an Interface With Claude First?
Start in plan mode, so Claude reads your code and proposes the interface while edits are blocked. Then change the proposal directly with Ctrl+G and approve it only when the shape is right. In the Claude app there's no plan mode, so you ask for the design and tell Claude to stop there.
/plan I'm adding [component] to [project]. Read [paths it connects to] first. It has to [goals]. Constraints: [load, allowed dependencies, deadline]. It will be called by [callers]. Propose only the public interface: signatures, data shapes, error behavior and the boundary with its callers. List the three decisions that would be most expensive to change later, each with your recommended default and what would change your mind. Design for the requirements above, not hypothetical future ones. Ask me about anything the code can't tell you.
- 1/plan with your constraints
- 2Claude reads and proposes
- 3Ctrl+G to edit the plan
Try it now
- 1Paste the prompt into Claude Code. The status bar shows
⏸ plan mode on. - 2When the plan appears, press
Ctrl+Gto open it in your text editor and fix anything wrong. - 3To iterate, choose No, keep planning and say what to change. When it's right, choose Yes, manually approve edits to review each edit as it happens.
- 4It worked if the first files Claude edits use the signatures you approved.
Use it when
New components or services, and anywhere several parts must agree on a contract. Anthropic's help center suggests planning first for anything touching more than two or three files. In the Claude app, add the relevant files with + and Add from GitHub first, because Claude only sees what you add.
Skip it when
Throwaway scripts and glue code nothing else will call. A task you could describe in one sentence, too, since you'd only be reading a plan that restates it. If you can't state the requirements yet, have Claude interview you into a spec first.
Why it works
Anthropic's docs say plan mode lets Claude read files and run shell commands to explore, while edits stay blocked until you approve the plan. So the proposal is based on your real code, and changing it costs a few words instead of a rewrite. The plan is also saved as a file. Anthropic's large-codebase guide says Claude Code re-injects that file after each compaction, so a long session keeps the plan even when history is summarized. What Claude can't get from the code are your constraints: expected load, allowed dependencies, who calls this. Those have to come from you.
Example
You're adding a notifications service. You state that it sends about 2,000 emails a day, that web requests can't wait on the mail provider, and that the team has no queue running today. A useful plan might propose Notifier.send(channel, payload), flag sync or queued sending as the costly decision, and ask whether a Postgres table is acceptable as the queue. You settle that before any code exists.
Going further
Run /model opusplan to use Opus while planning and Sonnet while executing. To make planning the default for a repo, set defaultMode to plan in .claude/settings.json. The VS Code extension ignores that project setting, so set claudeCode.initialPermissionMode in your user settings there. Plans are stored in ~/.claude/plans/, and the plansDirectory setting moves them. One limit to remember: the built-in Explore and Plan subagents skip your CLAUDE.md files to stay fast, so restate any constraint that really matters in the prompt.
Common mistakes
- Thinking plan mode means nothing runs. Claude can still run shell commands to explore. Depending on your session, a classifier reviews them or you're prompted.
- Choosing Yes, and use auto mode by reflex when you wanted to watch the first edits. That option starts auto mode, so routine edits go ahead without asking you.
- Leaving out constraints, then finding the design can't meet your latency or team limits.
- Reading the plan only in the terminal when it's long.
Ctrl+Gis faster than describing each change back to Claude.
Sources
- Choose a permission mode, Claude Code Docs
- Set up Claude Code in a monorepo or large codebase
- Subagents, Claude Code Docs
- Model configuration, Claude Code Docs
- Models, usage, and limits in Claude Code, Claude Help Center
- Using the GitHub integration, Claude Help Center
Checked 6 November 2026. Products change often, so confirm details with the vendor.