CLAUDE.md: The Complete Guide to Claude Code Memory

A CLAUDE.mdfile is Claude Code’s project memory file: a Markdown file whose contents are loaded into the model’s context automatically at the start of every session. Instead of re-explaining how to build the project or which conventions to follow, you write those instructions in CLAUDE.mdonce and Claude Code reads them every time. Because it’s always on, it’s also a recurring token cost — which is why the golden rule is to keep it tight and high-signal.

What is a CLAUDE.md file?

Think of CLAUDE.md as a README written for the agent rather than for a human contributor. A human-facing README explains the project to a person browsing GitHub; CLAUDE.mdtells Claude Code the operational details it needs to work effectively — the exact commands, the conventions, the architecture, and the boundaries. The key difference from a README is whenit’s used: Claude Code injects CLAUDE.mdinto context at the start of each session without you asking, so it’s always present in the model’s working memory.

That always-on behavior is the whole point, and also the constraint. It means a fact you put in CLAUDE.md never has to be rediscovered, but it also means every line is paid for in tokens on every request. A tight, bulleted CLAUDE.md beats a long one that buries the important rules in prose.

Where does CLAUDE.md live? The memory hierarchy

Claude Code doesn’t read a single CLAUDE.md— it reads several, from different scopes, and merges them. The further down (more specific) a file is, the higher its precedence when instructions overlap. Here’s the full hierarchy:

The subdirectory files are what make this powerful in a monorepo: a CLAUDE.mddeep in a package only enters context when you’re editing files in that package, so its rules don’t cost you anything — or muddy the agent’s focus — when you’re working elsewhere.

How do I create a CLAUDE.md file?

You don’t have to start from a blank file. The fastest way is the /initcommand: run it inside a project and Claude Code scans the repository — package files, directory structure, existing config — and drafts a starter CLAUDE.md capturing what it found. Treat that draft as a first pass, then prune and sharpen it.

For quick, in-the-moment additions there’s the # shortcut. Start a message with # during a session and Claude Code appends that line to your CLAUDE.mdas a memory — handy for capturing a convention the instant you notice the agent getting it wrong, without breaking flow to open the file.

1. 1

   Run /init inside the project

   Claude Code scans the repo — package files, directory structure, existing config.
2. 2

   Claude Code drafts a starter CLAUDE.md

   It captures what it found as a first pass.
3. 3

   Prune and sharpen it

   Edit it like any Markdown file — cut noise down to a tight, high-signal cheat sheet.
4. 4

   Append memories with the # shortcut

   Start a message with # during a session and Claude Code appends that line to CLAUDE.md.

Using @imports for one source of truth

A CLAUDE.md file can pull in other files with an @ reference. Writing @README.md or @docs/architecture.mdon its own line tells Claude Code to expand that file’s contents inline. Imports resolve recursively— an imported file can import others, up to roughly five hops — so you can compose your context from focused pieces instead of one sprawling file.

This is the modern replacement for copy-pasting. Rather than duplicating your architecture notes into CLAUDE.mdand watching the two drift, you keep one canonical doc and import it. It’s also the idiomatic way to reuse an existing AGENTS.md— more on that below.

# CLAUDE.md

## Commands
- Install: `pnpm install`
- Dev: `pnpm dev`
- Test: `pnpm test` (must pass before any commit)
- Lint + types: `pnpm lint && pnpm typecheck`

## Conventions
- TypeScript strict mode; named exports only
- Files under 800 lines, functions under 50
- Tailwind 4 syntax: `(--var)` parens, not `[var(--var)]`

## Architecture
@docs/architecture.md

## Don't
- Don't add a dependency without flagging it first
- Don't edit generated files under `/dist`

What to put in CLAUDE.md (and what not to)

Because every line is loaded on every session, the goal is maximum signal per token. The content that earns its place:

• Commands. The exact setup, build, test, and lint commands. An agent that can run your tests can verify its own work.
• Conventions.Stated as rules, not essays. “Named exports only” beats a paragraph on module philosophy.
• Architecture.A short map of where things live and how the pieces fit — ideally @-imported from a canonical doc.
• Don’ts.Explicit negative constraints prevent the most expensive mistakes (don’t touch generated files, don’t add deps silently).

What notto do: don’t paste your entire docs site, your changelog, or long design rationale. CLAUDE.md is a cheat sheet, not a knowledge base. If a body of guidance is long and only relevant to specific tasks, it belongs in a skill, not in always-on memory.

CLAUDE.md vs skills: facts vs procedures

The cleanest way to decide where something goes is the facts-versus- procedures test. CLAUDE.md holds always-on facts — the constraints and conventions Claude should never forget, loaded every session. Skills hold on-demand procedures— task-specific playbooks that load only when they’re relevant, so a twelve-step deployment runbook doesn’t cost you context when you’re writing a unit test.

Put another way: if it’s a rule that applies to all work in the repo, it goes in CLAUDE.md; if it’s a recipe for a particular kind of task, it’s a skill. For the full mental model and how skills are structured, see the guide to Claude Code skills.

CLAUDE.md vs AGENTS.md

AGENTS.mdis the portable, cross-tool standard — a plain-Markdown file read by Codex, Cursor, Copilot, Gemini, and dozens of other agents. CLAUDE.md is Claude-Code-only, but it trades portability for power: @imports, CLAUDE.local.md overrides, and the hierarchical memory described above.

The catch worth knowing: Claude Code does not read AGENTS.md natively (as of mid-2026). A repo with only an AGENTS.mdloads zero project instructions in Claude Code — silently, with no error. If your team has standardized on AGENTS.md, the two clean workarounds are a thin CLAUDE.md that does @AGENTS.md (Claude Code expands the import) or a symlink, ln -s AGENTS.md CLAUDE.md. This is fast-moving, so confirm against the current docs.

For the deeper dive on the open standard, read the AGENTS.md standard explained, and for the full five-way comparison across every rules file, see SKILL.md vs CLAUDE.md vs .cursorrules vs AGENTS.md. Migrating from another tool? Here’s how to convert a .cursorrules file to CLAUDE.md.

Managing CLAUDE.md across projects

One CLAUDE.md per repo is easy. The pain starts when you have ten repos that all share the same conventions, plus a CLAUDE.md for Claude Code, a .cursorrules for Cursor, and an AGENTS.mdfor everything else — all encoding the same rules, all drifting out of sync. The @import trick solves this withina single repo; it doesn’t help you keep the same standards consistent across projects and tools.

That’s the problem Skillwright exists to solve: keep your rules and skills in one canonical library, treat CLAUDE.mdas a first-class output, and compile to each tool’s format — Claude Code’s CLAUDE.md, Cursor’s .mdc, and AGENTS.md— so nothing drifts. Start from a vetted base with the templates, then read how to manage AI coding rules across tools to see the workflow end to end.

Frequently asked questions