Plan mode was shipped as a way to get Claude Code to think through a task before executing it — useful for large refactors, risky migrations, and situations where you want to see the approach before files start changing. But there’s a less obvious use case that’s been quietly valuable: using plan mode to design CLAUDE.md files before writing them, and to audit existing ones before they get longer.
The core idea is using Claude’s planning pass as a design review. You describe what you want CLAUDE.md to achieve, ask Claude to plan what should go in it, and then respond to the plan before writing a single line. The output is a CLAUDE.md with better structure, fewer conflicts, and less noise than one written top-down from scratch.
Why CLAUDE.md Files Go Wrong
Most CLAUDE.md files start as good ideas and accumulate problems over time:
Specification creep: Every time an agent does something wrong, someone adds a rule to prevent it. After six months, you have 40 rules and the agent is spending significant context on instructions that haven’t been relevant in weeks.
Internal conflicts: Rule A says “prefer functional programming patterns.” Rule B says “use class-based services for all business logic.” Both were added by different people at different times. The agent has to pick one and it’s not always predictable which.
Scope ambiguity: Rules written for one context apply globally. A rule about TypeScript error handling applies to shell scripts. A rule about React components applies to database migration files.
Missing rationale: Rules without context get eroded. “Never use any” gets a // @ts-ignore workaround when someone’s in a hurry, because there’s no explanation of why the rule exists.
Plan mode surfaces all of these before they become embedded in a CLAUDE.md that’s actively making your agent worse.
The Planning Workflow
The workflow has two phases: design planning for new CLAUDE.md files, and audit planning for existing ones.
Phase 1: Design Planning (New File)
Start a conversation with Claude Code, enter plan mode with /plan, and give it a project description:
/plan
I need to design a CLAUDE.md for a Node.js API project. Here's the context:
- Fastify framework, TypeScript strict mode
- PostgreSQL via Drizzle ORM
- Jest for testing (migrating to Vitest next quarter)
- 3 developers, mix of senior and mid-level
- Main pain points: inconsistent error handling, devs sometimes push directly to main,
test coverage dropped from 80% to 60% over last 6 months
What sections should this CLAUDE.md contain? For each section, explain:
1. What problem it solves
2. What information goes in it
3. What to leave out (and why)
Don't write the actual CLAUDE.md yet — just the structural plan.Plan mode response (condensed):
## Proposed CLAUDE.md Structure
### 1. Commands (essential — include always)
Problem: Agents waste context and make mistakes when they have to guess build commands.
Include: Exact commands for build, test, lint, type-check, and dev server.
Exclude: Environment setup (too verbose, changes often), deployment (agent shouldn't do this).
Note: You mentioned migrating to Vitest next quarter. The test command will change.
Consider adding an inline comment in CLAUDE.md or a note so the agent doesn't get confused
during the migration window.
### 2. Code Style
Problem: Inconsistent TypeScript patterns across the codebase.
Include: Strict mode note, specific patterns (error handling style, import conventions,
naming conventions for routes vs services).
Exclude: Generic best practices that TypeScript or ESLint already enforce —
the agent doesn't need to be told "use semicolons" if .eslintrc handles it.
### 3. Architecture Constraints
Problem: Devs "sometimes push directly to main" suggests architectural/process confusion.
Include: Layer rules (routes call services, services call repositories), protected paths
(e.g., migrations directory), branch strategy.
Exclude: Rationale for the architecture — that belongs in a separate ADR, not CLAUDE.md.
### 4. Error Handling (given you called this a pain point)
Problem: Inconsistent error handling across the codebase.
Include: Specific error class to use, required error format, where to catch vs where to throw.
Exclude: General error handling philosophy — give the agent the pattern, not the reasoning.
### ⚠ Potential conflicts I noticed:
- You mentioned Vitest migration next quarter. If agents start using Vitest imports
and syntax based on CLAUDE.md while the codebase is still Jest, you'll get test failures.
Decide: keep CLAUDE.md on Jest until migration is done, or make the migration rule explicit.
### ⚠ What to leave out:
- CI/CD pipeline details (agents don't run deploys)
- Database schema documentation (goes in a separate file, reference from CLAUDE.md)
- Onboarding docs for human developers (different audience)
Ready to write the CLAUDE.md based on this structure?This is the useful part of the planning pass: the conflict detection (“you mentioned Vitest migration… decide now”) and the scope pruning (“agents don’t run deploys — leave it out”). These are the insights that don’t appear when you write CLAUDE.md top-down.
Phase 2: Audit Planning (Existing File)
For existing CLAUDE.md files, the planning prompt is different:
/plan
Here is my current CLAUDE.md (attached). I want you to audit it before I make changes.
For each section or rule, categorize it as:
- KEEP: Essential, well-scoped, still accurate
- TRIM: Correct but over-specified or too verbose
- REMOVE: No longer relevant, handled elsewhere, or too broad
- CONFLICT: Contradicts another rule in this file
- CLARIFY: Too vague to be actionable
Don't rewrite anything yet. Just give me the categorized audit.The planning pass here is acting as a second set of eyes before you start editing. The key is getting categorizations without edits — you want to understand what’s wrong before deciding what to change.
Specific Techniques
Identify Scope Creep with the “Does This Apply to X?” Test
In plan mode, ask Claude to apply each rule to unlikely file types:
/plan
Here are 5 rules from my CLAUDE.md. For each one, tell me:
- What file types it clearly applies to
- What file types it shouldn't apply to but would (based on how it's written)
- Whether the rule needs scoping
Rules:
1. Always use named exports, never default exports
2. Return errors as Result<T, E> types, never throw
3. Validate all inputs at the boundary layer
4. Use camelCase for variables, PascalCase for types
5. Add JSDoc comments to all public functionsCommon findings: “Never throw” is reasonable for service layer functions but breaks shell script utilities. “JSDoc on all public functions” is appropriate for a library but not a 3-file utility script.
Conflict Detection
/plan
Review these rules for logical conflicts or cases where following rule A makes
rule B impossible to follow:
[paste your full CLAUDE.md]
Focus only on logical contradictions and impossible-to-satisfy combinations.
Do not suggest new rules or improvements — just find the conflicts.Rationale Extraction
Plan mode is good at inferring why a rule might exist from its content, which you can then use to write better rule comments:
/plan
For each of these rules, infer the most likely reason it was added
(what problem was someone trying to prevent?). Then suggest a one-sentence
"Why this matters" comment that I can add inline.
Rules: [paste rules]What Plan Mode Won’t Do
Planning is better than writing blind, but it has limits. Claude in plan mode is working from the text you provide — it doesn’t know about your actual codebase, your team’s actual behavior, or the specific incidents that led to each rule. The planning pass surfaces structural issues, not contextual ones.
A conflict between “use functional patterns” and “use class-based services” will be caught. A rule that says “never use setTimeout in tests” but doesn’t specify that Vitest fake timers are the intended replacement won’t be caught — that’s a knowledge gap that requires human judgment.
The useful framing: plan mode is a structural reviewer, not a domain expert. Use it for structure and then apply your own knowledge for content.
Token Budget Consideration
One concrete benefit of planning before writing: CLAUDE.md files designed through planning tend to be shorter than ones written directly. The planning pass consistently identifies rules that overlap with ESLint/Prettier/TypeScript configuration that the agent doesn’t need to know about. In one case, running an audit on a 600-line CLAUDE.md via plan mode identified 40% of the content as either redundant with tooling or no longer accurate — the resulting 360-line file performed better in practice because the agent spent less context on noise.
If you’re trying to keep CLAUDE.md under 2000 tokens (a reasonable target for leaving room for code context), the planning pass is the most reliable way to stay under budget while keeping everything that matters.