Claude Code Plan Mode Workflow: A Production Guide

The claude code plan mode workflow separates thinking from doing. Before Claude writes a single line of code, it produces a structured plan you can read, challenge, and approve. That separation is not a convenience feature; it is the primary mechanism for keeping a human in the loop on consequential changes. This guide explains how to use it deliberately, what to put in CLAUDE.md to make it stick, and how to chain plan mode with tests and gates so the output is verifiable rather than "best effort."

What is plan mode in Claude Code, and when should you use it?

Plan mode is a first-pass execution phase in which Claude Code reads your codebase, reasons about the task, and produces a written plan without making any file edits. You review the plan, request changes, and only then trigger the implementation phase.

Use plan mode whenever:

• The change touches more than one file or module boundary.
• You cannot easily reverse the edit (database migrations, API contract changes, dependency upgrades).
• You are working in an unfamiliar codebase and want Claude to surface its assumptions before it acts on them.
• A team member other than the requester needs to sign off.

For single-file, low-risk edits, the overhead of a full plan cycle is rarely worth it. The exam-relevant principle here is proportionate fixes: apply the heaviest process to the highest-stakes work.

How does the plan-then-execute cycle actually work?

The cycle has four phases. Each phase has a clear exit condition before the next begins.

1. Codebase Q&A. Before writing the plan, ask Claude to read the relevant files and answer scoping questions. This surfaces stale assumptions early. See the incremental codebase understanding pattern for how to structure these reads.
2. Plan generation. Claude produces a numbered list of changes: which files, what edits, in what order, and why. No writes happen.
3. Human review and approval. You read the plan, push back on anything that looks wrong, and give explicit approval. This is the checkpoint.
4. Execution. Claude implements the approved plan. If it encounters something unexpected, it surfaces it rather than improvising.

The cycle maps directly to the hybrid plan-then-execute pattern covered in Domain 1 of the CCAR-F exam, which carries 27% of the exam weight.

User: /plan Refactor the payment module to support multi-currency.
Claude: [reads src/payment/, src/models/, tests/payment_test.py]
        Plan:
        1. Add `currency` field to PaymentIntent schema (models/payment.py, line 42)
        2. Update PaymentService.charge() to accept currency param (services/payment.py)
        3. Add currency validation helper (utils/currency.py, new file)
        4. Update 3 existing tests; add 2 new currency-specific cases
        Assumptions: USD is the default; no FX conversion in scope.
        Proceed? (y/n)

The explicit "Assumptions" line is worth requiring in your CLAUDE.md. Surfaced assumptions are reviewable; buried assumptions become bugs.

What should go in CLAUDE.md to enforce plan mode?

CLAUDE.md is the project-level configuration file Claude Code reads at session start. It is the right place to encode team conventions that should apply to every task, not just the ones you remember to mention. The three-level configuration hierarchy means a project-level CLAUDE.md at the repo root overrides user-level defaults, so team conventions win.

What belongs in CLAUDE.md:

• Mandatory plan phase. State explicitly that Claude must produce a plan and wait for approval before editing any file outside the current working directory.
• Assumption surfacing. Require an "Assumptions" section in every plan.
• Test gate. Require that all existing tests pass before the task is marked complete.
• Scope limits. List directories or files that are off-limits without explicit permission (e.g., infra/, migrations/).
• Output format. Specify how Claude should report completion (e.g., a structured summary with files changed, tests run, and any open questions).

What does NOT belong in CLAUDE.md:

• Long prose explanations of why a rule exists. Claude reads the file on every session; verbose rationale dilutes the signal.
• Rules that contradict each other. Conflicting instructions produce unpredictable behaviour; resolve conflicts before committing them.
• Anything that changes per-task. Per-task instructions belong in the prompt, not the config file.

# CLAUDE.md

## Mandatory workflow
1. Read all files relevant to the task before writing any plan.
2. Output a numbered plan with an explicit "Assumptions:" section.
3. Wait for the user to type "approved" before making any edits.
4. Run the test suite after edits. Report pass/fail counts.
5. Do not edit files under infra/ or migrations/ without explicit permission.

## Output format on completion
- Files changed: <list>
- Tests: <pass count>/<total>
- Open questions: <list or "none">

How do you structure a plan for a large feature or multi-repo change?

Large features benefit from phase decomposition: break the work into phases that can each be planned, approved, and executed independently. This is the dynamic adaptive decomposition pattern applied to a single-engineer workflow.

A practical phase structure for a large feature:

