Table of Contents
Overview
Have you ever felt, while using Claude Code, like you're "repeating the same explanation every time"? Explaining a project's tech stack and coding conventions from scratch at the start of every session is inefficient. That's where a file called "CLAUDE.md" comes in — placed at the project root or in a directory, it's automatically loaded at the start of a session, functioning as a kind of "instruction manual for the AI."
Structure it around WHAT, WHY, and HOW
A widely shared, effective template for CLAUDE.md is structuring it around three perspectives: WHAT (what the project does), WHY (why a given rule exists), and HOW (specifically how to implement it). Rather than just listing rules, writing in the background of "why this rule exists" seems to help the AI understand the intent behind a rule and apply it with better judgment in edge cases.
Aim for roughly 200 lines or fewer per file
Another important guideline concerns length. It's recommended to keep each CLAUDE.md file to roughly 200 lines or fewer. If content is going to exceed that, it's better to split it out into Skills or a ".claude/rules/" directory. As a file grows bloated, the AI becomes more likely to miss the rules that actually matter — so staying concise seems to pay off in better accuracy.
Practical writing tips
A commonly cited point when writing CLAUDE.md is to avoid subjective phrasing like "make it look nice." Claude can't interpret a vague phrase like "nice." Instead, you need to translate it into something objective and verifiable — "use camelCase consistently for variable names," for instance.
An interesting point also worth noting: prohibitive instructions ("don't do X") tend to be followed more reliably than affirmative ones ("please do Y"). Explicitly spelling out behavior you want to avoid, it turns out, is actually an effective way to steer things.
A ready-to-use template structure
If starting from a blank page feels daunting, filling in the following five sections as a template makes it more approachable:
- Project overview
- Tech stack
- Coding conventions
- Prohibited actions
- Frequently used commands
Starting from these five sections should let even a first-time CLAUDE.md writer get going without much hesitation.
Layer it for multiple projects
If you're going beyond personal projects and using Claude Code across a "monorepo" that bundles multiple packages or services into one repository, it's worth knowing how to lay out CLAUDE.md hierarchically. Concretely, you place a CLAUDE.md with shared rules (coding conventions and CI/CD policy that apply repo-wide) directly under the repository root, and place a separate CLAUDE.md with rules specific to that area inside each package's directory — say, the frontend package or the API package.
Claude Code appears to recursively search for CLAUDE.md files from your working directory up toward parent directories, load all the ones it finds, and prioritize the more specific (deeper) instructions. One subtlety worth knowing here: the root-level CLAUDE.md gets reloaded even after mid-conversation context cleanup via "/compact," while a nested (subdirectory) CLAUDE.md does not get re-injected. If a subdirectory-specific rule seems to stop applying during a long work session, this behavior may be the reason.
Don't aim for perfection — let it grow
Another important mindset for maintaining CLAUDE.md is not trying to build a perfect version from the start. A recommended, incremental style is adding one line each time something goes wrong — "watch out for this next time." Keeping in mind that, over weeks and months, it naturally grows into something well-tuned to your specific project should lower the initial hurdle considerably.
How it relates to MEMORY.md
Claude Code also has something called MEMORY.md, which its agent quietly edits from time to time with project information. The trouble is, old information can be left sitting in there, or the agent can occasionally write something incorrect.
There's no strictly documented priority rule, but the two are treated differently:
- CLAUDE.md: handed over with strong language along the lines of "these instructions override default behavior and must be followed exactly as written." It's positioned as currently valid, deliberately curated instruction. - MEMORY.md (memory): comes with the caveat that "this is a snapshot at a point in time, and may not always be current — check it against the present state before using it." It's reference information, not an absolute instruction.
I think checking the contents of MEMORY.md from time to time as you work leads to fewer mistakes. (More often than not, when I trace back the cause after something's gone wrong, it turns out the information in MEMORY.md was wrong or out of date...)
Summary
Points worth keeping in mind when writing CLAUDE.md:
- Structure it around the three perspectives of WHAT, WHY, and HOW
- Aim for roughly 200 lines or fewer per file, splitting into .claude/rules/ if you exceed that
- Avoid vague phrasing like "make it nice" — use concrete verbs and prohibitive phrasing instead
- Don't aim for perfection from the start — let it grow, one line at a time, after each failure
Treating CLAUDE.md not as a file you write once and finish, but as a living document that grows alongside the project, should make it something you can keep up without much strain.