Claude Code Project Planning: Plan Mode & ak plan (2026)

Why plan before you let Claude Code write code?

The most common mistake with Claude Code is typing one prompt and letting it code straight away. It feels fast, but the risk is real: the AI often "solves the wrong problem" - it does exactly what it thinks you want, not what you actually need. By the time you look at the diff, a dozen files have already changed, and now you are stuck choosing between fixing it by hand or throwing it all out and starting over.

Planning first fixes exactly that. When you force Claude to lay out a plan before it touches any code, you get to preview the scope of the change, catch misunderstandings while they are still cheap, and keep the work inside its boundaries. Bonus: it saves tokens, because editing one line in a plan is far cheaper than letting the AI write the wrong thing and rewrite it.

There is a benefit people rarely mention: the plan is where you and the AI agree on the "definition of done." When the plan spells out which files will change and how to verify them, you have a reference to check the final diff against - instead of reading the code and wondering "did it actually do what I meant?" In other words, planning turns review from guesswork into a checklist comparison.

When you SHOULD plan: the change touches many files; you are not sure how to approach it; or you are working in an unfamiliar codebase whose flow you do not know yet. When to skip it for speed: fixing a typo, changing a constant, tweaking a single line - if you can describe the diff in exactly one sentence, planning is just extra overhead. If you are brand new to the tool, read what Claude Code is and how it works first, then come back to the sections below.

What plan mode is in Claude Code & how to turn it on

Plan mode is a permission mode in Claude Code: when it is on, Claude only reads files and proposes a plan, without writing any changes to disk until you approve. Think of it as a safety brake that lets you see what the AI intends to do before you allow it.

There are three ways to turn it on:

1. Press Shift+Tab to cycle through the modes: default → acceptEdits → plan. Keep pressing until you land on plan.
2. Launch straight into plan mode from the terminal:

   claude --permission-mode plan

3. Confirm it in the status bar - when plan mode is active, the status bar shows ⏸ plan mode on.

A lesser-known tip: once Claude has produced a plan, press Ctrl+G to open that plan in a text editor and edit it by hand before it runs - add constraints, drop unnecessary steps, or point to specific files. Editing a plan is always cheaper than editing code that has already been written.

The shortcut behavior above follows Anthropic's official documentation (best practices and common workflows, viewed 2026-08-09). Because plan mode is evolving fast, double-check the shortcuts in the version of Claude Code you are running.

The 4-step planning loop: Explore → Plan → Implement → Commit

This is the loop Anthropic recommends, and it is the easiest one to remember. Each step has its own goal - do not blur them together.

Explore (in plan mode)

Before discussing any solution, let Claude read and understand the existing code. In plan mode it only reads, never edits, so you can let it dig around freely:

Read src/payments/ and src/orders/ to understand how the system handles payments today. No proposals yet - just summarize the flow.

For large projects, hand the research off to a subagent to keep the main session's context clean - the subagent reads and returns a summary, while your main context window is not stuffed with thousands of lines. The goal of this step is not the solution; it is to get Claude to describe, in its own words, how the system currently works. If the summary is wrong, you know immediately that it has not understood the problem.

Plan

Once Claude understands the code, ask it for a concrete plan:

I want to add discount codes to orders. Which files need to change? How does the flow work? Write a detailed plan before coding.

Read the plan carefully. If something is off, press Ctrl+G to edit it by hand, or reply so Claude revises it. Do not rush to approve.

Implement

Approve the plan (or press Shift+Tab to exit plan mode) so Claude starts coding. The key point: anchor the plan with verification criteria - state exactly what the AI must do to prove it is done:

Execute the plan. When finished, run npm test and make sure every test passes. If any test fails, fix it until it is green.

Commit

Finally, wrap it up into a clean commit and open a PR:

Commit the changes with a clear descriptive message, then open a pull request with a summary of what changed.

See also our Git workflow & creating PRs with Claude Code to standardize this step.

Break a large project into phases & a roadmap

The 4-step loop above works well for a self-contained feature. But a project that runs for days or weeks breaks a flat plan: context thins out, Claude forgets earlier decisions, and you lose control.

The more durable approach: ask Claude to build a roadmap of multiple phases, where each phase spells out its goal, the files it will touch, and its "done" criteria. Save the roadmap to a file (for example PLAN.md or a plans/ folder) so it does not vanish when you run /clear. Then execute each phase in its own session, with a clean context - run /clear between phases so each one starts lean, loading only the slice of the roadmap it needs.

The principle for splitting phases: each phase should stand on its own and end in a green state (tests pass, app runs) so you can stop at any point without leaving code half-finished. Phase order should move from the foundation outward - build the backend/logic first, the interface later - so every later phase has solid ground to build on.

Example roadmap for a "Sign in with Google (OAuth)" feature:

