CLAUDE.md: user, project, and local

Close a Claude Code session and everything it learned is gone. The next session opens with a fresh context window, which is the working memory the model can see at one time. Two things carry over. One is a set of files you write called CLAUDE.md. The other is a set of notes Claude writes for itself called auto memory. This lesson covers both, with the exact paths and rules as of September 2026.

If you took the system prompting module, CLAUDE.md will feel familiar. It does the job of a system prompt and you write it the same way: who you are, what matters, what to never do. The six-part template in Anatomy of a good system prompt works here almost unchanged. One technical difference worth knowing: Claude Code delivers the file as a user message right after the real system prompt, not inside it. Claude reads it and tries to follow it. That distinction matters later in this lesson.

The four places instructions live

A CLAUDE.md is a plain markdown file. What changes is where you put it, because location decides who else sees it. Tap each layer below. The example contents belong to a made-up landscaping company in St. George whose website repo we will use all lesson.

# Red Rock Web Studio policy

- Never paste API keys, customer phone numbers, or
  addresses into a chat or a commit.
- Every client site ships with robots.txt, sitemap.xml,
  and a LocalBusiness schema block.
- Ask before running any command that deletes files.

In words, broadest to most specific:

• Managed policy. On a Mac it sits at /Library/Application Support/ClaudeCode/CLAUDE.md. Linux uses /etc/claude-code/CLAUDE.md and Windows uses a folder under Program Files. IT deploys it, every user on the machine gets it, and no personal setting can exclude it. If you are a one-person shop you will probably never create this one.
• User. ~/.claude/CLAUDE.md, where the tilde means your home folder. Loads in every project you open. This is for preferences about you, not about any one codebase.
• Project. ./CLAUDE.md at the repo root, or ./.claude/CLAUDE.md if you prefer to keep it out of sight. Either works. It is checked into git, so it belongs to the team. Build commands, layout, conventions, the stuff a new hire would ask about on day one.
• Local. ./CLAUDE.local.md, also at the repo root. Same project, but private. Add it to .gitignore so your sandbox URLs and test accounts never land in a teammate's clone.

A quick test for which file a line belongs in: ask "who would be annoyed if they had to read this?" If a teammate would, it is user or local. If a different client's repo would, it is project. If nobody would, it is a candidate for managed policy or user.

How the files stack

Here is the part that trips up almost everyone who comes from configuration files like .gitconfig or ESLint, where a closer file wins. CLAUDE.md does not work that way. Claude Code finds every CLAUDE.md and CLAUDE.local.md from your current folder up to the filesystem root, then concatenates them, meaning it pastes them one after another into the context. Content is ordered from the root down to where you launched, so the closest file is read last. Within one folder, CLAUDE.local.md is appended after CLAUDE.md, so your private notes are the final thing Claude reads at that level.

Nothing is overridden. A rule in the user file and a contradicting rule in the project file both arrive, in that order, and the docs say plainly that when two instructions conflict Claude may pick one arbitrarily. Position is not precedence.

Files in subdirectories behave differently. If src/app/services has its own CLAUDE.md, it does not load at launch. It loads on demand, the first time Claude reads a file inside that folder. That is how a big repo keeps its startup context small: the gallery folder's notes only cost tokens when Claude is actually in the gallery folder.

Imports and rules folders

Two mechanisms keep a CLAUDE.md from turning into a scroll. The first is imports. Any line containing @ followed by a path pulls that file into context at launch, right alongside the file that referenced it. The rules, verified against the docs this month:

• Relative paths resolve from the file doing the importing, not from the folder you launched in. So @docs/deploy.md inside ./.claude/CLAUDE.md looks for ./.claude/docs/deploy.md.
• Imported files can import other files, to a depth of four hops.
• Anything inside backticks or a fenced code block is skipped. Write `@README` with backticks to mention the file, write @README bare to import it.
• Imports do not save context. The imported file still loads at launch. They are for organization, not for slimming.
• If a project file imports something outside the working directory, such as @~/.claude/desert-bloom-notes.md in your home folder, that is an external import. The first time Claude Code sees one in a project it shows an approval dialog listing the files. Decline, and those imports stay off with no repeat prompt. The dialog exists because a teammate could commit an import you never reviewed. Your own user-scope files skip the dialog.

That last point has a practical use. A gitignored CLAUDE.local.md only exists in the git worktree where you created it. If you run several worktrees of the same repo, keep your private notes in your home folder and import them from each worktree instead.

The second mechanism is a rules folder. Drop markdown files into ./.claude/rules/ and every .md file in there, including subfolders, is discovered. A rule with no frontmatter loads at launch with the same standing as .claude/CLAUDE.md. Frontmatter is the small block between three-dash lines at the top of a markdown file. Add a paths key and the rule becomes conditional: it only enters context when Claude reads a file that matches the pattern.

