How to Write CLAUDE.md | Memory Configuration and File Placement for Claude Code

What Is CLAUDE.md — The "Instruction File" Claude Reads Every Time

CLAUDE.md is a Markdown file that Claude Code automatically reads at the start of each session. It plays a role similar to the onboarding documentation you hand to a new team member — except the reader is Claude, not a person.

Every Claude Code session starts with a completely blank context window. This means you would need to re-explain project build commands, code conventions, architecture decisions, and other "always-needed background information" with every prompt. By writing these in CLAUDE.md, that content is loaded at the beginning of the conversation, eliminating repetitive explanations.

The official blog describes this property as: "CLAUDE.md is not documentation — it's a behavioral contract between the team and the AI. Every line should change how Claude behaves; if it doesn't, remove it." (source). The key idea is that CLAUDE.md is not a place for notes — it should contain only instructions that actually change Claude's behavior.

The Difference Between CLAUDE.md and Automatic Memory (Two Memory Systems)

Claude Code has two mechanisms for retaining knowledge across sessions. Both are loaded at the start of a conversation, but they serve distinct roles.

• CLAUDE.md files: Instructions and rules you write. Describe coding standards, workflows, project architecture — anything representing "how I want Claude to behave."
• Automatic memory: Notes Claude writes itself. Claude learns from your corrections and preferences, accumulating knowledge about build commands, debugging insights, and code style tendencies.

In short: use CLAUDE.md when you want to actively guide Claude's behavior; use automatic memory when you want Claude to learn from your correction history without manual effort. Note that both are treated as context (reference information), not enforced configuration. If you need to reliably block certain operations, use a PreToolUse hook rather than CLAUDE.md.

Where to Place CLAUDE.md and Load Order (4 Scopes)

The scope of a CLAUDE.md file depends on where you place it. The official documentation lists the following 4 types, loaded from broadest to narrowest scope:

1. Enterprise policy (organization-wide): Organization-wide instructions distributed by IT/DevOps. On macOS: /Library/Application Support/ClaudeCode/CLAUDE.md; on Linux/WSL: /etc/claude-code/CLAUDE.md; on Windows: C:\Program Files\ClaudeCode\CLAUDE.md.
2. User instructions (all projects): ~/.claude/CLAUDE.md. Your personal preferences (code style, tool shortcuts, etc.), applied across all projects.
3. Project instructions (team-shared): ./CLAUDE.md or ./.claude/CLAUDE.md. Committed to version control and shared with the team as project-wide standards.
4. Local instructions (personal only): ./CLAUDE.local.md. Preferences specific to the project but not meant to be shared. Add to .gitignore.

Files are loaded from broadest to narrowest, with later-loaded instructions acting as closer context for Claude. Additionally, Claude Code traverses the directory tree from the current directory up toward the root, concatenating CLAUDE.md files found at each level. For example, launching from foo/bar/ loads foo/CLAUDE.md followed by foo/bar/CLAUDE.md. CLAUDE.md files in subdirectories are not loaded at startup — they are loaded on demand when Claude reads files in that folder.

How to Write CLAUDE.md — 3 Principles for Effective Instructions

CLAUDE.md is loaded into the context window at every session, consuming tokens alongside the conversation. Long, vague files reduce compliance, so the official documentation recommends three principles:

1. Size: Aim for 200 lines or fewer per file. The longer the file, the more context it consumes and the lower the compliance rate. If it grows too large, split it using .claude/rules/ or @import (described below).
2. Structure: Use Markdown headings and bullet points to group related instructions. Claude scans structure the same way humans do — organized sections are easier to follow.
3. Specificity: Write instructions that are specific enough to be verifiable.

The third principle — specificity — makes the biggest difference. The official documentation offers clear contrasts:

• Not "format code appropriately" — instead, "use 2-space indentation"
• Not "test your changes" — instead, "run npm test before committing"
• Not "keep files organized" — instead, "place API handlers in src/api/handlers/"

Also, when instructions conflict, Claude will arbitrarily choose one. Review and remove outdated rules regularly.

Auto-Generating with the /init Command

If writing from scratch feels daunting, running /init is the quickest path. Claude analyzes your codebase and automatically generates a CLAUDE.md containing the build commands, test procedures, and project conventions it finds. If a CLAUDE.md already exists, it will suggest improvements rather than overwriting it.

The efficient approach is to use the generated template as a base, then manually add team-specific rules that Claude cannot discover on its own — naming conventions, review policies, pitfalls to avoid, and so on.

Organizing Rules with @import and .claude/rules

When CLAUDE.md grows large, you can split its contents into external files. There are two approaches.

