What Is CLAUDE.md?

Module: Configuration | Lesson: 1 of 5 | Time: ~10 minutes

What You Will Learn

• What CLAUDE.md files are and why they exist
• Where CLAUDE.md files are located
• When Claude reads them during a session
• What kind of information belongs in a CLAUDE.md file

Prerequisites

• Completed Module 02: Core Features

Main Content

The Briefing Document for Claude

Every time you start a new Claude Code session, Claude has no memory of previous conversations. It does not remember what your project does, what language it uses, or what coding conventions you follow. CLAUDE.md solves this problem.

CLAUDE.md is a special markdown file that gives Claude persistent instructions about your project. Think of it as a briefing document that Claude reads before every conversation. Instead of repeating the same context every time you start a session, you write it once in CLAUDE.md and Claude picks it up automatically.

Why This Matters

Without a CLAUDE.md, you would need to re-explain your project setup, conventions, and preferences at the start of every session. With one, Claude already knows the important details before you type your first prompt.

Where CLAUDE.md Lives

CLAUDE.md can live in a few places:

Location	Scope	When to Use
Project root (next to your main files)	Whole project	Most common location
.claude/ folder in your project	Whole project	Keeps your root folder tidy
Subdirectories	That folder and below	Different rules for different areas
~/.claude/CLAUDE.md (your home folder)	All projects	Personal preferences that apply everywhere

On Windows, your home folder is typically C:\Users\YourName. So the global file would be at C:\Users\YourName\.claude\CLAUDE.md.

For most projects, placing a single CLAUDE.md file in the project root is all you need.

When Claude Reads It

Claude reads your CLAUDE.md file at the start of every session -- the moment you launch claude from your terminal inside that project folder. Claude also picks up CLAUDE.md files from parent directories, so if you have one in your home folder and one in your project, Claude reads both.

The reading order is:

1. Global CLAUDE.md (from ~/.claude/CLAUDE.md)
2. Project root CLAUDE.md (from your project folder)
3. Subdirectory CLAUDE.md files (if you navigate into a subfolder)

If instructions conflict, the more specific (closer to your working directory) file wins.

What to Put in CLAUDE.md

A good CLAUDE.md answers the questions Claude would otherwise need to ask you:

• Project description -- What does this project do? What is it for?
• Tech stack -- What language, framework, and tools does it use?
• Conventions -- Naming patterns, file organization, coding style
• Common commands -- How to build, test, and run the project
• Pitfalls -- Things that are easy to get wrong

Keep It Focused

CLAUDE.md is not documentation for humans -- it is instructions for Claude. Write it the way you would brief a new team member on their first day: short, specific, and practical.

Example CLAUDE.md for a Simple Project

Here is what a CLAUDE.md might look like for a beginner's web project:

# My Portfolio Website

## Project Overview
A personal portfolio website built with HTML, CSS, and vanilla JavaScript.
No frameworks. Hosted on GitHub Pages.

## Tech Stack
- HTML5, CSS3, JavaScript (ES6+)
- No build tools -- files are served directly
- Windows development environment

## File Structure
- index.html -- main page
- /css -- stylesheets
- /js -- JavaScript files
- /images -- image assets

## Conventions
- Use camelCase for JavaScript variables and functions
- Use kebab-case for CSS classes
- Always use const/let, never var
- Add alt text to all images

## Commands
- Open in browser: start index.html (Windows)
- No build step required

## Important Notes
- All paths must use forward slashes in HTML/CSS (not backslashes)
- Images should be under 500KB for fast loading

Notice how specific this is. It does not say "use appropriate naming" -- it says exactly which naming convention to use and where.

Creating CLAUDE.md with the /init Command

Claude Code has a built-in shortcut for creating your first CLAUDE.md. When you are inside a project folder, type:

/init

Claude will analyze your project and generate a starter CLAUDE.md file. You can then edit it to add more detail.

note

The /init command creates a reasonable starting point, but you will almost always want to customize the result. The auto-generated version is a foundation, not a finished product.

Try It Yourself

Let us create a basic CLAUDE.md for your practice folder.

1. Open your terminal and navigate to the practice folder you created in Module 01:

   cd C:\Users\YourName\claude-practice

2. Create a CLAUDE.md file using any text editor. In PowerShell you can open Notepad:

   notepad CLAUDE.md

3. Write the following content (customize it for your own practice project):

   # Claude Practice Project
   
   ## Overview
   A practice project for learning Claude Code on Windows.
   
   ## Environment
   - Windows with PowerShell
   - Using Claude Code CLI
   
   ## Conventions
   - Use PowerShell commands (not bash/Linux commands)
   - Keep files organized in folders by topic

4. Save the file and close the editor.

5. Start Claude Code in that folder:

   claude

6. Test it by asking Claude something like:

   What do you know about this project?

   Claude should reference the information from your CLAUDE.md file in its response.

Verification

If Claude mentions your project details (like "practice project" and "Windows with PowerShell"), your CLAUDE.md is working. If it seems unaware of these details, double-check that the file is named exactly CLAUDE.md (all caps) and is in the same folder where you launched Claude Code.

What You Learned

• CLAUDE.md is a markdown file that gives Claude persistent instructions about your project
• It lives in your project root, the .claude/ folder, or your home directory
• Claude reads it at the start of every session, so you never have to repeat project context
• A good CLAUDE.md includes your project description, tech stack, conventions, and common commands
• You can use /init to generate a starter CLAUDE.md, then customize it

---

Help Us Improve

How was this lesson? Take 2 minutes to share your feedback — it helps us make the tutorials better for everyone.

Give Feedback →

Next Up

Next: Writing Effective CLAUDE.md Files