Learn Claude Code

CLAUDE.md explained: memory and /init

How CLAUDE.md memory files work in Claude Code, how /init creates one, the user, project and folder hierarchy, and what to put in yours.

Lesson 3.1⏱ 8 min read🚗 Daily driver❓ 3-question quiz
The short answer

CLAUDE.md is a markdown file Claude Code loads automatically at the start of every session, acting as its long-term memory for your project. Run /init to generate one, keep team rules in the project-level file, and personal preferences in ~/.claude/CLAUDE.md.

What CLAUDE.md is

Every new session, Claude starts fresh. CLAUDE.md fixes that: it's a plain markdown file that Claude Code reads automatically, so it always knows your project's essentials.

Good things to include:

  • How to build, run and test the project (npm run dev, npm test)
  • Coding conventions ("use British spelling in UI copy", "prefer async/await")
  • Architecture notes ("API routes live in /server/routes")
  • Gotchas ("never edit generated files in /dist")
Analogy: CLAUDE.md is the onboarding pack you'd hand a new starter on day one.

Create one in seconds with /init

Inside a project, run:

/init

Claude explores the codebase and writes a starter CLAUDE.md. Review it, trim the fluff, and add what only you know. Use /memory to see which memory files are loaded and open them for editing.

The memory hierarchy

  • User level: ~/.claude/CLAUDE.md. Your personal preferences across all projects. Not shared with anyone.
  • Project level: CLAUDE.md (or .claude/CLAUDE.md) at the repo root. Committed to git and shared with the whole team.
  • Folder level: a CLAUDE.md in a subfolder, picked up when Claude works in that part of the project.
Classic trap: a new teammate's Claude ignores your team conventions. Why? The rules were in someone's user-level file, not the project file. Team rules belong in the project CLAUDE.md.

You can also keep things modular: import other files with @path/to/file.md syntax, or put topic-specific rules in .claude/rules/: including rules that only load for matching file paths.

Keep it lean

CLAUDE.md is loaded into context every time, so every line costs attention. Aim for short, specific, high-value instructions. Put long, task-specific procedures into skills or custom commands instead (covered later).

Tip: when you catch yourself correcting Claude for the same thing twice, add a line to CLAUDE.md.

Check yourself

Three quick questions to check it stuck.

Ask the tutor

Stuck on something in this lesson? Ask the AI tutor. It answers from this lesson and points you to others that help. Answers are written by AI and can be wrong. Do not include personal details, passwords or company secrets.

Frequently asked

What is CLAUDE.md?

CLAUDE.md is a markdown memory file that Claude Code loads automatically at the start of each session. It holds project instructions such as build commands, conventions and architecture notes.

Where should I put CLAUDE.md?

Put team-wide rules in a CLAUDE.md at the project root so it is shared via git. Put personal preferences in ~/.claude/CLAUDE.md. Subfolders can have their own CLAUDE.md files too.

What does /init do in Claude Code?

/init analyses your codebase and generates a starter CLAUDE.md file describing the project, which you can then review and edit.