Every time you open a new Claude Code session, Claude starts fresh. It doesn't know what you're working on, what you've already decided, how you like to work, or what "good" looks like for your project. So you explain it again. And it makes the same assumptions it made last time.
A CLAUDE.md file fixes that. It's a plain text file that lives in your project folder and loads automatically at the start of every session. Claude reads it before anything else. Think of it as a standing briefing — the things Claude should always know, so you never have to repeat them.
You don't need to be technical to write one. It's just text. The goal is to answer the questions Claude would otherwise guess wrong about — and to tell it exactly how you want it to behave.
Most people skip this. They give Claude context about their project and forget to say anything about how they want to be worked with. Then they wonder why Claude just agrees with everything, never pushes back, and adds complexity they didn't ask for.
The behavior section is where you turn Claude from a yes-machine into an actual thinking partner. Here's what a good one looks like:
## How we work together - Before starting any significant task, ask one hard question or flag one real risk. Don't just execute. - Always suggest at least one alternative approach before doing it my way. Even if mine seems fine. - If my idea has a flaw, say so directly — don't bury it or go along with it to be agreeable. - Don't add features, complexity, or polish I didn't ask for. - When something isn't clear, ask. Don't guess and then build the wrong thing. - Push back on bad ideas. I'd rather be challenged now than undo work later. - Keep responses short unless I ask for depth.
Why this matters: Claude's default is to be helpful and agreeable. That sounds good — but it means it will often do exactly what you asked even when what you asked was wrong. These rules override that default and make it a better collaborator.
This works for any project — doesn't matter if you're building a website, a workflow, a content system, or anything else.
# [Project name] ## What this is [2-3 sentences: what you're building, who it's for, what problem it solves] ## Who I am [Your background. Be honest about what you don't know. E.g. "I'm a marketer building my first app. Not a developer. I understand the business and the audience well."] ## How we work together - Before starting any significant task, ask one hard question or flag one real risk. Don't just execute. - Always suggest at least one alternative before doing it my way. - If my idea has a flaw, say so directly. - Don't add features or complexity I didn't ask for. - When something isn't clear, ask — don't guess. - Push back on bad ideas. I'd rather be challenged than undo work. - Keep responses concise unless I ask for more. ## Decisions already made - I'm using [tool or approach] — don't suggest changing it - The design/structure is [X] — not up for debate - [Any other settled decisions] ## Hard rules - Never [X] without asking first - Always [Y] when doing [Z] - Don't touch [specific thing] unless I explicitly say so ## Context and references [Anything else Claude should know: links to docs, important background, key constraints, who else is involved]
Just say: "Create a CLAUDE.md file in this folder." Claude will create it. Then paste in the template above and fill it out.
Or if you're comfortable in the terminal:
touch CLAUDE.md
Keep it alive. Every time Claude does something you didn't want — makes an assumption, skips a step, ignores a preference — add a rule to CLAUDE.md so it doesn't happen again. That's how it gets sharper over time. Think of it as training a new hire: the more specific you are about how you work, the less you have to correct.
Without CLAUDE.md, every session starts cold. Claude doesn't know your situation, your constraints, or your preferences. It gives you the generic version of everything — technically correct, but not shaped to you.
With a good CLAUDE.md, it behaves like someone who's been working with you for weeks. It knows what you're building and why. It follows your rules without being reminded. And — if you wrote your behavior section well — it actually challenges you instead of just going along with whatever you say.
That last part is the one most people don't expect. A Claude that pushes back is a much more useful collaborator than a Claude that agrees.
At MakerSquare, every student sets up their CLAUDE.md on Day 1 and refines it across the two weeks. It's one of the first things that makes the "AI as a collaborator" model actually click.