CLAUDE.md Grew to 2,000 Lines and Nobody Read It — Here's How to Fix It

A 2,000-line CLAUDE.md isn’t a knowledge base. It’s a liability.

The file exists to give Claude context about your project before every session. But Claude Code processes its entire content as part of your context window. When it’s long enough, three things happen: context fills up faster, Claude starts treating the file as background noise rather than active instructions, and — worst of all — you stop reading it yourself when something needs to change.

Here’s how to fix it without losing the information.

Why Long CLAUDE.md Files Stop Working

Claude Code reads CLAUDE.md files at the start of every session and before every significant tool call. The content is injected directly into the context window as system-level instructions.

That’s the mechanism. Here’s the failure mode.

When a CLAUDE.md is 2,000 lines, it’s consuming a significant portion of available context before any actual work starts. On a 200,000-token model with a complex codebase, that’s manageable. On a model with more constrained context, or a session that’s already deep into a long task, the file starts competing with actual work for space.

More practically: long files grow because people keep adding to them without removing anything. After six months, you have:

• Current coding conventions (useful)
• Conventions from a framework you migrated away from (stale)
• A detailed explanation of a bug that was fixed in March (irrelevant)
• Three conflicting rules about how to handle API errors because three people edited the file without reading it first

The file becomes untrustworthy. Claude reads it. Engineers don’t. Nobody’s sure what’s current.

The Hierarchical System You’re Probably Not Using

Claude Code supports CLAUDE.md files in subdirectories, not just the project root. This is the key feature that makes large codebases manageable.

The lookup rules:

1. Claude reads the root CLAUDE.md first
2. When Claude navigates to a subdirectory (by reading files, running tools, or being directed there), it reads that directory’s CLAUDE.md automatically
3. Child CLAUDE.md files supplement the root — they don’t replace it

This means a monorepo with a frontend and a backend can have:

project-root/
├── CLAUDE.md                    # Global: conventions, architecture overview, cross-cutting rules
├── packages/
│   ├── frontend/
│   │   └── CLAUDE.md            # React conventions, component patterns, CSS approach
│   └── backend/
│       └── CLAUDE.md            # API design, database patterns, auth flow
└── scripts/
    └── CLAUDE.md                # Build scripts, CI helpers, deployment steps

When Claude is working in packages/frontend/, it has both the global context and the frontend-specific context. When it’s in packages/backend/, it has global context and backend-specific context. It never loads context it doesn’t need.

For most projects, this alone cuts the effective root CLAUDE.md size by 60-70%. The root stays focused on what’s always relevant. Everything else goes where it belongs.

Import Directives: Splitting Without Fragmenting

Claude Code also supports explicit imports in CLAUDE.md. You can reference another file, and Claude will include its content as part of the instructions:

# Project Context

See our architecture overview for background on how services connect.

@./docs/architecture.md
@./docs/api-conventions.md
@./scripts/CLAUDE.md

The @./path/to/file syntax tells Claude Code to include the referenced file’s content inline. It works with any text file, not just CLAUDE.md files.

This is useful for two patterns:

Pattern 1: Keeping docs in sync with CLAUDE.md

Your architecture doc lives in docs/architecture.md because developers need it too. Your CLAUDE.md imports it instead of duplicating it. When the architecture changes, you update one file and both uses stay current.

Pattern 2: Topic-based splits for flat repositories

Not every project is a monorepo with clean subdirectory boundaries. A single-package library might have no obvious place to put sub-CLAUDE.md files. Imports let you split by topic:

project-root/
├── CLAUDE.md                    # Imports everything else; minimal own content
├── .claude/
│   ├── conventions.md           # Coding standards, naming, formatting
│   ├── testing.md               # Test patterns, fixtures, mocking approach
│   ├── deployment.md            # How to build, what the pipeline does
│   └── known-issues.md          # Current bugs, workarounds, gotchas

The root CLAUDE.md becomes an index:

# Project: Acme API

A REST API serving the Acme platform. Node.js + Express + PostgreSQL.

@./.claude/conventions.md
@./.claude/testing.md
@./.claude/deployment.md
@./.claude/known-issues.md

Each imported file can be updated independently. The root stays stable.

What Goes in Root vs. What Goes in Sub-Files

The decision rule is simple: root for universal, sub-files for contextual.

Root CLAUDE.md: always-relevant context

Root content should be true and useful in every Claude Code session, regardless of what Claude is working on:

• Project name, purpose, tech stack (the 30-second overview)
• Repository structure (where things live, what the top-level directories mean)
• How to run the project locally (the commands that always work)
• Absolute rules that apply everywhere (never commit secrets, always write tests for public APIs, etc.)
• Links or imports to more specific context

Target length: under 200 lines. If you can’t get there, you’re including contextual content in the root.

Sub-files: context-specific knowledge

Everything that only matters when working in a specific part of the codebase:

<!-- packages/frontend/CLAUDE.md -->
# Frontend Package

## Stack
React 18 + TypeScript + Tailwind CSS. Vite for bundling.

## Component conventions
- Components live in src/components/
- One component per file
- Props interfaces are defined in the same file, above the component
- No default exports — use named exports only

## State management
We use Zustand for global state. Local state with useState is fine for
component-level concerns. Don't add Redux — we migrated away from it.

## Testing
Vitest + Testing Library. Tests live next to the component (Component.test.tsx).
Snapshot tests are banned — they fail on every style change and provide no signal.

