Typical Workflows: Explore, Plan, Implement

Every experienced developer knows that the most costly mistake is quickly writing the right code for the wrong problem. Claude Code's agentic loop amplifies this risk: if the agent jumps straight to code without understanding the context, it can produce hundreds of lines of quality, well-structured code that solves the wrong problem entirely. That's why the officially recommended workflow looks like this:

Explore → Plan → Code → Commit

This isn't just a convenient mnemonic — it's an architectural decision for working with an agent that has a limited context window and a tendency toward premature implementation.

flowchart TD
    A([🚀 New Task]) --> B{Is the task simple?}
    B -- Yes, one file,\none change --> G[⚡ Straight to code]
    B -- No, multiple files\nor unfamiliar code --> C

    C[🔍 EXPLORE\nPlan mode: Shift+Tab\nReading files, @references,\nsubagents for large research] --> D

    D[📋 PLAN\nCtrl+G — edit plan\nFile list, steps, verifiers] --> E

    E[💻 CODE\nNormal mode\nImplementation + tests/build\nAgent iterates until passing] --> F

    F[✅ COMMIT\nMeaningful commit\ngh pr create\nclaude --from-pr to resume] --> H([🎯 Done])
    G --> F

    style A fill:#4CAF50,color:#fff
    style H fill:#4CAF50,color:#fff
    style C fill:#2196F3,color:#fff
    style D fill:#FF9800,color:#fff
    style E fill:#9C27B0,color:#fff
    style F fill:#607D8B,color:#fff
    style G fill:#9C27B0,color:#fff

Phase 1: Explore — Understand Before You Touch Anything

The most important principle: Claude should not edit files until it understands the context. This is what plan mode is for — a special mode where the agent can read files, run Bash commands, and ask questions, but cannot make any changes to the filesystem.

Plan mode can be activated in three ways:

# Launch directly in plan mode
claude --permission-mode plan

# Toggle mid-session — Shift+Tab
# or with the command:
/plan

Typical prompts for the exploration phase:

Read src/auth and figure out how we handle sessions and login.
Also check how we manage environment variables for secrets.

Show me the architecture of the payments module — which files are responsible for what?

Trace a request from the frontend to the database for the /api/users endpoint

Note the @ syntax — it lets you explicitly pass a file or directory without waiting for Claude to find it on its own:

Explain the logic in @src/utils/auth.js

What is the structure of @src/components?

The difference between @file and asking Claude to "read a file" is that an @-reference includes the content immediately, before the response is generated.

When exploration consumes too much context. If a task requires reading dozens of files, consider delegating the exploration to a subagent — it runs in a separate context window and returns only a summary:

Use a subagent to explore how our auth system handles refresh tokens
and whether any existing OAuth utilities are already in place.

The subagent reads the files, compiles a report, and returns it to the main session — without polluting the main dialogue's context. Learn more in Subagents and Context Isolation.

Phase 2: Plan — A Detailed Plan Before the First Change

Once the agent understands the code structure, ask for a concrete implementation plan — right there in plan mode:

I want to add Google OAuth. Which files need to change?
What will the session flow look like? Write a detailed plan.

Once you have the plan, you can edit it directly in your text editor — press Ctrl+G inside the session and the plan will open in your editor. This isn't just a convenience: you can remove unnecessary steps, add constraints, and clarify priorities. Claude will follow the edited plan during implementation.

A good plan includes:

• A list of files with specific changes
• A sequence of steps (what comes first, what comes next)
• Verification checkpoints (after which steps to run tests)
• Explicit constraints ("don't touch legacy module X", "don't add new dependencies")

Anthropic's documentation offers a useful trick for complex features — have Claude conduct an "interview" before planning:

I want to implement a notifications system. Run a detailed interview
using AskUserQuestion. Ask about the technical approach, UX,
edge cases, and trade-offs. Don't ask obvious questions —
dig into the hard parts I might not have thought about.
After the interview, write a complete spec in SPEC.md.

Once you have the spec, start a fresh session for implementation — that way the planning context doesn't bleed into the implementation context.

Phase 3: Code — Implementation with Verification

Switch out of plan mode and kick off the implementation. The key principle of this phase: give Claude a way to verify the result.

Without a verification mechanism, Claude stops when things "look done." With tests, a build, or a script, it iterates on its own:

# Bad prompt:
implement the OAuth flow from your plan

# Good prompt:
implement the OAuth flow from your plan. Write tests for the callback handler,
run the suite, and fix any failures. Make sure the build passes.

What you can use as a verifier:

A few more principles for writing quality prompts in the code phase:

Reference existing patterns. Instead of an abstract "add a widget," show an example:

Look at how the existing widgets on the home page are implemented.
HotDogWidget.php is a good example. Follow that pattern
to implement a new CalendarWidget. No third-party libraries
other than those already used in the codebase.

Describe the symptom, not your guess about the cause. Instead of "fix the login bug":

Users report that login fails after a session expires.
Check the auth flow in src/auth/, especially token refresh.
Write a failing test that reproduces the issue, then fix it.

Point Claude to sources for answering questions:

Why does ExecutionFactory have such a strange API?
Look at the git history for ExecutionFactory and explain how it ended up this way.

Phase 4: Commit — Meaningful Commits and PRs

After successful verification, ask Claude to commit the changes:

make a commit with a descriptive message and open a PR

Claude Code can create commits, push a branch, and open a PR via gh pr create — all through the Bash tool. One important detail: if a session created a PR via gh pr create, it is automatically linked to that PR. You can return to it later with:

claude --from-pr <number>

This lets you continue working on the PR in a future session without losing context.

Pattern Variations: When to Simplify

The explore → plan → code → commit pattern isn't needed for every task. It adds overhead — and that's worth accounting for.

When to skip planning:

• Fixing a typo or adding a log line
• Renaming a variable
• The task fits in one sentence: "add a null check on line 42"

When planning is mandatory:

• The change touches multiple files
• You're unfamiliar with the code being changed
• The task is architectural — multiple approaches with trade-offs
• After several Sonnet sessions, the right solution still hasn't emerged

The Writer/Reviewer pattern. For complex changes, consider using two sessions:

The reviewer works with a clean context — it has no knowledge of the reasoning that led to the implementation and evaluates the result objectively.

Common Anti-Patterns

The "kitchen sink" session. You started with one task, asked about something unrelated, then came back to the first. The context is polluted. Fix: use /clear between unrelated tasks.

Endless correction. Claude did something wrong, you corrected it, it got it wrong again. After two failed corrections in the same session — use /clear and write a new, more specific prompt informed by what you learned. A fresh session with a better prompt almost always beats a long session full of accumulated corrections.

Unbounded exploration. You asked Claude to "explore" something without setting limits — it read hundreds of files and filled the context window. Fix: scope exploration to specific directories or use a subagent.

Trust without verification. Claude wrote a plausible-looking implementation, you shipped it to production, and an edge case broke it. Fix: always provide a verifier.

See also

• Plan Mode and Test-Driven Development — a deep dive into plan mode and the TDD cycle with an agent
• Best Practices and Code Organization Patterns — the full set of Anthropic recommendations, including context discipline and CLAUDE.md
• Git, Commits, and Pull Requests — how Claude works with git in the commit phase, branches, worktrees, and conflict resolution
• Subagents and Context Isolation — delegating research tasks to subagents to keep the main context clean
• CLAUDE.md and the Memory System — how to encode architectural context in CLAUDE.md so you don't have to explain it at the start of every session
• Managing the Context Window — /clear, /compact, and other context management tools that are critical for long working sessions
• Headless Mode and CLI Scripting — the fan-out pattern for parallel tasks via claude -p