CLAUDE.md Fundamentals

Explain what CLAUDE.md is and why it matters

Create a CLAUDE.md file with /init

Know what to include and what to leave out

Place CLAUDE.md files in the right locations

Maintain CLAUDE.md over time

Every time you start Claude Code, it reads a special file called CLAUDE.md. This file contains instructions, context, and rules that Claude follows throughout your session. It is like onboarding documentation for your AI teammate.

Without CLAUDE.md, you would need to explain your project's conventions, build commands, and preferences every session. With CLAUDE.md, Claude knows these things from the start.

This lesson teaches you how to create an effective CLAUDE.md file. You will learn what to include, what to leave out, and where to put the file for different scenarios.

CLAUDE.md is persistent context. Claude reads it at the start of every session in that project. The instructions inside shape how Claude behaves.

Use cases:

Build commands Claude cannot guess (your custom test runner)

Code style rules that differ from defaults (tabs instead of spaces)

Architecture decisions (why you use a specific pattern)

Project-specific gotchas (avoid this deprecated API)

Workflow rules (always run lint before committing)

Think of it as the knowledge a senior developer would share when onboarding a new team member. What do they need to know to work effectively on this codebase?

The fastest way to start is with the /init command:

Claude Code analyzes your project and generates a starter CLAUDE.md. It detects:

Build systems (npm, pip, cargo, etc.)

Test frameworks

Code patterns and conventions

Project structure

The generated file gives you a foundation to refine. Read through it and adjust what Claude got wrong or incomplete.

Interactive init:

Set the environment variable CLAUDE_CODE_NEW_INIT=1 for a more interactive initialization that walks through skills, hooks, and personal memory files.

Good CLAUDE.md files are concise and focused. Include only what Claude cannot figure out by reading your code.

Commands Claude cannot guess:

Code style rules that differ from defaults:

Project-specific gotchas:

Architecture decisions:

Just as important is knowing what not to include.

Things Claude can figure out from code:

What programming language you use

Basic project structure

Standard library conventions

Generic best practices Claude already knows:

"Write clean code"

"Use meaningful variable names"

"Add comments where helpful"

Long documentation:

If you have extensive API docs or style guides, link to them rather than pasting them in. CLAUDE.md should be scannable.

Frequently changing information:

Information that changes often becomes stale quickly. Keep CLAUDE.md focused on stable conventions.

The guideline: keep CLAUDE.md under 200 lines. If it is longer, Claude may start ignoring parts of it.

Where you put CLAUDE.md determines who sees it.

Project root (./CLAUDE.md):

Applies to this project. Check it into Git so your team shares the same context.

Home folder (~/.claude/CLAUDE.md):

Applies to all your Claude Code sessions across all projects. Good for personal preferences that are not project-specific.

Project root local (./CLAUDE.local.md):

Your personal notes for this project. Add to .gitignore so it is not shared. Good for your specific workflow preferences.

Parent directories:

In monorepos, both root/CLAUDE.md and root/frontend/CLAUDE.md are read when you work in the frontend directory. Rules accumulate.

Child directories:

Claude discovers CLAUDE.md files in subdirectories when working with files there. Rules in src/api/CLAUDE.md apply when working on API files.

CLAUDE.md can reference other files:

When Claude reads CLAUDE.md, it also loads the referenced files. This keeps CLAUDE.md short while making detailed information available.

CLAUDE.md is not write-once. Maintain it over time.

Add rules when Claude makes mistakes:

If Claude keeps doing something wrong, add a rule to prevent it. For example, if Claude keeps using the deprecated API, add:

Remove rules Claude follows naturally:

If a rule is not needed because Claude already does it correctly, remove it. Extra rules add noise.

Review periodically:

Every few weeks, read through CLAUDE.md. Remove outdated information. Add new conventions.

Test changes:

After editing CLAUDE.md, start a fresh session and see if Claude follows the new rules. Adjust wording if needed.

Sometimes Claude ignores rules buried in a long file. You can add emphasis:

These emphasized rules get more attention. Use sparingly, only for truly critical rules.

CLAUDE.md is persistent context read at the start of every session

Use /init to generate a starter file, then refine it

Include commands, style rules, gotchas, and architecture decisions

Leave out things Claude can figure out or already knows

Keep it under 200 lines and focused

Place files appropriately: project root for team, home folder for personal

Maintain over time by adding rules when Claude makes mistakes

Create or improve your CLAUDE.md:

Start Claude Code in a project.

Run /init to generate a starter CLAUDE.md.

Read through the generated file.

Add one command that Claude would not know.

Add one code style rule specific to your project.

Add one gotcha or important note.

Remove anything obvious that Claude would figure out anyway.

Start a new session and verify Claude follows your rules.

This exercise creates a CLAUDE.md that makes every future session better.

https://code.claude.com/docs/en/memory - CLAUDE.md documentation, file locations, auto-memory

https://www.builder.io/blog/claude-md-guide - Best practices for writing effective CLAUDE.md

https://code.claude.com/docs/en/best-practices - Keeping CLAUDE.md concise