## What not to do
- Don't import from ../../packages/backend — the packages are separate deployments
- Don't use CSS modules (legacy) — Tailwind only for new code

This is extremely useful when Claude is working in the frontend. It’s irrelevant noise when Claude is in the backend or scripts directory. Putting it in a subdirectory CLAUDE.md means it only loads when needed.

Diagnosing an Existing Bloated CLAUDE.md

Before splitting, audit what’s in there. A quick categorization:

Evergreen (keep in root):

• Architecture overview and core principles
• How to run the project
• Team conventions that apply everywhere

Contextual (move to sub-files):

• Package-specific patterns and conventions
• How a specific service works
• Deployment-specific instructions
• Test infrastructure details

Stale (delete):

• References to libraries you no longer use
• Notes about completed migrations
• Bug reports for issues that are closed
• Instructions for setup steps that have been automated

Redundant (delete):

• Things that are obvious from the code itself
• Rules that the linter enforces (if ESLint catches it, Claude doesn’t need to know about it separately)
• Documentation that already exists in a README or doc site

In practice, most bloated CLAUDE.md files are about 30% stale, 30% redundant, and 40% legitimately useful content in the wrong place.

A Before/After Example

Before — a 1,400-line root CLAUDE.md with everything:

CLAUDE.md (1,400 lines)
├── Project overview (30 lines)
├── Global conventions (50 lines)
├── Frontend: React patterns (200 lines)
├── Frontend: CSS approach (100 lines)
├── Frontend: Test setup (150 lines)
├── Backend: API design (200 lines)
├── Backend: Database patterns (150 lines)
├── Backend: Auth flow (100 lines)
├── CI/CD pipeline (120 lines)
├── Deployment steps (150 lines)
└── Misc notes and workarounds (150 lines)

After — the same information, reorganized:

CLAUDE.md (80 lines)
├── Project overview (30 lines)
├── Global conventions (30 lines)
└── Imports: frontend.md, backend.md, deployment.md

.claude/frontend.md (450 lines)
├── React patterns
├── CSS approach
└── Test setup

.claude/backend.md (450 lines)
├── API design
├── Database patterns
└── Auth flow

.claude/deployment.md (270 lines)
├── CI/CD pipeline
└── Deployment steps
└── Known issues (moved from misc)

The root shrank from 1,400 lines to 80. Every session starts with 80 lines of context. When Claude works in the frontend, it gets 80 + 450. When it works across both, it gets everything — but only because the task requires it.

Managing CLAUDE.md in Teams

The same problem that bloats individual CLAUDE.md files hits teams harder: everyone adds, nobody removes, nobody audits.

A few practices that help:

Assign ownership of sub-files. The frontend team owns packages/frontend/CLAUDE.md. If something in there is wrong, it’s their responsibility. Diffuse ownership of a single root file means nobody owns it.

Review CLAUDE.md changes in PRs the same way you review code. A PR that adds 50 lines to CLAUDE.md without removing anything should get the same scrutiny as a PR that adds 50 lines of code without explaining why.

Set a size budget. Root file stays under 200 lines. If a PR would push it over, something has to come out. The budget is a forcing function that prevents gradual bloat.

Quarterly audits. Once per quarter, go through each file and delete anything that hasn’t been touched or referenced in 90 days. Stale rules are worse than no rules — they mislead Claude about the current state of the codebase.

For details on the .claude/settings.json side of team configuration — the permission rules, the allowlist, the gitignore setup — see Claude Code settings.json in Teams: How to Prevent Conflicts and Share Config Safely.

What the Official Docs Don’t Say Clearly

The Claude Code documentation describes the hierarchical system accurately but doesn’t tell you when sub-directory files get loaded. Here’s the precise behavior:

• ~/.claude/CLAUDE.md — your global personal file, loaded every session
• {project-root}/CLAUDE.md — loaded at session start
• {project-root}/packages/foo/CLAUDE.md — loaded when Claude operates in that directory

“Operates in that directory” means: when Claude reads a file in that directory, edits a file in that directory, or runs a Bash command from that directory. It doesn’t mean “when you tell Claude to work on the frontend” in abstract terms — the file loads when Claude actually navigates there via tools.

This matters because it means the hierarchical system is active-context sensitive, not task-description sensitive. If you describe a frontend task but Claude’s first action is reading a root config file, the frontend CLAUDE.md won’t load until Claude actually touches a frontend file. Plan your sub-file boundaries around where files live, not around conceptual task categories.

Quick Wins if You’re Overwhelmed

If your CLAUDE.md is 2,000 lines and you don’t have time for a full reorganization today:

1. Delete the stale content first. Identify anything that references a library, pattern, or architecture that’s been replaced. Delete it. You’ll be at 1,400 lines and Claude’s instructions are now accurate.

2. Move the “how to run” section to README.md and import it. Every project has this section. It usually lives in both places already. Pick one canonical location and import it.

3. Create a known-issues.md and move the workarounds there. Workarounds accumulate and get stale. Isolating them makes them easier to audit and prune.

Those three steps take an hour and probably cut your file by 40%. The full hierarchy restructure can happen in a dedicated session when you have the time.

A CLAUDE.md that Claude actually follows is more useful than a comprehensive one that Claude treats as boilerplate. Shorter, accurate, and hierarchically organized beats long and complete every time.