How to Use CLAUDE.md Files: The Complete Guide

CLAUDE.md is the single most important configuration file in Claude Code. Set it up once, and Claude remembers your preferences, conventions, and project context across every session.

CLAUDE.md is a Markdown file that Claude Code reads automatically at the start of every session. Place it in your project root to give Claude persistent memory of your coding conventions, project structure, test commands, and workflow preferences. You write your instructions once, and Claude follows them every time — no repeating yourself.

This guide shows you exactly where to put CLAUDE.md files, what to include in them, and the common mistakes that make them useless.

What Is CLAUDE.md?

CLAUDE.md is a special configuration file that Claude Code looks for automatically. When Claude finds it, it reads the contents before you even type your first message.

Think of it as a briefing document. Instead of explaining your project every time ("we use React, tests are in the __tests__ folder, run npm test, oh and we use semicolons..."), you write it once in CLAUDE.md and Claude just knows.

Without CLAUDE.md: Every session starts fresh. You repeat context. Claude makes assumptions that don't match your project.

With CLAUDE.md: Claude starts every session already understanding your project, your preferences, and your workflow.

Where to Put Your CLAUDE.md File

Claude Code looks for CLAUDE.md files in several locations. Here's where to put yours:

How to Create Your First CLAUDE.md

The fastest way to get started is with the /init command.

That's it. The file is created and Claude will read it automatically from now on.

What to Put in Your CLAUDE.md

Here's the golden rule: Only include things Claude can't figure out by reading your code.

Claude is smart. It can read your package.json, understand your folder structure, and infer a lot. Don't waste space telling it obvious things.

A Real Example

Here's what a good CLAUDE.md looks like for a typical web project:

# Project: Marketing Dashboard

