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

​
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.

Writing a good Claude.md

Comprehensive guide by Humanlayer on creating effective CLAUDE.md files
Keep your CLAUDE.md under 150 lines for reliable adherence. Focus on critical patterns, gotchas, and non-obvious conventions.

​
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:
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.
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
FileLoaded at Launch?Reason
/mymonorepo/CLAUDE.md✅ YesIt’s your current working directory
/mymonorepo/frontend/CLAUDE.md❌ NoLoaded only when you read/edit files in frontend/
/mymonorepo/backend/CLAUDE.md❌ NoLoaded only when you read/edit files in backend/
/mymonorepo/api/CLAUDE.md❌ NoLoaded 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
FileLoaded at Launch?Reason
/mymonorepo/CLAUDE.md✅ YesIt’s an ancestor directory
/mymonorepo/frontend/CLAUDE.md✅ YesIt’s your current working directory
/mymonorepo/backend/CLAUDE.md❌ NoDifferent branch of the directory tree
/mymonorepo/api/CLAUDE.md❌ NoDifferent branch of the directory tree

​
Key Takeaways

Ancestors Always Load

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.

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.

Siblings Never Load

If you’re working in frontend/, you won’t get backend/CLAUDE.md or api/CLAUDE.md loaded into context.

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

1

Shared instructions propagate down

Root-level CLAUDE.md contains repository-wide conventions, coding standards, and common patterns that apply everywhere.
2

Component-specific instructions stay isolated

Frontend developers don’t need backend-specific instructions cluttering their context, and vice versa.
3

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

Coding standards, commit message formats, PR templates, and other repository-wide guidelines.
Framework-specific patterns, component architecture, testing conventions unique to that component.
Add it to .gitignore for instructions that shouldn’t be shared with the team.
Keep CLAUDE.md files focused and concise. Long, unfocused memory files can dilute Claude’s attention to critical patterns.

​
Sources

Memory Documentation

Official Claude Code memory documentation

Boris Cherny on X

Clarification on CLAUDE.md loading behavior

Writing a good Claude.md

Humanlayer’s comprehensive guide

Build docs developers (and LLMs) love

Get started for freeTalk to us