Field Guide
ModulesPhase 1: Foundations

1. Memory

/memory
The 30-second answer

"Every session starts with an empty context window. Claude Code carries knowledge forward two ways. CLAUDE.md files are instructions you write: build commands, conventions, rules. Auto memory is notes Claude writes for itself when you correct it. Both load at the start of every session. /memory is where you open and edit them, and where you turn auto memory on or off. One thing to know up front: memory is guidance, not enforcement. If something must never happen, that's a hook or a permission rule, not a line in CLAUDE.md."

That last sentence is the one that marks you as an architect rather than a user.

Say it yourself first, then compare.
See it

8 pictures, in order.

Use the arrow keys or the dots. Tap a picture to see it full size.

Two memory systems compared1 of 8
Know it

The facts someone can check.

Two systems, side by side
CLAUDE.md Auto memory
Who writes it You Claude
Holds Instructions and rules Learnings, preferences, corrections
Scope Org, user, project, or local One per git repo, shared across its worktrees
What loads The whole file (skipped entirely if over 4 MiB) First 200 lines or 25KB of MEMORY.md, whichever comes first
The four CLAUDE.md scopes, in load order (broadest first)
Scope Where it lives Who sees it
Managed policy macOS /Library/Application Support/ClaudeCode/CLAUDE.md, Linux /etc/claude-code/CLAUDE.md, Windows C:\Program Files\ClaudeCode\CLAUDE.md Everyone on the machine. Deployed by IT through MDM, Group Policy, Ansible
User ~/.claude/CLAUDE.md Just you, every project
Project ./CLAUDE.md or ./.claude/CLAUDE.md The team, through git
Local ./CLAUDE.local.md (gitignore it) Just you, this project

How they combine. Files are concatenated, not overridden. Claude reads them root-down, so the file closest to where you launched is read last. If two files contradict each other, Claude may follow either one. There is no "winner." The fix is to remove the conflict, not to rely on order.

Loading rules
  • CLAUDE.md files in your working directory and every folder above it load at launch.
  • CLAUDE.md files in subfolders load later, the first time Claude touches a file in that folder.
  • @path/to/file inside a CLAUDE.md pulls another file in. Up to four hops deep. Relative paths resolve from the file doing the importing. Imports help organize a file but do not save context, because the imported file loads too.
  • An import that points outside the project triggers a one-time approval dialog. That stops a teammate's commit from quietly pulling in files from your home directory.
  • HTML comments (<!-- like this -->) are stripped before loading. Notes for humans cost no context.
Rules: the scalable version of CLAUDE.md
  • .claude/rules/*.md, one topic per file (testing.md, security.md).
  • Add paths: frontmatter with globs ("src/api/**/*.ts") and the rule loads only when Claude works on a matching file. This is how a big monorepo keeps context lean.
  • ~/.claude/rules/ holds personal rules for every project.
  • claudeMdExcludes in settings skips other teams' CLAUDE.md files in a monorepo. It cannot exclude the managed one.
AGENTS.md (the cross-tool standard)
  • Claude Code reads AGENTS.md on its own, but only if there is no CLAUDE.md in the project. If both exist, it reads CLAUDE.md only.
  • To use both: put @AGENTS.md at the top of CLAUDE.md, or change Project instructions in /config.
Auto memory
  • On by default in local sessions. Toggle it in /memory, or set autoMemoryEnabled: false in a project's settings, or CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.
  • Stored at ~/.claude/projects/<project>/memory/: a MEMORY.md index plus one file per memory.
  • Four types: user, feedback, project, reference.
  • Only the index loads at startup. Topic files are read on demand.
  • Machine-local. It does not follow you to another laptop or to cloud sessions.
  • Subagents do not get the main conversation's auto memory (a fork does, because it copies the whole conversation).
  • Saying "remember that we use pnpm" goes to auto memory. Saying "add this to CLAUDE.md" goes to CLAUDE.md.
What /memory actually does

