Skip to content

claude-memory.md

Latest commit

 

History

History
121 lines (78 loc) · 5.25 KB

claude-memory.md

File metadata and controls

121 lines (78 loc) · 5.25 KB

Claude Memory

Persistent context via CLAUDE.md files — how to write them and how they load in monorepos.

← Back to Claude Code Best Practice Claude

1. Writing a Good CLAUDE.md

A well-structured CLAUDE.md is the single most impactful way to improve Claude Code's output for your project. Humanlayer has an excellent guide covering what to include, how to structure it, and common pitfalls.

2. CLAUDE.md in Large Monorepos

When working with Claude Code in a monorepo, understanding how CLAUDE.md files are loaded into context is crucial for organizing your project instructions effectively.

CLAUDE.md loading in monorepos

The Two Loading Mechanisms

Claude Code uses two distinct mechanisms for loading CLAUDE.md files:

Ancestor Loading (UP the directory tree)

When you start Claude Code, it walks upward from your current working directory toward the filesystem root and loads every CLAUDE.md it finds along the way. These files are loaded immediately at startup.

Descendant Loading (DOWN the directory tree)

CLAUDE.md files in subdirectories below your current working directory are NOT loaded at launch. They are only included when Claude reads files in those subdirectories during your session. This is known as lazy loading.

Example Monorepo Structure

Consider a typical monorepo with separate directories for different components:

/mymonorepo/
├── CLAUDE.md          # Root-level instructions (shared across all components)
├── frontend/
│   └── CLAUDE.md      # Frontend-specific instructions
├── backend/
│   └── CLAUDE.md      # Backend-specific instructions
└── api/
    └── CLAUDE.md      # API-specific instructions

Scenario 1: Running Claude Code from the Root Directory

When you run Claude Code from /mymonorepo/:

cd /mymonorepo
claude
File Loaded at Launch? Reason
/mymonorepo/CLAUDE.md Yes It's your current working directory
/mymonorepo/frontend/CLAUDE.md No Loaded only when you read/edit files in frontend/
/mymonorepo/backend/CLAUDE.md No Loaded only when you read/edit files in backend/
/mymonorepo/api/CLAUDE.md No Loaded only when you read/edit files in api/

Scenario 2: Running Claude Code from a Component Directory

When you run Claude Code from /mymonorepo/frontend/:

cd /mymonorepo/frontend
claude
File Loaded at Launch? Reason
/mymonorepo/CLAUDE.md Yes It's an ancestor directory
/mymonorepo/frontend/CLAUDE.md Yes It's your current working directory
/mymonorepo/backend/CLAUDE.md No Different branch of the directory tree
/mymonorepo/api/CLAUDE.md No Different branch of the directory tree

Key Takeaways

  1. Ancestors always load at startup — Claude walks UP the directory tree and loads all CLAUDE.md files it finds. This ensures you always have access to root-level, repository-wide instructions.

  2. Descendants load lazily — Subdirectory CLAUDE.md files only load when you interact with files in those subdirectories. This prevents irrelevant context from bloating your session.

  3. Siblings never load — If you're working in frontend/, you won't get backend/CLAUDE.md or api/CLAUDE.md loaded into context.

  4. Global CLAUDE.md — You can also place a CLAUDE.md at ~/.claude/CLAUDE.md in your home folder, which applies to ALL Claude Code sessions regardless of project.

Why This Design Works for Monorepos

  • Shared instructions propagate down — Root-level CLAUDE.md contains repository-wide conventions, coding standards, and common patterns that apply everywhere.

  • Component-specific instructions stay isolated — Frontend developers don't need backend-specific instructions cluttering their context, and vice versa.

  • Context is optimized — By lazily loading descendant CLAUDE.md files, Claude Code avoids loading potentially hundreds of kilobytes of irrelevant instructions at startup.

Best Practices

  1. Put shared conventions in root CLAUDE.md — Coding standards, commit message formats, PR templates, and other repository-wide guidelines.

  2. Put component-specific instructions in component CLAUDE.md — Framework-specific patterns, component architecture, testing conventions unique to that component.

  3. Use CLAUDE.local.md for personal preferences — Add it to .gitignore for instructions that shouldn't be shared with the team.

Sources