The gist
Imagine you're hiring a new employee. The first thing you do is explain: what the company is, how everything works, what the ground rules are. CLAUDE.md is exactly that kind of briefing for your agent (an autonomous program that does the work). You write it once, and the agent reads it at the start of every session.
Key concepts
- CLAUDE.md = a system prompt (a prompt is a text request to the AI) that the agent reads at the start of every session and keeps in its context
- Three layers: WHAT (what's here), WHY (why it's here), HOW (how to work)
- The brevity principle: every word costs tokens (tokens are the smallest units of text for an AI)
- Progressive loading: pointers instead of duplication
- /init: automatic CLAUDE.md generation for existing code
Theory
What CLAUDE.md is and why you need it
When you open a new conversation with Claude Code, the agent starts from zero. It doesn't remember what you built last time. It doesn't know how your project is set up. It doesn't know your preferences.
That creates a problem: every time, you have to explain the context again (the context is the content of the conversation the AI can see). "This project is in TypeScript (JavaScript with types), we use Supabase for the database, we have three services..." That's 5-10 minutes every session.
CLAUDE.md solves this problem.
It's a file named CLAUDE.md in the root of your project folder (spell the name in capitals exactly: on Linux, case matters). The agent reads it automatically at the start of every conversation. It's like a personal briefing: "Hi, I'm this project. Here's what you need to know to work with me."
Technically: CLAUDE.md is a Markdown file (Markdown is a simple text formatting language). The agent uses it as context that's "always on" for this project.
The three layers of CLAUDE.md
A well-written CLAUDE.md has three layers. Think of them as answers to three questions.
Layer 1: WHAT (what's here)
A technical description of the project. The agent needs to understand what parts the system is made of.
What to include:
- Tech stack: language (Python, JS or TS), frameworks, database
- Folder structure: what's in each folder and why
- Packages/libraries: which external dependencies are already installed
- Runtime environment: local, Docker, Cloudflare Workers, Vercel
Example:
## Tech stack - Python 3.11 - We use requests for HTTP requests - Supabase as the database (SDK: supabase-py) - Deployment: Render.com (cron job) ## Project structure /workflows/ — markdown files describing the workflows /tools/ — python scripts, one per tool /config/ — settings (JSON files) /logs/ — automatic run logs main.py — entry point
Layer 2: WHY (why each component exists)
This is the most frequently skipped layer. And the most important one for understanding.
The agent sees there's a /tools/ folder. But it doesn't know why the tools live in a separate folder instead of one file. Without that understanding, it might break the architecture, for example by adding a new function straight into main.py instead of creating a new tool.
Example:
## Architecture decisions **Why tools live in a separate folder:** Each tool is a self-contained function. Workflows call tools by name. This lets us reuse one tool across different workflows. **Why Supabase and not CSV:** We need persistence between runs. Each run appends to the database instead of overwriting it.
Layer 3: HOW (how the agent should work)
The working rules. How the agent should make decisions, what constraints exist, what to do in common situations.
Example:
## Working rules - When adding a new tool, create a separate file in /tools/, don't add it to main.py - All API keys are stored in the .env file; never hardcode them - Before creating a new file, check whether a similar one already exists - Code style: Python snake_case, comments in English - If a task needs a new package, ask before adding it
The brevity principle: tokens are money
The contents of CLAUDE.md stay in context for the entire session and count toward every request. If your CLAUDE.md is 2,000 words, those 2,000 words get added to every message you send.
Token prices depend on the model (current prices: What's current). But with dozens of requests a day, a bloated CLAUDE.md noticeably raises your costs and fills up the context window faster.
The rule: if you can leave something out, leave it out. If something is written in detail, ask yourself: "Does the agent really need this detail right now?"
What definitely belongs in CLAUDE.md:
- Key architecture decisions
- Unusual conventions the agent won't guess
- The project structure (one paragraph, not a detailed tree)
- Rules that must always be followed
What does NOT belong in CLAUDE.md:
- Obvious things ("use Python syntax")
- Long instructions you need once a month
- Full API documentation (API: Application Programming Interface) (a link to a file is better)
- The project's history and the reasoning behind every decision
Progressive loading: pointers instead of duplication
Here's a powerful pattern that saves tokens without losing quality:
Bad (duplication in CLAUDE.md):
## Perplexity API
Endpoint: https://api.perplexity.ai/chat/completions
Method: POST
Headers: Authorization: Bearer {API_KEY}, Content-Type: application/json
Body: {"model": "sonar", "messages": [...]}
Response example: {"choices": [{"message": {"content": "..."}}]}
...200 more lines of documentation...Good (a pointer):
## External APIs Documentation for all APIs: see /docs/api-reference.md Request examples are there too.
The agent will read /docs/api-reference.md only when it actually needs to: when it's working with that API. Not on every request.
This is called progressive loading: you load only what's needed right now.
/init: automatic CLAUDE.md generation
If you already have existing code (for example, you started from a ready-made template or inherited someone else's project), Claude Code can generate a CLAUDE.md itself by analyzing the code.
The command:
/initThe agent will:
- Look through the whole folder structure
- Read the key files (package.json, requirements.txt, the main scripts)
- Draft a CLAUDE.md with the three layers
- You edit and refine it
This doesn't replace writing CLAUDE.md from scratch for a new project, because then there's nothing to analyze yet. But for existing projects it saves 20-30 minutes.
What else Claude Code reads (as of October 2026)
CLAUDE.md isn't the only way to give the agent persistent context:
- AGENTS.md: Claude Code reads it too, if your project already has one (other agent tools use it as well).
.claude/rules/: rules tied to file types, for example separate rules for tests or for the frontend folder. This keeps the main CLAUDE.md short.- Auto memory: Claude writes down lessons from your corrections between sessions on its own. You manage it with the
/memorycommand.
Minimal CLAUDE.md template (cheat sheet)
Copy this template as a starting point for any new project:
# [Project name] — CLAUDE.md ## What this is (WHAT) [1-2 sentences: what the project does and who it's for] ## Stack - Language: [Python / JavaScript / TypeScript] - Frameworks: [if any] - Database: [if any] - APIs: [which external services] - Deployment: [where it's deployed] ## Project structure /workflows/ — workflows (markdown instructions) /tools/ — tools (one file per function) /config/ — settings (JSON (a key-value data format)/YAML (a config file format)) /docs/ — API documentation and reference /logs/ — automatic logs .env — API keys (NEVER commit to git (a code version control system)) ## Why it's built this way (WHY) - [Architecture decision 1: why this way and not another] - [Architecture decision 2] ## Working rules (HOW) - New tool = new file in /tools/, no edits to existing ones - API keys only in .env, never hardcode them - Before deploying, test on test data - Code style: [snake_case / camelCase], comments in [English/Spanish] - If a task needs a new package, ask before adding it
A real-world CLAUDE.md example for a newsletter workflow
# Newsletter Automation — CLAUDE.md ## What this is An automated weekly real estate news newsletter for the agency's clients. Runs on a schedule, gathers news, generates HTML and sends it through the Gmail API. ## Stack - Python 3.11 - Perplexity API — news search - Anthropic API — text generation - Gmail API — sending - Google Sheets API — recipient list - Scheduling: cron (a scheduler for automated tasks) via trigger.dev ## Structure /workflows/weekly_newsletter.md — the main workflow (read it before changing anything) /tools/ — a separate file for each tool /config/newsletter_style.json — newsletter style and parameters /config/recipients.json — recipient list (only update this file) .env — API keys (never commit) ## Rules - When changing the logic, update weekly_newsletter.md first, then the code - New tool = new file in /tools/, no edits to existing ones - Testing: always send to test@agency.example first, before the main send - Logs for every run are written to /logs/ automatically (don't touch this format)
Short, specific, and it covers everything the agent needs to know.
Practice
Assignment: Create a three-layer CLAUDE.md for a practice project.
Step 1: Choose your project (5 min)
Pick one of the automations you want to build (or use the practice example: "a weekly digest email for clients").
Step 2: Write the WHAT layer (8 min)
Create a CLAUDE.md file in the project folder. Write down the tech stack and the folder structure you're planning.
Step 3: Write the WHY layer (7 min)
Add an "Architecture decisions" section explaining why the stack and structure are the way they are.
Step 4: Write the HOW layer (5 min)
Add a "Working rules" section with 3-5 rules.
Step 5: Check it (5 min)
Ask Claude Code: "Read CLAUDE.md and tell me what you understand about this project and how to work with it." If the agent missed something important, refine CLAUDE.md.
Common mistakes
❌ Mistake: Writing a 3,000-word CLAUDE.md with full documentation for every API.
✅ Instead: CLAUDE.md is read with EVERY request = every word costs tokens. Keep it short (200-500 words). Move detailed documentation into separate files and link to them: "see /docs/api-reference.md."
❌ Mistake: Skipping the WHY layer and writing only WHAT and HOW.
✅ Instead: Without WHY, the agent doesn't understand the architecture decisions and may break the structure. Why are the tools in separate files? Why Supabase and not CSV? Explain briefly.
❌ Mistake: Forgetting to update CLAUDE.md when the project changes.
✅ Instead: When you add a new tool, change the stack or change the rules, update CLAUDE.md. An outdated system prompt is worse than none: the agent will follow the wrong instructions.
Tools and resources
- Claude Code: the main tool
- Markdown: the format CLAUDE.md is written in (headings with
#, lists with-) - Claude Code: memory and CLAUDE.md: official documentation on CLAUDE.md, rules and auto memory
- Anthropic Prompt Engineering: general principles for writing prompts
- The
/initcommand: automatic CLAUDE.md generation from an analysis of existing code
→ See the Four C's Framework lesson: CLAUDE.md as the carrier of the four C's
→ See the Prompting fundamentals lesson: principles for writing good prompts
→ See the WAT framework lesson: project folder structure
→ See the What Skills are lesson: how to add Capabilities to CLAUDE.md
Key takeaways
CLAUDE.md = your project's system prompt. The agent reads it at the start of every session. Set it up once and it always works.
Three layers: WHAT (what's here), WHY (why it's here), HOW (how to work). Without WHY, the agent will break the architecture, not out of malice.
Brevity matters: every extra word is extra tokens in every request. Use pointers instead of duplication.
Next lesson
→ WAT framework: Workflows, Agent, Tools
The mark stays in this browser only and is never sent anywhere. My progress