Skip to content
Back to articles
claude-codeplan-modecontext-engineeringplanejamentoboas-praticas

Why Your Claude Code Isn't Delivering (And It's Not Its Fault): The Power of Plan Mode

Claude Code disappointing you? Before switching tools, understand why plan mode, CLAUDE.md and microtask breakdowns separate the ones who ship from the ones who get stuck.

10 min read

Why Your Claude Code Isn't Delivering (And It's Not Its Fault): The Power of Plan Mode

Before swapping tools, check the one step most users skip: planning before prompting for code.

The problem isn't Claude

There's a clear pattern on forums like r/ClaudeAI: one person says Claude Code is great, another replies that "mine doesn't deliver anything close to that". Same model, same tool, opposite results. Why?

In most cases, it isn't Claude. It's the request.

People who get stuck describe the whole app in one message and expect a finished result. People who ship do something different first: they plan. They break it down. They write what they want before asking for code.

The recurring pattern on forums where serious users hang out is blunt: the bottleneck isn't "knowing how to code", it's knowing how to split a problem into pieces small enough for Claude to ship each one successfully. One button, one function, one screen at a time, instead of the whole app in a single prompt.

This article covers why this happens, what Claude Code's plan mode actually does, and how a well-written CLAUDE.md fixes 80% of the problem without switching tools.

The most common mistake: asking for the whole app at once

The natural instinct is to treat the AI like a hired developer. You send a big brief, come back two hours later, check the result.

It doesn't work that way. Language models have a finite context window and, as Anthropic itself states, "LLM performance degrades as context fills". When the context is full, Claude starts "forgetting" earlier instructions and making more mistakes. Every bit of window occupied by codebase exploration, failed attempts and irrelevant files is window missing for the actual implementation.

A giant prompt causes two problems at once: too much new code in a single pass (hard to review) and a context polluted with everything that had to be read to get there. Often, it's easier to rewrite from scratch than to fix what came out.

What works: separate three phases. Explore, plan, implement. Each with a specific goal.

What plan mode is (and how it works)

Plan mode is a native permission mode in Claude Code. The official description:

"Plan Mode instructs Claude to create a plan by analyzing the codebase with read-only operations, perfect for exploring codebases, planning complex changes, or reviewing code safely."

Claude Code docs, "Use Plan Mode for safe code analysis".

What this means in practice:

  • Read-only operations. In plan mode, Claude doesn't write files or run destructive commands. It reads, analyzes, and produces a detailed plan.
  • Question-asking tool. It uses AskUserQuestion to clarify requirements before proposing the plan. You get interviewed; you don't do the interviewing.
  • Editable plan. When the plan shows up, Ctrl+G opens it in your default text editor so you can review and tweak before accepting.

How to turn plan mode on

The official docs describe three ways:

1. During an active session. Press Shift+Tab to cycle through permission modes. From normal mode, the first Shift+Tab enters "Auto-Accept Mode" (indicator ⏵⏵ accept edits on at the bottom). A second Shift+Tab switches to plan mode (indicator ⏸ plan mode on).

2. Starting a new session directly in plan mode. Use the --permission-mode plan flag:

claude --permission-mode plan

3. In headless (non-interactive) mode. Combine -p with the same flag:

claude --permission-mode plan -p "Analyze the authentication system and suggest improvements"

Making it your project default

If your flow almost always plans before executing, pin that in .claude/settings.json:

{
  "permissions": {
    "defaultMode": "plan"
  }
}

The --permission-mode flag overrides the settings defaultMode whenever you need a different start.

Why planning before coding changes everything

Three technical reasons, not mystical ones.

Context stays clean. During exploration, you spend context reading code. But the final plan is short: a few paragraphs that fit in a small footprint. Accepting the plan and leaving plan mode hands the implementation the distilled answer without dragging along the whole draft of how you got there.

Bad decisions surface before bad code. A written plan exposes choices: "I'll use OAuth2 with refresh tokens stored in an httpOnly cookie". You see that decision before it becomes 400 lines of code to unwind.

Subtasks become review units. A plan with six steps has six clear "done" gates. Without a plan, you only know it worked when you try to use it.

Anthropic itself recommends the four-phase flow in the best-practices guide: explore → plan → implement → commit. In plan mode you explore and plan. In normal mode you implement and commit.

"Planning is most useful when you're uncertain about the approach, when the change modifies multiple files, or when you're unfamiliar with the code being modified. If you could describe the diff in one sentence, skip the plan."

Anthropic, Best Practices for Claude Code.

Not everything needs a plan. Swap a string, add a log line, rename a variable: just ask directly. But for anything that touches multiple files or involves an uncertain approach, planning costs less than redoing.

PRD as starting point (not as bureaucracy)

The advice repeated most often by non-programmers who actually shipped real apps is counterintuitive: before asking for code, ask for a PRD.

PRD = Product Requirements Document. A short document that answers:

  • What does this app do?
  • Who uses it?
  • What's the MVP (minimum feature set to be useful)?
  • Which user flows exist?
  • What data needs to be stored?

Claude itself can write this for you. In plan mode, ask something like: "I want to build X. Interview me in detail using AskUserQuestion. Ask about technical implementation, UI/UX, edge cases, tradeoffs. Skip obvious questions. When we're done, write a complete spec to SPEC.md."

Anthropic documents this exact pattern as "Let Claude interview you". The logic: a fresh session, starting with SPEC.md on hand, has clean context focused entirely on implementation. You don't have to re-explain anything.

This isn't corporate ceremony. It's compression. Instead of explaining the app every time, you write it once and reference it when needed.

CLAUDE.md: the long-term memory most readers ignore

If plan mode solves "what to do next", CLAUDE.md solves "what Claude should always know about this project".

