Imagine starting every conversation with the AI from scratch, re-explaining what you’re building, which tools you use, and how you like to receive answers. Exhausting and costly in tokens. O CLAUDE.md handle this: it’s a file that’s read automatically at the start of every session, becoming the agent’s base context—your project memory that doesn’t disappear when the conversation ends.
Illustrative diagram — CLAUDE.md is “injected” into the agent’s context every time you open a session, so it already starts knowing who it is, what it’s building, and how to act.
📌 CLAUDE.md as a persistent system prompt
What it is
O CLAUDE.md is a file in Markdown that sits at the root of your project and defines the role, o context and the preferences under which the agent will operate. When you open a work session in that folder, the agent reads this file before anything else—it becomes the project’s "system prompt," meaning the base instruction that shapes all of the AI’s behavior from then on.
What is it?System prompt — the background instruction that tells AI who it is and how to act, always active behind the conversation. Markdown — a simple way to write text with headings (#), lists, and emphasis without needing to program. Session — a “round” of work with the agent, from when you open it until you close it.
The keyword is persistent. An ordinary conversation disappears: close the window and the agent forgets everything. The CLAUDE.md doesn’t—it lives on disk, is versioned with the project, and is read again in every session. That’s why the best analogy is a constitution: a short, stable document that governs how the project works, which the agent always follows, regardless of who is talking to it—or when.
Why learn
Without CLAUDE.md, every day starts from scratch: you paste the context again, repeat your rules, and remind it of your preferences. With it, project knowledge is recorded once and reused indefinitely. It’s the difference between training a new employee every morning and having a veteran who already knows the ropes.
- •Zero re-explanation: the context loads automatically in every session.
- •Consistency: all sessions follow the same rules.
- •The foundation of everything: the other topics in this module refine this file.
Key concepts
.md file at the top of the project.
Doesn't disappear when you close the conversation.
Loaded at the start of each session.
Governs the agent's behavior.
🧱 Anatomy of CLAUDE.md
What it is
A good CLAUDE.md has five typical sections: Role (who the agent is—for example, “you are an n8n workflow assistant”), Context (what’s being built and why), Operational rules (how it should work), Style (communication preferences) and Folder structure (where things go). Each section answers a different question the AI would ask if it were just arriving on the project.
Illustrative diagram — the five sections aren't isolated compartments; together they form the complete "template" the agent acts from.
Why learn
You don’t need to write these sections by hand. The vibe coding approach is ask in natural language: "create a CLAUDE.md for a project that builds automations in n8n, with rules to look for a tool before creating one and keep the file concise". The AI generates the outline with the right sections; you just review and adjust it. Knowing the anatomy helps you understand what to ask for e what to check in the result.
✓ Sections every anatomy has
- ✓Role: "you are an n8n workflow assistant."
- ✓Context: what the project is and its main goal.
- ✓Rules + Style + Structure: how to act, how to speak, where things go.
✗ What clutters the anatomy
- ✗Step-by-step tutorials for specific tasks.
- ✗Long documentation for a single tool.
- ✗History of old conversations and decisions.
Key concepts
Who the agent is.
What’s being built.
How to act and how to speak.
In natural language, not by hand.
⚙️ Operational rules
What it is
Operational rules are short instructions about how the agent should work — not what to build, but the day-to-day discipline. Three rules are worth their weight in gold in almost every project: look for an existing tool before creating a new one, learn and adapt when something fails, e keep workflows and files up to date at all times. It’s only a few lines, but they radically change the behavior.
What is it?Self-improvement cycle — when the agent makes a mistake and adjusts its own way of working (and even CLAUDE.md itself) instead of just patching the output. Tool — a capability the agent can use (read a file, call an API, run a skill).
These rules are exactly what enables the self-improvement cycle. “Search before creating” avoids reinventing the wheel and keeps the project clean. “Learn from failures” leads the agent to treat an error as information, not a dead end. “Keep everything up to date” ensures the documentation and workflows don’t fall out of sync with what actually exists. Together, they turn the agent from a passive executor into a collaborator that improves on its own.
✓ Rules that trigger the cycle
- ✓"Look for an existing tool before creating a new one."
- ✓"When something fails, learn and adapt your approach."
- ✓"Keep workflows and files up to date at all times."
✗ Anti-patterns in the rules
- ✗Create a new tool every time, ignoring what already exists.
- ✗Keep insisting on the same approach that has already failed.
- ✗Leave the documentation out of date with reality.
🎯 Practical tip
Write rules like short, actionable principles, not as paragraphs. "Search before creating" is better than three sentences explaining why. AI follows concise rules more faithfully—and they're easy to find in the file.
Key concepts
Reuse > recreate.
An error becomes an adjustment.
Docs = reality.
The rules connect the cycle.
✂️ Keep it lean (< ~500 lines)
What it is
How CLAUDE.md fits into the context for each session, it competes for space with the rest of the conversation. The rule of thumb: keep it lean, under ~500 lines. A short file makes every rule "carry more weight"; a long file dilutes the important instructions in too much text, and the agent ends up "missing" exactly what matters.
What is it?Context (context window) — the agent’s “working memory space” in a session; everything that goes in there (including CLAUDE.md) takes up space. Token — the small piece of text the AI counts; the more lines in the file, the more tokens used each session.
Illustrative diagram — the more space the file takes up, the less room remains for the conversation, and the easier it is for the AI to “miss” an important rule buried in the text.
Why learn
There's a classic symptom: if the agent keeps doing something wrong even though there's a clear rule against it, the file is probably too long and the rule is getting lost. The solution isn't to shout the rule in all caps—it's to trim the fat. Remove what doesn’t apply to every session, condense paragraphs into principles, and the rule carries more weight again. Being concise is an engineering decision, not laziness.
🎯 Practical tip
Rule of thumb: if the CLAUDE.md doesn’t fit in one or two screens of scrolling, it's already too large. Before adding anything, ask: "is this really for every session?". If it’s for a specific task, it belongs in a skill (next topic).
Key concepts
Always uses context.
Practical limit.
Rules get lost.
Still gets it wrong despite the rule = cut it.
🔀 CLAUDE.md vs. skills — what goes where
What it is
The most important routing rule in this module: the CLAUDE.md stores only what applies to every session (project purpose, framework, main objective, operating rules). Instructions specific to a task — such as “generate an invoice as a PDF” or “scrape a website”—belong to a skill, loaded on demand, only when the task comes up.
What is it?Skill — a set of specialized instructions for a task, stored in a separate file and loaded only when needed. On demand (on demand) — only enters the context when it’s used, instead of staying loaded all the time.
Illustrative diagram — many skills (20 a 50) don’t bloat the context because they load only when the task calls for them; a huge CLAUDE.md would bloat every session.
Why learn
Stuff everything into CLAUDE.md exceeds the context window: each session loads tons of instructions that may not even be used that day. Skills solve this through loading savings. You can have 20, 30, 50 skills without inflating the context, because each one only appears when the corresponding task comes up—unlike a giant CLAUDE.md, which would incur the cost in all the sessions.
✓ Goes in CLAUDE.md
- ✓Project purpose and main objective.
- ✓Framework and operational rules (for every session).
- ✓Communication style and folder structure.
✗ Doesn’t go here (goes in a skill)
- ✗Step-by-step instructions for a one-off task (e.g., generating a PDF).
- ✗Instructions for an integration used occasionally.
- ✗Long recipes that only work for one type of request.
Key concepts
Only what’s always present.
Specific, on demand.
20–50 skills fit.
Prevents filling up the context.
💬 Iterate on the file by chatting
What it is
CLAUDE.md is a living document. You don’t need to open an editor to edit it: just ask the agent itself. “Add a section about keeping explanations concise,” “remove rule X that we no longer use,” “record that this project uses Supabase.” The AI edits the file, and the change takes effect starting with the next session. The file evolves alongside the project.
What is it?Living document — a file you expect to change frequently, not something written once and frozen. Iterate — make small improvements in cycles, validating each step (the same mindset as Track 1).
How the file evolves
-
1
Initial session: you ask for a basic CLAUDE.md (role, context, rules). The agent generates the skeleton.
-
2
A pattern emerges: you notice that you always ask for short answers. "Add a section saying to keep the explanations concise."
-
3
The project grows: adds a new tool. "Record that we use Supabase for the data." The context stays current.
-
4
Time to prune: the file grew beyond ~500 lines. "Move the invoice task instructions into a skill and trim down CLAUDE.md."
Why learn
Treating CLAUDE.md as something you can edit at any time, in natural language, completes the module’s self-improvement cycle: whenever the agent makes a mistake because a rule is missing, you add the rule talking; every time the file grows, you prune it talking. It’s not a sacred document—it’s a working tool that you keep sharpening.
🎯 Goal: generate a concise CLAUDE.md for the project
crie um CLAUDE.md na raiz para um projeto que <descreva o que você constrói>. Seções: Papel, Contexto, Regras operacionais, Estilo, Estrutura de pastas. Regras: procurar uma tool existente antes de criar; aprender ao falhar; manter sob ~500 linhas.
✅ How to verify: open the generated file; check the 5 sections and that it fits in ~1 screen of scrolling.
📜 Skeleton: a minimal, concise CLAUDE.md
# Papel Você é um assistente de workflows n8n para este projeto. ## Contexto Construímos automações que conectam e-mail, planilhas e um banco Supabase. Objetivo principal: notificar a equipe sobre leads novos em tempo real. ## Regras - Procure uma tool/skill existente antes de criar uma nova. - Quando algo falhar, aprenda e adapte a abordagem. - Mantenha este arquivo sob ~500 linhas (tarefa específica vira skill). ## Estilo - Respostas curtas e diretas, em PT-BR. - Explique o "porquê" das decisões em 1 frase. ## Estrutura - /workflows → fluxos n8n exportados - /skills → instruções de tarefas específicas - /docs → notas e decisões do projeto
✅ How to verify: each section has 1–3 lines; no task-specific step-by-step instructions are here (those go in /skills).
Where should step-by-step instructions for "generating a PDF invoice" go, for a task that only comes up once in a while?
Key concepts
Evolves with the project.
In natural language.
Made a mistake? Write down the rule.
Too bloated? Trim it down.
📌 Module Summary
Next Module:
2.2 — The WAT Framework in Depth