CLAUDE.md

The instruction file that makes Claude actually understand your work, your preferences, and your style. Explained for everyone — no coding required.

What is CLAUDE.md?

It's a simple text file where you write down how you want Claude to work for you. Claude reads it at the start of every conversation — like a cheat sheet it never forgets.

Without CLAUDE.md

  • Claude uses a generic formal tone every time
  • Doesn't know your brand name or style guide
  • Gives US-formatted dates when you need UK format
  • You re-explain your role and context each session
  • Team members get wildly different outputs

With CLAUDE.md

  • Claude matches your brand's friendly, casual tone
  • Knows your company name, products, and terminology
  • Always uses the right date format, currency, etc.
  • Remembers your role and preferences every session
  • Whole team gets consistent, on-brand outputs
Think of it this way: A CLAUDE.md is like the onboarding doc you give a new team member on their first day. Without it, they ask the same questions every morning. With it, they show up and just know how things work here.

Simulation: Before vs After

Watch the same task — "draft a customer email" — play out with and without a CLAUDE.md.

🔴 No CLAUDE.md

🟢 With CLAUDE.md

The File Hierarchy

CLAUDE.md isn't just one file — it's a layered system. Think of it like dress code rules: company-wide policy at the top, team guidelines in the middle, your personal style at the bottom.

Layer 1 — Company-Wide

Organization Policy

Set by your IT department. Applies to everyone in the company. Example: "Never share customer PII. Always include a legal disclaimer in external emails."

Everyone Cannot be overridden
Layer 2 — Your Personal Defaults

Global Preferences

Your personal preferences across all projects. Example: "I prefer casual tone. Use UK date format (DD/MM/YYYY). I work in the marketing department."

Just you All projects
Layer 3 — Team / Project

Shared Project Instructions

Shared with your team. Example: "Our brand name is 'BrightPath' (always capitalized). Customer emails use the template in /templates/. Our fiscal year starts in April."

Whole team Shared
Layer 4 — Your Project Notes

Personal Project Notes

Your private notes for this project. Example: "I'm new to financial reporting — explain calculations step by step. My clients are in the healthcare vertical."

Just you Private
Key insight: All layers are combined together — Claude reads everything. If there's a conflict, the more specific layer gets the last word. So your personal preference for "casual tone" beats a generic company guideline about "professional communication" for your own sessions.

Simulation: How It Loads

Watch Claude discover and read all your instruction files when you start a conversation.

📂 Loading Sequence

What Should Go in a CLAUDE.md?

The golden rule: every line should answer "Would Claude do the wrong thing without this?" If no, delete it.

✓ Include

  • Your company name and product names (exact spelling)
  • Brand voice: "friendly and casual" or "formal and authoritative"
  • Formatting rules: date format, currency, units
  • Your role: "I'm a sales manager at BrightPath"
  • Industry jargon: "ARR = Annual Recurring Revenue"
  • Common tasks: "Customer follow-ups use the template in /templates/"
  • Audience: "Our customers are small business owners"

