AI Mastering, PART III — Start with CLAUDE.md

MCPs, skills, agents — the AI tooling hype is loud. The single most impactful thing you can do takes 15 minutes: write a great CLAUDE.md. Here's how.

2026-03-21 · By Guilherme Salgueiro

*Part III of The AI Leverage Stack*

In The Karate Kid, a teenager named Daniel LaRusso showed up at Mr. Miyagi's house expecting to learn karate. Instead, he got some weird instructions.

*Wax on. Wax off. Paint the fence. Sand the floor.*

Daniel thought it was pointless. He'd signed up for roundhouse kicks, not chores. But Miyagi wasn't stalling — he was configuring. Every circular motion built muscle memory that would fire automatically in a fight Daniel hadn't yet imagined. The boring setup *was* the leverage. By the time the tournament arrived, Daniel didn't need to think about his blocks. They were already there.

There's a moment like that with AI tools. A moment where the setup you almost skipped becomes the reason the tool actually works.

---

Open a terminal. Type `claude`. Press Enter.

A cursor blinks. You type your first request. The response is... fine. Competent the way a temp is competent on day one — technically doing the job, but missing every unspoken expectation, every shortcut, every thing that makes your project *yours*.

You haven't given it a job description. You haven't told it what you're building, how you work, or what good looks like. You handed the most capable collaborator you've ever had a blank canvas and said *"figure it out."*

So it does. Generically. Over and over. And you start to wonder if AI tools are overrated.

They're not. You just skipped the wax.

---

There's a file — a plain markdown file — that sits at the root of your project. It's the first thing Claude Code reads when a session starts. Before your prompt. Before your context. Before anything.

It's called `CLAUDE.md`.

It's your AI's job description. Its onboarding document. Its understanding of what you expect, how you work, what matters, and what will waste both of your time.

The internet is saturated with guides on MCPs, skills, agents, and parallel execution — the flashy machinery of AI-assisted work. But none of that machinery performs well without this file. This is where it starts.

Daniel didn't win the All-Valley Tournament with the crane kick. The only reason he got to that moment is because he mastered the basics. You want to learn how to use Claude Code? Start with `CLAUDE.md`.

---

What Your AI Reads Before You Speak

The typical interaction with AI tools is transactional. You ask, it responds, the conversation ends. Next time, you start from scratch. It knows nothing about you, your project, your preferences, or your last three months of work.

`CLAUDE.md` changes that equation.

It's a markdown file — plain text, nothing fancy — that Claude Code loads into context at the beginning of every session. Not sometimes. Every time. Before you type your first word, Claude has already read this file. It's the closest thing to giving an AI a memory that persists between conversations.

There's a scene in Groundhog Day where Bill Murray keeps waking up to the same morning. Same song. Same conversations. Same blank slate. That's what using Claude Code without a `CLAUDE.md` feels like — except you're the one stuck in the loop, re-explaining your project, your preferences, and your stack to a collaborator with permanent amnesia.

The file breaks the loop.

And it doesn't just live in one place. There's a hierarchy:

Global shapes the baseline — your working style, communication preferences, standards. Project gives the job brief — this codebase, this stack, these commands. Subfolder files add specialist knowledge for different parts of the building. Claude reads them all, layered, every time.

If you use other tools, you've seen variations of this pattern. Cursor has `.cursor/rules/`. Codex uses `agents.md`. Windsurf has its own rules format. The concept is the same everywhere: **persistent context that shapes how the AI works with you**, session after session, without you repeating yourself. The specifics change across tools. The principle doesn't.

Where Do You Start?

That depends on where your project is.

**Starting from scratch?** Don't create a `CLAUDE.md` in an empty folder — there's nothing for Claude to understand yet. Write your first few files, sketch the structure, get the skeleton in place. Then tell Claude about it. You need a project before you need a project description.

**Working with existing code?** This is where it clicks fastest. Open Claude Code in your project folder, type `/init`, and let it scan what's there. It'll generate a starting scaffold — your tech stack, folder structure, key commands. That gives you a foundation. But it's just the beginning — the equivalent of filling out a form. The real value comes from what you add after.

**Already using Claude Code but never wrote one?** You're probably repeating the same instructions every session without realizing it. Start by noticing what you keep re-explaining. Those repetitions are your first entries.

Why This Matters More Than Your Prompts

There's a concept gaining traction in the AI engineering world: *context engineering*. Anthropic's engineering team, GitHub's developer tools group, and Forrester have all started using this term. The idea is simple but powerful: the quality of an AI tool's output depends less on how you prompt it and more on the environment you build around it.

As one senior engineer put it: *"Coding agents don't need better prompts. They need better environments."*

`CLAUDE.md` is the programmable layer of that environment.