## Commands
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`
- Dev server: `npm run dev`

## Code Style
- Use ES modules (import/export), not CommonJS (require)
- 2-space indentation
- Single quotes for strings
- Always use semicolons

## Testing
- Tests go in __tests__ folders next to the code they test
- Use Jest and React Testing Library
- Run single test files during development: `npm test -- path/to/test`

## Git Workflow
- Branch naming: feature/*, bugfix/*, docs/*
- Squash commits before merging
- Write commit messages in imperative mood ("Add feature" not "Added feature")

## Gotchas
- Run `npm run db:migrate` after pulling if you see database errors
- The API requires the AUTH_TOKEN env variable to be set

Notice how short this is. Every line serves a purpose. There's no fluff.

The Most Common Mistake: Writing Too Much

This is where most people go wrong.

They write a 500-line CLAUDE.md with detailed explanations, API documentation, coding tutorials, and style guides. Then they wonder why Claude ignores their instructions.

Here's what happens: Claude has limited context space. When your CLAUDE.md is huge, it crowds out everything else. Important instructions get lost in the noise. Claude starts ignoring things.

Apply this test to every line: "Would removing this cause Claude to make mistakes?" If the answer is no, delete it.

Using Multiple CLAUDE.md Files

For larger projects, you can organize your instructions into multiple files:

your-project/
├── CLAUDE.md                    # Main project config
├── CLAUDE.local.md              # Your personal preferences (gitignored)
└── .claude/
    └── rules/
        ├── code-style.md        # Code style guidelines
        ├── testing.md           # Testing conventions
        └── api/
            └── endpoints.md     # API-specific rules

All .md files in the .claude/rules/ folder are loaded automatically.

Path-Specific Rules

You can make rules apply only to certain files. Add this to the top of a rules file:

---
paths:
  - "src/api/**/*.ts"
  - "src/**/*.test.ts"
---

# API Rules
- All endpoints must validate input
- Use standard error response format

Now these rules only apply when Claude is working with files that match those patterns.

Importing Other Files

Your CLAUDE.md can reference other files using the @ syntax:

# Project Overview
See @README.md for the full project description.

# Available Commands
Check @package.json for all npm scripts.

# Git Workflow
Follow the process in @docs/contributing.md

This keeps your CLAUDE.md short while still giving Claude access to detailed documentation when needed.

Automatic Memory

As of February 2026, Claude Code can automatically record and recall memories as it works. This means Claude learns from your sessions and builds up context over time without you explicitly adding to CLAUDE.md.

Auto memory is enabled by default. If you prefer to manage memory manually, disable it by setting the environment variable:

export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

Auto-recorded memories are stored separately from your CLAUDE.md file, so they won't clutter your project configuration. Think of auto memory as Claude's personal notes, while CLAUDE.md is the official project handbook.

The .claude Folder Ecosystem

The .claude folder in your project root houses more than just settings. Here is the full structure:

your-project/
├── CLAUDE.md                    # Main project config
├── CLAUDE.local.md              # Personal preferences (gitignored)
└── .claude/
    ├── CLAUDE.md                # Alternative location for main config
    ├── settings.json            # Permission rules, model, env vars
    ├── settings.local.json      # Personal settings overrides
    ├── rules/                   # Modular rule files (auto-loaded)
    │   ├── code-style.md
    │   └── testing.md
    ├── skills/                  # Custom slash commands
    │   └── deploy.md
    └── agents/                  # Custom subagent definitions
        └── reviewer.md

Skills defined in .claude/skills/ become available as slash commands. For example, a file at .claude/skills/deploy.md creates a /deploy command that Claude can invoke. Skills from additional directories (via --add-dir) are also loaded automatically.

Checking What Claude Loaded

Want to see what CLAUDE.md files Claude actually loaded? Run /memory in Claude Code.

This shows you all the memory files that were discovered and loaded for your current session. Useful for debugging when something isn't working.

Making Claude Follow Instructions Better

If Claude isn't following a particular instruction, try these techniques:

• Use emphasis: Write critical rules in ALL CAPS or add "IMPORTANT:" before them
• Be specific: "Use 2-space indentation" works better than "Use consistent indentation"
• Give examples: Show what you want, not just what you don't want
• Shorten the file: Remove anything Claude doesn't need to know

Common Mistakes to Avoid

1. Wrong filename: It must be exactly CLAUDE.md (uppercase CLAUDE, lowercase .md). Files named claude.md or Claude.md won't work.
2. Too much content: Keep it to 1-2 screens of text. If you need more, use the rules folder or imports.
3. Obvious information: Don't tell Claude that JavaScript uses curly braces. It knows.
4. Forgetting /init: The /init command gives you a great starting point. Don't write from scratch.
5. Not checking it into git: Your team should share the same CLAUDE.md so Claude behaves consistently for everyone.

FAQ

Do I need a CLAUDE.md file?

Technically no. Claude Code works without one. But you'll spend more time repeating context, and Claude will make more assumptions that don't match your project. For any serious work, create one.

How often should I update it?

Whenever you notice Claude making repeated mistakes, or when your project conventions change. Treat it like code—review it periodically and keep it current.

Can I have different CLAUDE.md files for different branches?

Yes, since it's just a file in your repo. Different branches can have different configurations. This is useful for experimental branches with different conventions.

What's the difference between CLAUDE.md and CLAUDE.local.md?

CLAUDE.md is shared with your team (checked into git). CLAUDE.local.md is personal (add it to .gitignore). Use the local file for your individual preferences that shouldn't affect others.

What is the .claude/rules/ folder for?

The rules folder lets you break your instructions into modular files. All .md files in .claude/rules/ are loaded automatically. You can organize by topic (code-style.md, testing.md, api-rules.md) and even add path-specific frontmatter so rules only apply to certain files.

What are skills in Claude Code?

Skills are custom slash commands defined as markdown files in .claude/skills/. A file at .claude/skills/deploy.md creates a /deploy command. Skills can contain instructions, prompts, and workflows that Claude follows when invoked.

Does Claude Code have auto memory now?

Yes. As of February 2026, Claude Code automatically records and recalls memories as it works. This supplements your CLAUDE.md with learned context. Disable it with CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 if you prefer manual control.

Related Guides

• What Is Claude Code? — understand the basics
• Claude Code Prompts & Examples — effective prompting techniques
• Claude Code Tutorial for Beginners — your first project