A CLAUDE.md file is a plain-text file at the root of a project that Claude reads at the start of every session. Most explanations frame it as a coding tool, since it started in Claude Code. The format holds up for any project you'd return to more than once: a client folder, a content calendar, a research file. By the end of this, you'll have working examples for four different kinds of projects, plus a blank version to fill in yourself.
The quick answer
Put a file named CLAUDE.md in your project's root folder. Fill it with what someone joining the project would need to be told on day one that isn't obvious just from looking at the files: the rules, the recurring steps, the things that are off-limits. Claude loads this file automatically every session, no matter what the project contains.
What goes wrong without one
Without a CLAUDE.md file, Claude guesses at things a person on the project would just know: which folder holds a client's final files versus a draft, whether a specific tone applies to outbound emails, whether one section of a document is off-limits to touch. The guesses are usually reasonable. Reasonable isn't the same as correct, and you end up correcting the same handful of things every time you start a new conversation.
A CLAUDE.md file closes that gap once instead of every time.
What to put in it, and what to leave out
Anthropic's own Claude Code documentation lays out a simple split, and it holds up outside of code too. Include:
- The exact steps or values Claude can't guess: commands for a coding project, a specific format or template for anything else
- Rules that differ from the obvious default: a style choice, a naming convention, a tone
- What "done" looks like for a task in this project
- Etiquette: how files get organized, named, or handed off
- Decisions specific to this project that wouldn't apply anywhere else
- Access or environment quirks: logins, folder structures, required steps
- Known gotchas or mistakes that already happened once
Leave out:
- Anything Claude can figure out on its own by looking at the project
- Standard conventions Claude already knows
- Long reference material (link to it instead of pasting it in)
- Information that changes often
- Self-evident advice like "communicate clearly"
Four project types, one format
The file's shape barely changes: an overview, the rules that aren't obvious, and a running list of gotchas. What goes inside those sections is what changes. Here's the same format applied to four different kinds of projects.
A website or content project
This is the version most people picture, and it's the one this website runs on. The CLAUDE.md file for itechnicallykan.com opens with a one-line description of the site, documents the exact CSS variables and page structure every page has to match, and ends with a literal checklist to run through before shipping a new page. None of that is guessable from the HTML alone.
# Site Name
One-line description of what this site is.
## Design rules
- Color variables: (list them)
- Fonts: (list them)
- Every page must include: nav, footer, analytics snippet
## Before shipping any page
- [ ] All nav links present, correct one marked active
- [ ] Images use the right asset path
- [ ] Meta title and description written by hand, not left blank
## Known gotchas
- (Add a line here every time a page ships with something missing)A client services business
For an agency, consultant, or freelancer managing multiple clients through Claude or Cowork, the CLAUDE.md file protects against the mistake that costs the most: mixing clients up.
# Client: [Name]
Scope: what we do for this client, in one sentence.
## File organization
- Drafts live in /drafts, approved final versions live in /final
- Never overwrite a file in /final directly
## Tone and rules for this client
- Formal, no contractions, in anything client-facing
- Never send an email directly. Draft it and hand it back for review.
## Known gotchas
- (e.g. "This client's invoices go out on the 1st, not the 30th")A personal research or writing project
For a book, a thesis, or a long-running personal project, the CLAUDE.md file keeps voice and sourcing consistent across work that might stretch on for months.
# Project: [Working title]
Topic and audience, in one or two sentences.
## Voice
- Rules pulled from your own style guide, if you have one
- Words or phrases to avoid
## Sources
- Only cite sources that are linkable and checkable
- Flag anything that's opinion, not fact
## Structure
- Chapter files are numbered: 01-intro.md, 02-background.md
- Keep a running outline in outline.md, update it when structure changes
## Known gotchas
- (What's gone wrong once already)A small ops or admin workflow
For the parts of running a business that aren't glamorous, invoicing, scheduling, inbox triage, the CLAUDE.md file works closer to a standard operating procedure than a style guide.
# Admin workflows
## Invoicing
- Template lives at: (path or link)
- Always confirm the amount with me before sending
## Email
- Draft replies, don't send anything client-facing without review
- Signature block: (paste it)
## Recurring tasks
- Weekly: (list them)
- Monthly: (list them)
## Known gotchas
- (What's gone wrong once already)A blank version, if you'd rather start from nothing:
# Project Name
One or two sentences: what this project is and who it's for.
## Key facts
- (Anything Claude would otherwise have to ask about every time)
## Rules
- (Anything that differs from the obvious default)
## Structure or process
- (How files, tasks, or steps are organized)
## Things to always check
- [ ]
- [ ]
## Known gotchas
- (This section grows over time. Every time Claude makes the same
mistake twice, add a line here.)
## Do not
- (Anything genuinely off-limits)Generating a starting point automatically
If your project is a codebase, you don't have to write the first draft by hand. Run the /init command and Claude scans the project, detects the build system and existing patterns, and writes a starter CLAUDE.md file based on what it finds. For anything that isn't code, a content project, a client folder, a research file, there's no equivalent scan. You're filling in one of the templates above by hand, which usually takes less time than reviewing the first /init draft would anyway.
Keeping it useful
The most common failure, in any kind of project, is a CLAUDE.md file that keeps growing until it stops being useful. Anthropic's own engineering team has said bloated CLAUDE.md files cause Claude to ignore your instructions, because the important rules get buried in the noise. For every line, ask whether removing it would cause a mistake. If the answer is no, cut it.
Write it the way you'd write a rule, not a suggestion. "Always confirm the invoice amount before sending" works. "We generally like to confirm invoice amounts when possible" doesn't, because Claude reads the second version as optional.
Treat the file like something you maintain, not something you write once and forget. When the same mistake happens twice, that's a missing line. Run /context after an edit to confirm the file loaded the way you expect.
What "done" looks like
A finished CLAUDE.md file is never really finished. It stays short enough that Claude reads every line of it, specific enough that it answers questions before they get asked, and current enough that the last edit came from something that went wrong last week, not a wishlist from month one.
CLAUDE.md and skills solve a related problem in different ways. CLAUDE.md loads on every session, so it works best short and universal to the whole project. For instructions that only apply sometimes, one specific report format, one client's odd request, Claude Skills are the better fit, since they load only when the task calls for them. And the format doesn't care what surface you're using: Claude Code, the API, and Cowork mode all read a project's CLAUDE.md file the same way, whether that project is a codebase or a client folder.
