CLAUDE.md — The Complete Beginner’s Guide (2026)

by

Every Claude Code session starts with amnesia. It has never seen your project before. It doesn’t know your tech stack, your coding conventions, which folders are off-limits, or what command runs your tests. Without help, it guesses — and guesses wrong often enough to be frustrating. Most beginners spend weeks re-explaining the same things at the start of every session and assume that’s just how Claude Code works. It isn’t. There’s a fix, it takes about 20 minutes to set up, and it’s called CLAUDE.md.

CLAUDE.md is a single plain-text file you place in your project folder. Claude Code reads it automatically before every session starts. Everything in it lands in Claude’s context before you type your first message — your project overview, your stack, your rules, your hard limits. A well-written CLAUDE.md is the difference between a Claude Code that feels generic and one that feels like a team member who already knows your codebase. This guide shows you exactly what to put in it, how to structure it, and the mistakes that make it less effective than it should be.

## 📋 TL;DR

– CLAUDE.md is a markdown file Claude Code reads automatically at the start of every session — it’s your project’s persistent memory.
– Without it, Claude starts every session blind and has to re-learn your project from scratch.
– Place it in your project root folder. The filename must be exactly CLAUDE.md — uppercase, case-sensitive.
– The fastest way to create one is by running /init inside a Claude Code session — it generates a starter file by reading your codebase.
– Keep it under ~200 lines. Longer isn’t better — it eats into your context budget and dilutes the rules that matter.
– You can have multiple CLAUDE.md files: one global (applies to every project) and one per-project (overrides the global).
– CLAUDE.md is different from a system prompt — it shapes how Claude works in your codebase, not how Claude behaves for end users.

Table of Contents

What CLAUDE.md Actually Does

To understand why CLAUDE.md matters so much, you need to know one fact about how Claude Code works: it has no memory between sessions. Every time you run claude in your terminal, Claude starts fresh. It has no idea what you worked on yesterday, what your project does, or what conventions you’ve been following.

This isn’t a bug — it’s how large language models work. They process the conversation in front of them and nothing else. The question is: what’s in that conversation before you type your first message?

Without CLAUDE.md, the answer is: not much. Claude reads your project files as you go, but it starts with no prior knowledge of what matters, what’s off-limits, or how your team works.

With CLAUDE.md, Claude Code reads your file and injects its contents into the conversation before your first message arrives. Technically, it gets added as a high-priority context block that Claude Code labels with instructions to treat it as overriding context. The practical result: Claude starts every session already knowing your project.

Think of it like this. Imagine hiring a contractor to work on your house. Without any briefing, they show up and start guessing — which rooms to avoid, what paint color you’re using, where the fuse box is. With a good briefing document, they walk in knowing the answers before they pick up a single tool. CLAUDE.md is that briefing document.

The impact is immediate and noticeable. Claude Code stops using the wrong test runner. It stops suggesting code that contradicts your architecture. It stops asking you to re-explain things you’ve explained before. For teams, it means every developer who opens Claude Code in your repo gets the same informed starting point, automatically.

Side-by-side terminal comparison — left shows Claude starting a session without CLAUDE.md and immediately asking “What framework are you using?” / right shows Claude starting a session with CLAUDE.md and immediately referencing the correct framework and project structure

What is CLAUDE.md?

How to Create Your First CLAUDE.md

There are two ways to create a CLAUDE.md: let Claude Code generate one for you, or write it yourself from a template. The fastest path is the first option.

Option 1: Use the /init command (recommended for beginners)

Open a Claude Code session inside your project directory and type:


/init

Claude Code reads your project — your package files, directory structure, config files, and existing documentation — and generates a starter CLAUDE.md based on what it finds. This takes about 30 seconds. The result is a solid first draft tailored to your actual codebase.

Important: treat /init as a starting point, not a finished product. Read through what it generated, correct anything wrong, and add the things it couldn’t infer — like which folders are off-limits, your deployment process, and team-specific conventions that aren’t visible in the code.

If a CLAUDE.md already exists in your project, /init will update it rather than overwrite it.

Option 2: Create it manually

