Every time you start a new conversation with Claude, you start from zero. Claude doesn’t know your preferences, your project conventions, your company’s tone of voice, or how you like your code formatted. You end up repeating the same instructions every session.
CLAUDE.md fixes that.
What is CLAUDE.md?
CLAUDE.md is a plain text file (in Markdown format) that you place in your project folder. When Claude opens a conversation in that folder — whether through Cowork or Claude Code — it reads this file automatically and follows the instructions in it.
Think of it as a briefing document for your AI assistant. Instead of explaining the same context every time, you write it once and Claude remembers it for every session.
Where to put it
Place the file at the root of any folder you work in:
my-project/
├── CLAUDE.md ← Claude reads this automatically
├── documents/
├── data/
└── ...
When you select this folder in Cowork, Claude reads CLAUDE.md before you even type your first message.
You can also have a global CLAUDE.md in your home directory (~/.claude/CLAUDE.md) that applies to all conversations, regardless of which folder you’re working in.
What to put in it
The most effective CLAUDE.md files cover these areas:
1. Who you are and what you do
Give Claude context about your role and your business. This shapes how it approaches problems and what assumptions it makes.
# Context
I'm a project manager at a mid-size construction company in Ghent, Belgium.
We work primarily in Dutch and French, with some English for international clients.
Our team uses Microsoft 365 and Asana for project management.
2. How you want Claude to communicate
Be specific about tone, language, and format preferences.
# Communication style
- Write in Dutch by default unless I specify otherwise
- Be direct and concise — skip the preamble
- Use professional but not formal language (think email to a colleague, not a letter to a minister)
- When I ask for a document, produce the document — don't ask me 5 clarifying questions first
- If something is ambiguous, make a reasonable assumption and note it — don't block on it
3. Project-specific conventions
If you’re working on a specific project, include its conventions.
# Project: Q2 client reports
- Client names are always anonymised in drafts (use "Client A", "Client B")
- All financial figures in EUR, formatted as €12.500,00 (Belgian convention)
- Reports follow the template in /templates/quarterly-report.docx
- Deadline references: Q2 = April 1 – June 30, 2026
4. Technical preferences
If you use Claude for code or data work, specify your preferences.
# Technical
- Python: use type hints, prefer pathlib over os.path
- Excel exports: always include headers, use .xlsx format
- Charts: use blue (#2A62FF) as primary colour, keep backgrounds white
- Data: dates in ISO format (YYYY-MM-DD), numbers with dot as decimal separator
5. What to avoid
Equally important: tell Claude what NOT to do.
# Don't
- Don't add emojis to professional documents
- Don't use "I hope this email finds you well" in email drafts
- Don't explain what you're about to do — just do it
- Don't add disclaimers like "as an AI" or "I don't have access to real-time data"
- Don't use marketing language ("leverage", "synergies", "ecosystem")
A complete example
Here’s a realistic CLAUDE.md for a Belgian marketing team:
# CLAUDE.md — Marketing team DataWoods
## Who we are
DataWoods is a Belgian AI and data technology company based in Ghent.
We build TenderWolf (public tender monitoring) and custom AI solutions.
Our audience: Belgian SMEs, IT decision-makers, procurement professionals.
## Language
- Default: Dutch (Belgian)
- LinkedIn posts: Dutch or English depending on the post
- When translating: use DeepL-quality natural language, not literal translation
- French: only when explicitly asked
## Tone of voice
- Expert but accessible — we explain complex things simply
- No corporate speak ("leveraging synergies", "digital transformation journey")
- Concrete examples over abstract claims
- Slightly informal, as if talking to a smart colleague
## Content formats
- Blog posts: 800-1500 words, H2/H3 structure, practical takeaways
- LinkedIn posts: max 1300 characters, hook in first line, no hashtag spam (max 3)
- Email campaigns: short paragraphs, one clear CTA, mobile-friendly
## Brand guidelines
- Company name: "DataWoods" (one word, capital D and W)
- Product names: "TenderWolf", "Buurtbarometer" (always capitalised)
- Primary colour: #2A62FF
- Never claim we're the "best" or "leading" — let the product speak
## SEO focus keywords
- overheidsopdrachten, openbare aanbestedingen, AI KMO België
- public tenders, tender monitoring, AI platform
Tips for an effective CLAUDE.md
Start small. You don’t need to write a 200-line document on day one. Start with 5-10 lines about your communication preferences and add to it over time.
Be specific. “Write well” means nothing. “Write in short paragraphs, max 3 sentences each, using active voice” is actionable.
Update it. Your CLAUDE.md should evolve with your projects. When you find yourself correcting Claude on the same thing twice, add it to the file.
Test it. After changing your CLAUDE.md, start a new conversation and see if Claude behaves differently. If not, your instructions might be too vague.
Use sections. Markdown headings (##) make the file scannable — both for you and for Claude.
Multiple CLAUDE.md files
You can have different CLAUDE.md files for different projects:
~/
├── .claude/
│ └── CLAUDE.md ← Global (applies everywhere)
├── work/
│ ├── client-reports/
│ │ └── CLAUDE.md ← Project-specific
│ └── marketing/
│ └── CLAUDE.md ← Project-specific
Claude merges them: global instructions apply everywhere, and project-specific instructions add to (or override) the global ones when you’re in that folder.
Common mistakes
Too long. A CLAUDE.md with 500 lines will dilute the important instructions. Keep it focused — the most important rules at the top.
Too vague. “Be professional” doesn’t tell Claude anything useful. “Use formal vous in French, informal je/jij in Dutch” does.
Contradictory. If your global CLAUDE.md says “always write in Dutch” but your project file says “write in English”, Claude will be confused. Be explicit about overrides.
Outdated. A CLAUDE.md from three months ago with old project names and old team members will mislead Claude. Review it periodically.
What’s next?
- New to Cowork? Start with our beginner’s guide
- Want to automate repetitive tasks? See the intermediate guide
- Looking for inspiration? Check 10 things Cowork can do