Claude Code Context Management: CLAUDE.md Design Patterns

I spent hours crafting the perfect CLAUDE.md, only to watch Claude Code completely ignore it. "You didn't even read that, did you?" — I've had that thought more times than I can count. It turned out the problem wasn't Claude. It was how I was writing CLAUDE.md.

This article covers the practical context management patterns I've developed over three months of daily Claude Code use. By combining the right CLAUDE.md design patterns with .claudeignore and Plan mode, I've seen a significant boost in productivity — here's exactly how.

Why Does the 200,000-Token Context Window Fill Up So Fast?

Claude Code's context window is currently 200,000 tokens. That sounds enormous, but in real development work it fills up faster than you'd expect.

Take a Next.js project where you ask Claude to refactor every page. Just reading the source files consumes tens of thousands of tokens. Add conversation history, the CLAUDE.md content, and generated code, and you're approaching the limit quickly.

What happens when context overflows? Claude starts forgetting older information. In the worst case, it simply ignores the rules you wrote in CLAUDE.md and presses on as if they don't exist. That's the real reason CLAUDE.md gets "ignored."

Rough token estimates (from experience):

• A typical CLAUDE.md: 2,000–5,000 tokens
• One source file (500 lines): ~5,000 tokens
• A long conversation session: 20,000–50,000 tokens

Context management is fundamentally a design problem: deciding what goes inside the window and what stays out.

Why Does Claude Code Ignore Your CLAUDE.md?

From experience, CLAUDE.md failures almost always trace back to three root causes.

Mistake 1: Too many rules

When you cram in coding conventions, directory structures, prohibited patterns, and testing policies all at once, Claude has to process all of it before doing anything else. Attention gets spread thin, and the important rules stop being followed.

Mistake 2: Vague instructions

"Write clean code" and "make it easy to understand" don't work. Write rules that can be evaluated mechanically: "Functions have a single responsibility" or "Comments are written in English."

Mistake 3: One file for the entire project

A single root-level CLAUDE.md tends to balloon in size and can only express generic project-wide rules. When different modules have different requirements, placing separate CLAUDE.md files in subdirectories works far better.

What CLAUDE.md Design Patterns Actually Work in Practice?

Here are the five patterns I've settled on after extensive trial and error.

Pattern 1: Minimal (for small projects)

# Project Rules
- Language: TypeScript strict mode
- Test: Vitest. Run `pnpm test` before committing
- Style: No inline styles. Tailwind only

Write only what's essential. Aim for under ten lines. Don't fear whitespace.

Pattern 2: Sectioned (for medium-sized projects)

# CLAUDE.md

## Critical Rules (non-negotiable)
- No direct writes to production DB
- Never console.log secrets

## Code Style
- Prefer pure functions
- Isolate side effects in useEffect / event handlers

## Project Context
- Next.js 15 App Router
- Supabase (RLS enabled)
- Deploy target: Vercel

Separating "rules that are catastrophic if broken" from "style guidelines" makes it clear where Claude should focus its attention.

Pattern 3: Task-Focused (for specific work sessions)

# Current Task Context
Today's task: Refactor the auth module
Files to touch: src/auth/ only
Files NOT to touch: src/api/, src/components/

## Constraints
- Do not modify Supabase Auth
- Existing tests must pass (adding new tests is fine)

Effective when you want Claude focused exclusively on today's work in a long-running project. Rewrite at the start of each session.

Pattern 4: Hierarchical (for large projects)

root/CLAUDE.md              # Project-wide rules (keep minimal)
src/api/CLAUDE.md           # API layer rules
src/components/CLAUDE.md    # UI layer rules
src/lib/CLAUDE.md           # Utility layer rules

Claude Code searches upward from the current directory and reads all CLAUDE.md files it finds. Separating by layer lets you apply the right rules to the right context.

Pattern 5: Context Index (for referencing external documentation)

## Architecture Decision Records
See: docs/adr/ (key design decisions live here)

## API Specification
See: docs/api-spec.md (full endpoint list)

## Known Issues
- #234: Session persists after logout in some edge cases (in progress)