The first is @import (importing). Use the @path/to/file syntax to include another file. Relative paths are resolved from the importing file's location, and recursive imports support up to 4 levels of nesting. For example:

Refer to @README for project overview and @package.json for npm commands.

# Additional Instructions
- See @docs/git-instructions.md for the git workflow

Note that imported files are also loaded at startup, so this does not reduce token usage — the purpose is organization only.

The second approach is the .claude/rules/ directory. Split instructions into topic-specific Markdown files such as testing.md and security.md. By adding a YAML frontmatter paths field, you can make a given rule file load only when editing specific files.

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules
- All API endpoints must include input validation
- Use the standard error response format

These "path-specific rules" avoid consuming context when irrelevant, reducing noise while conserving context capacity. For procedures that are only needed for specific tasks rather than always, consider splitting them into Skills rather than rules.

To summarize the two approaches:

• @import — Always loads the entire file at startup. Purpose: organization. Does not reduce tokens.
• .claude/rules/ — Loads only when editing matching files. Purpose: token savings.

The deciding factor is "when should the rule be loaded?" If you want to reorganize a growing CLAUDE.md first, use @import. If you want to limit context consumption to specific tasks, use .claude/rules/.

Relationship with AGENTS.md (Coexisting with Other Tools)

Some users already have an AGENTS.md for other coding tools. Claude Code reads CLAUDE.md, not AGENTS.md. To avoid duplication, import AGENTS.md from within CLAUDE.md:

@AGENTS.md

## Claude Code
Use Plan Mode for changes under `src/billing/`

If you have no Claude-specific additions, a symlink (ln -s AGENTS.md CLAUDE.md) also works. On Windows, symlinks require administrator privileges, so use the @AGENTS.md import approach instead.

Does CLAUDE.md Work the Same Way via Vertex AI?

Whether you use Claude Code through Anthropic directly or through Google Cloud's Vertex AI, the CLAUDE.md specification is exactly the same. Only the authentication and billing path differs — the memory loading specification is common to both.

Specifically, all four scopes (enterprise policy /etc/claude-code/CLAUDE.md, user ~/.claude/CLAUDE.md, project ./CLAUDE.md, local CLAUDE.local.md) are active regardless of the access path, and organization-wide policy distribution works the same way via Vertex. For setup instructions using Vertex AI, see "How to Use Claude Code with Google."

Troubleshooting When CLAUDE.md Doesn't Seem to Work

When Claude isn't following instructions you wrote, work through the following steps:

1. Check if it's being loaded: Run /memory to display a list of all CLAUDE.md, CLAUDE.local.md, and rule files loaded in the current session. If yours isn't listed, Claude isn't reading it.
2. Review the file location: Confirm that the CLAUDE.md in question is placed at a level that gets loaded for the session (the project root or a parent directory).
3. Make instructions more specific: As described above, rewrite vague phrasing like "appropriately" into verifiable expressions like "2 spaces."
4. Look for conflicts: Check whether any CLAUDE.md files or rules contain contradictory instructions.

It is worth noting that CLAUDE.md is not "the system prompt itself" — it is context passed as a subsequent user message. Strict compliance is not guaranteed. For processing that must reliably run at specific moments — such as before a commit or after editing a file — write it as a hook. Hooks run as system commands on a fixed lifecycle and are not subject to Claude's judgment.

One more note: even if you use /compact to compress the conversation, the CLAUDE.md at the project root is reloaded from disk and is not lost. If instructions appear to disappear after compressing, they were either passed only during the conversation or belong to a subdirectory CLAUDE.md that has not been reloaded yet. For any instruction you want to persist, write it in CLAUDE.md rather than relying on the conversation.

Summary

CLAUDE.md is an "instruction file" that eliminates the need to repeat the same explanations to Claude Code every time, letting you write project rules once and have them apply across all sessions. Key takeaways:

• What it is: An instruction file read every session. Two systems: CLAUDE.md you write, and automatic memory Claude writes.
• Placement: 4 scopes — enterprise policy / user (~/.claude/CLAUDE.md) / project (./CLAUDE.md) / local (CLAUDE.local.md). Loaded from broadest to narrowest.
• Writing: 3 principles — under 200 lines, structured, verifiably specific. Use /init to generate a template; organize with @import and .claude/rules/.
• Limitations: Context, not enforcement. Use hooks for guaranteed control.

The recommended starting point is to run /init to generate a template, then add the explanations you find yourself repeating one by one.

Sources:

• Claude Code official documentation "How Claude remembers your project" https://code.claude.com/docs/en/memory
• Anthropic official blog "Using CLAUDE.md files" https://claude.com/blog/using-claude-md-files