Claude Code Context Management: CLAUDE.md Design Patterns

Claude Code context management comes down to one principle: keep CLAUDE.md short and specific, split rules by directory, and actively manage what enters the context window. The five CLAUDE.md design patterns in this article — Minimal, Sectioned, Task-Focused, Hierarchical, and Context Index — combined with Auto Memory, Hooks, and session splitting, will get Claude to actually follow your rules.

You wrote a detailed CLAUDE.md, only to watch Claude Code completely ignore it. "You didn't even read that, did you?" — it's one of the most common complaints in GitHub Discussions. The problem usually isn't Claude. It's how the CLAUDE.md is written.

This article covers the practical context management patterns that emerge from real-world Claude Code usage. By combining the right CLAUDE.md design patterns with .claudeignore and Plan mode, you can see a significant boost in productivity — here's exactly how.

Why Does the Context Window Fill Up So Fast?

As of March 2026, Claude Code supports up to 1 million tokens of context on Opus 4.6 and Sonnet 4.6 — a massive jump from the previous 200K limit. But even with 1M tokens, context management still matters. More context doesn't mean better output — it means more noise for Claude to sift through.

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, tool definitions, MCP servers, and generated code, and context fills up faster than you'd expect.

What happens when context gets bloated? Claude's attention gets diluted. Important rules compete with thousands of lines of irrelevant code. In practice, a focused 200K session often outperforms a sprawling 1M session because signal density is higher.

Rough token estimates (from experience):

• A typical CLAUDE.md: 2,000–5,000 tokens
• System prompt + tools: ~40,000 tokens
• One source file (500 lines): ~5,000 tokens
• A long conversation session: 50,000–200,000 tokens

Use the /context command to see exactly how your token budget is being spent. Claude Code also shows a context usage indicator at the bottom of the screen.

Context management is fundamentally a design problem: deciding what goes inside the window and what stays out — regardless of how large the window is.

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)

Turn the Task-Focused pattern into a reusable template. Keep a blank version with three sections — "Today's task," "Files to touch," and "Constraints" — and fill it in at session start. This one habit dramatically improves how well Claude stays on track.

# 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 makes Claude think through what it will do before writing a single line of code. Press Shift+Tab twice to activate Plan mode, or type /plan directly in the prompt (available since v2.1.0).

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.

# Press Shift+Tab twice (or type /plan), then give your instruction
> I want to migrate user auth from JWT to Supabase Auth. Plan only, don't implement yet.

Review the plan Claude produces. If it looks good, exit Plan mode with Shift+Tab and tell Claude to proceed with implementation.

How Do You Choose Between /compact and /clear?

As sessions grow longer, context bloat degrades response quality. Two 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.

Checking context usage — Use /context to see exactly how tokens are distributed across system prompt, tools, MCP servers, memory, and conversation. This is the single most useful diagnostic when Claude starts behaving oddly.

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

For a deep dive on long-session strategies, see Claude Code Memory Management: How to Keep Long Sessions Productive.

Auto Memory — Claude Now Takes Its Own Notes

Added in late February 2026, Auto Memory lets Claude Code automatically record important information during conversations. Files are saved to ~/.claude/projects/<project>/memory/, with MEMORY.md serving as the index.

How CLAUDE.md and Auto Memory divide responsibilities:

Practical examples:

• Tell Claude "don't use mocks in tests" and Auto Memory records it as feedback. It persists across sessions
• Project context that doesn't appear in code (deadlines, stakeholder requirements) gets recorded
• "This user is a senior TypeScript developer" — Claude adjusts explanation depth automatically

What still belongs in CLAUDE.md hasn't changed: rules, constraints, tech stack. But "feedback to Claude" and "project state" should live in Auto Memory. Mixing them bloats CLAUDE.md.

# Managing Auto Memory
> /memory          # View memory entries

Only the first 200 lines of MEMORY.md are injected into context, so you'll need to prune old entries as memories accumulate.

Hooks — Turn "Requests" Into "Enforcement"

Rules in CLAUDE.md are ultimately requests. Claude might forget them under context pressure. Hooks let you run shell scripts automatically in response to specific events — upgrading rules from "please do this" to "this will happen."

Basic Hook structure (settings.json):

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash /path/to/check-script.sh"
          }
        ]
      }
    ]
  }
}

Three Hook events that matter most in practice:

1. PreToolUse — Check before a tool runs

Run a linter before any file write, block writes to specific directories, etc.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash scripts/hooks/pre-write-check.sh $FILE_PATH"
          }
        ]
      }
    ]
  }
}

2. PostToolUse — Process after a tool runs

Auto-run tests after a commit, run a formatter after file changes, etc.

3. PreCompact — Save critical info before context compression

When auto-compaction compresses context, critical decisions can get summarized away. PreCompact lets you write key state to a file before that happens — a root-cause fix for "Claude forgot the requirements mid-session."

Claude Code currently supports over 20 hook events — including SessionStart, WorktreeCreate, InstructionsLoaded, and more. You don't need all of them. The three above cover the majority of real-world use cases.