Create a new file in your project root folder. Name it exactly CLAUDE.md — all caps, no spaces. The filename is case-sensitive. A file named claude.md or Claude.md will not be read automatically.

Paste in a template (the starter template later in this guide works well) and fill in your project’s details.

One critical detail: file location

The standard location is your project root — the top-level folder of your repository, the same folder where your package.json or requirements.txt or README.md lives. Claude Code looks for CLAUDE.md there first.

A project-level CLAUDE.md is also committable to Git, which means every developer on your team automatically gets the benefit when they use Claude Code. This is one of its most underrated features for team projects.

💡 Pro Tip: Run /init in the terminal session, then immediately spend five minutes editing the output. The generated file gets the facts right (your tech stack, your directory structure) but misses the judgment calls — the files Claude should never touch, the commands that break things, the shortcuts that only your team knows. Those five minutes of editing are the highest-value investment you can make in your Claude Code setup.

How to Create Your First CLAUDE.md File

[CLAUDE.md Templates — Copy and Use These]

The Five Sections That Belong in Every CLAUDE.md

CLAUDE.md can contain anything, but these five sections deliver the most value for the least space. Structure them as markdown headers — Claude reads and parses them clearly that way.

1. Project Overview (5–10 lines)

A plain-English summary of what this project is, who it’s for, and what it does. This sounds obvious, but it immediately gives Claude the frame of reference it needs to make good decisions throughout the session. One paragraph is enough.


## Project Overview
A B2B SaaS application for restaurant inventory management. 
Built with Next.js 15, TypeScript, and PostgreSQL via Supabase.
Serves around 200 restaurant clients. Deployed on Vercel.

2. Build and Test Commands (the single most valuable section)

The exact commands to run your tests, start your dev server, build for production, and run your linter. Claude Code uses these without asking. Getting these right eliminates a whole category of wrong-command errors.


## Commands
- Start dev server: `npm run dev`
- Run tests: `npm test` (or `npm test -- --watch` for watch mode)
- Run linter: `npm run lint`
- Build: `npm run build`
- Database migrations: `npm run db:migrate`

3. Architecture and Key Directories

Where things live in your project. The most important folders and files. How data flows. This is what lets Claude navigate a large codebase without reading every file first.


## Architecture
- `app/` — Next.js App Router pages and layouts
- `components/ui/` — Shared UI primitives (buttons, inputs, modals)
- `components/features/` — Feature-specific components
- `lib/` — Business logic, utilities, API clients
- `db/` — Database schema, migrations, Supabase types

4. Coding Conventions

Your house rules for how code is written. The things that aren’t enforced by your linter but that your team cares about. Keep this section short — only conventions Claude couldn’t infer from reading your files.


## Conventions
- TypeScript strict mode — no `any` types
- Functional components only (no class components)
- All API calls go through `lib/api-client.ts`
- Error messages must be user-facing strings, not internal codes
- Write tests for all utility functions in `lib/`

5. Off-Limits and Hard Rules

This is the section most people skip — and the one that prevents the most painful mistakes. Tell Claude explicitly what it must never do.


## Hard Rules
- NEVER modify `db/migrations/` directly — only generate new migrations
- NEVER touch `src/payments/` — all payment changes require a separate PR
- Do NOT run `npm run build` in this project — it will kill the dev server
- Do NOT commit directly to `main` — always work on a feature branch

💡 Pro Tip: The hard rules section is where you document the things that, if Claude got wrong, would cost you hours to fix. Think back to your worst Claude Code mistake — one where it touched something it shouldn’t have, or ran a destructive command. Write that rule down now. Your future self will thank you.

[What to Put in Your CLAUDE.md]

[CLAUDE.md Best Practices]

Global vs Project-Level CLAUDE.md

You’re not limited to one CLAUDE.md. Claude Code has a hierarchy of locations it reads from, and they layer on top of each other. Understanding this hierarchy lets you stop duplicating the same personal preferences across every project you work on.

The four locations, in load order:

Global (~/.claude/CLAUDE.md) — This file applies to every Claude Code session on your machine, regardless of which project you’re in. Use it for preferences that are about you, not about any specific project: your preferred coding style, your general rules, the kind of explanations you want, any universal conventions you follow everywhere.

