CLAUDE.md: the permanent briefing
A text file that gives Claude Code your project's context, conventions, and rules. So you never have to explain the same things twice.
The problem
You ask Claude to write a LinkedIn post for your product launch. It writes "We are thrilled to announce our innovative solution..." when your brand is casual and first-person. You correct it. Next session, it does it again.
You ask for a creative brief. It forgets your target is freelancers and small teams, not enterprise. You re-explain. It forgets your positioning is "simple and direct", not "holistic solution". You re-explain again.
Every session, Claude starts from zero. It doesn't know your product, your audience, your editorial tone, your constraints. It's competent but amnesic. And the time you spend re-explaining context is time you're not spending on actual work.
CLAUDE.md fixes this. It's a text file that Claude loads automatically at every session. You write your rules once. It applies them every time.
A text file, nothing more
A CLAUDE.md is a markdown file at the root of your project. No special software, no syntax to learn. Structured text with # and -.
my-project/
CLAUDE.md ← Claude reads it at the start of every session
src/
...
Claude loads it silently. You don't mention it. It applies what's written like a colleague who read the project brief before starting.
Before / after
To understand what changes, here's the same work with and without CLAUDE.md.
"Write a LinkedIn post for our new product."
We are thrilled to announce the launch of our innovative solution...
"No, we use casual tone. And it's not an innovative solution, it's an invoicing tool for freelancers."
You'll love our revolutionary new tool...
"Not 'revolutionary' either. Direct, factual tone."
5 minutes to get the right register. Tomorrow, we start over.
"Write a LinkedIn post for our new product."
Claude already knows:
- The product (invoicing for freelancers)
- The target (independents, small teams)
- The tone (direct, casual, no jargon)
- The banned words ("innovative", "revolutionary", "solution")
First draft usable in 30 seconds.
The gain isn't dramatic on a single session. It's huge over 50.
Anatomy of a CLAUDE.md
No imposed format. But a four-block structure covers 90% of cases.
1. Context
What Claude needs to know before producing anything. The product, the audience, the positioning.
Claude doesn't need to know everything. It needs what influences its output: if you ask for a sales argument, it needs the price. If you ask for a LinkedIn post, it needs the positioning.
2. Tone and editorial
How you talk to your audience. This is the section that eliminates the most corrections.
3. Constraints
What Claude must never do. Often more useful than what it should do, because default mistakes are predictable.
"NEVER" in capitals isn't a formatting quirk. Claude gives higher weight to capitalized words. It's like bolding something in a brief: it signals priority.
4. Formats and conventions
Rules that apply to everything Claude produces for this project.
24 lines total. No novel. Each line eliminates a category of mistakes.
A real example
The CLAUDE.md of a content agency producing newsletters and LinkedIn posts for its clients.
19 lines. No novel. "ALWAYS read client guidelines" is enough for Claude to find the right file before starting. "NEVER publish directly" is the kind of guardrail that prevents disaster.
How to build it
Don't start with a perfect CLAUDE.md. Start with a nearly empty file.
1. The minimum viable
Product, audience, tone in 5 lines. Enough for Claude to stop guessing.
2. Work, correct, note
Every time you correct Claude ("no corporate speak", "we say 'users' not 'customers'"), make a mental note. Two identical corrections = a rule to write down.
3. Two weeks later
Your CLAUDE.md has 20-30 lines covering 90% of cases. You open a session, you work directly. No context to re-explain.
The test: if your first request in a new session gives a usable result on the first try, the CLAUDE.md is doing its job.
And you don't even have to write it yourself. Claude can generate it:
Claude is good at inferring tone and conventions from what exists. What it can't guess: constraints, positioning nuances, business rules. Those lines are yours to add.
Three levels that stack
Claude loads instructions from three places. All three layer on top of each other.
The project doesn't replace the global, it adds to it. In case of conflict, the most specific wins. If your global says "casual tone" but the project says "formal for this brand", the project wins.
By role: 3 concrete examples
CLAUDE.md isn't just for developers. Any project that lives in a folder can have one.
For a product launch:
## Product
- Mobile budgeting app for 25-35 year olds
- Freemium: free with ads, $4.99/month without ads + export
- Differentiation: minimal interface, no charts, just numbers
## Audience
- Young professionals, first salary or first investments
- They tried Mint/YNAB and found it too complex
## Tone
- Casual but not try-hard. Like a friend who's good with money.
- No banking jargon ("aggregate balance", "categorization engine")
- NEVER: "take control of your finances"
For a content team:
## Editorial guidelines
- Casual tone everywhere except legal pages
- Headlines: informative, not clickbait
- Articles: 800-1500 words. If longer, split.
- Every article has a publish date AND a last updated date
- Sources: always cite, always link
- NEVER use unquantified superlatives
For competitive intelligence:
## Context
- Market: project management tools for agencies (10-50 people)
- Direct competitors: Monday, Asana, Notion (misused)
- Our angle: built for agencies, not adapted from enterprise
## Research
- When analyzing a competitor, look at: pricing, differentiating
features, latest announcements, recent Capterra/G2 reviews
- Output format: comparison table, no prose
The content changes. The principle stays the same: rules Claude applies without re-explanation.
What NOT to put in it
| Don't include | Why |
|---|---|
| Tool documentation | Claude knows it or can search for it |
| A specific campaign brief | That's a Skill, not CLAUDE.md |
| Decision history | Too long, not actionable |
| Explanatory paragraphs | Rules, not essays |
| "This client is difficult" | Not actionable. Say what to do concretely. |
The boundary with Skills: if it's a permanent convention in one line ("casual tone"), it's CLAUDE.md. If it's a multi-step workflow with output format ("generate a creative brief with this structure"), it's a Skill.
CLAUDE.md in a team
When the CLAUDE.md is in the repo, the whole team gets the same rules.
Classic scenario: a new content manager joins. Without CLAUDE.md, they spend two weeks absorbing the editorial guidelines through trial and error. With a CLAUDE.md, Claude applies conventions from the first session. The newcomer produces conforming content from draft one.
Another scenario: the team decides to switch to casual tone on the blog. Instead of telling everyone and hoping they comply, one line in the CLAUDE.md is enough. Every team member using Claude Code applies the new convention automatically.
CLAUDE.md and Skills: how they coexist
Loaded automatically, all the time.
- Who the audience is
- What tone to use
- What we never do
- Project conventions
"How we work here."
Loaded on demand, when you invoke it.
- Steps to follow
- Evaluation criteria
- Output format
- Sources to consult
"How we do this specific task."
Both stack. When you run a writing Skill, Claude applies the Skill's instructions (structure, steps) AND the CLAUDE.md conventions (tone, constraints, audience). The result respects both the method and the frame.
Classic mistakes
Three patterns found in most CLAUDE.md files that don't work.
We decided during the January offsite to switch to casual tone because our user tests showed that formal language created a perceived distance that reduced conversion rate by 12% on landing page B. This decision was validated by the editorial committee on February 3.
Casual tone everywhere except legal pages.
Use a professional but approachable tone.
Write quality content.
Be creative with hooks.
Casual tone, short sentences, no jargon unless explained.
800-1200 words per article, informative title.
First sentence = fact or number, never a rhetorical question.
Direct, casual tone.
For landing page audits, evaluate: message clarity in 5 seconds, visual hierarchy, journey from arrival to CTA, editorial tone. For each criterion, produce a finding, verdict, and suggestion...
CLAUDE.md: Direct, casual tone.
Skill /audit-landing: the 30 lines of audit instructions.
What's next
You now have the frame (CLAUDE.md) and the methods (Skills). The next article shows how to build a real Skills library: organization, naming, patterns that work, examples from daily use.