CLAUDE.md is a markdown file placed in your project root that provides standing instructions to Claude Code. It is read at the start of every session and shapes how Claude approaches your codebase — your stack, conventions, constraints, and domain context.

Without CLAUDE.md, Claude starts every session without project-specific context. You end up repeating the same instructions about your stack, conventions, and rules. The file eliminates that repetition by encoding your preferences once.

Include four main sections: your tech stack and versions, coding conventions and file structure rules, explicit don'ts (things to avoid), and domain-specific context about your product and business rules.

Update it whenever you correct Claude for the same thing twice, introduce a new pattern or library, change an existing convention, or complete a major feature that introduced new domain rules. Treat it as a living document.

Yes. CLAUDE.md is a project file, not a personal preference. Committing it to the repository ensures everyone on the team gets the same set of instructions when using Claude Code. Personal preferences go in a home directory CLAUDE.md instead.

Yes. Claude reads CLAUDE.md files from the project root and from subfolders. The root file provides project-wide rules, and subfolder files add or override rules for specific areas. Claude merges them, with more specific files taking precedence.

There is no strict limit. Most effective files are between 30 and 100 lines. Focus on rules that affect Claude's output. If a line does not change the code Claude produces, it probably does not need to be there.

Conventions describe how things should be done: file naming, export style, component boundaries. Don'ts describe specific unwanted behaviors to prevent: no surprise dependencies, no extra comments, no out-of-scope refactoring. Both are important and serve different purposes.

Yes. After a productive session, ask Claude: 'Based on what we just built, what should I add to CLAUDE.md?' Claude will suggest additions based on the patterns and corrections from your conversation. Review the suggestions and commit what fits.

The most common mistakes are being too vague ('write clean code'), including information that does not affect output (project history), and writing it once and never updating it. Specific, actionable rules that evolve with the project produce the best results.