The Real Problem With AI Coding

Most complaints about AI coding come down to the same thing: the agent produces low-quality code that doesn’t fit the codebase.

The problem isn’t the AI. The problem is that you’re asking it to write code before it understands what it’s working with.

An AI agent can only work with what’s in its context window. If it hasn’t read a file, it can’t edit it well. If it doesn’t understand your project structure, it’ll make bad assumptions about where things belong.

Plan mode fixes this by building context before any code gets written.

How Plan Mode Works

In Claude Code, you enter plan mode by starting with --permission-mode plan or typing /plan during a session.

What the agent can do:

• Read files
• Explore codebase
• Analyze code
• Ask clarifying questions

What the agent cannot do:

• Edit files
• Run commands
• Execute tests

The agent explores your repo, asks questions, and produces a step-by-step plan. Once you’re satisfied, you exit plan mode and let it execute.

The Plan Mode Loop

The process is simple:

1. Dictate what you want — Can be high-level (“add user auth”) or specific (“refactor handleSubmit in LoginForm.tsx”)
2. Enter plan mode
3. Iterate until the plan is right — Ask questions, refine requirements, catch edge cases
4. Exit and execute

For large features, you might spend an hour in plan mode before writing any code. That hour saves you days of debugging.

You usually don’t clear the context window between planning and execution. The agent carries forward all the files it read and the context it built during planning. This is why it works—the plan document matters, but the primed context window matters more.

Why Context Matters More Than Instructions

Think about what happens without plan mode:

1. You give the agent a task
2. The agent guesses which files are relevant
3. It reads some of them, misses others
4. It starts writing code based on incomplete information
5. The code doesn’t fit your codebase
6. You get frustrated

Now with plan mode:

1. You give the agent a task
2. The agent explores your codebase systematically
3. It reads all the files it will need to modify
4. It discovers how different parts connect
5. It asks questions about ambiguities
6. By the time it codes, it knows exactly what to do

The difference isn’t subtle. It’s the difference between working with a contractor who walked through your house versus one who just saw the address.

Use Dictation. Seriously.

If you’re typing prompts to AI, you’re falling behind.

Dictation lets you spit out ideas faster than any other input method. The key insight: AI doesn’t need grammatically perfect input. Especially in plan mode—the agent rewrites your prompt anyway.

Messy, stream-of-consciousness dictation works fine. The grammatically incorrect inputs at the top of the conversation don’t matter once the agent has refined them into a coherent plan.

Tools that work well:

• Wispr Flow on Windows
• Superwhisper on Mac
• Built-in OS dictation (surprisingly good now)

The combination of dictation plus plan mode means you can describe complex requirements in seconds and have them refined into executable plans.

Plan Mode Helps You Too

You don’t know what you want until you try to explain it.

This is true for clients. It’s true for you too. Don’t fool yourself that you have perfect clarity before you start. You don’t.

Plan mode is a forcing function for concrete requirements. You wouldn’t chuck vague requirements at a human colleague and expect good results. Without plan mode, that’s exactly what you’re doing to an AI.

The agent is the best rubber duck you’ve ever had. It understands codebases instantly, is available 24/7, and asks surprisingly good questions. Plan mode forces you to articulate what you want, which makes you better at building software.

Often, explaining what you want reveals that you wanted something slightly different.

When Plan Mode “Slows You Down”

Sometimes plan mode is slower than just coding it yourself. If you know a repo inside-out and can see the solution instantly, you might be faster without the AI.

But consider what you’re optimizing for:

These tools keep improving. Speed is one of the main areas they’re getting better at. Every time you use plan mode, you build intuition about what AI can handle and how to communicate requirements. That skill compounds.

Less mental fatigue. Focusing on high-level decisions uses fewer brain cycles than fixing syntax errors and chasing type mismatches. You get more done with less exhaustion.

Extended reach. When you’re in an unfamiliar codebase, or you need to think through requirements before diving in, plan mode is essential. It lets you contribute in places you couldn’t before.

The question isn’t “is this slower right now?” It’s “what am I optimizing for?”

The Full Workflow

Here’s how I use plan mode for everything, even small bug fixes:

Small fixes:

1. /plan
2. Describe the bug
3. Agent explores, proposes fix
4. I validate it makes sense
5. Exit, execute, done

Medium features:

1. /plan
2. Describe the feature
3. Agent explores related code
4. We iterate on approach
5. Plan gets refined 2-3 times
6. Exit, execute

Large features:

1. /plan
2. High-level description
3. Agent explores extensively
4. We break it into phases
5. Plan, exit, execute phase 1
6. New /plan for phase 2
7. Repeat

The key is that every execution phase starts with a fully-loaded context window and a clear set of instructions.

FAQ

Key Takeaways