📄 What is CLAUDE.md
New here? O CLAUDE.md is a plain text file (extension .md, short for “markdown”—a plain-text format with a few formatting
symbols—placed in the project root, which the agent reads automatically whenever it opens the folder.
It’s your standing note to the agent.
💡 Main Concept
- •Automatic loading: you don’t need to paste the rules into every conversation.
- •Persistent rules: remain in effect in every new session.
New here? "The project root" is the main folder — the top-level one above
all the others, the one you opened when you typed claude in the terminal (the command-line program where you type instructions instead of clicking buttons). If your project is a folder called
meu-site with subfolders imagens/ e textos/ inside, CLAUDE.md sits
loose inside meu-site/, at the same level as imagens/ e textos/ — never
inside a subfolder.
imagens/ or textos/.🔍 See inside
The CLAUDE.md is an ordinary text file, just like a photo or a document — it’s saved on your computer, inside the project folder. Nothing in it "goes online" on its own: it only leaves your machine if you publish the project somewhere (e.g., git push) or paste the content into a website.
It costs nothing to exist—it’s just a text file. The only “cost” is indirect: the more lines it has, the more text the agent processes each session, which can make responses slower and more expensive (the topic of the next section).
✓ Where to create the file
- ✓Right in the project root, at the same level as the other folders
- ✓Exact name:
CLAUDE.md, with uppercase letters and the extension.md
✗ Common mistakes
- ✗Save it inside a subfolder — the agent won’t find it on its own
- ✗Wrong name, such as
claude.mdlowercase orClaude.MD— in some systems, this breaks automatic reading
🔁 Why it’s read every session
New here? A “session” is a window of conversation with the agent —
it starts when you open the terminal and type claude, and ends when you close that window or
process. Each new conversation session “forgets” what was said in the previous one—the agent starts
from scratch, without remembering anything you agreed on before. CLAUDE.md provides basic continuity:
any new session starts with the project essentials already in place.
💡 Practical Tip
Pasting the rules into the chat every time works, but it gets tiring and you’ll forget one day. CLAUDE.md solves that once and for all: write them just once, and from then on every new session—even three months from now—starts out knowing the project rules.
You close the terminal
That session’s conversation is lost.
You run claude again, days later
A new session, with no memory of the previous conversation.
The CLAUDE.md is read again automatically
The fixed rules still apply, even when you don’t repeat them.
⚠️ Common error: I edited the file and “it didn’t work”
If you edit CLAUDE.md in the middle of a session that’s already open, it’s normal for the change not to take effect right away—the agent already read the file at the start of that session and doesn’t keep checking it with every message. Simple solution: save the file and start a new session (close and run claude again, or type /clear if the command exists in your version). In the new session, it reads the updated version.
✂️ Why lean beats huge
This is the module’s key principle: a well-written 20-line CLAUDE.md provides better guidance than a generic 500-line one. The agent reads the entire file every session — too much information dilutes what really matters, and overly specific rules compete for attention with essential rules.
Think of it this way: if someone handed you a 40-page manual before every 5-minute task, you wouldn’t be able to remember everything—the most important instructions would get lost among rare details. Something similar happens with the agent: it reads the entire CLAUDE.md, but the more text it contains, the harder it is for the agent to “weigh” every rule equally. A short file keeps the 3–5 rules that really matter front and center instead of buried among rare exceptions.
Signs your CLAUDE.md has gotten too bloated: you can't remember what's written there; it has sections you haven't reread since creating them; or the agent starts ignoring a rule that was clear — a sign it has "disappeared" in the middle of too much text. In these cases, cut what's rarely needed and keep only what changes behavior on almost every task.
✓ Lean CLAUDE.md
- ✓20–40 lines, straight to the point
- ✓Rules that actually change behavior
- ✓Points to other files when more detail is needed
✗ Huge CLAUDE.md
- ✗Hundreds of lines, tries to document everything
- ✗Rare rules mixed in with the essentials
- ✗The agent "loses" the important rule in the middle of the text
💡 Practical Tip
The same principle comes up again in Track 3 (Skills): good documentation points you to things instead of bloating itself.
📋 Real example of CLAUDE.md, ready to copy
Copy the template below, adjust the marked sections, and save it as CLAUDE.md in your project root.
Objective: have a working CLAUDE.md in your first project. How to verify: open Claude Code in the folder and ask "what are this project’s rules?"—the answer should mention what you wrote.
🔍 Each model section, explained
- Objective: a sentence that sums up the project — helps the agent understand the overall context before any specific task.
- Rules: the heart of the file — behaviors that should always apply, such as “never publish without approval” or “respond in Portuguese.”
- Useful commands: shortcuts you use frequently (e.g., how to run tests, how to start the server) — saves the agent from "guessing" the right command.
- What to never do: the list of red lines — folders that can’t be deleted, actions that require explicit confirmation before running.
✓ When writing yours
- ✓Save it with the exact name
CLAUDE.md, without spaces - ✓Use short, direct sentences, one rule per line
✗ Common mistakes
- ✗Leave the sample texts (
<...>) without replacing it — the agent will take it literally - ✗Writing overly vague rules, like "be careful"—prefer something specific and testable
🧩 When the project grows: point, don’t bloat
If the project gains more complex processes, put the extra details in separate files (inside
.claude/ or a folder doc/) that CLAUDE.md points to with a line — not inside
it. This keeps the main file lean, even as the project grows.
🔍 Inside
This "point instead of bloat" approach is the same principle behind the skills — reusable processes that the agent loads only when needed, the topic of Track 3.
✓ When the project grows
- ✓Create a separate file for each subject (e.g.,
doc/deploy.md) - ✓In CLAUDE.md, leave only one line pointing to it
✗ What to avoid
- ✗Paste the entire contents of the detail file into CLAUDE.md
- ✗Keep outdated information duplicated in two places
🧪 Test CLAUDE.md: ask for a summary
The way to check that the file works is simple: ask the agent to summarize its own project right after writing the file. If the response matches what you wrote, it worked.
Objective: confirm that CLAUDE.md is actually being read. How to verify: the answer must cite the objective and rules exactly as you wrote them — this is the track’s final exercise, revisited in module 0.6.
⚠️ Didn't work? Quick checklist
- •Did the response come back generic, without mentioning your rules? Check that the file is actually at the project root (Topic 1) and that you opened the terminal inside from this folder before running
claude. - •Did you just edit the file and the response didn’t change? Close this session and open a new one (Topic 2)—edits made mid-session aren’t reread automatically.
- •Saved as
.txtby mistake instead of.md? Rename the file — the wrong extension prevents automatic reading.