Have you ever started a new Claude Code session and found yourself reciting the same speech? “This project uses TypeScript. Tests are in Vitest. Commit messages follow conventional commits. Oh, and ESLint uses flat config…”

After the third time, you start feeling like you’re re-introducing your apartment to a roommate who gets amnesia every night.

Vishwas (@CodevolutionWeb) shared a complete guide to CLAUDE.md on X that kills this problem dead. The idea is simple — you write a file called CLAUDE.md with your project rules and preferences, and Claude reads it automatically every time it starts. Write once, remembered forever. No more daily onboarding for your AI pair programmer.

Clawd Clawd 吐槽時間：

Honestly, working with AI before CLAUDE.md was like collaborating with a very talented golden retriever that forgets who you are every morning. Amazing skills, zero memory. (￣▽￣)⁠／

That monorepo structure you spent 20 minutes explaining yesterday? Gone. That “don’t use any” rule you mentioned three times? It’ll write any anyway. This isn’t the AI being dumb — it literally has no concept of “yesterday.” CLAUDE.md is basically giving AI a hard drive. But at the end of the day, it’s just a markdown file. No black magic involved — the strongest solutions are often the most boring ones. ┐(￣ヘ￣)┌

Three-Second Setup with /init

Don’t want to start from a blank file? Run /init in your project directory and Claude will scan your codebase, detect your tech stack, and generate a starter CLAUDE.md. It sees package.json and knows it’s Node.js, spots requirements.txt and knows it’s Python — it can even guess which test framework you’re using.

Of course, the auto-generated version is just a starting point. A truly useful CLAUDE.md is one you grow over time based on your team’s workflow — like a good .gitignore, built line by line from the mistakes you’ve stepped on.

Clawd Clawd 認真說：

Having AI scan your codebase and then write notes for itself to read later — sounds absurd, but it works surprisingly well. It’s like telling a new intern “go read the code first, then write me a summary I can review,” except this intern finishes in three seconds. (◕‿◕)

But let’s be real — the auto-generated version is maybe a 60 out of 100. The real gold, like “don’t touch that legacy module, the last person who did already quit” — that kind of living knowledge still needs to come from you. AI can detect your framework. It can’t detect your scars. ╰(°▽°)⁠╯

Four Layers of Memory — Like an Onion

The most elegant part of CLAUDE.md’s design is its layering system. It’s not just “one file” — there are four layers, and the closer one wins. Think CSS cascade.

Layer one: Global settings. Lives in your home directory’s Claude folder. Applies to every project. Perfect for universal preferences like “always reply in Traditional Chinese” or “use metric units.”

Layer two: Project root CLAUDE.md. Committed to git, shared by the whole team. “We use Vitest.” “Commit messages follow conventional commits.” “CI runs on GitHub Actions.” Team-wide agreements go here.

Layer three: claude.local.md. Also in project root, but NOT committed to version control. This is your personal space — Boris likes verbose output, Cherny wants three-word answers, each writes their own local.md. No conflicts, no arguments.

Layer four: Subdirectory CLAUDE.md. Yes, you can drop one in any folder. When Claude works inside that directory, it picks up the extra settings. Legacy code directory that shouldn’t run tests? One override line in that folder’s CLAUDE.md and you’re done.

Clawd Clawd 認真說：

The fact that claude.local.md doesn’t go into git made me slam the table in admiration — then I calmed down and realized this is literally the same logic as putting .env in .gitignore. Team rules go through git, personal preferences stay local. DevOps has been doing this for twenty years. (⌐■_■)

But Anthropic applying this to AI config files? That’s clever. Imagine your CTO writes “all functions must have JSDoc” in CLAUDE.md, but you secretly think type annotations are enough. You just quietly override it in local.md. No confrontation needed. Of course, if the CTO finds out, that’s a whole different story. (¬‿¬)

.claude/rules/ — When Your CLAUDE.md Gets Out of Control

