A flat-vector illustration on a parchment cream field with a faint blue-grey azulejo tile pattern across the lower left. Left of centre stands a deep navy ship's wheel with ocean blue and green fittings. A blank, softly glowing rolled sheet of sand-colored paper is tied to one of its spokes with a terracotta ribbon, and thin golden current lines flow out from the wheel to the right across open space.
All Resources

What Is a CLAUDE.md File? (And What Goes in One)

By Chad Stamm · November 16, 2026 · 6 min read

If you've started using Claude Code, someone has probably told you to "set up your CLAUDE.md." It usually arrives the way developers say "check the README," as if everyone already knows what goes in one.

Most people don't. The name doesn't help either. It sounds like a configuration file, the kind you'd break by touching.

In practice it's closer to a note left on the desk for whoever starts work tomorrow. You write it once. Claude reads it every morning.

What is a CLAUDE.md file?

A CLAUDE.md file is a plain-text Markdown file of standing instructions that Claude Code reads at the start of every session. You write it, save it in a specific folder, and Claude treats what's inside as context for everything it does there. Anthropic's documentation puts the purpose in one line: "Treat CLAUDE.md as the place you write down what you'd otherwise re-explain."

In Anthropic's words, "Each Claude Code session begins with a fresh context window." Whatever Claude learned about you yesterday is gone by default. The file is how knowledge survives the reset.

The ".md" just means Markdown: ordinary text with a pound sign for headings and a dash for bullets. You can write it in any text editor.

Where does a CLAUDE.md file live?

In more than one place, and the location decides who it's for.

Location Who it applies to Good for
~/.claude/CLAUDE.md (your home folder) You, in every project How you work, wherever you work
CLAUDE.md at the top of a project folder Everyone on the project, shared through version control The project's rules, structure, and conventions
CLAUDE.local.md in a project folder You, in that project only Personal notes you don't want to share
A managed file set by IT Everyone in the organization Company-wide standards

The ~ is shorthand for your home folder. On a Mac, that's the folder with your username on it.

Claude doesn't pick one file and ignore the rest. It loads the CLAUDE.md in the folder you started in, plus every one in the folders above it, and the docs say they are "concatenated into context rather than overriding each other." The file closest to where you're working gets read last.

/init analyzes a project and drafts a starter CLAUDE.md for you. /memory lists the instruction files Claude found and opens any of them for editing.

When does Claude read it?

At the start of every session, before you type anything. The project-level file also comes back after a long conversation gets compacted, because Claude re-reads it from disk.

One thing to understand early: the file is advice, not a lock. Anthropic says Claude treats these files "as context, not enforced configuration." For a true hard stop, like never deleting a folder, the docs point to settings and permission controls instead, which Claude Code enforces whatever the model decides. This guide to agent context covers that second layer.

What should go in a CLAUDE.md file?

Anthropic's examples are written for programmers: build commands, conventions, where files live. The principle travels anyway. Write down whatever you'd otherwise explain again.

For someone who isn't a developer, that usually means four things:

  • Who you are. Your role, your work, and how you make decisions.
  • How you write. Voice rules, with a line or two of real examples.
  • What's current. The projects and deadlines in play right now.
  • Standing rules. What to always do, and what never to do without asking.

If you want the longer list, here's what goes in an AI context file in general.

Make every rule something you could check. The docs contrast "Use 2-space indentation" with "Format code properly," and the same logic holds outside code. "Be concise" is a wish. "Keep client emails under 150 words" is a rule, and you can see at a glance whether it was followed.

Here's what the top of a personal file might look like, for a made-up independent consultant:

# About me (updated 2026-11-16)

## Who I am
Independent brand consultant. Small food and beverage clients.
I decide on clarity first, then speed, then polish.

## How I write
- Short sentences. No jargon.
- Sign emails with my first name only

## Right now
- Two client rebrands due before December 15

## Rules
- Never send anything without my approval
- Ask before you guess at a client's pricing

Short, headed, checkable. Anthropic recommends exactly that shape: group instructions "under markdown headers and bullets."

What doesn't belong in a CLAUDE.md file?

Length is the first thing to watch. Anthropic's guidance is to "target under 200 lines per CLAUDE.md file," because "longer files consume more context and reduce adherence." You can pull other files in with an @ import, but the docs are clear that imports "don't reduce its context cost." The words still load.

