What is CLAUDE.md: Project Memory in Claude Code

CLAUDE.md is the file that determines whether Claude Code understands your project or works against it. Without it, every session starts from zero: no stack knowledge, no conventions, no architecture context.

With a well-written CLAUDE.md, Claude Code follows your patterns from the first prompt. This guide covers exactly what to put in it, how to structure it, and how to keep it working as the project grows.

Key Takeaways

• Persistent project memory: CLAUDE.md is a plain Markdown file Claude Code reads automatically at the start of every session.
• Content beats prompting: Stack details, naming conventions, and test commands eliminate more errors than any prompt technique can.
• Three scope levels exist: Project-level, directory-level, and user-level files serve different purposes across the memory architecture.
• Use /init to start: Running /init generates an accurate first draft from your project in under a minute.
• Operational, not documentary: Write CLAUDE.md for Claude Code, not for a human reader. Instructions, not explanations.
• Under 500 words for most projects: A bloated file dilutes the signal. Include only what changes Claude Code's behaviour.

AI App Development

Your Business. Powered by AI

We build AI-driven apps that don’t just solve problems—they transform how people experience your product.

Let's talk

What Is CLAUDE.md and Why Does It Exist?

CLAUDE.md is a plain Markdown file that Claude Code reads automatically at the start of every session, giving it persistent context about your project: stack, conventions, commands, and architecture decisions.

Claude Code has no memory between sessions. Each run starts fresh. If you are still getting Claude Code installed and configured, do that before continuing.

• No memory means no context: Without CLAUDE.md, Claude Code infers conventions from file contents alone, producing inconsistent naming and wrong commands.
• Every session starts from scratch: Architecture decisions made in session five are invisible to session six unless they are written down somewhere.
• CLAUDE.md fills the gap: It functions like an onboarding document for a new team member who forgets everything overnight.
• Wrong inferences cost time: Missed architecture patterns, incorrect test commands, and naming inconsistencies are all symptoms of a missing or poor CLAUDE.md.
• Generate a first draft fast: Run /init inside any Claude Code session to produce a starting file based on your project's detected structure.

The generated /init file needs editing, but it gives you accurate scaffolding in under a minute rather than starting from a blank page.

What Should You Actually Put in CLAUDE.md?

CLAUDE.md should contain the operational facts Claude Code cannot reliably infer from reading your files: your exact commands, your naming rules, and the architectural decisions that break things when ignored.

Every category below represents a class of errors CLAUDE.md prevents. If Claude Code keeps getting something wrong, it probably belongs in this file.

• Tech stack declaration: Framework, language, runtime version, and package manager, for example, "Next.js 14, TypeScript, pnpm."
• Development commands: Exact commands to run tests, start the dev server, build, and lint, including required flags and environment variables.
• Architecture rules: Where key directories live, what the data flow pattern is, and what Claude Code must never do (for example, no direct DB calls from client components).
• Naming conventions: Component vs utility vs hook naming rules, file structure patterns, and anything that differs from framework defaults.
• Exclusion test: If Claude Code can figure it out by reading two project files, leave it out. If it gets it wrong repeatedly, add it.

For real CLAUDE.md examples across project types including Next.js, REST APIs, and Python backends, that guide shows what these files look like in practice.

What Is the Difference Between CLAUDE.md and Claude Code's In-Session Memory?

CLAUDE.md is persistent, file-based, and survives every session end. In-session memory is the context window: everything visible in the current session only, discarded when the session closes.

Understanding how in-session memory works clarifies why CLAUDE.md fills a gap the context window alone cannot.

• File on disk vs ephemeral context: CLAUDE.md persists across restarts and updates because it is a file, not a memory state.
• Different content belongs in each: Project conventions go in CLAUDE.md; task-specific instructions belong as session prompts.
• Good CLAUDE.md example: "Always use Tailwind for styling" is a project rule and belongs in the file.
• Good session prompt example: "For this task, skip styling and focus on the data model" is session-specific and belongs in the prompt.
• CLAUDE.md cannot remember sessions: If a decision was made in session twelve, update CLAUDE.md manually. It does not update itself.

The practical test: if an instruction should apply every time Claude Code works on this project, it belongs in CLAUDE.md.

Where Should CLAUDE.md Live — and Are There Multiple Files?

CLAUDE.md has three scope levels: project-level at the root, directory-level inside subdirectories, and user-level at ~/.claude/CLAUDE.md. Each layer loads in that order, with later layers able to override earlier ones.

Most projects need at least one project-level file. Larger or team projects often benefit from all three layers.

• Project-level file: Placed at the project root, loaded automatically in every session run from that directory.
• Directory-level files: A CLAUDE.md inside /backend/ or /packages/api/ loads when Claude Code works within that scope.
• User-level file: Lives at ~/.claude/CLAUDE.md and applies across all projects. Use it for personal preferences, not project rules.
• Load order matters: User-level loads first, then project-level, then directory-level. Each can override the previous.
• When to use multiple files: Monorepos with distinct frontend and backend conventions benefit most from directory-level files.