For complex features, use the interview → SPEC.md → new session pattern: tell Claude to "interview me one question at a time about the requirements, then write it to SPEC.md," then open a fresh session that reads the SPEC and executes with a clean context. This is the essence of spec-driven development (write SPEC.md first), and it lines up with the brainstorm → plan → cook → ship workflow that many working devs already use.

Tips for higher-quality plans

• Anchor with verification criteria. A good plan always includes how to check it: which tests must pass, the build must run, the screenshot must match. You can also set a condition with /goal so the AI evaluates itself after each step instead of declaring "done" when it is not.
• Write a CLAUDE.md. Record your project conventions (folder structure, naming rules, test commands) in a CLAUDE.md file so every plan stays in the right context without you repeating it each time.
• Be specific in prompts. Point to the exact files, name a sample pattern to follow, and state what is out of scope. The more specific you are, the closer the plan lands.
• Use a subagent to review the plan. Have a subagent with fresh context look over the plan or the diff - a "clean" perspective often catches gaps the main session has grown blind to.
• Use /rewind. If a planning direction is not working, rewind and try another approach instead of patching on top of it.

A quick side-by-side to see the difference:

Weak prompt: "Add Google login to the app."

Strong prompt: "Read src/auth/ and src/routes/. I want to add Google login (OAuth) following the exact session pattern already in src/auth/session.ts. Out of scope: no refresh token yet. Write a plan: which files change, how the callback flow works, and the verification criteria (auth.spec.ts passes)."

ak plan - a ready-made planning skill (AgentKit)

A quick note to avoid confusion: AgentKit here is a kit for Claude Code (agentkit.best, using the ak CLI), which is completely different from "OpenAI AgentKit."

If you find yourself "prompting for a plan" every time you start a feature, there is a skill that packages that process for you: ak-plan. Instead of writing the prompt yourself, you call the skill and it generates a multi-phase plan with a roadmap in a consistent framework, supporting --html (a self-contained artifact you can view/share) and --wiki (publish to AgentWiki). This skill lives in the Engineer Kit - a $99 package (the site lists no recurring fee) with 60+ skills and 30+ workflows. If you want to try it right away, you can activate the ak CLI (20% off via link) and install the kit from there.

To be honest: for most work, native plan mode is already enough, and it is free - you do not need a kit to plan well. ak plan is worth considering when you need plans that are standardized, repeatable, and documented (artifact/wiki) for a whole team, not as a prerequisite to get started.

Common mistakes when planning with AI

• Planning for something too small. Firing up plan mode to change one line just wastes time. If you can describe the diff in one sentence, let it run.
• A long plan with no verification anchor. A dozen-step plan sounds impressive, but without check criteria the AI can easily "look done" while nothing actually runs. Always attach tests/build/clear conditions.
• Cramming many tasks into one session. Doing three unrelated features in the same context window confuses the AI. Run /clear between tasks to keep context lean.
• Trusting the plan and skipping the diff. A correct plan does not guarantee correct code. You still have to read the real diff before you commit.

Frequently asked questions (FAQ)

Does plan mode cost extra?

No. Plan mode is a built-in mode in Claude Code, not a paid add-on. You use it under your current plan (for example Pro at $20/month, or Max 5x at $100/month).

Which key turns plan mode on?

Press Shift+Tab to cycle default → acceptEdits → plan and stop on plan. Or launch with claude --permission-mode plan. The status bar will show ⏸ plan mode on.

Does plan mode edit files on its own?

No. In plan mode, Claude only reads files and proposes a plan; it does not write changes to disk until you approve. That is the core safety feature of the mode.

How is plan mode different from extended thinking (think/ultrathink)?

They are different. Plan mode is a permission mode - it controls whether the AI is allowed to edit files. Extended thinking (think/ultrathink) increases the model's reasoning depth. You can use both together: turn on plan mode for safety, and ask for deeper thinking when the problem is complex.

Is ak plan required, and how is it different from native plan mode?

It is not required. Native plan mode is enough for most cases and it is free. ak plan is a ready-made skill (in AgentKit's Engineer Kit) that generates standardized multi-phase plans with --html/--wiki artifacts - handy when you need to repeat the process and have documentation for a team.

How should I split a large project?

Ask Claude to build a multi-phase roadmap (each phase with a goal, files touched, and done criteria), save it to PLAN.md, then execute each phase in its own session and run /clear between phases to keep context clean.

Conclusion + next steps

Bottom line: do not let Claude Code code right away - go Explore → Plan → Implement → Commit, turn on plan mode with Shift+Tab to preview before you approve, and split large projects into phases with a clean context. Next, read the brainstorm → plan → cook → ship workflow for a complete working framework, and spec-driven development when you need a rigorous plan for a large feature.