Your first CLAUDE.md

Claude Code starts every session by reading any file named CLAUDE.md it can find and treating the contents as standing instructions — things it should know without you repeating them. You do not need an elaborate one. This page gives you a short starter you can copy, tells you exactly where the file goes on each operating system, and helps you decide what deserves a line in it. The deeper treatment — how the files merge, the cross-tool AGENTS.md format, writing instructions that help instead of bloat — is in Give an agent standing instructions .

Two files, two scopes

There are two places the file usually lives, and they answer different questions:

Both are loaded when present and their contents are concatenated — the project file adds to your personal one rather than replacing it. That also means they should not contradict each other: when two rules conflict, the agent may follow either one.

A good split: facts about the project (how to run it, what not to touch) go in the project file; facts about you (how much explanation you want, your preferred language) go in the personal one.

A starter template

Copy this into a file, then make every line true of your actual project — replace the commands with your real ones and delete anything that does not apply. A line that is not true is worse than no line at all.

# Notes for Claude

## Run and test
- Run the app: `npm run dev` (replace with your project's command)
- Run the tests: `npm test` — run them after every change you make.

## Style
- Match the style of the surrounding code; don't reformat files you aren't otherwise changing.
- Small functions and clear names beat clever one-liners and long comments.

## Do not touch
- Generated files and build output (`build/`, `dist/`, coverage reports) — edit the source instead.
- Vendored or third-party code (`vendor/`, `node_modules/`).
- Never put a password, API key, or token in code, and never commit a `.env` file.

## Working with me
- Summarize what you changed and why in a few sentences — no long essays.
- If the task is ambiguous, ask one clarifying question before writing code.

Where the file goes

The project file — same place on every OS

CLAUDE.md goes at the root of the repository, next to your README. This is identical on macOS, Linux, Windows, and anywhere else: it is a normal file in the repo, and you commit it so everyone who clones the project — and every agent they run — gets the same instructions. Claude Code also picks up CLAUDE.md files in subdirectories when it works on files there, but ignore that for your first file.

The personal file — depends on your OS

Your personal, applies-to-everything file is ~/.claude/CLAUDE.md — a .claude folder in your home directory. What that means per system:

Two honesty notes. Claude Code’s documentation writes the personal path as ~/.claude/CLAUDE.md without spelling out a Windows-specific location — on Windows, ~ resolves to your user profile folder (%USERPROFILE%), which is where the .claude folder is created. And FreeBSD is not on Claude Code’s official supported-platform list (macOS, Linux, and Windows are); if you run it there anyway, the same ~/.claude/ home-directory convention applies, but you are off the documented path.

Personal notes for one project — kept out of git

Sometimes a note is about one project but only for you — your local database path, a quirk of your machine. For that, create CLAUDE.local.md at the project root and add it to .gitignore: Claude Code loads it alongside the project’s CLAUDE.md, but your teammates never see it. Claude Code does the same for settings: personal permission tweaks go in .claude/settings.local.json, which it keeps out of shared repos automatically, so a local override does not land in the team’s repository.

What belongs in it — and what does not

The file is read at the start of every single session, so every line is a small permanent tax on the agent’s attention. The test for each line:

• Put in what you would otherwise repeat every session. The test command, the “don’t touch dist/” rule, “answer briefly.” If you have typed it three times, it belongs in the file.
• Leave out what changes per task. “Fix the login bug” is a prompt, not a standing instruction. If it will not still be true next month, it does not belong.
• Keep it short. Ten sharp lines beat a hundred vague ones — a wall of instructions gets skimmed, not followed. When the file grows past a screen, cut before you add.
• Never put a secret in it. No API keys, passwords, or tokens — it is a plain-text file that gets committed, shared, and fed into every session. Name the path to a credential if the agent needs one (“the key is in .env, never print it”); never the value.

One habit worth building from day one: when the agent gets the same thing wrong twice, add a line to the file instead of correcting it by hand a third time. That is how the file earns its keep.

Where to go next

• The full story on instruction files, AGENTS.md, and writing rules that work: Give an agent standing instructions .
• The agent that reads all of this: Claude Code .