---
paths:
  - "src/app/services/**/*.tsx"
---

# Service pages

- Every service page ends with a call-to-action block
  that links to /contact.
- Mention the St. George service area once, naturally.

Patterns are globs, the same wildcard syntax as .gitignore. A double star matches any depth of folders. You can list several patterns, and brace groups like src/**/*.{ts,tsx} expand to multiple patterns. There is also a personal version: ~/.claude/rules/ applies to every project on your machine and loads before project rules, so the project's rules land later in context.

Keep it short, and know what it is not

The official target is under 200 lines per file. Longer files spend more context and, in Anthropic's words, reduce adherence. When a file grows past that, move folder-specific material into path-scoped rules and multi-step procedures into skills, which are the subject of lesson 5. Write instructions concrete enough to check: "use 2-space indentation" beats "format code properly." Block-level HTML comments are stripped before the file reaches Claude, so you can leave notes for human maintainers for free.

Now the point that the whole lesson has been building toward. CLAUDE.md is context, not enforcement. It shapes what Claude does. It does not stop Claude from doing anything. Anthropic's own docs say to use a hook to block an action regardless of what Claude decides, and that if something must happen at a fixed moment, such as before every commit, it belongs in a hook, not in a memory file. A hook is a shell command Claude Code runs at a set point in its loop, whether or not the model remembers. Lesson 8, Subagents and hooks, covers them. For now, a rule of thumb: "prefer" and "usually" go in CLAUDE.md. "Always" and "never" deserve a second look.

Three commands you will use constantly:

• /init reads the codebase and generates a starting project CLAUDE.md with build commands and conventions it found. If one exists, it suggests improvements instead of overwriting. It also folds in Cursor and Copilot rules files if the repo has them.
• /memory lists every memory file location across user and project scope, including files that do not exist yet. Select one to open it in your editor, and selecting a missing file creates it. It also holds the auto memory toggle.
• /context shows what actually loaded into this session. Look under the heading Memory files. If your file is not listed there, Claude cannot see it, no matter how good it is.

Auto memory: the notes Claude writes itself

The second memory system runs without you. As Claude works, it saves notes into a folder that belongs to the project, and reads them back at the start of later sessions. The path is ~/.claude/projects/<project>/memory/, where the project name is derived from the git repository. That means every worktree and subfolder of one repo shares a single memory folder, and it stays on your machine only.

Inside, MEMORY.md is an index with one line per memory, and each memory is its own small markdown file. Only the index loads at startup, and only its first 200 lines or 25 KB, whichever comes first. Topic files are read on demand. Claude records one of four types in each file's frontmatter:

• user: your role, expertise, and how you like to work.
• feedback: corrections you gave and approaches you confirmed.
• project: ongoing work, deadlines, decisions Claude cannot get from the code or git history.
• reference: where to find things outside the repo, like a ticket tracker or a dashboard.

Claude is supposed to skip anything it could derive from the codebase and anything your CLAUDE.md already says, so the two systems do not double up. It also does not save something every session. When you see "Saved 2 memories" in the interface, that is this folder being written. Saying "remember that the lead form needs a test name" in chat lands in auto memory. Saying "add this to CLAUDE.md" puts it in the file instead.

Audit it the same way you would audit a new employee's notebook. Run /memory, pick the auto memory folder, and read what is there. It is plain markdown you can edit or delete. If a stale fact keeps resurfacing, that is where it lives. To turn the feature off, use the toggle in /memory, which writes autoMemoryEnabled to your user settings, or set it to false in a single project's settings file. Lesson 9 covers those settings files in detail.

Try this yourself

Write your user file today. It is the layer you fully control and the one that pays off on every project. Open Claude Code anywhere, run /memory, select the user CLAUDE.md entry, and it will create the file and open it in your editor. Paste this and swap in three preferences that are actually yours.

# How I work

## Answers
- Lead with the next step. Short by default.
- Ask one question if a detail is missing instead of guessing.

## Code
- I use bun on every JavaScript project. Do not add package-lock.json.
- Search for an existing file or function before inventing a new one.
- Match the style already in the file you are editing.

## Git
- Commit messages: imperative mood, under 60 characters.
- Never force-push main.

## Business context
- I run a small web shop in St. George, Utah. Clients are local trades.

Save it, start a new session, and run /context. Under Memory files you should see ~/.claude/CLAUDE.md listed. If it is not there, check the path and the spelling, then try again. Once it shows up, give Claude a small task and watch which of your three preferences it honors without being asked. That is the whole feedback loop: write a line, confirm it loaded, see it change behavior, keep or cut it. Next lesson, you will make the project layer serve every coding tool you use, not just this one.