A good prompt helps once. A good `CLAUDE.md` helps every time.

It compounds. Every instruction you add — tested, refined, earned through use — makes every future session slightly better. Anthropic's own documentation says it directly: *"The file compounds in value over time."*

And yet, the common pattern is to either skip it entirely or run `/init` once and never touch it again. If you've felt the [overwhelm of keeping up with AI tools](/writing/you-already-failed-at-ai), this is the antidote — one file, fifteen minutes.

`/init` is a fine starting point. It scans your codebase and generates a scaffold — build commands, directory map, naming patterns. But here's what `/init` cannot capture: your workflow, your architectural decisions, the historical context behind your choices, your safety constraints, or what you're working on right now. As one practitioner put it: *"The generated file is the skeleton. You provide the soul."*

The difference between `/init` and a crafted `CLAUDE.md` is the difference between a LinkedIn profile and actually working with someone for six months. One gives you facts. The other gives you judgment.

---

How to Build Your AI's Operating Manual

A well-crafted `CLAUDE.md` answers three questions. Just three. But they need to be the right answers.

The WHAT — Give It a Map

What are you working on? What tools are you using? Where does the important stuff live?

This is the terrain briefing. Claude can explore your project on its own, but telling it where to look saves time and prevents wrong turns. Think of it as the difference between handing someone a city map versus dropping them at a random intersection and saying "find the restaurant."

Here's what a simple WHAT section looks like:

The commands section lists the shortcuts your project uses — even if you don't fully know what they mean yet, Claude does, and listing them here means Claude will use the right ones instead of guessing.

Notice the "NOT a mobile app" line. That's not obvious — it's a learned correction. AI tools are trained on millions of projects and will sometimes default to patterns from the wrong type of project. These "not that" lines prevent the most common wrong turns. You'll discover which ones you need as you go.

The WHY — Give It Purpose

What does your project do? Who's it for? What should the tone feel like?

This is the part that tends to get skipped. The tools get described but not the mission. The why matters because it shapes every judgment call Claude makes. Should an error message be technical or friendly? Should the writing be formal or casual? The purpose answers these questions before they're asked.

Four lines. But now Claude knows this is a writer's platform, not an enterprise tool. Everything it produces — from code to copy — shifts to match.

The HOW — Give It Expectations

Here's where the real gap appears. The project gets described but never the *job*. What do you actually expect from your AI collaborator?

This is the job description. Not "here's my project" but "here's how I expect you to work with me."

Notice the emphasis words — NEVER, ALWAYS. These aren't stylistic choices. Anthropic's own documentation confirms that words like "IMPORTANT", "YOU MUST", and "NEVER" make Claude pay closer attention to a rule. Write your non-negotiables with conviction.

And then there's the part that separates good from great: **the rules you earn the hard way.**

These aren't generic tips from a blog post. They're corrections born from real moments where Claude did something wrong and you added a rule so it wouldn't happen again. Over weeks and months, these accumulate into something powerful: a collaborator that knows your project's history.

What Stays OUT

There's a temptation to put everything in this file until it's 500 lines long. Resist it. The more instructions you pile in, the more likely the important ones get lost.

What belongs somewhere else:

• **Detailed style guides** — Let automated tools handle formatting. Your `CLAUDE.md` isn't a style manual.
• **Instructions for one specific task** — If it only applies to today's work, say it in the conversation, not the file.
• **Full documents pasted in** — Don't copy a 200-line guide into your `CLAUDE.md`. Reference it instead, and Claude will read it when it needs to. (More on that in the next section.)

The file should stay focused: 30 to 50 lines of the stuff that matters for *every* session.

The Template — Your Starting Point

Here's a starter you can copy right now:

Here's the thing that rarely gets mentioned: **you don't have to write this by hand.**

Copy that template. Open Claude Code in your project folder. Paste it and say:

> *"Use this structure to create a CLAUDE.md for this project. Read the project first, then fill in each section based on what you find. Ask me questions about the Purpose and How We Work sections — those need my input."*

Claude will scan your project, identify what you're using, map the structure, and generate a solid first draft. Then you refine it — add your expectations, your preferences, your hard-won lessons. The AI builds the scaffolding; you add the intelligence.

That's the 15-minute version. And it's already better than what the vast majority of setups have.

---

The Six Principles That Make It Work

Writing a `CLAUDE.md` is easy. Writing one that actually changes how your AI works requires a few principles — earned by practitioners who've been refining theirs for months.

1. Less Is More

A great DJ doesn't play every song they know. They play the twelve that matter for *this* crowd. Your `CLAUDE.md` is a set list, not a Spotify library.

A short, focused file will outperform a long, comprehensive one. This isn't intuition — it's how AI models work. The more instructions you give, the more likely the important ones get diluted.