Project root (CLAUDE.md in your repo’s root folder) — This is the standard project-level file. It’s the one you share with your team via Git. Use it for everything about this specific project: tech stack, commands, architecture, team conventions, hard limits.

Subdirectory (CLAUDE.md inside a subfolder) — Useful for monorepos where different parts of the project have different rules. If your repo contains both a frontend and a backend, each can have its own CLAUDE.md with context specific to that part. Claude loads the subdirectory CLAUDE.md when it’s working inside that directory.

User-specific project (.claude/CLAUDE.md inside your project, added to .gitignore) — For personal preferences that apply to this project but shouldn’t be shared with your team. Your local editor shortcuts, your personal workflow preferences, things only you care about.

The priority rule: more specific wins

When files conflict, the more specific (closer to the current directory) file takes precedence. A project CLAUDE.md overrides a global one. A subdirectory CLAUDE.md overrides the project root one.

A practical setup for most people: put your coding style preferences and general rules in your global ~/.claude/CLAUDE.md once, then never touch it again. Put every project in its own CLAUDE.md committed to the repo. That way your preferences are always active, and your team gets consistent project context automatically.

[CLAUDE.md Global vs Project Level]

Diagram showing the four CLAUDE.md locations in a file tree: home folder, project root, subdirectory, and .claude/ folder — with arrows showing which file “wins” when they conflict

A Starter Template You Can Copy Right Now

This template covers the five essential sections for any software project. Copy it, replace the placeholder text with your project’s real details, and you’ll have a working CLAUDE.md in under ten minutes.


# CLAUDE.md

