Lesson 17: CLAUDE.md: Teaching Claude About Your Project

Day 17 of 50 · ~7 min read · Phase 3: Customization

The Opening Question

You've been using Claude Code for several days now. Every conversation, you're explaining the same things: how your tests run, where the config files are, what your naming conventions are, what your build process looks like.

It's repetitive. And it wastes context window space.

Here's the question: What if Claude already knew all of this? What if you could write down the conventions once, and Claude would read them automatically at the start of every conversation?

That's what CLAUDE.md is. It's not documentation for humans. It's instructions for Claude.

Discovery

Let's understand what CLAUDE.md does and when to use it.

Question 1: What goes into CLAUDE.md?

Think about everything you've been telling Claude over and over:

• "We use Jest for testing"
• "Run npm test to test"
• "We follow this style guide for naming"
• "All tests go in a /tests folder"
• "We import like this: import { thing } from '@project/thing'"
• "We use TypeScript"
• "The database schema is in /db/migrations"
• "We have this build step that runs first"

Claude probably asks you about these things in the first few messages of every conversation. That's wasted context.

CLAUDE.md is where you put the answers upfront.

Here's what a simple CLAUDE.md might contain:

# Project Overview
This is a React + Node.js web app for managing tasks.

## How to Test
Run `npm test`. Tests are in `/tests` and use Jest.

## How to Build
Run `npm run build`. Output goes to `/dist`.

## Code Style
- JavaScript/TypeScript
- Use async/await, not .then()
- Name components like MyComponent.jsx
- Use camelCase for functions and variables
- Indent with 2 spaces

## Project Structure
- `/src` — React components and frontend code
- `/server` — Node.js backend
- `/tests` — All test files
- `/public` — Static assets

That's it. No need for a 10,000-word guide. Just the essentials.

Pause and think: What information would save Claude the most questions in the first message of a conversation?

The answer is: the stuff you're tired of repeating.

Question 2: Where should CLAUDE.md live?

This is important: CLAUDE.md should live at the root of your project.

When you run claude in your project directory, Claude Code automatically loads CLAUDE.md from that directory (if it exists) and reads it at the start of every conversation. It becomes part of Claude's context from the beginning.

This is different from regular documentation. Regular docs go in /docs or /README.md and are for humans. CLAUDE.md goes at the root and is for Claude.

Project structure:

my-project/
├── CLAUDE.md          ← automatically loaded
├── README.md          ← for humans
├── src/
├── tests/
├── package.json
└── ...

The location matters because it signals: "This is project-specific configuration for Claude Code."

Pause and think: If CLAUDE.md is in a subfolder instead of the root, what would happen? Would Claude find it?

It might not. Claude Code is specifically designed to look for it in the project root. If you bury it in a subfolder, Claude won't automatically load it. You'd have to manually point Claude to it.

Question 3: How long should CLAUDE.md be?

Here's a hard rule: keep CLAUDE.md under 200 lines.

This matters because CLAUDE.md gets loaded every conversation. If it's enormous, it eats into your context window before you even start working.

The goal is to capture the essentials, not write a comprehensive guide. Think of it as a cheat sheet, not documentation.

Typical structure:

• Project overview (2–3 lines)
• How to test (2–3 lines)
• How to build (2–3 lines)
• Code style guidelines (5–10 lines)
• Project structure (5–10 lines)
• Important patterns or conventions (5–15 lines)
• Tools we use (2–5 lines)
• Common commands (5–10 lines)

That's probably 30–60 lines. Room for elaboration if your project is complex, but never a novel.

If you're tempted to write more than 200 lines, it probably means:

1. Your project is genuinely complex (consider breaking CLAUDE.md into sections)
2. You're over-explaining things (trust Claude to infer some details)
3. You should move some of it to regular documentation for humans

Pause and think: Why would a 200-line CLAUDE.md be better than a 1000-line one, even if the 1000-line version had more information?

Because 200 lines costs less context window, loads faster mentally, and forces you to prioritize what actually matters. If Claude needs more details, it can ask or read the regular docs.

Question 4: What's the difference between CLAUDE.md and ad-hoc instructions?

You've probably given Claude ad-hoc instructions before:

"In this project, we use this pattern for error handling. Here's an example. Keep that in mind."

That instruction lives in the conversation. It's useful for that conversation, but forgotten in the next one.

CLAUDE.md is persistent. It's read every time.

But there's a difference in scope:

• CLAUDE.md: Project-wide conventions that apply to all future work
• Ad-hoc instructions: Specific guidance for this task or this conversation

Example:

• CLAUDE.md: "We use async/await for asynchronous operations"
• Ad-hoc: "For this specific refactor, prioritize clarity over performance"

When should you add something to CLAUDE.md?

Ask: "Will I need to tell Claude this again in a future conversation?"

If yes, add it to CLAUDE.md. If no (it's specific to this task), keep it as an ad-hoc instruction.

Over time, as you notice yourself repeating instructions, you gradually build CLAUDE.md. It becomes a living document that captures your project's personality.

Pause and think: What happens if you put too many ad-hoc instructions in CLAUDE.md? When would you regret that decision?

If the instruction is too specific or temporary, it clutters CLAUDE.md and becomes noise. Claude reads it, incorporates it, and then follows it for tasks where it doesn't apply. Better to keep CLAUDE.md focused on lasting conventions.

The Insight

Here's what CLAUDE.md really is:

CLAUDE.md is a compact file at your project root that teaches Claude your project's conventions, style, build process, and testing strategy — all loaded automatically at the start of every conversation. It's not documentation for humans. It's configuration for Claude Code. It transforms Claude from a generic AI assistant into a specialized partner for your specific project.

The mental model: Think of CLAUDE.md as your project's working agreement with Claude. It's like onboarding a new team member: "Here's how we work here. Here are our conventions. Here's how to run tests. Here's our style." Claude reads it once at the start, and from then on, it works like a team member who already knows the project.

Try It

You're going to build your first CLAUDE.md.

1. Pick a project (real or test project)

2. Think about what you've repeated to Claude. What questions does Claude always ask?

   • How do you run tests?
   • What's your code style?
   • Where do files go?
   • How do you build?

3. Create CLAUDE.md at the project root:

   touch CLAUDE.md
   

4. Write a simple version:

   • Project overview (what is this project?)
   • How to test (what command runs tests?)
   • How to build (what command builds?)
   • Code style (key conventions)
   • Project structure (quick tour of important folders)

5. Start a conversation: claude

6. Watch Claude read CLAUDE.md automatically. It should mention it: "I see you have a CLAUDE.md file. I've read it and understand your project uses [test framework], follows [style], etc."

7. Notice the difference:

   • Claude doesn't ask how to test — it already knows
   • Claude follows your style without you explaining it
   • Claude understands the project structure
   • You start deeper in the conversation, not explaining basics

8. Over the next few conversations, notice what Claude asks about that's not in CLAUDE.md. Consider whether those things should be added.

9. Keep it updated. When you change how you test, update CLAUDE.md. When you adopt a new convention, add it. CLAUDE.md grows with your project.

Key Concepts Introduced

Bridge to Lesson 18

You now understand how to teach Claude about your project at the start of every conversation. CLAUDE.md sets the baseline. But there's more nuance to this: permissions and access control.

Claude Code is powerful — it can read files, run commands, edit code, push to git. But you should control what Claude can do in your project.

Next lesson's question: How do you define what Claude is allowed to do?

We'll explore permissions, safety, and how to set boundaries on Claude's access and actions so you stay in full control of your codebase.

← Back to Curriculum · Lesson 18 →