What is CLAUDE.md and Why You Need It

CLAUDE.md is a Markdown file that Claude Code reads automatically at the start of every session. It encodes project-specific knowledge — your tech stack, naming conventions, architectural decisions, coding rules — directly into your repository so Claude always has context without you re-explaining it each time. Place it at the root of your project, commit it to git, and every session for every developer on your team starts with Claude already knowing your codebase. It's the lightest-weight way to give Claude persistent project knowledge.

Yes. Claude reads CLAUDE.md before your first message in every Claude Code session. The contents are injected into Claude's context as a system-level instruction, so the rules apply persistently throughout the conversation without consuming your conversation turns. You don't need to paste it in or remind Claude — it just works. You can also place CLAUDE.md files in subdirectories; Claude reads them when it navigates into those directories, enabling per-module rules layered on top of the project root file.

Put your project's main CLAUDE.md at the root of the repository, alongside your README and package.json, and commit it to git. This way every team member and every CI environment gets identical Claude behavior. For per-module conventions, you can place additional CLAUDE.md files in subdirectories — Claude reads them when it navigates into those areas, layered on top of the root file. For your personal cross-project defaults, a separate file lives at ~/.claude/CLAUDE.md (or the platform equivalent).

Focus on project-specific knowledge Claude cannot infer from reading your code. Good candidates include: tech stack and exact versions, coding conventions and style preferences, common commands like build/test/deploy, architectural constraints such as "never use X here", file and directory structure, and business-domain context. Avoid restating general programming best practices — Claude already knows those. Start with 10–20 lines covering your stack and top three conventions, and expand from there as you notice Claude making preventable mistakes.

Yes. Every byte of CLAUDE.md consumes context tokens, so a 10,000-word file leaves less room for actual code and conversation. Aim to keep it under 500 lines, prefer bullet points over prose paragraphs, and reference longer documents rather than inlining them — for example, "see docs/api-conventions.md for the full guide" plus a few key points. The most effective CLAUDE.md files are dense and specific rather than long and exhaustive.

Without CLAUDE.md, every new Claude Code session starts with no memory of your project — Claude doesn't know your naming conventions, preferred libraries, or the architectural decisions your team made months ago. You spend the first few minutes re-explaining your stack, you correct the same mistakes session after session, and different teammates get inconsistent behavior because they haven't set up the same context. CLAUDE.md fixes this by giving Claude persistent, version-controlled project knowledge that applies to every session for every developer.