07. Context Is Everything: CLAUDE.md and Projects

07. Context Is Everything: CLAUDE.md and Projects — Yaiment

Why Claude Forgets Everything

Every new Claude Code session starts completely blank. Claude does not remember what you said yesterday. It does not know your project. It does not remember the rules you set last time. Every session, you start from zero.

A session is the time between when you open Claude Code and when you close it. Like a phone call. When you hang up, the call is over. The next call starts fresh.

That creates a real problem. You end up re-explaining the same things every single time. "This is a React project." "Always use short functions." "The important files are in the /src folder." It gets old fast.

Imagine hiring a talented assistant who forgets everything overnight. Every morning, they do not know your name, your project, or the rules you set. You explain it all from scratch. Every day. That is Claude without a fix in place.

The Fix: CLAUDE.md

The fix is a file called CLAUDE.md. The .md part stands for markdown, which is just plain text with a few simple symbols for headers and lists. The # at the start of a line marks a heading. A dash at the start of a line marks a bullet. Any text editor works.

You place CLAUDE.md in your project folder. When Claude Code starts up, it reads this file automatically and injects its contents into the session before you type a single message. Claude already knows what is in it.

It works like a sticky note you leave on the office door before a meeting. The consultant reads it on the way in. When they sit down, they already know the ground rules.

One important thing: Claude reads this file. It does not write to it. If you want the file to change, you change it yourself.

Info

Tip: Keep your CLAUDE.md under 200 lines. Files longer than that still load, but Claude follows the instructions less reliably because they consume more of the session's working memory. Three to five sentences about the project, a couple of rules, and a list of key folders is enough to start.

What Goes in Your CLAUDE.md

Keep it short and honest. Here is what belongs in it:

What the project is and what it is for
The tools or technology involved, even vaguely ("this is a website built with React")
Rules Claude should follow, like tone, what not to delete, or naming conventions
Which folders matter and what they contain
Anything you would spend a paragraph explaining to a new helper

Here is a simple example:

# My Blog Project
 
## What this is
A personal blog I built with a friend. It uses Next.js (a website framework,
which is a pre-built collection of code that gives you a head start).
The main content lives in the /posts folder. Each file is one blog post.
 
## Rules
- Always write in a casual, conversational tone
- Prefer short functions over long ones
- Never delete existing content (ask first)
 
## Key files
- /posts/ : all blog content, one .md file per post
- /components/ : reusable pieces of the website
- /pages/ : the actual pages visitors see

You do not need to understand the technology to write a useful CLAUDE.md. Write it in plain English. Claude figures out the technical parts.

One common mistake: vague instructions. "Keep code organized" does nothing. "All API handlers go in src/api/handlers/" is something Claude can actually follow. Be concrete.

Global vs. Project-Level CLAUDE.md

There are two places you can put a CLAUDE.md, and they serve different purposes.

The first is inside your project folder. This is the one you will use most. It tells Claude about the specific project you are working on right now.

The second is in a hidden folder on your computer, at ~/.claude/CLAUDE.md. The ~ symbol is shorthand for your home folder, the one where your Desktop and Documents folders live. The .claude folder inside it is where Claude Code stores its personal configuration.

Claude reads the global file first, then the project file on top of it. On a conflict, the project file usually wins, because Claude reads it last. What to put in the global one: your name, your preferred response style, things that are always true no matter what project you are in. "Always explain things in plain English." "My name is Enrique." That kind of thing.

Info

Warning: CLAUDE.md is a regular text file. Claude reads it but does not update it automatically. If your project changes significantly, update your CLAUDE.md to match. Claude cannot do this unless you ask it to.

Sub-folder CLAUDE.md Files

You can also put a CLAUDE.md inside a sub-folder. This is useful when one part of your project has its own rules. A tests/CLAUDE.md could say "always write assertions before implementations." A docs/CLAUDE.md could say "write in plain English, no jargon."

The rule: files above your current working directory load at session start. Files in sub-folders load on demand, when Claude reads a file in that directory. This keeps the initial session lean.

If a project gets complex, Claude Code also supports a .claude/rules/ folder for path-scoped rules. A rule in that folder activates only when Claude works with files matching a specific path. That is worth knowing when a project grows past a few dozen lines of instructions.

Importing Other Files

If your CLAUDE.md gets long, you can split it. Use the @ syntax to include another file:

# My Project
 
@README.md
@docs/architecture.md
 
## Rules
- Always use TypeScript
- Tests go in /tests

When Claude Code starts, it expands those references and loads the full content of each file. Paths can be relative or absolute.

A useful detail: splitting the file into imports does not save context space. All imported files still load in full. The benefit is organization for humans reading the files, not token savings for Claude.

CLAUDE.local.md

There is a variant called CLAUDE.local.md. It lives in the same folder as your regular CLAUDE.md and loads right after it.

The point is that CLAUDE.local.md is for personal notes you do not want to commit to git. If you work on a shared project and have your own preferences that only apply to you, put them there. Add CLAUDE.local.md to your .gitignore and the rest of the team never sees it.

Memory vs. Context

These two words are easy to mix up. They mean different things here.

Memory is what CLAUDE.md gives you. It loads before the conversation starts. It is always there, before you type a single word.

Context is what builds up during the conversation. Every message you send, every file Claude reads in the session, every question you ask. Context grows as you work. When you close the session, that context disappears.

CLAUDE.md does not replace context. It is the foundation. Context is everything you build on top during the session. When you use /compact to compress a long conversation, the project-root CLAUDE.md re-loads automatically. Sub-folder files do not re-load unless Claude reads a file in that folder again.

Try It Yourself

1. Open a project folder in Claude Code
2. Create a new file called CLAUDE.md in that folder
3. Write 3-5 sentences describing:
   - What the project is
   - One concrete rule you want Claude to follow (specific, not vague)
   - Which folder contains the most important files
4. Run /clear to start a fresh session
5. Ask Claude: "What do you know about this project?"
   Claude should summarize what it read from your CLAUDE.md.

Summary

Every Claude Code session starts blank. CLAUDE.md is the fix. It is a plain text file that lives in your project folder, and Claude reads it automatically every time a session starts. You write your context once and never repeat it again. There is also a global version at ~/.claude/CLAUDE.md for things that apply across all your projects. Sub-folders can have their own CLAUDE.md files that load on demand. Large files can import others using @path/to/file. Personal overrides go in CLAUDE.local.md. Memory from CLAUDE.md is always there. Conversation context builds on top during the session and resets when you close.

Next up: 08. The Karpathy Rules: From 4 Habits to a 12-Rule CLAUDE.md.