# CLAUDE.md Best Practices: What to Put in Your Project File

> What belongs in CLAUDE.md, what to cut, and when to use rules, imports, skills and hooks instead, based on Anthropic's Claude Code documentation.

6 October 2026 · Technical · How-to · 9 min read · https://bridge-terminal.com/atlas/blog/claude-md-best-practices-project-instructions/

## The short version

- A good CLAUDE.md is short and specific. It holds only what Claude Code can't work out from your code: exact build and test commands, style rules that differ from defaults, and known gotchas.
- Claude treats CLAUDE.md as context, not enforced configuration, so there is no guarantee it is always followed, especially when instructions are vague or conflict.
- Aim for under 200 lines per CLAUDE.md file. Longer files use more context and lower adherence, and Claude Code warns at startup and in /status when a file is over the recommended length.
- Anything that must happen every time belongs in a hook, which runs deterministically, not in CLAUDE.md, which is advisory.
- Instructions that apply to only part of a project, or only matter sometimes, belong in path-scoped rules or skills. Imports organize a file but don't reduce its context cost.

A good CLAUDE.md is short and specific. It holds what Claude Code can't work out from your code: the exact build and test commands, style rules that differ from the defaults, repository etiquette, and the gotchas people keep running into. Three kinds of content belong elsewhere: anything Claude can learn by reading the code, anything that applies to only one corner of the repo, and anything that must happen every time without exception.

This guide follows Anthropic's Claude Code documentation. It covers where the file goes, what to put in it, what to leave out, and what to check when Claude ignores it.

## What CLAUDE.md is and isn't

Every Claude Code session starts with a fresh context window. CLAUDE.md is a Markdown file you write, and Claude reads it at the start of every session, so you don't have to explain your project again each time.

Claude treats CLAUDE.md as **context, not enforced configuration**. According to the documentation, the content is "delivered as a user message after the system prompt," and Claude tries to follow it, "but there's no guarantee of strict compliance, especially for vague or conflicting instructions." So whether your conventions get followed depends on two things: how clearly you write them, and whether hard requirements live somewhere that enforces them.

## Where to put CLAUDE.md files

Claude Code reads instruction files from several places. They load from the broadest scope to the most specific:

| Scope | Location | Use it for |
| --- | --- | --- |
| Managed policy | `/Library/Application Support/ClaudeCode/CLAUDE.md` (macOS), `/etc/claude-code/CLAUDE.md` (Linux/WSL), `C:\Program Files\ClaudeCode\CLAUDE.md` (Windows) | Organization-wide instructions managed by IT or DevOps |
| User | `~/.claude/CLAUDE.md` | Your personal preferences across all projects |
| Project | `./CLAUDE.md` or `./.claude/CLAUDE.md` | Team conventions, checked into git |
| Local | `./CLAUDE.local.md` | Your private notes for this project; add it to `.gitignore` |

Files are concatenated, not overridden. Claude Code loads CLAUDE.md and CLAUDE.local.md from your working directory and every directory above it. Files closer to where you launched Claude are read last, and within each directory `CLAUDE.local.md` comes after `CLAUDE.md`. A CLAUDE.md in a subdirectory below your working directory isn't loaded at launch. It loads once Claude reads, writes or edits a file in that subdirectory.

If you use git worktrees, note that a gitignored `CLAUDE.local.md` exists only in the worktree where you created it. To share personal instructions across worktrees, import a file from your home directory instead (imports are covered below).

## Start with /init, then cut it down

Run `/init` in a session to generate a first draft. Claude analyzes your codebase and writes a file with the build commands, test instructions and conventions it finds. If a CLAUDE.md already exists, `/init` suggests improvements instead of overwriting it. It also reads Cursor rules (`.cursor/rules/` or `.cursorrules`) and Copilot instructions (`.github/copilot-instructions.md`) and brings the relevant parts into the draft. For an interactive version, set `CLAUDE_CODE_NEW_INIT=1` before running `/init`. It asks which artifacts to set up (CLAUDE.md files, skills and hooks), asks follow-up questions, and shows you a proposal before it writes any files.

Treat the draft as a starting point. The documentation says to refine it "with instructions Claude wouldn't discover on its own." Begin by cutting anything Claude could work out from the repository.

## What to put in CLAUDE.md

Anthropic's best-practices guide has an include/exclude table. The include side:

- **Bash commands Claude can't guess.** Your real test, lint, typecheck and build commands, with the flags your project needs.
- **Code style rules that differ from defaults.** Skip anything the language's standard conventions already cover.
- **Testing instructions and preferred test runners.**
- **Repository etiquette.** Branch naming and pull request conventions.
- **Architectural decisions specific to your project.**
- **Developer environment quirks**, such as required environment variables.
- **Common gotchas**: behavior that isn't obvious from reading the code.

