Using Claude Code, you'll often run into a file named "CLAUDE.md." It sounds technical, but in one line it's "a note where you write down, once, the things you'd otherwise re-explain to Claude every time" — like an onboarding guide you hand a new teammate. This article explains what CLAUDE.md is and what to put in it, simply.
What is CLAUDE.md? (one-sentence definition)
CLAUDE.md is a markdown file holding "persistent guidance" about your project or how you work. "Markdown" just means a plain-text file written in ordinary words (no special coding needed). The key point: Claude Code reads this file automatically at the start of every session.
Why is it needed?
Claude Code starts fresh at the beginning of each conversation (session). It won't remember the project structure or rules you explained yesterday. So without CLAUDE.md, you'd repeat "here's how our project looks, build with this command, follow these rules" every time — like re-onboarding a new hire every single morning.
Write it once in CLAUDE.md, and since Claude reads it automatically at session start, you no longer repeat the same explanations.
What do you put in it?
The guiding rule is simple: write down "the things you keep re-explaining." The official docs recommend facts Claude should hold in every session:
- Build/run commands — frequently used commands (e.g., the dev server command).
- Project structure — folder layout, where things live.
- Coding rules/conventions — indentation, naming, style agreements.
- "Always do X" rules — fixed rules like "always write tests first" or "answer in Korean."
- What to avoid — files not to touch or actions to forbid.
Conversely, a multi-step procedure or content that only matters for one part of the codebase is better moved to a Skill or a path-scoped rule instead of CLAUDE.md. Since CLAUDE.md gets messy as it grows, keep it concise — around 50–200 lines.
Where does it go? (location hierarchy)
CLAUDE.md can live in several places, each with a different scope. Per the official docs, the main hierarchy is:
- Enterprise policy — rules applied org-wide, managed by IT/admins.
- Project (
./CLAUDE.md) — guidance shared by that project's team, usually included in the source code. - User (
~/.claude/CLAUDE.md) — personal preferences applied across all your projects; only you see it.
With multiple files, higher (broader) files load first as a foundation, and more specific files build on top. Important: CLAUDE.md is treated as "context," not enforced configuration — it's guidance Claude considers, not a hard block. So the more specific and concise you write it, the more consistently it's followed.
A simple example
If it's your first time, starting this short is plenty.
# Project guide
## Commands
- Dev server: npm run dev
- Tests: npm test
## Rules
- Always write tests first
- Comments and explanations in Korean
- Do not modify the src/legacy folderYou don't need to fill it perfectly from the start. Whenever you catch yourself thinking "I'm explaining this again," add a line then.
Summary
CLAUDE.md isn't a hard config file — it's "a note for what you'd otherwise re-explain every time." Claude reads it automatically each session, it holds build commands, structure, and rules, and its scope depends on location. For ready-to-use templates, continue with CLAUDE.md templates and examples by project type on this site.
This article explains public information from official Anthropic docs (code.claude.com/docs, docs.anthropic.com) in beginner-friendly terms. File locations and behavior can change with product updates, so verify against the official docs. This site is not an official Anthropic site.