How to Configure Claude Code with CLAUDE.md: The Complete Guide

CLAUDE.md is the primary configuration file for Claude Code. When you start a session, Claude Code reads it and uses the contents as persistent context — your project conventions, preferred commands, architecture notes, and any instructions that should apply across the entire session. Getting this right dramatically improves the quality of Claude's output on your codebase.

The File Hierarchy

Claude Code loads CLAUDE.md files from multiple locations, and they merge in a specific order:

• User-level: ~/.claude/CLAUDE.md — loaded for all projects. Good for personal preferences, common shell aliases, universal rules.
• Project root: /your-project/CLAUDE.md — loaded when Claude Code is run inside that project. This is where project-specific context lives.
• Subdirectory: /your-project/src/CLAUDE.md — loaded when Claude Code operates within that subdirectory. Useful for component-specific rules in large monorepos.

All three levels are active simultaneously. User-level context is available alongside project context — you don't need to re-document personal preferences in every project file.

The @import Syntax

For large projects, a single CLAUDE.md file becomes unwieldy. The @import directive lets you split it into modular files:

# CLAUDE.md
@import ./docs/architecture.md
@import ./docs/conventions.md
@import ./docs/deployment.md

Imports are resolved relative to the CLAUDE.md file's location. They can be nested — imported files can themselves import other files. This makes it practical to maintain separate documents for architecture, coding conventions, and deployment workflows, then pull them together in the root CLAUDE.md.

What to Include

Effective CLAUDE.md files focus on non-obvious context that Claude cannot infer from the code itself. Include:

• Build and test commands: npm run build, npm test -- --watch, etc.
• Architecture decisions: Why you chose a particular pattern, what the major abstractions are.
• Naming conventions: File naming patterns, component structure, module boundaries.
• What not to do: Anti-patterns specific to your codebase, deprecated modules to avoid.
• Environment setup: Required env vars, service dependencies.

What not to include: obvious instructions like "write clean code" or documentation that merely restates the code. Claude can read the code directly; CLAUDE.md should add context that isn't in the code.

How Claude Code Uses It During Sessions

Claude Code reads all applicable CLAUDE.md files at session start and prepends them to the context window as system-level instructions. They are not re-read during the session — changes take effect on the next session start. For long sessions, this means your instructions remain stable throughout.

The CCA-F exam tests understanding of this loading behaviour. CLAUDE.md is not a dynamic context source — it is a static configuration that sets the session's persistent instructions. Real-time data (database schemas, recent commits, API responses) should come from tools, not CLAUDE.md.

Hooks and Permissions

CLAUDE.md can also reference Claude Code's hook system. Hooks allow you to run scripts at specific lifecycle points — before a tool call, after a file edit, on session start. Configuring hooks via CLAUDE.md lets you enforce project-level automation without requiring each developer to configure their environment separately.