# CLAUDE.md explained: how to give Claude Code project instructions

CLAUDE.md is a Markdown file of instructions that Claude Code reads at the start of every session. Put one at the root of your repository with your build and test commands, conventions and the mistakes Claude should not repeat, and keep it under 200 lines. Run /init to have Claude write a first version from your code.

- Page: https://tecyfy.com/coding-agents/claude-code/project-instructions
- Guide: Claude Code (https://tecyfy.com/coding-agents/claude-code), from Anthropic's documentation (https://code.claude.com/docs/en/overview)

Every Claude Code session starts with an empty [Context Window](https://tecyfy.com/concepts/context-window). Nothing from yesterday's conversation is there, and Claude has to learn your project again: how to build it, how to run the tests, what not to touch. CLAUDE.md is how you skip that. It is a Markdown file that Claude Code loads at the start of every session, so its instructions are in front of Claude before you type anything.

## Start with /init

In a project with no CLAUDE.md, run `/init`. Claude looks through the code and writes a first version with the build commands, test commands and conventions it finds. If a CLAUDE.md already exists, it suggests improvements instead of overwriting it.

Treat that as a draft. The useful part of CLAUDE.md is what Claude cannot find in the code, and only you know that.

## What to write in it

Write down what you would otherwise explain again every session. A good rule from Anthropic's docs: add a line when Claude makes the same mistake twice, or when a review catches something it should have known.

```markdown
# Orders service

## Commands
- Run one test file: `pnpm vitest run src/orders/refund.test.ts`
- Lint and types: `pnpm check` (run before saying a task is done)
- Never run `pnpm db:reset`; it empties the shared dev database.

## Conventions
- Money is in integer cents, never floats. Use `formatCents()` to show it.
- API handlers live in `src/api/handlers/`, one file per route.
- Generated files in `src/gen/` are rebuilt by `pnpm codegen`. Do not edit them.

## Pull requests
- Branch names: `fix/<ticket>` or `feat/<ticket>`.
```

Make each line specific enough to check. "Use 2-space indentation" is followed; "format code properly" is not. "Run `pnpm check` before finishing" works; "test your changes" leaves Claude guessing what you mean.

## What to leave out

- **What the code already says.** Folder trees, lists of dependencies and an architecture overview Claude can read for itself use up space in every session.
- **Long procedures.** A 20-step release process belongs in a [skill](/coding-agents/claude-code/skills), which loads only when it is needed.
- **Rules for part of the code.** Put those in `.claude/rules/` with a `paths` line (below), so they load only when Claude touches those files.

Keep the file under 200 lines. A longer one costs context in every session, and its rules get followed less reliably. Splitting it with imports does not help with that, since imported files load too.

## Where CLAUDE.md files go

| File | For | Shared |
| --- | --- | --- |
| `CLAUDE.md` or `.claude/CLAUDE.md` at the repository root | The project's commands and rules | With the team, through Git |
| `CLAUDE.local.md` at the root | Your own notes for this project, such as a test account | Only you: add it to `.gitignore` |
| `~/.claude/CLAUDE.md` | Your preferences for every project | Only you |
| `CLAUDE.md` in a subfolder | Rules for that part of a monorepo | With the team |

Claude Code reads the CLAUDE.md in the folder you start in and every folder above it, and adds them together rather than letting one replace another. A CLAUDE.md in a subfolder loads later, the first time Claude opens a file there.

## Rules for some files only

A file in `.claude/rules/` is a CLAUDE.md for one subject. Give it a `paths` list and it loads only when Claude reads or edits a matching file:

```markdown
---
paths:
  - "src/api/**/*.ts"
---
- Validate every request body with the schema in src/api/schemas/.
- Return errors in the { error: { code, message } } shape.
```

Without `paths`, a rules file loads in every session, like CLAUDE.md. Your own rules for every project can go in `~/.claude/rules/`.

## Imports and comments

`@path` pulls another file in: `See @README.md for the overview` puts the README into context with CLAUDE.md. Paths are relative to the file that imports them. To mention a path without importing it, put it in backticks.

HTML comments, such as `<!-- why this rule exists -->`, are removed before Claude sees the file, so they cost nothing and are a good place for notes to your team.

## If you already have AGENTS.md

AGENTS.md is the instructions file other coding agents read. Since version 2.1.277, Claude Code reads it when there is no CLAUDE.md or CLAUDE.local.md in the folder or above. If you want both, keep AGENTS.md as the shared file and make CLAUDE.md a single line that imports it:

```markdown
@AGENTS.md
```

## When Claude does not follow it

CLAUDE.md is guidance, not a setting Claude Code enforces. Claude reads it and tries to follow it, and usually does, but nothing makes it.

- Run `/context` and check the file is listed under memory files. If it is not there, Claude never saw it.
- Look for 2 instructions that contradict each other, across all your CLAUDE.md and rules files. Claude may pick either.
- Make the rule concrete, and shorten the file.
- After `/compact`, the CLAUDE.md at the root is read again from disk. An instruction you gave only in conversation is not; if it matters, add it to the file.

If something must happen every time, such as running the formatter after each edit or blocking writes to a folder, use a [hook](/coding-agents/claude-code/hooks) or a [permission rule](/coding-agents/claude-code/permissions). Those run whatever Claude decides.

## Auto memory: what Claude writes itself

As you work, Claude also keeps its own notes: your preferences, corrections you gave it, decisions about the project and where to find things outside it. It skips what is already in the code or in CLAUDE.md. They are saved per repository in `~/.claude/projects/<project>/memory/`, on your machine only, as plain Markdown files with an index, `MEMORY.md`. The first 200 lines (or 25KB) of the index load into every session.

Run `/memory` to open your CLAUDE.md files, browse what auto memory has saved, edit or delete it, or turn the feature off. Seeing "Saved 2 memories" in a session means Claude has just written to that folder.

## Questions

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

Things Claude cannot work out from the code and needs in every session - the exact build, test and lint commands, conventions that differ from the usual, where things live, and rules such as "never edit generated files". Leave out what Claude can read from the code itself, and move long procedures into skills.

### Where does CLAUDE.md go?

At the root of the repository, as CLAUDE.md or .claude/CLAUDE.md, committed so your team shares it. Your own preferences for every project go in ~/.claude/CLAUDE.md, and preferences for one project that you do not want to commit go in CLAUDE.local.md.

### Does Claude Code read AGENTS.md?

Yes, from version 2.1.277. By default it reads AGENTS.md when there is no CLAUDE.md or CLAUDE.local.md in the folder or above it. To use both, import it with @AGENTS.md from your CLAUDE.md, or set Project instructions in /config.

### Why is Claude ignoring my CLAUDE.md?

CLAUDE.md is guidance, not enforcement. Run /context to check the file is loaded, make vague rules concrete ("use 2-space indentation", not "format nicely"), remove instructions that contradict each other, and shorten a long file. Anything that must happen every time, such as a check before each commit, belongs in a hook.

### What is auto memory in Claude Code?

Notes Claude writes for itself as you work - your preferences, corrections you gave it, decisions about the project. They are saved per repository in ~/.claude/projects/, and the first 200 lines of their index are loaded into every session. Run /memory to read, edit or delete them, or turn the feature off.

## Sources

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