C:\>DOS to AI

C:\blog> more claudemd.txt

What is CLAUDE.md? The notes file Claude Code reads first

4 min readby Ian Willis

I’m Ian, tech-obsessed since I was eight. Let’s get you up to speed, fast.

This is episode 3 of Claude Basics, and it’s the one that saves you the most typing. If you’ve used Claude Code for more than a day, you’ve probably told it the same things more than once: keep the sentences short, don’t delete anything without asking, tell me what you changed. Claude Code can now remember some of that on its own (it calls this auto memory), but CLAUDE.md is the file you write yourself, so the rules you want every time are written down once and read every session.

What it is

CLAUDE.md is a plain text file, written in Markdown, that sits in your project folder. Claude Code loads it at the start of every session in that folder, before you’ve typed anything. Think of it as a note you leave on the desk for whoever sits there next: who they’re working for, how you like things done, and what to ask before they start. Here, the person sitting down is Claude, and it reads the note every single time.

There’s nothing special about the file. It’s a heading and some bullet points, and you can open it in any text editor.

An example

Here’s the whole file for Owen, a fictional writer on a fictional team. It’s five lines:

# Owen
Role: writer. Scripts, hooks and words.
- Short sentences, plain words.
- Ask before deleting anything.
- Report: done, not done, what you need.

That’s it. Start Claude Code in Owen’s folder, ask for a two-line hook, and you get short, plain sentences without saying so, because the file already said so.

What goes in it

The rule I use is simple: anything I’d type every time goes in the file. That usually means a few kinds of things.

  • Who it’s working for and what the project is. A line or two, so Claude isn’t guessing.
  • How you like things done. Sentence length, tone, which tools or commands to use, what to leave alone.
  • What to ask first. Anything you want a check on before Claude does it, like deleting files or sending anything anywhere.
  • How to report back. I like “done, not done, what you need”, because it tells me what to do next.

Keep it short. Anthropic’s own guidance is to aim for under 200 lines, because a long file uses up Claude’s working memory and the rules in it get followed less, not more. When Claude gets something wrong, add one line about it. That’s how the file grows, one correction at a time.

Getting a first draft

If you’re starting from a blank folder, you don’t have to write it from scratch. Type /init inside Claude Code and it looks through your folder and drafts a CLAUDE.md with what it finds: how the project is built, how it’s tested, the conventions it notices. Then you edit it down. If a CLAUDE.md already exists, /init suggests improvements instead of overwriting it.

One file for all your projects

There’s a second place Claude Code looks: a CLAUDE.md in the .claude folder inside your home folder. Anything in there applies to every project you open, so it’s the place for the preferences that never change, like “plain words” or “ask before deleting”. The project file adds to it, and when the two say different things, the project one wins. The folder is hidden by default; on a Mac, press Command-Shift-period in Finder to see it.

If you also use other tools

Several other AI coding tools read a file called AGENTS.md that does the same job. Since version 2.1.277, Claude Code reads AGENTS.md too when there’s no CLAUDE.md in the folder or above it. If you have both, Claude Code reads only CLAUDE.md, but you can put the line @AGENTS.md at the top of your CLAUDE.md and it reads both, so every tool on the project shares one set of rules. The next post covers AGENTS.md.

What to remember

  • CLAUDE.md is notes for Claude, read at the start of every session.
  • Write a rule once, instead of typing it every time.
  • Keep it short, and add a line when Claude gets something wrong.
  • /init drafts one for you from your folder.
  • A CLAUDE.md in your home folder’s .claude covers every project.

Hope you found this helpful. You’ll find more free prompts and articles on dos2ai.com.

Written in October 2026 with Claude Code 2.1.302. Claude Code changes fast, so always check the latest on Claude Code Docs: https://code.claude.com/docs/en/memory

Not affiliated with or endorsed by Anthropic. I’m an independent user.