Here's why, concretely: AI models can reliably follow around 150-200 instructions at a time. Claude Code's own system prompt already uses about 50 of those slots — a third of the budget, gone before you've written a single line. Every instruction in your `CLAUDE.md` competes for the remaining space. This is why keeping it lean isn't just a preference — it's arithmetic.

The working consensus among experienced users: stay under 100 lines. Under 60 is even better. If your file keeps growing, that's a signal to move content into separate referenced files, not to add more sections.

2. Earn Every Line

Don't try to anticipate every possible instruction on day one. You'll write rules for situations that never happen and miss the ones that matter.

Start with the basics. Use Claude. When it does something wrong — the wrong approach, the wrong tone, the wrong assumption — *that's* when you add a rule.

One of the most respected practitioners in this space put it simply: *"Start with nothing. Add entries only when you notice yourself repeating the same instruction."*

Rules born from real mistakes stick. Rules born from imagination clutter.

3. Name Your Principles

Generic rules are forgettable. Named principles are memorable — like the difference between "be a good person" and "treat others as you'd want to be treated."

Compare these two approaches:

Named principles are easier for Claude to remember, easier for you to reference in conversation ("remember Simple First"), and they signal that this is a standard, not a suggestion.

4. Tell It What NOT to Do

Documenting what you *don't* want is as valuable as documenting what you do.

AI tools are eager to help. Sometimes too eager. Without explicit boundaries, Claude will default to common patterns that may be exactly what you're trying to avoid.

One practitioner added the line: *"I tend to over-engineer solutions. Challenge me when you see this pattern."* Claude started pushing back on unnecessary complexity. The AI became a sanity check — not because it developed judgment, but because the instruction told it to apply judgment.

5. Point, Don't Paste

A librarian doesn't carry every book — they know where each one lives. Your `CLAUDE.md` should work the same way.

When you have detailed documents — a brand guide, an architecture overview, a list of known mistakes — don't paste their contents into your `CLAUDE.md`. Point to them:

Claude reads these files when it needs them. The main file stays lean. The AI's attention stays focused on what matters for *this* conversation.

6. Treat It Like a Living Document

Think of your `CLAUDE.md` as a garden, not a building. Buildings are finished. Gardens are tended.

• **Save it with your project** so you don't lose it, and so anyone who joins the project later gets it automatically.
• **Review it when things go wrong.** If Claude keeps ignoring a rule, the file is probably too long. If Claude asks questions already answered in the file, the wording might be unclear.
• **Prune regularly.** Remove rules that no longer apply. Update ones that have evolved. Delete instructions you've replaced with automated checks.
• **Test your changes.** Add a rule, start a new session, observe whether Claude's behavior actually shifts. If it didn't, the rule needs rewriting — not repeating.
• **Let Claude help you maintain it.** Boris Cherny, who created Claude Code, describes his own practice: after every correction, he tells Claude to update its own `CLAUDE.md`. The file evolves through use — the AI becomes a participant in maintaining its own instructions.

This is the discipline that turns a static file into a compounding advantage. Each week it gets slightly better. Each month it knows slightly more. The gap between "good enough AI" and "AI that feels like a real collaborator" lives in this file.

---

Beyond the Single File

`CLAUDE.md` is the seed. But the most effective setups grow into something bigger — an ecosystem that surrounds the AI with exactly the right knowledge at exactly the right time.

Think of it like a city. The `CLAUDE.md` is the city charter — the foundational rules that apply everywhere. But a city needs more than a charter. It needs zoning laws for different districts, emergency procedures, specialized departments, and infrastructure that keeps everything connected.

Claude Code's file system is designed for this kind of growth.

The Full Ecosystem

Here's what a mature setup looks like — not on day one, but after weeks or months of intentional use:

And then there's the invisible infrastructure: **hooks** that trigger actions automatically (run a check before every commit, format code after every save), **MCPs** (Model Context Protocol servers) that connect Claude to external tools like your project management board, your database, your deployment pipeline. The `CLAUDE.md` is the root. Everything else grows from it.

One important architectural insight: `CLAUDE.md` is guidance — Claude reads it and follows it, but it's advisory, not enforced. If you need a rule that *cannot* be broken (like blocking certain dangerous commands), that belongs in `settings.json` or hooks, which are deterministic. Think of it this way: `CLAUDE.md` is the brain — context and conventions. Settings and hooks are the muscles — guaranteed actions. The best setups use both.

You don't need any of this on day one. Claude will suggest and create these structures as your workflow demands them. But knowing the shape of the system helps you understand what's possible.

The Evolution Pattern

The journey from a blank `CLAUDE.md` to a full ecosystem tends to follow a similar arc:

**Week 1**: A basic `CLAUDE.md` with identity, commands, and purpose. Twenty lines. Already better than nothing — and already changing the quality of every conversation.

**Week 2-3**: Rules start accumulating. The "Things I've Learned" section grows as you catch Claude making mistakes you don't want to see twice. You're at 40-50 lines and the file is earning its weight.

**Month 2**: Some rules have gotten specific enough to split into their own files. Security rules go to `.claude/rules/security.md`. Testing standards get their own file. The main `CLAUDE.md` stays lean, but the intelligence around it deepens.

**Month 3+**: You've built custom skills for workflows you repeat weekly. You have specialized agents for different types of work. You've connected external tools via MCPs. The `CLAUDE.md` is still 50-60 lines — but the ecosystem it anchors is rich, deep, and uniquely yours.

This is the compound interest that Anthropic describes. The file didn't get longer — it got *surrounded* by an increasingly intelligent system that makes every session faster, more accurate, and more aligned with how you actually work.

The Principle That Transfers

If you're using Cursor, Codex, Windsurf, or any other AI tool — the filename and folder structure will differ, but the principle is identical.

The convergence is striking: Cursor uses `.cursor/rules/`. Windsurf uses `.windsurfrules`. GitHub Copilot reads `.github/copilot-instructions.md`. OpenAI's Codex uses `AGENTS.md` — a pattern now found in over 60,000 repositories and governed by the Linux Foundation. Every major AI tool independently arrived at the same solution: a markdown file, in a known location, loaded before every session.

**Give your AI persistent context. Structure it hierarchically. Keep the core lean and the detail accessible. Let it grow with your practice.**

The specific tools will evolve. The principle — *teach the AI who you are and what you expect* — won't. And the skill of writing great context files? That transfers to every tool you'll ever use.

---

The Part That Changes How You Work

There's something that happens — and it's hard to describe until you experience it — when your AI tool starts behaving like it *knows* you.

You open a session and ask for help. Instead of generic output, it follows your conventions. It runs your specific checks. It formats things the way you like. It avoids the pattern you corrected three weeks ago — without being asked.

It's a small thing. And then it's not.

Because what you're experiencing isn't a tool getting better. It's the compounding effect of every line you added to that file — every correction, every preference, every hard-won lesson — paying dividends simultaneously. The first week, the effect is subtle. By month three, it's transformative. You stop treating AI like a tool you use and start treating it like a partner you work with.

Now imagine that partner multiplies. One becomes three. Three become twelve. Specialized agents — each reading that same `CLAUDE.md`, each inheriting your standards, your voice, your expectations — working in parallel on different parts of your project. The file you wrote doesn't just shape one conversation. It shapes an entire team.

That's where this goes. But it starts with one file.

---

In the Apple TV series Foundation, based on Isaac Asimov's novels, a mathematician named Hari Seldon develops a way to use mathematics to predict the future of civilization. What he sees isn't encouraging: the Galactic Empire, the most powerful force in human history, is heading toward collapse. Not tomorrow. Not next decade. But inevitably.

He can't stop it. No one can. But he can do something else.

He gathers a small group of scholars and sends them to a remote planet at the edge of the galaxy. Their mission seems modest: build an encyclopedia. Preserve knowledge. Document what's known before it's forgotten.

But Seldon isn't building an encyclopedia. He's building infrastructure. A knowledge base designed to compound across generations. Each crisis the Foundation faces makes it stronger, each generation adds to what came before, and slowly — imperceptibly at first, then unmistakably — the Foundation becomes the most resilient force in the galaxy. Not through weapons. Through accumulated, structured, compounding knowledge.

---

Your `CLAUDE.md` is not going to save a galaxy. But the pattern is the same.

You start with something modest — a few lines describing your project, your expectations, your standards. It looks like nothing. A text file. A configuration that takes fifteen minutes.

But every rule you add, every correction you encode, every lesson you document — it compounds. Session after session. Week after week. What started as a handful of instructions becomes an ecosystem that knows your project's history, your working style, your scars. Not because the AI got smarter. Because you built the Foundation.

The prompts you write will be forgotten. The agents you deploy will complete and vanish. The features that fill the headlines today — those will evolve, merge, and be replaced.

But the file you write today? The one that teaches your AI who you are and what you expect? That endures. That compounds. That becomes the quiet infrastructure underneath everything else you'll build.

The most powerful things don't start with a bang.

They start with a file.

---

*This is Part III of the AI Leverage Stack:*

• *[Part I: 5 Levels of AI Chat](/writing/5-levels-ai-chat)* — *Where are you on the sophistication ladder?*
• *[Part II: AI Is Not a Chat Interface](/writing/ai-not-chat-interface)* — *What lies beyond the chat window?*
• *Part III: Start with CLAUDE.md* — *Your first concrete move*