Each phase produces a plan. Each plan gets approved before execution. The phases are small enough that a mistake in phase 3 does not require re-running phases 1 and 2.

For multi-repo refactors, the same structure applies but with an additional constraint: changes to shared interfaces (API contracts, shared libraries) must be planned and approved before any downstream repo work begins. This is a prerequisite gate design applied at the repository boundary.

How do you make Claude Code output verifiable rather than "best effort"?

Verifiable output requires three things: a test gate, a structured completion report, and a cross-check step.

Test gate. Require in CLAUDE.md that Claude runs the existing test suite after every implementation phase and reports the result. If tests fail, Claude must diagnose the failure before proceeding. This is not optional; a plan that passes review but breaks tests is not done.

Structured completion report. Require a machine-readable summary at the end of each phase. A JSON block works well for this because it is easy to parse in CI or a review script:

{
  "phase": "service_layer",
  "files_changed": ["services/payment.py", "utils/currency.py"],
  "tests_run": 47,
  "tests_passed": 47,
  "tests_failed": 0,
  "open_questions": []
}

Cross-check step. After implementation, ask Claude to re-read the plan and confirm that every item was addressed. This catches cases where Claude silently skipped a step because it encountered an unexpected dependency. The self-correction with cross-validation pattern formalises this.

The CCAR-F exam consistently rewards deterministic, verifiable solutions over probabilistic ones when stakes are high. A plan mode workflow with explicit gates is the architectural expression of that principle.

When should you use a command, a skill, or an agent instead of plan mode?

Plan mode is a session-level workflow. Commands, skills, and agents are reusable artefacts. The choice depends on how often you repeat the work and how much autonomy you want to grant.

For tasks you run more than a few times per week, encoding the plan as a skill or command pays off. The skill file captures the approved workflow so you do not have to re-approve the same plan repeatedly. See skills vs CLAUDE.md distinction for how these layers interact.

For tasks that benefit from parallelism, such as running the same analysis across multiple services simultaneously, parallel subagent spawning is more efficient than sequential plan mode cycles.

How do you chain Claude Code with GitHub CLI and CI checks?

The terminal-native workflow chains Claude Code with gh (GitHub CLI) to keep the full loop inside one session: plan, implement, test, commit, open PR, check CI.

# 1. Plan phase (no edits yet)
claude --plan "Add multi-currency support to payment module"

# 2. After approval, execute
claude "Implement the approved plan"

# 3. Run tests locally
pytest tests/payment_test.py -v

# 4. Commit and push
git add -p
git commit -m "feat: add multi-currency support to payment module"
git push origin feature/multi-currency

# 5. Open PR with gh CLI
gh pr create --title "feat: multi-currency payment support" \
  --body "Implements approved plan. All 47 tests pass." \
  --reviewer @payment-team

# 6. Check CI status
gh pr checks --watch

The --plan flag (or /plan slash command in interactive mode) triggers the plan phase without executing. The git add -p step is deliberate: reviewing the patch interactively is a second human checkpoint that catches anything the plan review missed.

If CI fails, bring the failure back into Claude Code with the output pasted as context. Claude can diagnose the failure and propose a targeted fix, which you then approve before applying. This keeps the human-in-the-loop pattern intact even in the fix cycle.

How does plan mode relate to the CCAR-F exam?

Plan mode sits squarely in Domain 3 (Claude Code Configuration and Workflows, 20% of the exam) and Domain 1 (Agentic Architecture and Orchestration, 27%). Together those two domains account for 47% of the exam weight.

The exam tests practical judgment, not recall. Scenario questions will present a situation where a team is getting unreliable output from Claude Code and ask you to diagnose the root cause and propose a fix. The correct answer almost always involves:

1. Adding a plan phase before execution.
2. Making assumptions explicit and reviewable.
3. Inserting a test gate before marking work complete.
4. Using deterministic enforcement (config, gates) rather than hoping the prompt is followed.

The prompt-based vs programmatic enforcement concept is directly relevant here: CLAUDE.md rules are prompt-based and can be overridden; CI gates and test requirements are programmatic and cannot. For high-stakes workflows, layer both.

Our Claude Code Configuration and Workflows concept library covers the full Domain 3 task statements, and the Agentic Architecture and Orchestration library covers Domain 1. Both are mapped to the 30 task statements in the CCAR-F exam guide.

The CCAR-F exam costs $125 per attempt, is scored on a 100 to 1000 scale with a passing score of 720, and Domain 3 alone represents one-fifth of that score. A solid plan mode workflow is not just good engineering practice; it is a high-yield exam topic.