The memory documentation also says when to add a line: Claude makes the same mistake a second time, a code review catches something Claude should have known, you type a correction you already typed last session, or a new teammate would need the same context to be productive.

### Write instructions you can check

The docs recommend instructions "concrete enough to verify," with these examples:

- "Use 2-space indentation" rather than "Format code properly"
- "Run `npm test` before committing" rather than "Test your changes"
- "API handlers live in `src/api/handlers/`" rather than "Keep files organized"

Group related rules under Markdown headings and bullet points. No format is required. The example in Anthropic's guide is this short:

```markdown
# Code style
- Use ES modules (import/export) syntax, not CommonJS (require)
- Destructure imports when possible (eg. import { foo } from 'bar')

# Workflow
- Be sure to typecheck when you're done making a series of code changes
- Prefer running single tests, and not the whole test suite, for performance
```

## What to leave out

The exclude side of the table:

- Anything Claude can figure out by reading the code
- Standard language conventions Claude already knows
- Detailed API documentation (link to it instead)
- Information that changes frequently
- Long explanations or tutorials
- File-by-file descriptions of the codebase
- Self-evident practices like "write clean code"

For each line, the guide suggests asking: *"Would removing this cause Claude to make mistakes?"* If not, cut it. The guide warns: "Bloated CLAUDE.md files cause Claude to ignore your actual instructions!" If Claude already does something correctly without an instruction, delete the instruction or turn it into a hook.

### Keep it under 200 lines

The documented target is under 200 lines per CLAUDE.md file, because longer files consume more context and reduce adherence. Claude Code shows a warning at startup and in `/status` when one of your instruction files is over the recommended length. It also warns when several files that are each within that length add up past a combined limit. Each CLAUDE.md, rules file and `@path` import counts as a separate file. Files over 4 MiB are skipped entirely.

Two commands help with trimming. `/doctor` proposes cuts for a checked-in CLAUDE.md. It removes content Claude can derive from the codebase, such as directory layouts, dependency lists and architecture overviews, and keeps pitfalls, rationale and conventions that differ from tool defaults. `/doctor prompt-audit` (Claude Code v2.1.283 or later) checks your instruction files for problems: instructions written for older models, references to files or commands that don't exist, and files that contradict each other. It reports findings with proposed edits and changes nothing until you ask Claude to apply them.

## Move the rest into rules, imports, skills and hooks

Content that isn't needed in every session can go somewhere else.

### Path-scoped rules in .claude/rules/

Put one topic per file, such as `testing.md` or `api-design.md`, in `.claude/rules/`. A rule without a `paths` field loads at launch with the same priority as `.claude/CLAUDE.md`. If you add `paths` frontmatter, the rule loads only when Claude works with matching files:

```markdown
---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments
```

This works well for conventions that apply to only part of a monorepo. Personal rules can go in `~/.claude/rules/` and apply to every project on your machine. If a user rule and a project rule conflict, Claude may follow either, so keep them consistent.

### Imports with @path

CLAUDE.md can pull in other files with `@path/to/file`. Relative paths resolve relative to the file that contains the import, not the working directory. Imported files can import others, up to four hops deep:

```text
See @README for project overview and @package.json for available npm commands for this project.

# Additional Instructions
- git workflow @docs/git-instructions.md
```

Imports help organize a long file, but they don't reduce its context cost, because imported files also load at launch. To mention a path without importing it, wrap it in backticks. The first time Claude Code finds imports that point outside your working directory in a project, it shows an approval dialog listing them.

### Skills for procedures

Multi-step procedures, and domain knowledge that only matters sometimes, belong in skills (`.claude/skills/<name>/SKILL.md`). A skill loads when you invoke it or when Claude decides it's relevant, so it doesn't take up context in every session.

### Hooks for anything that must always happen

If a rule has to hold every time, such as running eslint after each file edit or blocking writes to the migrations folder, use a hook. In the best-practices guide's words, CLAUDE.md instructions are advisory, while hooks "are deterministic and guarantee the action happens." Organizations have the same split. Managed settings such as `permissions.deny` are enforced by the client, while a managed CLAUDE.md shapes behavior but is "not a hard enforcement layer."

## Sharing one file with other coding agents

If your repository already has an `AGENTS.md` for other coding agents, Claude Code v2.1.277 or later reads it when there is no `CLAUDE.md`, `.claude/CLAUDE.md` or `CLAUDE.local.md` in your working directory or above it. If you want both files, the documented pattern is a CLAUDE.md that imports the shared file and then adds Claude-specific notes:

```markdown
@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.
```

Watch out for one thing: a `CLAUDE.local.md` counts as having a CLAUDE.md, so adding one stops Claude from reading `AGENTS.md` by default. To keep both, open `/config` and set **Project instructions** to `claude-md-and-agents-md`.

## When Claude ignores your CLAUDE.md

Work through these checks in order:

1. **Confirm it loaded.** Run `/context` and look under **Memory files**. If the file isn't listed, Claude can't see it. Subdirectory files don't appear there because they load on demand.
2. **Look for conflicts.** If two files give different guidance for the same behavior, Claude may pick one arbitrarily.
3. **Make the rule more specific.** If Claude asks questions that CLAUDE.md already answers, the wording may be ambiguous.
4. **Shorten the file.** If Claude keeps doing something despite a rule against it, the guide says the file "is probably too long and the rule is getting lost."
5. **Emphasize sparingly.** If Claude keeps skipping one instruction, adding "IMPORTANT" to that line alone can help. Emphasize many lines and none stands out.
6. **Check for built-in guidance.** If your file sets commit or pull request rules, turn off Claude Code's own git instructions with the `includeGitInstructions` setting.

If an instruction disappears after `/compact`, it was probably given only in chat, or it lives in a nested CLAUDE.md or path-scoped rule that hasn't loaded again yet. Claude re-reads the project-root CLAUDE.md from disk after compaction, so moving a chat instruction into that file keeps it.

Two smaller details: block-level HTML comments (`<!-- notes -->`) are stripped before the content reaches Claude, so you can leave notes for human maintainers without spending context. And asking Claude to "remember" something saves it to auto memory, not CLAUDE.md. To put it in the shared file, say "add this to CLAUDE.md" or edit the file yourself through `/memory`.

## When you run several agents

The same principles apply when several Claude Code sessions work on one codebase. Each session needs its role and constraints written down, and anything that must always hold needs a mechanism that enforces it, not just a sentence. [Atlas](https://bridge-terminal.com/atlas/) follows this pattern. Each engineer is its own Claude Code session with a written role and its own working folder. "Done" is enforced: completion is refused until the work is on main or queued for the landing train.

## Summary

The guide's advice is to treat CLAUDE.md like code. Generate a draft with `/init`, cut everything Claude could work out from the repository, and keep the rest concrete and under 200 lines. Move conventions that apply to only part of the codebase into path-scoped rules, procedures into skills, and steps that must always happen into hooks. Check the file into git, review it when Claude gets something wrong, and use `/context` to confirm what loaded.

## Questions people ask

### What should I put in my CLAUDE.md file?

Put in things Claude can't guess: your real build, test, lint and typecheck commands, code style rules that differ from defaults, testing instructions, branch and pull request conventions, architectural decisions specific to the project, environment quirks such as required variables, and common gotchas.

### What should I leave out of CLAUDE.md?

Leave out anything Claude can learn by reading the code, standard language conventions, detailed API docs (link to them instead), information that changes often, long tutorials, file-by-file descriptions and obvious advice like "write clean code". For each line, ask whether removing it would cause Claude to make mistakes. If not, cut it.

### How long should a CLAUDE.md file be?

Anthropic's documentation recommends under 200 lines per file. Longer files consume more context and reduce adherence. Claude Code warns at startup and in /status when a file is over the recommended length, and skips files over 4 MiB entirely.

### Why does Claude ignore my CLAUDE.md instructions?

CLAUDE.md is context, not enforced configuration. Common causes: the file didn't load (check /context), two files conflict, the wording is vague, or the file is too long and the rule gets lost. Shortening the file, making rules specific, and adding "IMPORTANT" to a single line can help.

### How do I make sure a rule is always followed?

Use a hook. CLAUDE.md instructions are advisory, while hooks are deterministic and run every time, for example running eslint after each file edit or blocking writes to the migrations folder.

## About Atlas: Written roles and enforced completion for a whole team

CLAUDE.md gives one Claude Code session your conventions, and hooks make the hard rules stick. Atlas applies the same split to a team. Each engineer is its own Claude Code session with a written role, its own working folder, and evidence it must produce. Completion is refused until the work is on main or queued for the landing train and the product's rules pass. — https://bridge-terminal.com/atlas/

## Sources

- [How Claude remembers your project (CLAUDE.md and auto memory) - Claude Code Docs](https://code.claude.com/docs/en/memory)
- [Best practices for Claude Code - Claude Code Docs](https://code.claude.com/docs/en/best-practices)

_Researched and drafted with Claude, then checked against the sources above. Atlas is an independent product, not affiliated with Anthropic or OpenAI._