Context Management

Key Files

Golden Rules

Quick Commands

claude /init

mkdir -p .claude/rules
cat > .claude/rules/testing.md <<'EOF'
---
paths: ["tests/**", "src/**/*.test.*"]
---
# Testing Rules
- Use pytest for all tests
- Fixtures go in conftest.py
EOF

# In Claude Code, ask:
"Show me your system prompt"
"What instructions do you have?"

wc -l CLAUDE.md .claude/rules/*.md
# Target: <200 root, <100 per rule

Token Economics

Every line of your CLAUDE.md is reprocessed with every single message in a conversation. A 500-line config file consumed at the start of each turn is not free -- it costs real tokens and real attention.

Current context window sizes shape what is possible:

Even with a 1M-token window, the practical budget for instructions is the same. Larger windows do not mean you should write longer config files. The model's attention degrades with length regardless of capacity.

The Attention Problem

Large language models do not read config files the way humans read manuals. There is no "careful sequential reading." Instead, instructions compete for attention weight. When your CLAUDE.md is 500 lines, important rules get lost in the noise -- the model gives each line roughly equal weight, and critical instructions become needles in a haystack.

A lean 50-line CLAUDE.md consistently outperforms a 500-line one. The shorter file has higher signal density -- every line matters, so the model pays attention to every line.

Quality vs. Quantity

Think of your context configuration like a resume, not an autobiography. The best resumes are one page. The best CLAUDE.md files are under 200 lines. They include only what the agent cannot infer from the code itself.

• Good: "Run pnpm test before committing" (agent cannot guess your package manager)
• Good: "Use snake_case for Python variables" (only if your codebase mixes styles)
• Bad: "Write clean, maintainable code" (the agent already does this)
• Bad: "Use descriptive variable names" (standard practice, no need to state)
• Bad: "Follow PEP 8" (Claude already knows PEP 8)

Context Budget

Everything competes for the same context window. Here is a rough breakdown of what fills it during a typical Claude Code session:

The "Conversation + tool use" segment grows with every message. The more tokens you consume with static config, the fewer you have for actual work. Bloated config means shorter effective conversations before the context window fills up.

How Discovery Works

Claude Code reads CLAUDE.md files recursively up the directory tree from your current working directory to the filesystem root. This means a monorepo can have layered config:

/
  CLAUDE.md                  ← loaded (ancestor)
  mycompany/
    CLAUDE.md                ← loaded (ancestor)
    myproject/
      CLAUDE.md              ← loaded (project root = cwd)
      .claude/
        CLAUDE.md            ← loaded (alternate location)
        rules/
          testing.md         ← loaded (project rule)
          deployment.md      ← loaded (project rule)
      frontend/
        CLAUDE.md            ← loaded on demand (child)
      backend/
        CLAUDE.md            ← loaded on demand (child)

Ancestor directory files (above cwd) are loaded in full at launch. Child directory files (below cwd) are loaded on demand when Claude reads files in those subtrees. This means your frontend/CLAUDE.md only takes effect when Claude is actually working in that directory.

Priority Order

When instructions conflict, higher specificity wins. The full priority chain from lowest to highest:

In practice, this means your CLAUDE.local.md can override team conventions for your personal workflow, and Claude's own learned memory takes highest priority since it reflects the most recent corrections.

The 200-Line Limit

There is no hard character limit on CLAUDE.md, but 200 lines is the practical ceiling for your root config. Beyond that, signal degrades. Here is what belongs in root and what does not:

@imports

CLAUDE.md supports an @import syntax to pull in content from other files using relative paths. This keeps your root file lean while referencing detailed docs:

# CLAUDE.md

## Build
Run `pnpm build` to compile. Run `pnpm test` to test.

## Architecture
@docs/architecture.md

## API Conventions
@docs/api-conventions.md

## Style
- Use kebab-case for files
- Components in PascalCase
- See .claude/rules/ for language-specific rules

Imports resolve relative paths from the file containing the @ directive. There is a maximum depth of 5 hops to prevent circular references. Each imported file counts against your context budget, so keep them focused.

Modular Rules with YAML Frontmatter

Files in .claude/rules/ can include YAML frontmatter with a paths field. This scopes the rule so it only activates when Claude is working with matching files:

# .claude/rules/frontend-testing.md
---
paths: ["src/components/**", "src/hooks/**", "**/*.test.tsx"]
---
# Frontend Testing Rules