Custom Commands — One-Command Shortcuts for Repeated Instructions

If you find yourself typing the same instructions every time, Custom Commands solve this. Place a Markdown file in .claude/commands/ and it becomes callable with /. Custom Commands have since been merged into "Skills" (.claude/skills/<name>/SKILL.md), but .claude/commands/ still works.

Example: Code review command

<!-- .claude/commands/review.md -->
Review the following file for:
- Type safety issues
- Missing error handling
- Gaps in test coverage

Target: $ARGUMENTS

Usage:

> /review src/auth/login.ts

Example: Pre-commit check

<!-- .claude/commands/pre-commit.md -->
Run the following in order:
1. `pnpm typecheck` for type checking
2. `pnpm test` for test execution
3. If issues found, fix them. If clean, run `git add` and `git commit`

When to use which:

• Custom Commands = explicitly invoked by you (/review)
• Hooks = triggered automatically by events (on file save)

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.

Session handoffs in the Auto Memory era: With Auto Memory enabled, Claude records important decisions automatically. However, Auto Memory only saves what Claude judges to be important. Project-specific handoff details ("next, work on this file") should still be written manually to session-handoff.md for reliability.

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.

How Should You Split CLAUDE.md in Monorepos?

As projects grow, putting all rules in a single CLAUDE.md becomes impractical. Claude Code reads .claude/rules/ directory and subdirectory CLAUDE.md files hierarchically.

Root CLAUDE.md (project-wide):

# Project-Wide Rules
- TypeScript strict mode required
- Tests use Vitest
- Commit messages follow Conventional Commits

.claude/rules/frontend.md (frontend-specific):

# Frontend Rules
- Prefer Server Components
- "use client" only when necessary
- Use Tailwind CSS v4 utility classes

packages/api/CLAUDE.md (API package-specific):

# API Rules
- Use Hono
- Validate responses with zod schemas
- Return errors in RFC 7807 format

This hierarchical structure follows three principles:

1. Root contains only shared rules — minimal rules that apply to all packages
2. .claude/rules/ splits by domain — frontend, backend, infrastructure
3. Subdirectory CLAUDE.md for local rules — loaded only when working in that directory

Claude Code automatically loads relevant CLAUDE.md files based on the working file path. When working in packages/api/, both the root CLAUDE.md and packages/api/CLAUDE.md are loaded.

Rule of thumb: If your CLAUDE.md total exceeds 200 lines, it's time to split. Root should only contain rules that apply regardless of which file you're editing.

Frequently Asked Questions

What's the difference between CLAUDE.md and .claude/rules/?

CLAUDE.md at the project root is loaded every session regardless of what file you're working on. Files in .claude/rules/ are also loaded automatically but are better suited for domain-specific rules (frontend, backend, etc.). Use root CLAUDE.md for universal rules and .claude/rules/ to split by domain. See the official memory documentation for details.

Does CLAUDE.md work with the 1M context window?

Yes, and it matters even more. With 1M tokens, Claude reads more files automatically, which means more noise competing with your CLAUDE.md rules. Keeping rules concise ensures they maintain high signal density regardless of window size.

How many lines should CLAUDE.md be?

Aim for 10–30 lines in the root CLAUDE.md. If you're over 200 lines total across all CLAUDE.md files, split them. Every line should pass the test: "Would removing this cause Claude to make a mistake?"

Can I use CLAUDE.md in a monorepo?

Absolutely. Place a minimal root CLAUDE.md with shared rules, use .claude/rules/ for domain-specific rules, and add package-level CLAUDE.md files (e.g., packages/api/CLAUDE.md). Claude loads all applicable files based on the working directory.

What should go in CLAUDE.md vs Auto Memory?

CLAUDE.md is for rules, constraints, and project structure that you write and maintain. Auto Memory is for preferences, feedback, and project state that Claude records itself. Don't put "always use this import style" in Auto Memory — that belongs in CLAUDE.md.

Does .claudeignore actually prevent Claude from reading files?

Partially. .claudeignore blocks automatic file discovery (search, indexing), which reduces token consumption. However, Claude can still read a file explicitly if you or a tool references it by path. For strict access control, use Hooks or settings.json deny permissions.

How often should I run /compact vs /clear?

Run /clear after each completed task — it's the most effective single habit. Use /compact when you're mid-task but context feels heavy. Check /context periodically to see actual usage numbers before deciding.

Can Hooks replace CLAUDE.md rules entirely?

No. Hooks enforce specific actions (block file writes, run linters), but they can't replace semantic guidance like "prefer pure functions" or "use Server Components by default." Use CLAUDE.md for intent and Hooks for enforcement.

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.

Related articles:

• Claude Code vs GitHub Copilot: 3-Month Real-World Verdict
• How to Fix "context window exceeded" in Claude Code
• How I Reduced Claude Code Token Consumption by 50%
• Claude Code Troubleshooting: Complete Guide
• Claude Code × TypeScript: Tips for Type-Safe Code Generation
• Claude Code Memory Management: Long Session Guide
• Claude Code Commands Cheatsheet