CLAUDE.md
Claude CodeDefinition
A markdown configuration file read by Claude Code at startup that injects persistent context, project conventions, and tool guidance into every session — without re-prompting. Claude Code supports CLAUDE.md files at the global, project-root, and subdirectory levels (see /glossary/path-specific-rules for the hierarchy). Uses @import for modular organization.
Example Usage
Put coding standards, architecture decisions, and banned file paths in the project CLAUDE.md so Claude Code always has context — no repeated instructions each session.
In Depth
CLAUDE.md is a plain Markdown file that Claude Code reads at startup. Its contents are injected into Claude's context window before the conversation begins, making it the primary mechanism for persistent, session-independent configuration.
File Format and Structure
CLAUDE.md is standard Markdown — headings, bullet lists, fenced code blocks, and inline links all work. There is no required schema or frontmatter. Convention is to use ## Section headings to group related rules, making the file scannable for both humans and the model.
## Architecture
- Monorepo: apps/web (Next.js 14), apps/api (Fastify), packages/shared
- State management: Zustand only — no Redux
## Coding Conventions
- TypeScript strict mode everywhere
- Named exports only; no default exports in src/
- Errors: always throw `AppError`, never bare `Error`
## Off-limits
- Never edit generated files in `src/generated/`
- Never run `db:reset` without explicit user confirmationWhat Belongs in CLAUDE.md
| Content type | CLAUDE.md? | Alternative |
|---|---|---|
| Architecture overview | Yes | — |
| Coding conventions, linting rules | Yes | — |
| Non-obvious codebase gotchas | Yes | — |
| Preferred test frameworks & commands | Yes | — |
| Reusable prompt logic / slash commands | No | Skills (~/.claude/skills/) |
| Tool permissions, model settings | No | settings.json |
| Secrets, API keys | Never | .env (gitignored) |
| Temporary debug flags | No | Inline prompt |
@import Syntax
Long CLAUDE.md files degrade context quality — every token consumed by config is a token unavailable for code. The @import directive keeps the root file short by inlining external files at load time:
@import docs/api-conventions.md
@import .claude/rules/security.md
@import .claude/rules/testing.mdClaude Code resolves each import relative to the file containing the directive and splices the content in-place before loading. Imports are static (evaluated once at startup), not dynamic.
Token-Cost Tradeoffs
Every line in CLAUDE.md consumes context tokens on every session. Practical guidance:
- Keep the root CLAUDE.md under ~150 lines; use @import to offload detail
- Prefer concrete rules over narrative prose — shorter and higher signal
- Archive stale decisions rather than leaving them to dilute current guidance
The three-level hierarchy (global → project → subdirectory) is covered in detail on Path-Specific Rules.
See also: @import Directive, Skills (Claude Code).
How It's Tested & Common Confusions
Exam questions on CLAUDE.md focus on file contents and format decisions, not hierarchy depth (hierarchy questions appear on Path-Specific Rules).
1. What belongs in CLAUDE.md vs. elsewhere
- "A developer wants Claude Code to always use a custom
/deploycommand. Where does this go?" — Answer: a Skill, not CLAUDE.md. - "Which of these should NOT be in CLAUDE.md: architecture overview / production secret / linting rules / test command?" — Answer: production secret.
2. @import mechanics
- "What does
@import docs/api-conventions.mddo?" — Claude Code inlines the file contents at load time; it does not fetch at runtime. - When to split vs. keep monolithic: use @import when content is reused across multiple CLAUDE.md files, or when the root file exceeds maintainable length.
3. Token tradeoffs
- Questions may ask about the cost of an oversized CLAUDE.md — the answer is that it consumes context window tokens every session, reducing space for code and output.
Frequently Asked Questions
Should I commit CLAUDE.md to version control?
The project-root CLAUDE.md should be committed so the whole team shares context. The global `~/.claude/CLAUDE.md` is personal and lives outside any repo. Never commit secrets or API keys inside CLAUDE.md — treat it like any other tracked config file.
How does Claude Code handle a very large CLAUDE.md?
Long CLAUDE.md files consume context tokens on every session and can bury important instructions in noise. Use the @import directive to split the file into focused modules — a short root file that imports security rules, testing rules, and architecture notes separately. This keeps each fragment maintainable and the root file scannable.
What is the difference between CLAUDE.md and settings.json?
CLAUDE.md injects natural-language context and instructions into Claude's prompt. settings.json configures the Claude Code tool itself — model selection, allowed commands, hook scripts, and environment variables. Put 'what to do' in CLAUDE.md; put 'how the tool behaves' in settings.json.