- Use React Testing Library, never Enzyme
- Test user behavior, not implementation details
- Mock API calls with msw
- Every component needs at least one render test

# .claude/rules/database.md
---
paths: ["src/db/**", "migrations/**", "*.sql"]
---
# Database Rules

- All migrations must be reversible
- Use parameterized queries, never string interpolation
- Index any column used in WHERE clauses

Path-scoped rules load only when relevant files are being worked on, which keeps the effective context lean even if you have dozens of rule files.

Bootstrapping with /init

The /init command in Claude Code analyzes your repository and generates a starter CLAUDE.md. It inspects your package manager, test runner, directory structure, and existing configuration to produce a focused initial config.

# In Claude Code, run:
/init

# Claude will:
# 1. Scan your repo structure
# 2. Detect build tools, test frameworks, linters
# 3. Generate a ~30-50 line CLAUDE.md
# 4. Ask you to review and customize

Example: Well-Structured CLAUDE.md

Here is what a clean, effective root config looks like for a real project:

# CLAUDE.md

## Build & Test
- `pnpm install` -- install deps
- `pnpm dev` -- start dev server (port 3000)
- `pnpm test` -- run vitest (no watch mode in CI)
- `pnpm lint` -- eslint + prettier check

## Stack
Next.js 14 (App Router), TypeScript strict, Tailwind, Prisma + Postgres

## Structure
src/app/          -- routes (App Router)
src/components/   -- shared React components
src/lib/          -- utilities and helpers
src/db/           -- Prisma schema and queries
tests/            -- integration tests (Playwright)

## Conventions
- File names: kebab-case
- Components: PascalCase, one per file
- Server actions in `actions.ts` files adjacent to routes
- Prefer server components; add "use client" only when needed

## Gotchas
- Auth middleware in `src/middleware.ts` -- do not rename
- `NEXT_PUBLIC_` prefix required for client env vars
- Prisma generates types on `pnpm install` -- re-run after schema changes

That is roughly 25 lines. Everything Claude needs, nothing Claude can figure out on its own. No tutorials, no generic advice, no explaining what Next.js is.

The Recursive Reading Model

Claude Code reads CLAUDE.md files recursively up the directory tree from your current working directory all the way to /. Files closer to where you are working take precedence over files higher up. Child-directory CLAUDE.md files are loaded lazily -- only when Claude reads files inside those subtrees.

Here is the loading model in practice. Suppose you launch Claude Code inside myproject/src/api/:

# Loaded at launch (ancestors of cwd):
/myproject/CLAUDE.md             # project-wide rules
/myproject/src/CLAUDE.md         # source-level conventions
/myproject/src/api/CLAUDE.md     # API-specific patterns (cwd)

# Loaded on demand (when Claude explores these directories):
/myproject/tests/CLAUDE.md       # only if Claude reads test files
/myproject/frontend/CLAUDE.md    # only if Claude reads frontend files

This means you get zero-cost specificity. You can scatter dozens of CLAUDE.md files throughout your repo and they will not bloat context until Claude actually needs them. The lazy loading is what makes this system scalable.

Full-Stack Monorepo Example

Here is what a well-structured monorepo looks like with full context layering. Every CLAUDE.md file has a specific scope and purpose:

myproject/
├── CLAUDE.md                    # Project-wide: git workflow, CI, naming
├── .claude/
│   ├── CLAUDE.md               # Alternative location (same as root)
│   └── rules/
│       ├── code-style.md       # Unconditional: applies everywhere
│       ├── security.md         # Unconditional: auth patterns
│       └── api-endpoints.md    # Path-scoped (see frontmatter below)
│           # ---
│           # paths:
│           #   - "src/api/**/*.ts"
│           # ---
├── CLAUDE.local.md              # Personal: my sandbox URLs, test data
│
├── frontend/
│   ├── CLAUDE.md               # React patterns, component conventions
│   ├── src/
│   │   └── components/
│   │       └── CLAUDE.md       # Component naming, prop patterns
│   └── tests/
│       └── CLAUDE.md           # Frontend test conventions (vitest)
│
├── backend/
│   ├── CLAUDE.md               # Express patterns, middleware conventions
│   ├── src/
│   │   ├── routes/
│   │   │   └── CLAUDE.md       # Route naming, validation patterns
│   │   └── models/
│   │       └── CLAUDE.md       # Schema conventions, migration rules
│   └── tests/
│       └── CLAUDE.md           # Backend test conventions (jest)
│
└── shared/
    └── CLAUDE.md               # Shared types, utility conventions

Notice the pattern: the root file is project-wide, each top-level directory owns its domain, and deeply nested files handle specialized concerns. Claude only ever loads what it needs.

Example Root CLAUDE.md

The root file should be short, focused, and universally applicable. If an instruction does not apply to every file in the repo, it does not belong here.

# MyProject

## Build & Test
- `pnpm install` -- install all workspaces
- `pnpm build` -- build all packages
- `pnpm test` -- run all tests
- `pnpm lint` -- eslint + prettier check

## Git Workflow
- Branch from main, PR required for merge
- Commit messages: conventional commits (feat:, fix:, chore:)
- All PRs need passing CI before merge

## Architecture
- Monorepo: frontend/ (React), backend/ (Express), shared/ (types)
- Frontend and backend import from shared/ -- never cross-import
- See subdirectory CLAUDE.md files for module-specific conventions

That is it. Twenty lines. Build commands, git workflow, and the one architectural constraint that matters everywhere (no cross-imports). Everything else lives in subdirectory files or .claude/rules/.

Example Subdirectory CLAUDE.md

Subdirectory files are scoped to their module. They can assume the parent context is already loaded and focus on what is different or specific to their directory.

# Backend (Express + TypeScript)

## Patterns
- All routes in src/routes/, one file per resource
- Middleware chain: auth -> validate -> handler -> error
- Database queries in src/models/, never in route handlers

## Testing
- Jest with supertest for API endpoints
- Test files mirror src/ structure in tests/
- Mock external services, never hit real APIs in tests

# React Components

## Naming
- PascalCase for component files and exports
- Props interface: ComponentNameProps
- One component per file, co-locate styles

## Patterns
- Prefer server components; add "use client" only when needed
- Custom hooks in adjacent hooks/ directory
- Barrel exports via index.ts per feature folder

Each file is lean -- 10-15 lines of highly specific instructions. Claude only loads these when it enters the relevant directory, so they are essentially free context until needed.

The .claude/rules/ System

For cross-cutting concerns that do not map cleanly to a single directory, use .claude/rules/. Each file in this directory is a modular rule that can be either unconditional (applies always) or path-scoped (applies only to matching files).

Unconditional rules have no paths: frontmatter and apply everywhere:

# Code Style
- Use 2-space indentation for TypeScript, 4-space for Python
- Prefer const over let; never use var
- No default exports except for pages and layouts
- Import order: stdlib -> external -> internal -> relative

Path-scoped rules include YAML frontmatter with paths: globs. They only activate when Claude works with files matching those patterns:

---
paths:
  - "src/api/**/*.ts"
  - "src/routes/**/*.ts"
---
# API Development Rules

- All endpoints must validate input with zod schemas
- Return standard error format: { error: string, code: number }
- Include OpenAPI JSDoc comments on all public endpoints
- Rate limiting middleware required on all public routes
- Use async/await, never raw Promise chains

Path scoping supports glob patterns, brace expansion (*.{ts,tsx}), and recursive matching (**). You can organize rules into subdirectories within .claude/rules/ -- they are discovered recursively.

Symlinks and Sharing

If you maintain multiple projects with shared conventions, you can use symlinks in .claude/rules/ to point to a central rule library:

# Central rule library (e.g., in a shared-configs repo)
~/shared-rules/
├── typescript-style.md
├── security-patterns.md
└── testing-conventions.md

# Symlink into each project
cd myproject/.claude/rules/
ln -s ~/shared-rules/typescript-style.md .
ln -s ~/shared-rules/security-patterns.md .