Straight from the docs:

"CLAUDE.md is a special file that Claude reads at the start of every conversation. Include Bash commands, code style, and workflow rules. This gives Claude persistent context it can't infer from code alone."

Anthropic, Best Practices for Claude Code.

In practice:

  • The file lives at the project root.
  • It's read automatically at the start of every session.
  • Committed to git, it becomes shared memory with the team (or with your future self).
  • It accepts imports from other files via @path/to/file when it gets long.

What to include:

  • Bash commands Claude can't guess (for example, pnpm dev:studio instead of the expected npm start).
  • Style rules that deviate from defaults (for example, "never use any in TypeScript, use unknown").
  • Branch and commit conventions for your team.
  • Required env vars and how they're validated.
  • Project-specific gotchas.

What not to include:

  • Anything Claude already knows from language or framework conventions.
  • File-by-file descriptions of the codebase.
  • Long explanations or tutorials.
  • Generic advice like "write clean code".

Anthropic's rule of thumb: for every line in CLAUDE.md, ask "if I remove this, would Claude make a mistake?". If not, cut it. A bloated file makes Claude ignore the important rules because they get lost in the noise.

Microtasks vs macro tasks

Back to the top-comment insight: "break your project into microscopic pieces". That isn't rhetorical exaggeration.

The old way: "build me a management app for my dental clinic with scheduling, patient records, billing and WhatsApp integration".

The way that works: take that plan, break it into individual steps, and ask for one at a time.

  • Iteration 1: Next.js + Prisma setup with Patient model.
  • Iteration 2: patient creation form with validation.
  • Iteration 3: paginated patient listing.
  • Iteration 4: Appointment model linked to Patient.
  • Iteration 5: scheduling calendar.

Each iteration fits in a short session. Each iteration has a clear done criterion. If something breaks, you roll back that single iteration, not the whole project.

Plan mode is the tool that takes you from "whole app" to this list. You describe the whole thing once, Claude interviews you, you get a plan, and the plan becomes your own task list.

Didactic example: bad prompt vs good prompt

The two examples below target the same goal. One tends to stall. The other tends to ship. Copy the pattern, not the details.

Bad prompt (one-shot, vague):

Build a clinic scheduling system with patient registration, appointment
booking, WhatsApp reminders, monthly reports and login. Use Next.js,
Prisma and PostgreSQL. Make it look nice.

What happens: Claude tries everything at once, context fills with partial decisions, auth ends up half-done, the database has no organized migrations, the frontend is missing validation. By the end, there's too much code to review and too little actually finished.

Good prompt (plan mode + microtask):

claude --permission-mode plan

I want to build a clinic management system (Next.js + Prisma + PostgreSQL).
Interview me with AskUserQuestion to generate a SPEC.md covering: data
models, user flows, MVP, exact stack, auth requirements. Don't implement
anything. Just plan.

Then, in a fresh session (normal mode):

Use the SPEC.md in this project. Implement only Iteration 1: Next.js 16
setup with App Router, Prisma configured with local PostgreSQL, Patient
model with fields name, ssn, phone, birth_date. Add an initial migration
and a /patients/new page with a form that creates a patient. Validate
with Zod. Run the project checks at the end (tsc --noEmit, eslint).

Notice: the second prompt has tight scope, verification criteria (checks at the end) and external context reference (SPEC.md). It's still a lot of code, but it's a lot of code that does one thing and can be reviewed in minutes.

In Practice

Step by step to start using plan mode today:

1. Open Claude Code at your project root

cd /path/to/project
claude

2. Enter plan mode

Press Shift+Tab twice until ⏸ plan mode on appears at the bottom of the terminal. (If you want to start in plan mode directly, exit and run claude --permission-mode plan.)

3. Ask for a plan, not an implementation

Example starting prompt:

I'm planning [short feature description]. Interview me using
AskUserQuestion about implementation, edge cases and tradeoffs. Don't
implement anything. When we finish, write the plan to PLAN.md.

4. Review the plan with Ctrl+G

When the plan appears, Ctrl+G opens it in your text editor. Edit freely. The plan is your document, not Claude's.

5. Leave plan mode and implement one iteration at a time

Exit plan mode (Shift+Tab back to "default mode" or "accept edits on") and request one iteration at a time, referencing the saved plan:

Implement Iteration 1 from @PLAN.md. Run the project checks at the end.

Tip: if you catch yourself correcting Claude more than twice on the same issue, run /clear to reset context. A fresh session with a better prompt almost always beats a long session with stacked corrections.

Conclusion: what separates shipping from stalling

Back to the opening question: why do two people with the same tool get such different results?

People who stall:

  • Describe the whole app in one shot.
  • Ask for code directly, without a plan.
  • Don't keep a CLAUDE.md.
  • Fix symptoms instead of causes.
  • Let context fill with failed attempts.

People who ship:

  • Explore, plan and implement in separate phases.
  • Use plan mode to interrogate their own project.
  • Keep a short, sharp CLAUDE.md.
  • Split the project into microtasks.
  • Run /clear between unrelated topics.

The tool is the same. The method is the difference. And the method isn't hidden: it's in the official docs, in the top comments of experienced users, and now in this article.

Change the order of operations before changing tools.

References

Where to go next

Plan mode, CLAUDE.md and context engineering are three of the 13 pillars covered in the Curso Claude Code: Criador de Apps (Portuguese-only course). The course takes you from full setup to a shipped app, with modules dedicated to How Claude Code Thinks, Prompt and Context Engineering, Turbocharging Your Claude Code (plugins, commands, skills, MCP, hooks, subagents) and Professional Workflow. Lifetime access from 12× R$39 (R$468 one-time), includes the Claude Code Guide as a bonus and a 7-day no-questions-asked guarantee.