Why This Matters#

Imagine you hired an assistant. On the first day, you explain the rules: “We write reports in this format,” “We respond to clients politely,” “Files go in this folder.” Without these rules, the assistant would do everything their own way.

CLAUDE.md is a file with such rules for Claude Code. You write your instructions there, and Claude follows them in every conversation. This saves time: no need to repeat the same things every time.

What is CLAUDE.md#

CLAUDE.md is a plain text file in Markdown format (.md extension). Markdown is a way to format text using simple symbols: # for headings, - for lists, ** for bold text.

Claude Code reads this file at the start of every conversation and follows the rules written there.

Types of CLAUDE.md Files#

Claude Code supports several levels of instructions. Think of them as rules at different scales:

💡 The ~ symbol means your home folder. For example, on Mac it’s /Users/your_name/.

Step-by-Step: Creating CLAUDE.md#

Step 1. Open Your Project Folder#

Navigate to your project folder in the terminal:

cd my-project

Step 2. Create the CLAUDE.md File#

Open a text editor and create a CLAUDE.md file in the project root. Here’s an example:

# Project Rules

## Code Style
- Write comments in English
- Use clear variable names
- Each function should be no longer than 20 lines

## Project Structure
- Source code is in the src/ folder
- Tests are in the tests/ folder
- Configuration is in the config/ folder

## Important Commands
- Start the project: npm start
- Run tests: npm test
- Build: npm run build

Step 3. Verify Claude Read the File#

Launch Claude Code in the project folder:

claude

Ask: “What project rules do you know?” — Claude should list what you wrote in CLAUDE.md.

Examples of Useful Instructions#

For a Website#

# Project: "Daisy" Café Website

## Technologies
- HTML, CSS, JavaScript
- Framework: none, pure code

## Rules
- All text in English
- Brand colors: #FF6B35 (orange), #004E89 (blue)
- Responsive layout for mobile devices

For Personal Settings (~/.claude/CLAUDE.md)#

# My Preferences

- Explain code in simple language
- Always add comments to code
- Suggest multiple solution options
- Respond in English

For Local Settings (CLAUDE.local.md)#

# My Local Settings

- My test server: http://localhost:3000
- For debugging I use port 9229

Claude’s Auto-Memory#

Besides CLAUDE.md files, Claude Code can remember information on its own. During work, it saves useful observations:

• Project patterns (how the code is structured)
• Solutions to complex problems
• Your work preferences

These notes are stored in ~/.claude/projects/<project>/memory/ and are loaded automatically.

Tips#

• ✅ Be specific: “Use 2-space indentation” is better than “Write nicely”
• ✅ Update the file when rules change
• ✅ Add CLAUDE.md to version control (Git) so the team uses the same rules
• ✅ Don’t add CLAUDE.local.md to Git — those are your personal settings

Lesson Summary#

• CLAUDE.md is an instruction file that Claude reads at the start of every conversation
• There are three levels: project (for the team), personal (for you everywhere), local (for you in one project)
• More specific settings take priority over general ones
• Claude also saves notes automatically (auto-memory)
• Good instructions save time and make working with Claude predictable