🍔 The problem: a bloated CLAUDE.md
New here? You already saw in Track 0 that the CLAUDE.md is the "brain" that the agent reads at the start of each session. The problem: if you start pasting detailed instructions for each MCP tool you install into it, it becomes a huge file — and huge files cost more (they're read in full every time) and are hard to maintain.
New here? When we say a large file "costs more," we mean it literally: every coding agent reads the entire CLAUDE.md at the start of each conversation, and that text becomes part of what we call context — the “short-term memory” the model carries while working with you. More context means two bad things: you pay to process more text with every message, and the agent is more likely to “lose the thread” between one rule and another because they’re competing for attention with the rest of the conversation.
The common pattern is predictable: you install an MCP server and paste a paragraph into CLAUDE.md explaining when to use each of its tools. The following week, you install another server and paste in another paragraph. After installing 4 or 5 servers, the file that was supposed to fit on one screen has become an endlessly scrolling document — and most of it is read in every message, even when the topic of the conversation has nothing to do with scraping, databases, or email.
Caption: the more MCP servers you install without separating their instructions into standalone files, the more CLAUDE.md swells—until it becomes costly to read and hard to maintain.
💡 Practical Tip
Before pasting any explanation of a new tool into CLAUDE.md, ask yourself: “Is this a general project rule, or a detail about ONE specific tool?” If it’s a detail about one tool, it belongs in a cheat sheet, not CLAUDE.md—that’s exactly what the next topic addresses.
✗ Bloated CLAUDE.md
- • 5 MCP servers, each with a paragraph pasted in
- • Every message reads rules that have nothing to do with the topic
- • Finding a specific rule becomes a search through running text
✓ Lean CLAUDE.md
- • Only general project rules; fits on one screen
- • Each MCP server has its own cheat sheet
- • The agent only opens the cheat sheet when the topic comes up
📋 The solution: a separate cheat sheet file
Caption: CLAUDE.md stays short and points only to the cheat sheet; the cheat sheet explains, with examples, which tool to choose in each situation — so the agent gets it right without you repeating the whole explanation every time.
New here? Cheat sheet — in
Portuguese, "exam cheat sheet" — is a separate markdown file, dedicated solely to teaching the agent to choose the
right tool within a domain (for example, scraping). The CLAUDE.md gets just one line: "for
scraping questions, see cheat-sheet.md". The agent only opens this file when the topic
comes up — keeping things lean day to day.
🔍 Under the hood: why this works
Nothing magical happens — it's just a matter of reading on demand. CLAUDE.md loads in every message; the cheat sheet is opened only when the agent decides it needs it, usually when you ask for something related (for example, "download this page"). In conversations where you don't touch on scraping, the cheat sheet stays on disk, costing no context. It's the same principle of on-demand loading that Track 3 will call progressive loading — load the essentials first, the details only when the topic comes up.
This also means the cheat sheet can grow quite a bit without any problem— it only "costs" something when it's read, and it's read rarely, always at the right moment.
🧱 Anatomy of a good cheat sheet
An effective cheat sheet has three parts: a table comparing the options, a one-sentence decision rule (“if X, use Y”), and real examples of requests → chosen tools. No long paragraphs—the goal is quick reference, not continuous reading.
Comparison table
The options side by side—when to use each, in one sentence per row.
Decision rule
A short sentence like “if the request mentions just 1 page, use scrape; if it mentions ‘the whole site,’ use crawl.”
Real examples
2–3 pairs of "user request → selected tool" to reinforce the pattern.
The difference between a cheat sheet that works and one that only exists on paper comes down to the writing details. Compare the two examples below for the same scraping server:
✗ Weak cheat sheet
- ✗"Use the right tool for each type of scraping" — vague, it doesn’t say which tool goes with which type
- ✗An 8-line paragraph explaining the philosophy behind each tool
- ✗No example of a real user request
✓ Strong cheat sheet
- ✓"1 page → scrape · list of pages → map · entire site → crawl"
- ✓A 3-row table, each row showing the tool and when to use it
- ✓"I want the text from this page" → scrape (real example)
✍️ Writing your first cheat sheet
You can ask the agent itself to draft the cheat sheet, then review it. Start by asking it to document the tools from an MCP server you just installed, in a table + decision rule format.
Objective: have a real cheat sheet in your project. How to verify: the file cheat-sheet.md appears in the folder with a table, and CLAUDE.md gets a new line pointing to it.
⚠️ Common errors when requesting the cheat sheet
- The agent invents tools that don't exist: if it has never
"talked" to the MCP server before (never called any tools), it may guess names. Ask it to
list the available tools first—usually with a command like
/mcp— before documenting. - A cheat sheet becomes a copy of the official documentation: pasting the server's entire documentation doesn't help — it's already too long for a "quick reference." Explicitly ask for a table + decision rule + examples format, not a generic summary.
- CLAUDE.md isn’t updated: sometimes the agent creates the cheat sheet but forgets to add the reference line to CLAUDE.md. Check both files, not just the new one.
🔗 CLAUDE.md points; it doesn't repeat
The golden rule: CLAUDE.md points for the reference files, never the repeats. This applies to MCP cheat sheets and will apply to skills in Track 3 — it's the same progressive loading principle: load the details only when the topic actually comes up.
🔍 Inside
It’s the same reason we use organized folders instead of one giant file—information is available, but only takes up “space” when it’s actually read.
Caption: CLAUDE.md stays small and central, pointing to files organized by topic — each one is read only when that topic comes up in the conversation.
✗ Repeats
- • Paste the entire MCP tool list into CLAUDE.md
- • Every message reads the entire content, whether it's used or not
- • Updating means editing one giant file
✓ Points to
- • One line only: "for MCP, see cheat-sheet.md"
- • Detailed content is read only when the topic comes up
- • Updating means editing the small, specific file
🔄 Keeping the cheat sheet up to date
Whenever you install a new MCP server or notice that the agent has chosen the wrong tool more than once, it’s a sign to update the cheat sheet — add a row to the table or make the decision rule clearer. It’s a living document, not a file you write once and forget.
Think of the cheat sheet as a plant that needs watering now and then, not a monument you build once and consider finished forever. The three most common reasons to review it are: installing a new MCP server, noticing the same wrong tool choice repeatedly, and the server itself changing (renamed tools, new parameters).
New MCP server installed
Ask the agent to document its tools in a new cheat sheet, or in a new section of an existing one.
Wrong choice, more than once
If you've already corrected it with “no, use X” twice for the same kind of request, the cheat sheet's decision rule is too weak—make it more explicit.
The server changed
A renamed tool or new parameter breaks the old example—it's worth reviewing the cheat sheet after updating any MCP server.
💡 Practical Tip
Whenever you correct the agent in the conversation ("no, use crawl here, not scrape"), ask it to update the cheat sheet with what it learned.
✗ Letting it die
- • Cheat sheet written once, never opened again
- • New server tools don't show up there
- • Agent keeps making the same wrong choice for weeks
✓ Keeping it alive
- • Reviewed with each new server or repeated error
- • The agent itself suggests an update when corrected
- • The decision rule gets clearer with each round