A new Claude Code session does not keep the previous conversation. It starts with a fresh context window: the system prompt, then your CLAUDE.md files and auto memory. CLAUDE.md is the markdown you add so project facts ride along every time: build commands, conventions, and how you know the work is done.
Claude treats that file as context, not as enforced configuration. It reads the instructions and tries to follow them. If an action must be blocked no matter what Claude decides, put a hard stop outside this file: add a permissions.deny rule, or a PreToolUse hook that runs before Claude uses a tool and can refuse the call.
Where it lives
Share a project file at CLAUDE.md or .claude/CLAUDE.md through git. Keep personal, unshared notes in CLAUDE.local.md and add that file to gitignore. Preferences that follow you across repos live in ~/.claude/CLAUDE.md. Claude concatenates the files it finds. If two rules disagree, Claude may follow one and ignore the other.
Run /init to draft instructions from the project files, then cut anything already obvious from package.json. Run /context and check the Memory files list to confirm the file loaded.
Claude Code v2.1.277 or later reads AGENTS.md on its own when the working directory and its parents have no CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md. Your ~/.claude/CLAUDE.md does not count. If one of those project files exists, Claude reads the CLAUDE.md files only, unless CLAUDE.md contains @AGENTS.md or Project instructions is set to claude-md-and-agents-md. Adding CLAUDE.local.md also stops that direct AGENTS.md load unless you set the same option.
If a session cannot read AGENTS.md — Claude Code before v2.1.277, the built-in agents-md plugin disabled, or some sessions before v2.1.281 — put this line in CLAUDE.md so the same instructions load:
@AGENTS.mdDo not copy the file.
What earns a line
Aim under two hundred lines. Claude Code loads a normal CLAUDE.md in full; a longer file still spends tokens and is easier to ignore. Files over 4 MiB are skipped. Write information Claude cannot find by reading the code:
- Install, typecheck, test, and build commands
- Conventions that differ from language defaults
- Where a kind of file belongs
- The check that means the work is done
“Format nicely” is too vague to follow. “Use 2-space indentation” and “run pnpm test on the files you touched before you stop” can be checked.
Leave a multi-step ritual to a skill, and instructions that matter only for some files to a path-scoped rule in .claude/rules/. Skills load when you invoke them or when Claude judges them relevant. CLAUDE.md loads every session.
Example
A sample file for a small task-manager app. Adjust the commands to match your repo.
# Task manager
## Commands
- Install: `pnpm install`
- Dev: `pnpm dev`
- Test: `pnpm test`
- Typecheck: `pnpm check`
## Layout
- UI in `src/components/`
- Server routes in `src/api/`
## API errors
- Return JSON `{ error, code }` with the matching HTTP status.
- Do not hide network failures in the client. If a request fails, show an error state.
## Done when
- Empty, loading, and error states for the task list all render.
- `pnpm test` passes for the files you changed.When Claude repeats a mistake, add one concrete line. When the same paragraph becomes a procedure you paste into chat, move it into .claude/skills/<name>/SKILL.md. Auto memory can store corrections Claude writes itself; CLAUDE.md is still the file teammates should see.