Rather than copying all your documentation into CLAUDE.md, use it as an index — "what to read to learn what." This keeps the file lean while still orienting Claude effectively.

How Do You Use .claudeignore to Cut Down Token Usage?

.claudeignore uses the same syntax as .gitignore and specifies files that Claude Code should skip when indexing the project.

# .claudeignore

# Build artifacts (always exclude)
.next/
dist/
out/
node_modules/

# Large files Claude never needs to read
*.lock
pnpm-lock.yaml
package-lock.json

# Test snapshots (huge token consumers)
**/__snapshots__/
**/*.snap

# Secrets
.env*
*.pem
*.key

# Images and binaries
*.png
*.jpg
*.svg
*.woff2

# Logs
*.log
logs/

The highest-value exclusions are node_modules/ and .next/. Excluding these alone dramatically reduces token consumption.

Lock files like pnpm-lock.yaml are also worth watching — they can run thousands of lines long, and accidentally pulling one into context wastes a significant chunk of your token budget.

When Should You Use Plan Mode in Claude Code?

Plan mode (/plan command) makes Claude think through what it will do before writing a single line of code.

When to use it:

• Wide-scope refactors affecting 10+ files
• Database schema changes
• Auth or payment flow changes
• When you genuinely don't know where to start

When you can skip it:

• Bug fixes with a clear root cause
• Adding a new component
• Adding or updating tests
• Simple renames or file moves

Plan mode's biggest advantage is catching alignment issues before implementation starts. When Claude says "I'll implement A → B → C," you can say "actually, do C before B" — rather than discovering the mismatch after hundreds of lines have been written.

# Plan mode in practice
> /plan Migrate user auth from JWT to Supabase Auth

Review the plan Claude produces, then use /approve to kick off implementation.

How Do You Choose Between /compact, /clear, and /context?

As sessions grow longer, context bloat degrades response quality. Three commands address this.

/compact — Compress context

Summarizes conversation history, keeping only important decisions. Use when you want to continue the same session but it's starting to feel heavy.

> /compact

/clear — Reset context

Clears all conversation history for a fresh start. Use when a task is complete or you're switching to completely different work. CLAUDE.md will be re-read.

/context — Check current context usage

> /context
# → Shows current token usage and remaining capacity

In practice, the single habit of running /clear at the end of each completed task prevents most context contamination.

How Do You Split Large Projects Across Multiple Sessions?

Don't try to do everything in one session. That's the foundational principle of context management.

Break large projects into session-sized chunks:

Example session breakdown:

• Session 1: Auth module refactor
• Session 2: API endpoint cleanup
• Session 3: Frontend state management overhaul
• Session 4: Test additions and coverage improvements

Track handoffs in Markdown.

# session-handoff.md (update at session end)

## Completed
- Migrated src/auth/login.ts from JWT to Supabase Auth
- All existing tests passing

## Next Session
- Migrate src/auth/register.ts (same approach as login.ts)
- Update auth check in middleware.ts

## Notes
- Supabase Row Level Security stays enabled
- NEXT_PUBLIC_SUPABASE_URL already set in .env.local

At the start of the next session, either reference this file in CLAUDE.md or paste it at the top of the conversation. Context is preserved even when sessions are interrupted.

How Do You Build a Context Monitoring Habit?

Simply being conscious of context management changes output quality. Here's the routine that's worked for me.

Pre-session checklist:

• Is today's task clearly defined?
• Does CLAUDE.md match today's task?
• Is .claudeignore excluding unnecessary files?
• Is there a handoff note from the last session?

Mid-session checkpoints:

• Check /context every 30 minutes
• Run /compact at the first sign of drift
• Run /clear after each completed task

End of session:

• Update session-handoff.md
• Reflect any decisions made into CLAUDE.md
• Note context that will be needed next time

Context management is the foundation of getting real value from Claude Code. The tool has remarkable capabilities, but unlocking them requires thinking like an architect — designing the information environment, not just issuing commands. CLAUDE.md is your blueprint. Context is your resource. Manage both well and you're working at a different level entirely.

Wrapping Up

If CLAUDE.md feels like it's being ignored, try cutting it in half first. The fear of leaving things out is less damaging than Claude's attention getting spread too thin.