The CLAUDE.md File — Anthropic Primer (Persistent Project Memory for Claude Code)

Source: raw/The_CLAUDE.md_file.md — Anthropic-published YouTube primer (https://www.youtube.com/watch?v=O0FGCxkHM-U, fetched 2026-05-20).

The canonical Anthropic-side primer on the CLAUDE.md file — what it is, where it lives, how it loads, and the practice patterns to keep it useful instead of bloated. Short-form Anthropic explainer video framing CLAUDE.md as “an onboarding script for your code base” whose contents are silently appended to the user prompt at session start.

Key Takeaways

• Definition. CLAUDE.md is a markdown file at the root of your project that Claude Code reads automatically at every session start. The contents are appended to your prompt. Think of it as persistent project memory — without it, Claude has to re-explore the codebase every session and may guess wrong about stack, conventions, or commands.
• /init slash command scaffolds one for you by inspecting the codebase and generating a starter CLAUDE.md. Use it as the starting point rather than writing from scratch.
• Three-level hierarchy of memory files:
  • Project-level (<repo>/CLAUDE.md) — shared via version control, written for the team.
  • User-level (~/.claude/CLAUDE.md) — personal preferences (comment style, default editor, etc.) that travel across every project on your machine.
  • Directory-level (<subdir>/CLAUDE.md) — local scope conventions tied to a specific subdirectory.
• @<path> reference syntax. When you want Claude to read another doc on demand, reference it inline: Coding standards are in @./standards/coding-style.md. The path expands when relevant.
• Three working principles from Anthropic:
  1. Course-correct, then save. When you have to correct Claude (e.g., “always use server actions instead of API routes”), explicitly ask it to save the correction to memory so future sessions inherit the rule.
  2. Reference docs via @. Don’t inline whole docs — point to them with the @ syntax so they expand only when needed.
  3. Start without a CLAUDE.md. Anthropic recommends working without one initially so you can see where you actually need to course-correct. This keeps the file compact and load-bearing rather than speculatively bloated.
• Worked example from the video. A typical project-level CLAUDE.md:
  • Stack: “Next.js 15 app using the app router, Tailwind, and Drizzle ORM.”
  • Commands: dev server, run tests, lint.
  • Code style: two-space indentation, prefer named exports.
  • Routing: all API routes go in app/api; prefer server actions where possible.
  • With this file present, Create a React component produces correctly styled output on the first try — without it, Claude has to guess the framework.

Why this matters

“The difference between a frustrating Claude Code session and a productive one comes down to the context, and the CLAUDE.md file is how you provide that context.”

Anthropic’s framing positions CLAUDE.md as the highest-ROI single artifact in a Claude Code setup. The hierarchy means you don’t have to choose between team-shared and personal — you can have both layered together.

How this complements existing wiki coverage

• The wiki’s Memory Architectures Compared article covers the advanced memory systems (automemory, memarch, Hermes three-file pattern) that extend CLAUDE.md. This article covers the primer-layer Anthropic positioning the advanced systems sit on top of.
• The Architect Certification Technical Reference includes the hierarchy in its certification-prep material; this article gives the canonical Anthropic-side framing the certification expects.
• See also Anthropic’s official docs (Claude Code /init command + memory hierarchy) for the authoritative reference.

Try It

1. Run /init at the root of any project you use Claude Code on. Inspect the generated CLAUDE.md.
2. Trim it. Remove anything the model can infer trivially (e.g., “this is a Python project” — pyproject.toml is right there). Keep only the load-bearing context: stack version pins, command shortcuts, conventions that aren’t obvious from the code.
3. Add a user-level CLAUDE.md. Put your personal preferences (comment style, preferred test framework, “prefer named exports”) at ~/.claude/CLAUDE.md. These now apply to every project on your machine without polluting team-shared files.
4. Practice the course-correct loop. Next time you correct Claude on a project convention (“we use Drizzle, not Prisma”), say “save this to memory.” Future sessions inherit the rule.
5. Use @<path> for docs. Instead of inlining the full style guide, reference it: Coding standards are in @./docs/style-guide.md. The doc loads on demand only when relevant.

Related

• Claude Code Memory Architectures Compared — built-in automemory vs memarch vs Hermes three-file pattern; sits on top of the CLAUDE.md primer here.
• Architect Certification Technical Reference — includes the three-level hierarchy and common exam trap (“instructions placed in user-level not project-level”).
• Claude Code Hooks — InstructionsLoaded event fires when CLAUDE.md loads; use it for context-injection workflows.
• Claude Code Best Practices — broader Anthropic guidance on Claude Code workflow.
• Claude Code CLI Reference — claude init / claude --init flags.
• Karpathy Techniques for Claude Code — applies the CLAUDE.md primitive to a notable real-world workflow.
• Everything Claude Code (ECC) — Affaan Mustafa — community tooling that audits CLAUDE.md for security and bloat.

Open Questions

• The video doesn’t specify the maximum size Anthropic recommends for CLAUDE.md — the memory architecture comparison article calls out “~200 lines” but that’s third-party guidance, not Anthropic’s stated cap.
• Order of precedence when project-level and user-level CLAUDE.md files contradict each other (e.g., project says 2-space indent, user says 4-space) — not stated in this primer.