# Or symlink the whole directory
ln -s ~/shared-rules/ .claude/rules/shared/

This keeps your team's conventions in one canonical location while each project inherits them through symlinks. Changes to the source propagate instantly.

The @import System

Instead of copying content into CLAUDE.md, use @import to reference existing documentation. This is ideal when you already have well-maintained docs that Claude should follow:

# CLAUDE.md

## Build
Run `pnpm build` to compile all packages.

## Architecture
@docs/architecture.md

## API Reference
@docs/api-conventions.md

## Database
@docs/database-schema.md

Key rules for imports:

• Paths are resolved relative to the file containing the @ directive
• Maximum depth of 5 hops to prevent circular references (imports can import, up to 5 levels deep)
• Imported content counts against your context budget, so keep referenced files focused
• Use imports to avoid duplicating docs you already maintain -- do not create files just for importing

Comparison Matrix

The AI coding agent space has fragmented into multiple config file formats. This table compares every major tool as of early 2026:

Claude Code

Codex CLI (OpenAI)

Gemini CLI (Google)

Cursor

Windsurf

Aider

GitHub Copilot

Cross-Tool Compatibility

Most teams use multiple AI tools. Here is which tools can read which other tools' config files natively:

Multi-Tool Strategies

If your team uses multiple AI coding agents, you need a strategy for sharing context without maintaining duplicate files. Here are the proven approaches:

# Maintain one source of truth
ln -s CLAUDE.md AGENTS.md
ln -s CLAUDE.md GEMINI.md

# All three tools read the same file

# CLAUDE.md
@docs/shared-context.md
# Claude-specific rules below...

# .aider.conf.yml
read: [docs/shared-context.md]

# .gemini/settings.json
{
  "context": {
    "fileName": ["CLAUDE.md"]
  }
}
# Gemini inherits Claude's config

# AGENTS.md is the open standard
# Many tools are adding support
# Use it as the shared base,
# add tool-specific files as needed

The Problem

Loading every instruction at startup is wasteful. A frontend developer editing React components does not need backend database migration rules in context. A developer writing tests does not need deployment conventions cluttering the prompt.

The solution is progressive disclosure: context that arrives precisely when needed, not before. Claude Code offers a full stack of mechanisms for this, from static file-based rules to dynamic runtime hooks.

The Solution Stack

Context injection mechanisms, ordered from static (always available, file-based) to dynamic (runtime, computed):

1. Path-Scoped Rules

The simplest form of progressive disclosure. Rules in .claude/rules/ with paths: frontmatter only activate when Claude works with matching files. Zero overhead when irrelevant.

# .claude/rules/react-components.md
---
paths:
  - "src/components/**/*.tsx"
  - "src/hooks/**/*.ts"
---
# React Component Rules
- Server components by default; "use client" only when needed
- Props interface named ComponentNameProps
- Co-locate styles, tests, and stories with components

These rules are invisible to Claude until it opens a file matching the glob pattern. You can have 50 path-scoped rules with zero startup cost.

2. Subdirectory CLAUDE.md

Lazy-loaded when Claude explores that area of the codebase. Perfect for module-level documentation that is too detailed for root config but too important to omit entirely.

# backend/src/models/CLAUDE.md
# Only loaded when Claude reads files in backend/src/models/

# Database Models
- Prisma schema in prisma/schema.prisma
- Every model needs createdAt and updatedAt timestamps
- Soft deletes: use deletedAt field, never hard delete
- Migration naming: YYYYMMDD_description.sql

3. @imports

Referenced documentation pulled in on demand. Use this when you already maintain comprehensive docs and want Claude to follow them without duplicating content.

# CLAUDE.md
## API Design
@docs/api-style-guide.md

## Database Conventions
@docs/database-patterns.md

The imported files are resolved and injected when CLAUDE.md is loaded. Keep imported files focused -- a 500-line API doc pulls its entire weight into context.

4. Skills

Reusable prompt templates that inject task-specific context on demand. Skills are Markdown files in .claude/skills/ that can preprocess shell commands using ! backtick syntax to pull in live data:

# .claude/skills/pr-summary.md
---
name: pr-summary
context: fork
agent: Explore
---
## PR Context
- Diff: !`gh pr diff`
- Comments: !`gh pr view --comments`

## Task
Summarize this PR: what changed, why, and any risks.

Skills are invoked explicitly (via slash commands or the skills menu), so they carry no cost until triggered. The ! backtick syntax runs shell commands at invocation time and injects the output, giving Claude live context about the current state of things.

5. Hooks

Deterministic lifecycle automation that runs at specific points during a Claude Code session. Unlike instructions (which are suggestions), hooks are enforced -- they run every time, regardless of what the model decides.

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "npx eslint --fix $CLAUDE_FILE_PATH"
      }]
    }]
  }
}

Available hook points in the lifecycle:

The matcher field uses regex to filter which tools trigger the hook. "Edit|Write" fires on file edits. "Bash" fires on shell commands. Omitting the matcher fires on every tool use.

6. Subagents

Isolated context windows for delegated tasks. Subagents run in a forked context with a restricted tool set, which means they do not pollute the main conversation's context window.

# .claude/skills/security-reviewer.md
---
name: security-reviewer
tools: Read, Grep, Glob
model: haiku
---
Review the specified files for OWASP Top 10 vulnerabilities.
Focus on: injection, broken auth, sensitive data exposure,
XXE, broken access control, security misconfiguration.

Report findings as a numbered list with severity (High/Medium/Low)
and the specific file + line number.

Subagents are ideal for specialized tasks that need deep focus: security review, documentation generation, test writing. They can use a smaller model (like Haiku) for cost efficiency, and their results are summarized back to the main conversation.

Decision Guide

The general rule: start static, go dynamic only when you need to. Most projects only need CLAUDE.md + a few path-scoped rules. Add skills and hooks when your workflow demands them. Subagents are for advanced use cases with clear delegation boundaries.

Auto Memory Location

~/.claude/projects/<project>/memory/
├── MEMORY.md          # Index -- first 200 lines loaded every session
├── debugging.md       # Detailed notes (loaded on demand)
├── api-conventions.md # API decisions (loaded on demand)
└── patterns.md        # Code patterns discovered

• <project> path derived from git repo root — all subdirs share one memory dir
• First 200 lines of MEMORY.md injected into system prompt at session start
• Topic files are NOT loaded at startup — Claude reads them on demand
• Claude reads AND writes memory files during sessions (live updates)
• Git worktrees get separate memory directories

What Claude Saves Automatically

Managing Memory

/memory

"remember that we use pnpm, not npm"

CLAUDE_CODE_DISABLE_AUTO_MEMORY=0

CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

MEMORY.md Best Practices

Session Lifecycle

The Core Principle

CLAUDE.md is for the LLM agent. README.md is for human developers. They have different audiences, different formats, different goals.

Side-by-Side Comparison

## Authentication
Our authentication system uses JWT tokens with refresh
token rotation. We chose this approach in Q3 2024 after
evaluating OAuth2, SAML, and session-based auth. The
decision was driven by our microservices architecture...

## Auth
- JWT + refresh token rotation
- Auth middleware: src/middleware/auth.ts
- Token refresh endpoint: POST /api/auth/refresh
- Never store tokens in localStorage -- use httpOnly cookies

When to Link vs Inline

The EMPHASIS Trick

# Normal instruction
- Use 2-space indentation in TypeScript files

# High-priority instruction
IMPORTANT: Never commit .env files or expose API keys in code.
YOU MUST run `pnpm lint` before committing any changes.

1. The Monolith

2. The Museum

3. The Duplicator

4. The Encyclopedia

5. The Accumulator

6. The Mirror

7. The Personality

8. The Task Leak

Context Rot Audit

Common Symptoms & Fixes

Debugging Commands

/memory

/context

wc -l CLAUDE.md
# Target: under 200 lines

find . -name "CLAUDE.md" | head -20
find .claude/rules -name "*.md" 2>/dev/null

The Nuclear Option

When context is thoroughly confused and Claude keeps making the same mistakes despite correct config:

The Context Engineering Mindset