CLAUDE.md placement is part of the broader question of structuring a project for Claude Code, since folder layout and naming conventions all affect how well Claude Code navigates the codebase.

How Do You Write a CLAUDE.md for an Existing Project?

Start with /init to generate a first draft, then make three targeted edits: add your exact test command with flags, your one non-negotiable architectural rule, and the convention Claude Code most commonly gets wrong.

The process of onboarding Claude Code to a codebase involves more than CLAUDE.md, but the memory file has the most lasting effect on output quality.

• What /init gets right: Language, framework, key directories, package manager, and main entry files, reliably, in most projects.
• What /init misses: Project-specific naming conventions, test commands with required flags, and architectural rules not obvious from file structure.
• The three manual additions: Your exact test command, your hardest architectural rule, and the convention Claude Code violates most on this specific project.
• Treat it like a maintained README: Update CLAUDE.md when the project changes significantly, such as a new framework, new test setup, or major refactor.
• Stale instructions cause errors: An instruction that was true six months ago but is not true now will produce consistent errors until corrected.

The editing pass after /init takes fifteen minutes and accounts for most of the improvement in output quality.

What Are the Best Practices for Keeping CLAUDE.md Effective?

A well-maintained CLAUDE.md is dense with accurate operational specifics, written as directives rather than descriptions, and pruned whenever instructions become stale or redundant.

Each practice below corresponds to a failure mode. If CLAUDE.md is not working as expected, one of these is usually the cause.

• Keep it under 500 words: Long files dilute high-signal instructions with low-value filler, making Claude Code less reliable.
• Write imperatives: "Use Tailwind for all styling" works better than "The project uses Tailwind CSS for styling purposes."
• Test it after writing: Start a new session after each update and check whether the first unprompted output follows your documented conventions.
• Version control it: CLAUDE.md belongs in git as part of developer tooling configuration, alongside .eslintrc and tsconfig.json.
• Remove stale instructions: An outdated rule is actively harmful. Claude Code follows what the file says, not what was once true.

For projects beyond a certain scale, managing context in large codebases covers the additional strategies needed when a single file is not sufficient.

How Do You Keep CLAUDE.md Effective as the Project Grows?

As projects grow, introduce directory-level CLAUDE.md files for subsystems with different conventions, update the project-level file on every significant architectural change, and document your MCP tool connections so Claude Code knows what it can access.

A single root-level file works for small projects. It stops being sufficient once the codebase has multiple distinct subsystems with conflicting conventions.

• Split by subsystem: Add /packages/api/CLAUDE.md and /packages/web/CLAUDE.md when frontend and backend have meaningfully different rules.
• Update on architectural changes: CLAUDE.md should be the first non-code file updated after any significant refactor, not the last.
• Document MCP connections: Your MCP server connections should be listed in CLAUDE.md so Claude Code knows which external tools are available in the session.
• Treat it as shared config: On team projects, CLAUDE.md changes should go through review like any other configuration file.

Undocumented CLAUDE.md changes cause inconsistent Claude Code behaviour across team members, the same way undocumented config changes cause environment drift.

Conclusion

CLAUDE.md is the highest-leverage configuration in Claude Code. More than prompting technique, more than model selection.

Developers getting consistent output from Claude Code almost universally have a tight, maintained CLAUDE.md. Those constantly re-explaining the project usually do not.

Run /init now to generate a first draft. Then add your exact test command, your one hard architectural rule, and the convention Claude Code most reliably gets wrong on your project. That is a working CLAUDE.md in under twenty minutes.

AI App Development

Your Business. Powered by AI

We build AI-driven apps that don’t just solve problems—they transform how people experience your product.

Let's talk

Want Claude Code Set Up Correctly for Your Project from Day One?

Most teams do not get the CLAUDE.md wrong on purpose. They write something generic, Claude Code behaves inconsistently, and they assume the tool is the problem. Usually the problem is a memory file that does not reflect how the project actually works.

At LowCode Agency, we are a strategic product team, not a dev shop. We configure Claude Code with the right CLAUDE.md, project structure, and memory architecture so it produces consistent, convention-compliant output from the first session, not after weeks of correction cycles.

• CLAUDE.md authoring: We write the memory file that reflects your actual stack, commands, naming rules, and architecture in operational language Claude Code follows reliably.
• Project structure setup: We organise directory layout, naming conventions, and file patterns so Claude Code navigates the codebase correctly without manual guidance.
• Multi-scope memory architecture: We configure project-level, directory-level, and user-level files for monorepos and team environments.
• MCP integration: We connect Claude Code to your databases, GitHub, and internal APIs so it has access to the tools the project actually needs.
• Convention testing: We run verification sessions after each configuration change to confirm Claude Code's output matches your documented patterns.
• Team onboarding: We document the Claude Code setup so every developer on the team gets consistent behaviour from their first session.
• AI implementation consulting: For teams building AI-assisted workflows at scale, our AI implementation consulting covers the full configuration and governance layer.

We have built 350+ products for clients including Coca-Cola, American Express, and Medtronic.

If you want Claude Code working correctly on your project from the first session, talk to our team.