## Project Overview
[One paragraph: what this project does, who uses it, the core purpose.]
[Example: "A REST API for a healthcare appointment booking platform. 
Patients use a React frontend (separate repo) to book appointments. 
This repo is the backend only."]

## Tech Stack
- Language: [e.g., Python 3.12]
- Framework: [e.g., FastAPI]
- Database: [e.g., PostgreSQL via SQLAlchemy]
- Testing: [e.g., pytest]
- Deployment: [e.g., AWS Lambda via Serverless Framework]

## Commands
- Start dev server: `[command]`
- Run tests: `[command]`
- Run single test: `[command]`
- Lint: `[command]`
- Format: `[command]`
- Build/deploy: `[command]`

## Architecture
- `[folder/]` — [what lives here]
- `[folder/]` — [what lives here]
- `[folder/]` — [what lives here]
[Add the 4–6 most important directories.]

## Coding Conventions
- [Convention 1 — things your linter doesn't enforce]
- [Convention 2]
- [Convention 3]
[Keep this short. Only include things Claude can't infer from the code.]

## Hard Rules — Read These First
- NEVER [destructive action] — [reason]
- NEVER modify [sensitive file/folder] — [reason]
- Do NOT run `[dangerous command]` — [reason]
- Always [important process] before [action]

## Current Work (optional — update as needed)
[Brief note on what's actively being worked on, if relevant.]
[Example: "Currently migrating from SQLAlchemy 1.x to 2.x. 
Don't refactor any models until the migration is complete."]

For framework-specific templates tailored to React/Next.js, Python, and Laravel/PHP projects, see the dedicated articles linked at the end of this guide.

[CLAUDE.md Templates — Copy and Use These]

CLAUDE.md for React/Next.js Projects

CLAUDE.md for Python Projects

CLAUDE.md for Laravel/PHP Projects

What NOT to Put in Your CLAUDE.md

Knowing what to leave out is as important as knowing what to include. A bloated CLAUDE.md is worse than a short one — every line consumes part of your context window budget at the start of every session, and content that’s always loaded but rarely relevant dilutes the rules that actually matter.

Don’t include things your linter already enforces. If ESLint catches trailing commas, you don’t need to put “always use trailing commas” in CLAUDE.md. Claude will follow the linter. Document the judgment calls, not the automated checks.

Don’t paste in your entire README. CLAUDE.md is a briefing, not a documentation dump. Claude can read your README if it needs to. CLAUDE.md should contain the things Claude needs to know before it looks at anything else — the context that shapes every decision.

Don’t include temporary or task-specific instructions. If you’re asking Claude to help with a specific refactor today, put that instruction in your prompt, not in CLAUDE.md. CLAUDE.md is for things that are true every session. Temporary context in a permanent file just becomes noise.

Don’t write paragraph after paragraph of style guidance. Bullets work better than prose here. Short, specific, unambiguous rules follow better than long explanations. “Use functional components” lands better than two paragraphs about why class components are considered legacy.

Don’t exceed ~200 lines. Multiple sources and Anthropic’s own guidance point to this as the practical ceiling. Beyond 200 lines, you start hitting a real problem: frontier models reliably follow roughly 150–200 instructions, and Claude Code’s own system prompt already takes up some of that budget. A 400-line CLAUDE.md doesn’t give Claude 400 rules — it gives it noise and quiet inconsistency.

The discipline is: write only what’s true every session. If something belongs in documentation, put it in documentation. If something belongs in a prompt, put it in a prompt. CLAUDE.md is for the durable, session-persistent context that shapes how Claude behaves across all tasks in this project.

How Long Should Your CLAUDE.md Be?

[CLAUDE.md Best Practices]

CLAUDE.md vs System Prompts — What’s the Difference?

If you’ve ever used Claude’s API directly, or built an application on top of Claude, you’ll have encountered system prompts — the instructions that tell Claude how to behave for your end users. A customer service bot has a system prompt that tells Claude to be helpful and only discuss topics related to the product. A writing assistant has a system prompt that defines the tone and format of responses.

CLAUDE.md and system prompts sound similar, but they operate at completely different layers and solve completely different problems.

CLAUDE.md shapes your development experience. It tells Claude Code how to work inside your codebase. It’s about commands, conventions, architecture, and rules for a developer — you — who is building something.

System prompts shape your users’ experience. They define how Claude behaves in the application you’re building and deploying for end users. They’re not about your development workflow at all.

Here’s a practical example. You’re building a customer support chatbot powered by Claude. Your CLAUDE.md tells Claude Code: “This is a Node.js project. Tests run with npm test. Don’t touch the prompts/ folder — it contains production system prompts.” Your system prompt (stored as a file in that prompts/ folder) tells Claude: “You are a helpful support agent for Acme Corp. Only answer questions about our products.”

These two things coexist, never interact directly, and each does its own job. Claude Code uses CLAUDE.md to help you build the chatbot. The chatbot uses the system prompt to talk to your users.

One subtle but important technical distinction: CLAUDE.md doesn’t go into Claude Code’s system prompt. It gets injected as a high-priority context block in the conversation messages — which is what allows it to be per-user and per-project while Claude Code’s actual system prompt stays the same for everyone. This design also keeps Anthropic’s prompt caching working efficiently, which is why your sessions don’t get dramatically more expensive just because you have a long CLAUDE.md.

[CLAUDE.md vs System Prompts]

Common Beginner Mistakes and How to Fix Them

Mistake 1: Not creating a CLAUDE.md at all

The problem: You’ve been using Claude Code for weeks, re-explaining your tech stack and conventions at the start of every session. You assume this is normal.

The fix: Run /init right now in your most-used project. Even the auto-generated file, unedited, will save you time. Spend five minutes refining it afterwards. The payoff is immediate — your very next session will start better.

Mistake 2: Getting the filename wrong

The problem: You create a file called claude.md or Claude.md or CLAUDE.MD. Claude Code doesn’t read it. Nothing changes. You assume CLAUDE.md doesn’t work.

The fix: The filename must be exactly CLAUDE.md — all capital letters, .md lowercase. It’s case-sensitive. If you’re not sure, open your terminal and run ls in your project root to confirm the exact name of the file.

Mistake 3: Making CLAUDE.md too long

The problem: You keep adding more and more to your CLAUDE.md. It grows to 400+ lines. Claude starts ignoring rules or following them inconsistently. You can’t figure out why.

The fix: Aim for under 200 lines. Be ruthless about what actually needs to be in there every session. Move detailed conventions into inline comments in your code, or into a linked document that Claude can read when relevant. The always-loaded file should be the essentials, not everything.

Mistake 4: Forgetting to include build and test commands

The problem: Claude Code keeps using the wrong test command, or asks you how to run the tests, or runs npm test when your project uses yarn jest --coverage.

The fix: The Commands section is the single highest-value part of CLAUDE.md. Make sure it’s there, make sure it’s accurate, and include the exact flags and variations you use most often. This is the first thing you should add if your current CLAUDE.md is missing it.

Mistake 5: Letting CLAUDE.md go stale

The problem: You refactored your project six months ago — the folder structure changed, you switched test frameworks, you moved to a different deployment process. Your CLAUDE.md still describes the old setup. Claude keeps making suggestions that don’t fit your current codebase.

The fix: Treat CLAUDE.md like any other important file in your project. When something significant changes in your project (framework upgrade, major refactor, new team conventions), update CLAUDE.md the same day. A stale CLAUDE.md is actively misleading — it’s better to have no CLAUDE.md than one with outdated commands that Claude will blindly run.

Quick Reference Cheatsheet

**Topic** **The answer**
What is CLAUDE.md? A markdown file Claude Code reads automatically before every session
Where does it go? Project root folder (same level as `package.json` or `README.md`)
Exact filename `CLAUDE.md` — case-sensitive, all caps
How to create it fast Run `/init` inside a Claude Code session
Ideal length Under ~200 lines — shorter is better
Five essential sections Project Overview, Commands, Architecture, Conventions, Hard Rules
Global CLAUDE.md location `~/.claude/CLAUDE.md` — applies to all projects on your machine
Priority when files conflict More specific file wins (project overrides global)
Private project preferences `.claude/CLAUDE.md` (add to `.gitignore`)
Subdirectory CLAUDE.md Place in any subfolder for context scoped to that directory
Team sharing Commit project-root CLAUDE.md to Git — everyone benefits automatically
When to update Whenever your tech stack, structure, or conventions change
What to leave out Things your linter enforces, entire README contents, temporary task instructions
CLAUDE.md vs system prompts CLAUDE.md = how Claude works in your codebase; system prompts = how Claude behaves for your users
Check current context usage `/context` inside a session shows how much CLAUDE.md is consuming

What to Learn Next

CLAUDE.md is the single highest-leverage thing you can set up in Claude Code. These articles go deeper on every aspect:

Start here:

Templates and examples:

Go deeper:

  • [What to Put in Your CLAUDE.md] — An exhaustive breakdown of every section you might include, with real examples from production CLAUDE.md files.
  • [CLAUDE.md Best Practices] — The rules experienced Claude Code users follow to keep their CLAUDE.md effective as projects grow.
  • How Long Should Your CLAUDE.md Be? — A practical guide to the length question, with the research behind the 200-line guideline.
  • [CLAUDE.md Global vs Project Level] — Deep dive into the four CLAUDE.md locations, how they layer, and the right content for each.

Related concepts:

  • [CLAUDE.md vs System Prompts] — Full comparison of the two mechanisms, who they’re for, and how they coexist in a project.

Key Takeaways

  • CLAUDE.md is Claude Code’s persistent memory for your project.** Without it, Claude starts every session blind. With it, Claude starts every session already knowing your tech stack, your commands, your architecture, and your rules. The difference in quality is immediate.
  • Create it with /init, then edit it yourself.** The /init command generates a solid first draft by reading your codebase. But it can’t infer your hard limits, your deployment quirks, or your team’s judgment calls. Those five minutes of manual editing are what make the difference.
  • Five sections cover most of what you need:** Project Overview, Commands, Architecture, Coding Conventions, and Hard Rules. The Commands section and the Hard Rules section deliver the most value per line.
  • Keep it under 200 lines.** Every line of CLAUDE.md consumes context budget at the start of every session. A lean, focused CLAUDE.md is more effective than a comprehensive one. Put the essentials in CLAUDE.md; put the details in documentation Claude can read when needed.
  • Use the global and project-level files together.** Your global ~/.claude/CLAUDE.md holds personal preferences that apply everywhere. Your project CLAUDE.md holds project-specific context committed to Git and shared with your team. Together they give you persistent, layered context across every project and every collaborator.

Last updated: July 2026. Claude Code is under active development — if anything here has changed, check Anthropic’s official documentation at docs.claude.com for the current details.