Keep CLAUDE.md Under 200 Lines: Use @import to Modularize Project Context

Every session loads your entire CLAUDE.md before any tool call — one bloated file silently inflates costs; split it with @import and let Claude focus on what each task actually needs.

Every Claude Code session injects your full CLAUDE.md into the context window before anything else runs. A 2,000-line CLAUDE.md that covers architecture, testing conventions, API standards, do-not-touch rules, and onboarding notes costs you those tokens on every prompt — even when you're just fixing a typo.

Claude Code's @ import syntax solves this cleanly:

# CLAUDE.md — keep this under ~200 lines

@.claude/architecture.md
@.claude/testing-conventions.md
@.claude/api-standards.md
@.claude/do-not-touch.md

## Quick reference
- Entry point: src/main.ts
- Config: ./config/
- Run tests: pnpm test
- Lint: pnpm lint

Each @path is expanded and loaded at session start, recursively (up to 4 hops), so architecture.md can itself import @.claude/modules/auth-patterns.md for deeper topics. Claude sees the full expanded content — the split is invisible to it.

Three patterns that work well

1. Split by concern

.claude/
├── architecture.md    # system topology, critical service invariants
├── testing.md         # framework, fixtures, mock strategy
├── api-standards.md   # REST conventions, error shapes, auth contracts
└── do-not-touch.md    # protected files, manual-only workflows, migrations

Keep each file focused on one concern. When a file grows past ~150 lines, split it further. Files under .claude/ are committed alongside code so the whole team benefits.

2. User-level vs project-level memory

Claude Code loads context from multiple locations, in priority order:

• ~/.claude/CLAUDE.md — your personal style preferences, shortcuts, editor setup (not committed; follows you everywhere)
• CLAUDE.md in the repo root (or .claude/CLAUDE.md) — team-wide project rules (committed)
• CLAUDE.md in any subdirectory — scoped to that subtree, useful in monorepos

A clean split: ~/.claude/CLAUDE.md holds your personal preferences; the project CLAUDE.md holds only what the whole team needs to agree on. Avoid duplicating rules across both — conflicts silently prefer the project file.

3. Audit with /doctor and /memory

Claude Code v2.1.206+ includes a CLAUDE.md size check in /doctor. Run it when something feels slow or context-heavy — it flags oversized CLAUDE.md files and suggests trimming. The /memory command shows everything Claude has loaded for the current session, including all imported files, so you can verify the import chain resolved correctly.

A CLAUDE.md that stays lean keeps every session snappier and keeps token costs predictable. The @import split takes 10 minutes to set up and pays off on every subsequent interaction.

Sources: How Claude remembers your project — Claude Code Docs · CLAUDE.md Complete Guide — SkillsPlayground · Five Ways to Give Claude Code the Right Context — wmedia.es