If you've started using Claude Code and found yourself re-explaining your project stack at the beginning of every session, CLAUDE.md is the fix. This tutorial covers what the file does, why skipping it costs you tokens and time, and how to write one in under five minutes — even if your project is already mid-flight.
1. Why This Matters Now
Claude Code has no persistent memory between sessions. Every time you run claude, the model starts fresh — it doesn't remember that your project uses Node 20, that your test runner is Vitest, or that you absolutely do not want console.log statements left in production code. You have to tell it again. And again.
This becomes a real problem at scale. If you're running multiple projects — or, like me, orchestrating workflows across a cluster of machines — those first three to five "re-orientation" turns per session add up fast. That's wasted context window, wasted tokens, and wasted focus before you've even typed a real question.
CLAUDE.md solves this at the source. It's a plain Markdown file that Claude Code reads automatically the moment you run the claude command. Before any conversation starts, that file is sitting at the top of the context window. Claude walks in already briefed.
2. The Core Idea
One file, placed once in your project root, replaces every repeated explanation you'd otherwise give at session start.
Think of it like the onboarding doc you hand a new contractor. You could walk them through the codebase verbally every morning — or you could write it down once. CLAUDE.md is that document, except Claude actually reads it every single time, without skimming.
The practical difference is stark. Without CLAUDE.md, Claude might ask "Should I remove the console.log here?" With CLAUDE.md containing a rule that says no console.log in production code, Claude never writes one in the first place.
There's a useful mental model here: if your context window is a goldfish with zero long-term memory, CLAUDE.md is the sticky note on the tank. It doesn't fix the memory — it just makes sure the right information is always visible.
3. How to Implement It
The minimum viable CLAUDE.md covers three things: your tech stack, your hard rules, and the commands Claude will need to run. Here's a real example from a TypeScript quant bot project:
Project: my-quant-bot
## Stack
- Runtime: Node 20 / TypeScript
- Test: Vitest (`vitest run`)
- Formatter: Prettier (`prettier --write .`)
- DB: PostgreSQL 16 (local Docker, port 5432)
## Rules
- Never leave console.log in production code
- Run type check before any PR: `npx tsc --noEmit`
- Do not modify files under /generated — these are auto-built
## Common Commands
- Dev server: `npm run dev`
- Run all tests: `npm test`
- Lint: `npm run lint`
That's it. Less than 20 lines. Claude now knows the runtime, knows what it can't do, and knows how to run the project without asking.
To generate the first draft automatically, run this from your project root:
claude 'Draft a CLAUDE.md for this project based on the current folder structure and package.json.'
Claude will scan what's there — package.json, directory layout, config files — and produce a working draft. Expected output is a Markdown file covering your detected stack, scripts pulled from package.json, and a placeholder rules section you fill in yourself.
Verify it's being picked up by opening a new Claude Code session and asking:
claude 'What runtime and test framework does this project use?'
If Claude answers correctly without you explaining anything, the file is working. If it hedges or asks clarifying questions, check that CLAUDE.md is in the project root (not a subdirectory) and that it's not listed in .claudeignore.
To confirm the file is in the right place:
ls -la CLAUDE.md
Expected output:
-rw-r--r-- 1 seunghyeon staff 412 May 27 09:14 CLAUDE.md
4. What to Watch in Production
Don't try to be exhaustive on day one. A five-line CLAUDE.md that actually exists beats a perfect spec that you never finish writing. The file is plain text — update it as your project grows. Add a rule the moment you catch Claude doing something you don't want repeated.
Rule specificity matters. "Be careful with SQL" is useless. "Never run DELETE or UPDATE without a WHERE clause" is a rule Claude can actually follow. The more concrete the rule, the more reliably it applies.
Watch for rule drift. If your stack changes — say you migrate from Jest to Vitest — update CLAUDE.md at the same time. Claude will follow the file, not what you said last week. Stale rules lead to stale behavior.
Environment differences to know:
| Scenario | What to do |
|---|---|
| Monorepo with multiple packages | Add a CLAUDE.md in each package subdirectory in addition to root |
| Docker-based dev environment | Include Docker commands explicitly; file paths may differ |
| Shared team project | Commit CLAUDE.md to source control so every dev's session is consistent |
| Personal experiment / solo project | Even a 5-line file pays off by session 3 |
One security note: if your CLAUDE.md references environment variables or internal hostnames, make sure you're not exposing anything sensitive. The file itself is just Markdown, but it will sit in context — treat it like any other committed config file.
FAQ
When should I use CLAUDE.md?
Any time you're running more than one Claude Code session on the same project, CLAUDE.md is worth having. The payoff hits fast — by the second session you've already recovered the time it took to write it. If you're working solo on a throwaway script, you might skip it. For anything you'll touch again, create the file.
What should I check before applying CLAUDE.md in production?
Make sure the file is in the project root and that the commands listed actually run correctly in your environment. The fastest way to cause confusion is to put a broken command in the "Common Commands" section — Claude will try to run it and hit an error it didn't expect. Do a dry run of every script in the file before committing it. Also confirm you haven't accidentally listed commands that require elevated permissions or external credentials without noting that context.
What is the easiest way to verify the result?
Open a fresh Claude Code session and ask Claude something only CLAUDE.md would tell it — like what test runner the project uses, or what the dev server command is. If it answers correctly without any prompting, the file is live and working. This takes about 30 seconds and tells you immediately whether Claude is reading the file or ignoring it.
Closing
CLAUDE.md is the lowest-effort, highest-leverage thing you can add to any Claude Code project. Write it once, commit it, and every future session starts informed instead of confused.
The immediate next step: run claude 'Draft a CLAUDE.md based on this project's structure and package.json' in your project root, review the output, add your team's hard rules, and commit the file.
🐦 Faster updates on X: @baegseungh7061
📚 More in this series: Code Intro
💌 Subscribe: Follow on X or grab the RSS
댓글
댓글 쓰기