✗ Exclude

  • Passwords, API keys, or login credentials
  • Things Claude already knows ("be helpful")
  • Vague advice: "write well" or "be professional"
  • Information that changes daily (today's tasks)
  • Long company history or backstory
  • Things obvious from context (document titles, etc.)
  • Detailed process manuals (link to them instead)
Size target: Keep it under a page. 30-60 lines is ideal. The best CLAUDE.md files are short, specific, and direct — like a sticky note on a monitor, not a training manual.

Example: A Great CLAUDE.md

For a marketing team at a B2B SaaS company. Short, specific, every line earns its place.

CLAUDE.md — 35 lines
# Company We are BrightPath (always one word, capital B capital P). B2B SaaS for small business workflow automation. Our product tiers: Starter, Growth, Enterprise. # Brand Voice - Friendly, confident, never salesy - Use "you" and "your" — speak to the reader directly - Avoid jargon unless writing for technical audience - Contractions are OK ("you'll" not "you will") # Formatting - Dates: April 5, 2026 (US format, spelled month) - Currency: USD ($) unless specified otherwise - Numbers over 999 use commas: 1,000 not 1000 # Email Conventions - Subject lines: max 50 characters, action-oriented - Always include a clear CTA (call to action) - Sign off: "Best, [Name]" for external, "Thanks, [Name]" for internal - Customer emails: warm, solution-focused, never blame the customer # Our Customers - Small business owners (5–50 employees) - Non-technical, time-poor, value simplicity - Pain points: manual processes, scattered tools, no visibility # Common Tasks - Case studies follow the Challenge → Solution → Result framework - Blog posts: 800–1,200 words, scannable with subheadings - Social posts: LinkedIn-first, professional but human IMPORTANT: Never promise specific uptime percentages or SLA terms in marketing content.

Personal vs Team

Some instructions belong to the whole team. Some are just for you.

File Who sees it Shared? Example content
Team CLAUDE.md Whole team Yes Brand voice, company info, templates, formatting rules
Personal CLAUDE.md Just you No (private) Your role, experience level, personal preferences
Global preferences Just you N/A Preferences that apply to everything you do

👥 Team File

# BrightPath Brand - Voice: friendly, confident, never salesy - Always capitalize: BrightPath, Starter, Growth, Enterprise - Customer emails end with "Best, [Name]" - Blog posts: 800–1,200 words with subheadings

🧑 Personal File

# About Me - I'm the Content Lead, been here 6 months - I prefer bullet-point drafts before full prose - I'm dyslexic — keep paragraphs short - My accounts: healthcare & fintech verticals
Why separate? The team file ensures everyone gets on-brand outputs. The personal file lets you customize Claude for your working style. A new intern gets the same brand knowledge as a senior VP — but each can tune their personal experience.

Simulation: Good vs Bad Instructions

Same task, different CLAUDE.md quality. Watch the difference.

🔴 Vague CLAUDE.md

🟢 Specific CLAUDE.md

Common Pitfalls

Mistakes that make your CLAUDE.md hurt more than help.

⚠ The Novel

A 3-page CLAUDE.md covering every possible scenario. Claude gets overwhelmed and misses the important stuff buried on page 2.

Fix: Keep it under 60 lines. If it's not preventing a specific mistake, cut it.

⚠ The Fossil

Written when the company was called "WorkflowHub" — but you rebranded to "BrightPath" six months ago. Claude keeps using the old name.

Fix: Review your CLAUDE.md when things change. Treat it like a living document, not a one-time setup.

⚠ The Fortune Cookie

"Write engaging content that resonates with our audience." That's nice, but Claude has no idea what "engaging" means to your audience.

Fix: Be concrete. "Use short sentences. Lead with the customer benefit. Include a specific number or stat in every paragraph."

⚠ The Secret Keeper

Someone puts the company's CRM password or API key in the shared CLAUDE.md. Now it's in the git history forever.

Fix: Never put passwords or secrets in CLAUDE.md. Reference systems by name, not by credentials.

⚠ The Contradiction

Team file says "always formal" but your personal file says "be casual." Which one wins? Claude gets confused and alternates randomly.

Fix: Be intentional about what goes where. Personal preferences should complement team rules, not contradict them.

Simulation: A Full Work Session

Watch how CLAUDE.md instructions naturally guide a real work conversation — from morning briefing to client email.

⚡ Full Session

Quick Reference

Everything at a glance.

📏

Size

Under 60 lines.
One page max.

🎯

Tone

Specific & direct.
"Do X" not "try to be X."

🔄

Updates

Review monthly.
Update when things change.

👥

Team vs You

Brand rules = shared.
Your quirks = private.

💡

Key Test

Would Claude mess up
without this line?

🔒

Never Include

Passwords, secrets,
or login credentials.

TL;DR

CLAUDE.md is a short instruction file Claude reads at the start of every conversation — like a cheat sheet.

It has layers: Company-wide rules > your personal defaults > team project rules > your private project notes. All combined.

Be specific. "Use US date format" beats "format dates nicely." Every line prevents a real mistake.

Share what's shared, keep what's personal. Brand guidelines go in the team file. Your preferences go in your private file.

Keep it small. The best CLAUDE.md is the shortest one that still gets the job done right.