Lists every memory file location across user and project scope (including ones that don't exist yet, so you can create them), opens the one you pick in your editor, toggles auto memory, and opens the auto memory folder. To see what actually loaded, use /context, not /memory. That's Module 2.

Sizing guidance
  • Keep each CLAUDE.md under 200 lines. Longer files cost context and get followed less reliably.
  • Write instructions you could check: "Run npm test before committing", not "test your changes."
  • /doctor prompt-audit finds stale, conflicting, or broken instructions and proposes fixes.

After /compact: the project-root CLAUDE.md is re-read from disk and survives. Anything said only in chat is gone. Subfolder files and path rules reload when they next match.

Guidance vs enforcement

The point that separates an architect's answer from a user's. CLAUDE.md is delivered as a message after the system prompt, so Claude tries to follow it but nothing guarantees it. Anything that must never happen goes in a layer the client enforces.

Quiz

Answer out loud, then flip the card.

Mark each one honestly. Cards you miss stay flagged for review, in this browser.

0 of 8 right
Question 1

A customer says "we put 'never push to main' in CLAUDE.md and Claude pushed to main anyway." What happened, and what do you recommend?

CLAUDE.md is context, not enforcement. It's delivered as a message Claude reads, and there's no guarantee it complies. For anything that must never happen, use a permission deny rule or a PreToolUse hook, which the client enforces no matter what Claude decides. At org scale, put the deny rule in managed settings so developers can't remove it. Keep CLAUDE.md for guidance.

Question 2

The security team wants org-wide instructions no developer can turn off. Where do they go?

The managed policy CLAUDE.md, deployed by MDM to the OS path (or the claudeMd key inside managed-settings.json). claudeMdExcludes can't skip it. Caveat worth saying out loud: a developer who launches with CLAUDE.md loading turned off entirely skips it too, which is exactly why real enforcement lives in managed settings (permissions.deny, sandbox.enabled), not in managed CLAUDE.md.

Question 3

User CLAUDE.md says "use tabs." Project CLAUDE.md says "use 2 spaces." Which wins?

Neither is guaranteed. Files are concatenated, not overridden. The project file is read later, which helps, but Claude may follow either. Fix the conflict instead of relying on order.

Question 4

A monorepo's CLAUDE.md is 900 lines and Claude ignores half of it. What do you do?

Split it. Keep the root file under 200 lines with what applies everywhere. Move area-specific rules into .claude/rules/ with paths: frontmatter so they load only when relevant. Move multi-step procedures into skills, which load only when invoked. Don't just split into @imports, because imports still load everything. Run /doctor prompt-audit to find stale or conflicting lines.

Question 5

A team already uses AGENTS.md for Cursor and Codex. Do they need to rewrite it for Claude Code?

No. Claude Code reads AGENTS.md directly when there's no CLAUDE.md. If they also want Claude-specific instructions, create a CLAUDE.md whose first line is @AGENTS.md, then add the Claude-only lines below it. One shared file, no drift.

Question 6

A developer says Claude "remembered" something on their laptop but not on their desktop. Why?

Auto memory is machine-local, stored under ~/.claude/projects/ on each machine. It isn't synced. Anything the whole team needs on every machine belongs in the project CLAUDE.md in git.

Question 7

How do you confirm a CLAUDE.md actually loaded?

Run /context and look under Memory files. /memory shows locations you can edit; /context shows what's actually in the session. A subfolder CLAUDE.md won't appear there until Claude touches a file in that folder.

Question 8

What's the difference between CLAUDE.md, a rule, and a skill?

CLAUDE.md: loads every session, for facts that always apply. Rule with paths:: loads only when Claude works on matching files. Skill: loads only when invoked or when Claude judges it relevant, for procedures and workflows. Rough cost order: CLAUDE.md is always paid, a rule is paid when it matches, a skill is paid on use.

Traps

Wrong answers that sound right.

Before you tap, say why each one is wrong.

Try it

Three moves in a fresh project.

Facts checked against code.claude.com/docs/en/memory and code.claude.com/docs/en/commands on 2026-10-25. Claude Code ships fast: confirm anything that matters against the official docs.