A CLAUDE.md file is project memory: the facts and constraints about your specific project that would otherwise need re-explaining in every single session.
1CLAUDE.md Is Project-Specific Memory
Claude Code automatically reads a CLAUDE.md file at the root of a project (and can read nested ones in subdirectories for monorepo-style overrides). It's the place to put facts that are true about this project specifically — the real test command, the real code style, real constraints like 'don't add dependencies without asking' — not general advice.
2Every Line Should Save a Re-Discovery
The test for whether a line belongs in CLAUDE.md: would Claude Code otherwise have to guess it, search for it, or be told it again next session? 'Tests run with npm test, not pytest' passes that test. 'Write clean, maintainable code' doesn't — it's already the default behavior and adds nothing specific.
3Step-by-Step Breakdown
Telling Claude Code How Fixly Works. Fixly has its own conventions: tests run with npm test, not pytest; it uses 2-space indentation; and the team never wants dependencies added without being asked first. A CLAUDE.md file at the project root tells Claude Code all of this once, instead of you repeating it in every session.
Without a CLAUDE.md, what happens when Claude Code needs to know 'how do I run this project's tests' in a new session?
- →It has to re-discover or guess the answer each session — by reading package.json, or asking — instead of already knowing it.
- →Claude Code cannot run any commands at all without a CLAUDE.md file present.
Draft a CLAUDE.md for a Real Project. Write the CLAUDE.md entries for a project with its own real conventions, so a new Claude Code session would know them immediately instead of guessing or asking.
Keep It Short and Load-Bearing. A CLAUDE.md that restates obvious things ('write good code', 'use best practices') adds noise without adding information — Claude Code already does that. The lines worth keeping are the ones that would otherwise have to be re-discovered or re-explained every session. Next: choosing what context to bring into a session at all.
Level Up 🚀
Advanced cheat sheets, SEO tricks, and interview prep for this topic.
Browser Support
N/A — CLAUDE.md is a plain text file read by the CLI.
N/A — CLAUDE.md is a plain text file read by the CLI.
N/A — CLAUDE.md is a plain text file read by the CLI.
N/A — CLAUDE.md is a plain text file read by the CLI.
Accessibility (A11y)
1Use Plain Headings and Short Lists
CLAUDE.md is read by both Claude Code and human teammates browsing the repo — scannable Markdown headings and short bullet lists serve both audiences better than dense prose.
## Commands
- Test: `npm test`SEO Implications
- 1
Target 'what is CLAUDE.md' and 'CLAUDE.md best practices' separately
New users search for what the file even is before they search for how to write a good one.
Best Practices
Include Real Commands, Real Conventions, and Real Hard Constraints
The highest-value CLAUDE.md content is exactly the three things a new teammate would need on day one: how to run things, how this codebase differs from default style, and anything that must never happen without asking (like adding a dependency or touching production data).
Frequent Bugs
Padding CLAUDE.md with generic software-engineering advice ('write tests', 'use meaningful names') that adds no project-specific information.
Keep only facts and constraints specific to this project that Claude Code couldn't already infer or wouldn't already do by default.
Real-World Examples
The Missing Test Command
Without a CLAUDE.md, a Claude Code session on a project using a custom test runner (`npm run test:unit` instead of `npm test`) spent its first turn discovering that by reading package.json. Adding one line to CLAUDE.md — the real command — removed that discovery step from every future session.
## Commands
- Test: `npm run test:unit` (not `npm test`)