What is CLAUDE.md and Why Every Senior Engineer Needs One
CLAUDE.md is the memory file that tells Claude Code how your project works — conventions, architecture, patterns, and constraints. Learn the three-tier hierarchy, @import directives, .claude/rules/ files, and see real examples for different project types.
Quick Reference
- →CLAUDE.md is a Markdown file that Claude Code reads at the start of every conversation
- →Three-tier hierarchy: user-level (~/.claude/CLAUDE.md) < project-level (./CLAUDE.md) < directory-level (./src/CLAUDE.md)
- →More specific CLAUDE.md files override more general ones for the same topic
- →@import allows splitting large configs into focused files
- →.claude/rules/ directory holds conditional rules loaded based on glob patterns
- →/init generates a starter CLAUDE.md by analyzing your codebase
- →/memory opens CLAUDE.md for direct editing inside Claude Code
- →CLAUDE.md is committed to the repo — it is shared knowledge for the whole team
- →Keep CLAUDE.md under 1000 lines — beyond that, split with @import or .claude/rules/
In this article
What is CLAUDE.md?
CLAUDE.md is a Markdown file that acts as persistent memory for Claude Code. It tells the AI assistant about your project's tech stack, coding conventions, architecture decisions, testing patterns, and anything else that should influence how code is written.
Every time you start a new Claude Code session, the first thing it does is read your CLAUDE.md files. This is how Claude Code knows that your project uses Tailwind CSS v4 instead of v3, that you prefer named exports, or that database migrations must go through a specific workflow. Without CLAUDE.md, Claude Code is a brilliant generalist. With it, Claude Code becomes a teammate who knows your codebase intimately.
Think of CLAUDE.md as the onboarding document you wish every new engineer received on their first day — except this one is read perfectly, every time, and never forgotten.
The Three-Tier Hierarchy
Claude Code supports CLAUDE.md files at three levels. More specific files take precedence over general ones, just like CSS specificity. This lets you set global preferences while allowing per-project or per-directory overrides.
| Level | Location | Scope | Committed to Git? |
|---|---|---|---|
| User | ~/.claude/CLAUDE.md | Every project you open with Claude Code | No (personal preferences) |
| Project | ./CLAUDE.md (repo root) | Everyone working on this repository | Yes (shared team knowledge) |
| Directory | ./src/api/CLAUDE.md | Only when working in that directory subtree | Yes |
@import and .claude/rules/
As your project grows, cramming everything into a single CLAUDE.md becomes unwieldy. Claude Code provides two mechanisms for splitting configuration: @import directives and the .claude/rules/ directory.
The .claude/rules/ directory takes a different approach. Instead of always loading rules, each file in this directory has a frontmatter section with a glob pattern. The rules are only loaded when Claude Code is working on files matching that pattern.
@import is best for content that is always relevant (architecture overview, general conventions). .claude/rules/ is best for domain-specific rules that would waste context when working in unrelated parts of the codebase.
Real-World Examples by Project Type
The ideal CLAUDE.md content varies dramatically by project type. Here are examples showing what to emphasize for different kinds of codebases.
What to Include (and What Not To)
The most common mistake with CLAUDE.md is including too much or too little. Here is a decision framework for what belongs in your CLAUDE.md and what does not.
| Include | Exclude |
|---|---|
| Tech stack and versions | Obvious language features (e.g., 'JavaScript has variables') |
| Naming conventions and patterns | Content that duplicates your linter/formatter config |
| Architecture and directory structure | Long tutorials or how-tos |
| Testing patterns and tools | Full API documentation (use @import to reference it) |
| Non-obvious project constraints | Personal preferences (put those in user-level CLAUDE.md) |
| Common pitfalls and gotchas | Information that changes weekly (it will go stale) |
Ask yourself: if a competent senior engineer joined the team today, what would they need to know that is NOT obvious from reading the code or the README? That is what goes in CLAUDE.md.
CLAUDE.md in a Team Workflow
CLAUDE.md is committed to the repository, which means it is a shared artifact subject to code review — just like your code. This has powerful implications for team alignment.
Initial Setup
One engineer runs /init to generate the base CLAUDE.md. The team reviews it in a PR, just like any other code change.
Ongoing Maintenance
When the team adopts a new convention (e.g., switching from REST to tRPC), someone updates CLAUDE.md in the same PR that introduces the change.
Onboarding
New team members read CLAUDE.md as part of onboarding. It serves double duty: teaching the human AND configuring their AI assistant.
Review Changes
CLAUDE.md changes should be reviewed carefully. A bad instruction in CLAUDE.md will propagate errors across every AI-assisted change in the project.
A well-written CLAUDE.md makes every AI interaction better. A poorly written one makes every interaction subtly worse. Treat CLAUDE.md changes with the same rigor as changes to your CI configuration.
Generating and Maintaining CLAUDE.md
CLAUDE.md is a living document. Here is the recommended workflow for creating and maintaining it over time.
Generate with /init
Run /init in your project root. Claude Code will analyze your codebase — package.json, directory structure, config files — and produce a first draft.
Review and Refine
Open the generated file with /memory and fix inaccuracies. Add non-obvious conventions that the analysis missed. Remove anything that duplicates existing docs.
Split if Needed
If CLAUDE.md exceeds a few hundred lines, move domain-specific rules into .claude/rules/ files with appropriate glob patterns.
Commit and Review
Submit CLAUDE.md in a PR. Get team buy-in. This is a configuration change that affects every AI-assisted commit.
Maintain Alongside Code
When you change a convention, update CLAUDE.md in the same PR. Stale CLAUDE.md entries are worse than missing ones because they actively mislead.
Advanced Patterns
Once you are comfortable with the basics, these advanced patterns can take your CLAUDE.md to the next level.
- ▸Conditional sections with .claude/rules/ glob patterns — load API rules only when editing API files, load test rules only when editing test files
- ▸Environment-specific instructions — include notes about local dev setup, staging quirks, and production constraints
- ▸Error pattern documentation — describe common errors and their fixes so Claude Code can diagnose issues faster
- ▸Migration guides — when moving between major versions (e.g., React 18 to 19), add temporary migration notes to CLAUDE.md
- ▸Security constraints — explicitly list things Claude Code should never do (e.g., 'never hardcode API keys', 'never disable CORS')
Best Practices
Do
- ✓Commit CLAUDE.md to version control so the entire team benefits
- ✓Update CLAUDE.md in the same PR that introduces a convention change
- ✓Use the three-tier hierarchy: user preferences, project conventions, directory-specific rules
- ✓Split large configurations using @import and .claude/rules/
- ✓Include non-obvious constraints that Claude would not know from reading code alone
- ✓Review CLAUDE.md changes with the same rigor as CI configuration changes
- ✓Use the 'new engineer test' — include what a competent new hire would need to know
Don’t
- ✗Don't put personal preferences in the project-level CLAUDE.md — use ~/.claude/CLAUDE.md
- ✗Don't duplicate information that already exists in your linter or formatter config
- ✗Don't let CLAUDE.md grow beyond 1000 lines without splitting it
- ✗Don't include information that changes frequently — it will go stale and mislead
- ✗Don't skip the review step when generating CLAUDE.md with /init
- ✗Don't treat CLAUDE.md as write-once — it is a living document
Key Takeaways
- ✓CLAUDE.md is the single most impactful file for Claude Code productivity — it transforms a generalist AI into a project-aware teammate
- ✓The three-tier hierarchy (user, project, directory) gives you precise control over what Claude knows and when
- ✓@import and .claude/rules/ prevent CLAUDE.md from becoming a bloated mess
- ✓Commit CLAUDE.md to the repo — it is shared team knowledge, not personal config
- ✓Update CLAUDE.md alongside code changes to prevent stale instructions from misleading the AI
- ✓Use the 'new engineer test' to decide what belongs in CLAUDE.md
- ✓Start with /init, refine with /memory, maintain with discipline
Video on this topic
CLAUDE.md Explained in 60 Seconds
tiktok