CLAUDE.md Hierarchy
CLAUDE.md files exist at multiple levels: ~/.claude/CLAUDE.md (global, applies to all projects), project root CLAUDE.md (project-level), and subdirectory CLAUDE.md files (scoped to specific directories). When Claude Code loads, it reads all applicable CLAUDE.md files and merges their content.
The global CLAUDE.md is for personal preferences that apply everywhere. The project CLAUDE.md is for team-shared context. Subdirectory CLAUDE.md files are for specialized instructions that only apply when working in that part of the codebase.
What to Include
Effective CLAUDE.md files include: project architecture overview, coding standards and conventions, build/test/deploy commands, important file paths and their purposes, common pitfalls and how to avoid them, and technology-specific instructions.
Keep the content concise and actionable. Every line in CLAUDE.md consumes context tokens, so focus on information that directly affects Claude's behavior. Avoid general documentation that belongs in a README.
What to Avoid
Do not put sensitive information (API keys, passwords) in CLAUDE.md — it's committed to version control. Do not include verbose documentation or tutorials. Do not repeat information that Claude already knows (e.g., general TypeScript syntax). Do not include instructions that conflict with the project settings.
The goal is density: maximum useful context per token. If a CLAUDE.md file is longer than a few hundred lines, it likely contains content that should be moved to documentation files referenced via @-mentions instead.
Key Concept
CLAUDE.md Is Persistent System Context
CLAUDE.md files serve as persistent system context that survives across conversations. Unlike system prompts in API calls (which are set per-conversation), CLAUDE.md is always present. This makes it the right place for information that should consistently influence Claude's behavior: coding standards, project conventions, and architectural constraints.
Exam Traps
Putting secrets in CLAUDE.md
CLAUDE.md is version-controlled. Never include API keys, passwords, or other secrets. Use environment variables for sensitive configuration.
Writing verbose CLAUDE.md files
Every line consumes context tokens. Verbose files waste context window space and can push out actual conversation content. Keep CLAUDE.md concise and actionable.
Not knowing about the hierarchy
The exam may test whether you know that CLAUDE.md files can exist at global, project, and subdirectory levels, and how they merge.
Check Your Understanding
A project has a monorepo with a React frontend and a Python backend. The frontend team uses TypeScript strict mode and the backend team uses Python type hints. Where should coding standard instructions go?
Build Exercise
Write an Effective CLAUDE.md
What you'll learn
- Structure a CLAUDE.md for a real project
- Write concise, actionable instructions
- Use the CLAUDE.md hierarchy effectively
- Avoid common CLAUDE.md mistakes
Create a project-root CLAUDE.md with: project name, tech stack summary, build/test commands, and 3-5 key coding conventions.
WHY: The root CLAUDE.md establishes baseline context for the entire project.
YOU SHOULD SEE: A concise CLAUDE.md under 50 lines with actionable project context.
Create a subdirectory CLAUDE.md (e.g., in src/api/) with directory-specific context: API conventions, route patterns, and error handling standards.
WHY: Subdirectory CLAUDE.md files provide focused context relevant to specific parts of the codebase.
YOU SHOULD SEE: A focused CLAUDE.md with context specific to API development.
Create a global ~/.claude/CLAUDE.md with personal preferences: preferred formatting, editor settings, and communication style.
WHY: Global CLAUDE.md captures preferences that apply across all your projects.
YOU SHOULD SEE: A personal CLAUDE.md with preferences that don't belong in any single project.
Test the CLAUDE.md hierarchy by starting Claude Code and verifying it follows your instructions. Check that subdirectory context is loaded when working in that directory.
WHY: Testing validates that your CLAUDE.md files are being read and followed correctly.
YOU SHOULD SEE: Claude Code follows your conventions and references your project context.
Sources
- Claude Code: Memory— Anthropic Documentation
- Claude Code Overview— Anthropic Documentation