Large Language Models are stateless — they don't automatically remember anything from previous sessions. Every time you start a new conversation, the model begins with a blank slate. For a coding assistant like Claude Code, that's a problem: without a way to persist project context, you'd have to re-explain your conventions, stack, and constraints over and over. CLAUDE.md is the answer — a persistent project handbook that Claude reads automatically whenever it works on your codebase.

Watch the walkthrough on our YouTube channel.

Why do we need CLAUDE.md?

Because the model has no memory across sessions, a project without its own instructions runs into the same friction again and again:

  • Claude Code cannot remember project conventions across sessions.
  • You must repeat the same instructions every time you start a new session.
  • Coding standards may be applied inconsistently.
  • Responses may vary from one session to the next.

CLAUDE.md solves this by providing persistent project instructions that Claude automatically reads whenever it works on your codebase.

Mental model: think of CLAUDE.md as a project handbook for Claude — written once, applied every session.

What is CLAUDE.md?

CLAUDE.md is a special project-level instruction file that Claude Code uses to guide its behavior while working on your project. Think of it as a persistent system prompt for your repository.

Instead of repeatedly telling Claude how things work, you define it once. A good CLAUDE.md captures things like:

  • How the project is structured
  • Coding conventions
  • Build and test commands
  • Preferred frameworks and tools
  • Project-specific rules

You write these instructions once, and Claude automatically loads them for every session.

How does /init work?

The /init command analyzes your project and generates an initial CLAUDE.md file so you don't have to start from a blank page.

# Generate an initial CLAUDE.md for the current project
/init

During initialization, Claude:

  • Scans high-signal configuration files such as package.json, requirements.txt, pom.xml, build.gradle, README.md, and any existing CLAUDE.md files.
  • Reads the project directory structure.
  • Detects the technology stack, folder organization, naming conventions, and common development commands.
  • Generates a CLAUDE.md in the project root containing the inferred project context.

The generated file is a starting point, not a finished product. Review it and customize it with your team's workflows, coding standards, constraints, and best practices.

What should CLAUDE.md contain?

A well-written CLAUDE.md typically includes:

Project overview

A brief description of the project and its purpose.

Coding standards

Guidelines that Claude should follow while generating or modifying code. For example:

  • Use Java 21.
  • Use Spring Boot 3.
  • Prefer constructor injection.
  • Follow the team's package structure.
  • Write unit tests for new features.

Critical rules

Project-specific constraints that Claude must never violate. For example:

  • Do not modify database.py unless absolutely necessary.
  • Patient IDs are provided by the client; never generate UUIDs automatically.
  • Never commit secrets or API keys.

Putting it together, a real CLAUDE.md might look like this:

# CLAUDE.md

## Project Overview
A patient-management REST API for a healthcare provider.
Built with Spring Boot and PostgreSQL.

## Coding Standards
- Use Java 21.
- Use Spring Boot 3.
- Prefer constructor injection over field injection.
- Follow the team's package structure (controller / service / repository).
- Write unit tests for every new feature.

## Critical Rules
- Do NOT modify database.py unless absolutely necessary.
- Patient IDs are provided by the client — never generate UUIDs automatically.
- Never commit secrets or API keys.

## Build & Test
- Build:  ./gradlew build
- Test:   ./gradlew test
- Run:    ./gradlew bootRun

Understanding the .claude directory

The .claude directory stores Claude Code's configuration files. It controls Claude's behavior either for a single project or across every project on your machine. The directory may contain:

  • Skills
  • Custom slash commands
  • Sub-agents
  • Hook configurations
  • Other Claude-related settings

Types of .claude directories

Project-level — ./.claude/

  • Scoped to a single project
  • Shared with the team
  • Usually committed to version control

User-level (global) — ~/.claude/

  • Personal configuration
  • Applies to every project
  • Not shared with other developers

Types of CLAUDE.md

Claude Code can load instructions from multiple locations, searching upward from the current working directory and combining everything it finds:

./CLAUDE.md               # Project-wide, shared with the team
./.claude/CLAUDE.md       # Additional project-specific instructions
./CLAUDE.local.md         # Personal, git-ignored preferences
./some/folder/CLAUDE.md   # Scoped to a subdirectory (monorepos)
  • Project root (./CLAUDE.md) — project-wide instructions shared by the team.
  • Project .claude folder (./.claude/CLAUDE.md) — additional project-specific instructions.
  • Local / personal (./CLAUDE.local.md) — personal preferences. This file is automatically ignored by Git, so developers can customize Claude without affecting the repository.
  • Subdirectory (./some/folder/CLAUDE.md) — Claude searches upward from the current working directory and loads any applicable CLAUDE.md or CLAUDE.local.md files it encounters. This is especially useful for large monorepositories where different folders require different instructions.

Understanding auto memory

Auto Memory is a persistent storage mechanism where Claude records useful project-specific information it discovers during development. For example, Claude might learn that:

  • The application uses INR instead of USD.
  • Authentication uses JWT.
  • The project follows Hexagonal Architecture.

Claude can reuse this information in future sessions without you having to repeat it.

Auto Memory complements CLAUDE.md — it does not replace it.

Important notes

  • Auto Memory is stored separately from CLAUDE.md.
  • Only the first 200 lines of MEMORY.md are loaded automatically.
  • Claude may create memory entries automatically when it identifies useful project patterns.
  • Developers can also manually add or update memory entries.

You can review or edit saved memory at any time:

# Review or edit everything Claude has remembered
/memory

Memory is stored at:

~/.claude/projects/<project>/memory/

Conclusion

Because LLMs are stateless, persistent context is what turns a generic coding assistant into one that actually understands your project. CLAUDE.md provides that context deliberately — your conventions, constraints, and commands — while Auto Memory and the .claude directory layer on the configuration and learned knowledge around it.

Start with /init, refine the generated file with your team's real standards, and commit it. From then on, every Claude Code session begins already knowing how your project works.

Frequently asked questions

What is CLAUDE.md?

CLAUDE.md is a project-level instruction file that Claude Code reads automatically whenever it works on your codebase. It acts as a persistent system prompt for your repository, capturing project structure, coding conventions, build and test commands, preferred tools, and project-specific rules.

Why do you need CLAUDE.md?

Because LLMs are stateless and forget everything between sessions, without CLAUDE.md you must re-explain your conventions, stack, and constraints every time. CLAUDE.md provides persistent project context so Claude applies your standards consistently across every session.

What does the /init command do?

The /init command analyzes your project — scanning config files like package.json, requirements.txt, and pom.xml, plus the directory structure — and generates an initial CLAUDE.md capturing the inferred stack, conventions, and commands. It is a starting point you then review and customize.

What should CLAUDE.md contain?

A good CLAUDE.md typically includes a project overview, coding standards (language and framework versions, style preferences, testing rules), and critical rules Claude must never violate (such as not modifying certain files or never committing secrets), along with build, test, and run commands.

What are the different types and locations of CLAUDE.md?

Claude Code loads instructions from several places: ./CLAUDE.md (project-wide, shared with the team), ./.claude/CLAUDE.md (additional project-specific instructions), ./CLAUDE.local.md (personal, git-ignored preferences), and any CLAUDE.md found by searching upward from a subdirectory — useful in monorepos.

What is Claude Code auto memory and how is it different from CLAUDE.md?

Auto Memory is a persistent store where Claude records useful project details it discovers during development and reuses them in future sessions. It complements CLAUDE.md rather than replacing it, is stored separately, and only the first 200 lines of MEMORY.md are loaded automatically.