So leave out:

  • Long procedures. A ten-step routine you run once a month belongs in a separate file, or in what Claude Code calls a skill, which loads only when it's needed.
  • Private details in a shared file. A project's CLAUDE.md travels with the project, so the docs suggest it hold "project-level standards rather than personal preferences." Your personal notes go in your home-folder file or in CLAUDE.local.md.
  • Contradictions. The docs warn that "if two instructions contradict each other, Claude may pick one arbitrarily." One rule per fact.
  • Anything you won't keep current. A stale deadline gets followed as confidently as a fresh one. Keeping context from going stale is its own habit.

CLAUDE.md vs AGENTS.md vs GEMINI.md

Other tools read their own version of the same idea.

File Read by Personal, all-projects version
CLAUDE.md Claude Code ~/.claude/CLAUDE.md
AGENTS.md Many coding agents, including OpenAI's Codex, Cursor, and GitHub Copilot's coding agent Varies by tool. Codex uses ~/.codex/AGENTS.md
GEMINI.md Google's Gemini CLI and its successor, Antigravity, which reads AGENTS.md too ~/.gemini/GEMINI.md

AGENTS.md calls itself "a README for agents" and is "just standard Markdown." It's now stewarded by the Agentic AI Foundation under the Linux Foundation.

Claude Code has started meeting it halfway. Recent versions read a project's AGENTS.md when there's no CLAUDE.md. If both exist, Claude reads only the CLAUDE.md by default. To keep one shared file, put the line @AGENTS.md at the top of your CLAUDE.md and add anything Claude-specific below it.

Google's Gemini CLI read GEMINI.md files, and Google replaced it with Antigravity CLI on June 18, 2026. Antigravity accepts either an AGENTS.md or a GEMINI.md, in a project or in the .gemini folder in your home directory.

The names differ. The contents can be identical, which is the whole argument for writing your context once, in plain text, and carrying it between tools.

Where to start

/init can find a project's build commands on its own. It can't find you. Your values, your voice, your priorities, and your people don't live in any folder Claude can read, so the most useful lines in a personal CLAUDE.md are the ones only you can write.

That's the material RUMO builds as six short documents you own, called context anchors.

Condense the essentials into your home-folder CLAUDE.md and keep the full anchors as separate files beside it. If you're unsure what to write first, start with the free Personal Constitution, which covers how you think and decide.

Then leave the note on the desk. Claude will read it tomorrow morning, and every morning after that.

Frequently Asked Questions

What is a CLAUDE.md file?
A CLAUDE.md file is a plain-text Markdown file of standing instructions that Claude Code reads at the start of every session. You write it once and save it in your home folder, a project folder, or both. Claude treats what's inside as context for everything it does there, so you stop re-explaining the same things each time you open a new session.
Where do I put my CLAUDE.md file?
For instructions that apply everywhere you work, save it as CLAUDE.md inside the .claude folder in your home directory. For one project, put a CLAUDE.md at the top of that project's folder, where it can be shared with your team. Personal notes for a single project go in a CLAUDE.local.md file next to it, which stays private to you.
What should I put in a CLAUDE.md file?
Anything you'd otherwise have to explain again: who you are and what you do, how you write, what you're working on, and the rules you want followed every time. Anthropic recommends instructions concrete enough to verify, grouped under headings. Leave out long step-by-step procedures, details that rarely matter, and anything you wouldn't want the rest of the project to read.
What is the difference between CLAUDE.md and AGENTS.md?
Both are Markdown files of instructions that an AI tool reads before it starts work. CLAUDE.md is Claude Code's own file. AGENTS.md is an open format read by many coding agents, including OpenAI's Codex and Cursor. Recent versions of Claude Code read AGENTS.md when a project has no CLAUDE.md. Google's tools read GEMINI.md, and Antigravity also reads AGENTS.md.
How long should a CLAUDE.md file be?
Anthropic's documentation recommends keeping each CLAUDE.md file under 200 lines, because longer files take up more of Claude's context and reduce how closely it follows the instructions. Pulling in other files with an import doesn't help with length, since imported files load along with the CLAUDE.md that names them. Move long reference material somewhere Claude reads only when needed.

Chad Stamm

Chad Stamm

Founder of RUMO

Chad is an AI strategist and integrator, context engineer, and creative director. He built RUMO so your AI can finally work on your behalf, not just answer your questions.

Start free

Give your AI a place to start.

Your Personal Constitution is the first context anchor, and it's free. Build it once, drop it into any AI tool, and watch it stop guessing who you are.

Build your free ConstitutionNo credit card required

Stay on course

Get AI tips, in your inbox.

We'll send practical context tips to help you build the best AI agents and systems.

No spam. Unsubscribe anytime.