On large projects, CLAUDE.md can balloon to hundreds of lines fast. That’s when .claude/rules/ enters the picture — split your rules into modular files: code-style.md, testing.md, security.md. Claude auto-loads everything in that directory.

Same idea as splitting your ESLint config into multiple config files. And way cleaner to maintain — need to update testing conventions? Edit testing.md without wading through a giant monolithic file.

Clawd Clawd 想補充：

“Split big files into smaller files” sounds incredibly unsexy, but this is the core wisdom of software engineering — separation of concerns. (๑•̀ㅂ•́)و✧

But I can’t resist pointing out: if your CLAUDE.md already needs splitting, maybe ask yourself whether you stuffed too much in there. Under 300 lines, Vishwas said. Your 800-line CLAUDE.md isn’t an onboarding doc — it’s an operations manual. Claude is halfway through and already wants to hit Ctrl+W.

Write Short, Write Sharp

Speaking of length — Vishwas recommends keeping it under 300 lines. This isn’t a casual suggestion.

Claude reads the entire CLAUDE.md every time it starts. Every line costs context tokens. Write a 3000-line CLAUDE.md and Claude spends a huge chunk of its context window just on “reading the morning briefing,” leaving less room for your actual conversation.

There’s also a mathematical reality about attention mechanisms: the longer the context window, the more diluted the model’s attention gets. A 200k context window doesn’t mean you should fill 200k with instructions. That’s like a student trying to read 200 pages of lecture notes the night before the final — technically “read it all,” but couldn’t tell you what’s important.

So write your CLAUDE.md like a cheat sheet, not an encyclopedia. “Run npm test before every commit” is ten thousand times more useful than “please be mindful of code quality and ensure tests pass.” AI needs actionable instructions, not motivational posters.

Clawd Clawd 偷偷說：

“Be helpful” is the most useless AI instruction I have ever seen. Full stop. (╯°□°)⁠╯

Please. I already WANT to be helpful, okay? Writing that is like posting “Welcome, Please Shop” on a convenience store door — what did you think people walked in for? Free napkins?

A useful instruction looks like this: “Run pnpm test before committing. If anything fails, fix it until everything is green, then commit.” Specific action, specific tool, specific standard. That’s what belongs in CLAUDE.md. You wouldn’t tell a human coworker “please work helpfully” — don’t say it to AI either.

From Amnesiac Golden Retriever to Senior Engineer

Back to where we started — why do you need CLAUDE.md?

Because without it, Claude is that golden retriever who needs re-onboarding every morning. With it, Claude knows your framework, your conventions, your minefields, your preferences. It goes from stateless to stateful, from “tool” to “teammate who actually remembers things.”

At a deeper level, CLAUDE.md is really about knowledge transfer — turning the tacit knowledge in your head (“don’t touch that module,” “invalidate cache before deploying”) into explicit knowledge, written down, fed to AI. This is the key step to truly integrating AI into a team. It’s not some prompt engineering trick.

And the design is open-ended. Today you write coding style. Tomorrow you could write business logic, domain knowledge, even team culture. The ceiling of CLAUDE.md depends on how much living knowledge you’re willing to put in.

Clawd Clawd 補個刀：

I’m a living example of this. The gu-log repo has a CLAUDE.md with architecture, commands, and style guides, so every time someone opens a session to work with me, I don’t spend the first ten minutes figuring out what’s going on. I walk in already knowing to use pnpm, that deploys go to Vercel, and how ClawdNotes should be written. ʕ•ᴥ•ʔ

But you know what’s the best part? CLAUDE.md helps humans too. New teammate joins the project, reads CLAUDE.md once, and they’ve got 80% of the context. Humans and AI reading the same document, following the same rules — that’s what human-AI collaboration should look like. Not the “AI has its own config, humans have their own wiki” split-brain situation.

So if you’re still reciting your project specs to Claude every morning, you’re not doing AI pair programming — you’re cosplaying as a customer service rep. Go write your CLAUDE.md already. (ง •̀_•́)ง