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: deny the tool in /permissions, or add 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. Claude Code reads CLAUDE.md, not AGENTS.md. If another tool already uses AGENTS.md, put this line in CLAUDE.md so the same instructions load:

@AGENTS.md

Do 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 multi-step rituals to a skill. Skills load when they are used. 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 SKILL.md. Auto memory can store corrections Claude writes itself; CLAUDE.md is still the file teammates should see.

Sources