Skip to main content

CLAUDE.md & Memory Files

Beginner

If you do one thing to make Claude Code better, do this. CLAUDE.md is a plain-text file Claude reads at the start of every session — your project's permanent briefing.

What you'll learn
  • Why CLAUDE.md is the single highest-leverage Claude Code setting
  • How the memory hierarchy merges from global to project-specific
  • How to generate a starting file with /init and trim it down
  • What belongs in CLAUDE.md — and what to keep out
  • How @imports let you reference docs without duplicating them

Why it's the highest-leverage setting​

Without it, you re-explain your project every session ("we use pnpm, tests are in __tests__, don't touch /generated…"). With it, Claude already knows. Good instructions here improve every future interaction at once.

The memory hierarchy​

Claude Code reads memory from several places and merges them, roughly most-global to most-specific:

  • User memory — your personal preferences across every project.
  • Project memory (./CLAUDE.md, committed) — how this repo works. Shared with your team.
  • Nested — drop a CLAUDE.md in a subfolder for rules that only apply there.
Know your memory layers
Press Enter or Space to flip the card. Use the left and right arrow keys to move between cards.Term shown.
1 / 4

Generate a starting point​

Guided walkthrough1 of 3
  1. Claude inspects the code and drafts a CLAUDE.md for you automatically.

Generate a draft CLAUDE.md

/init

Grab a ready-made starter from CLAUDE.md Templates.

What to put in it​

  • What the project is, in two sentences.
  • Tech stack and how to run / test / lint.
  • Conventions Claude can't infer (naming, structure, commit style).
  • Guardrails: "run tests before declaring done", "never edit /vendor", "never commit secrets".

What NOT to put in it​

Watch out
  • Claude follows CLAUDE.md literally — stale, vague, or wishful instructions actively hurt.
  • Describe how the project actually works today; short and true beats long and aspirational.
  • Avoid giant pasted docs (use @imports instead), secrets, and rules you don't actually follow.
  • Review it periodically so it stays accurate as the project evolves.

Imports​

Pull in existing docs instead of duplicating them — e.g. reference your style guide with an @path/to/file import so there's one source of truth. See the official memory docs for the exact syntax.

Pro tip
  • One source of truth: reference a file with @imports rather than pasting its contents into CLAUDE.md.
  • If a doc already exists, link it — don't copy it. Copies drift out of date.

Check yourself​

Check yourself

0/3
  1. Which file does Claude Code read at the start of every session as your project's permanent briefing?
  2. What does running /init do in a project?
  3. What is the recommended way to include a large existing doc like a style guide?
Key takeaways
  • CLAUDE.md is the highest-leverage setting: it improves every future session at once.
  • Memory merges from global to specific: enterprise policy, then user, project, and nested CLAUDE.md files.
  • Start with /init, then edit the draft down to what is actually true.
  • Include the project summary, run/test/lint commands, conventions, and guardrails.
  • Keep it short and true — use @imports for big docs, and never commit secrets.

Next​