$ man how-to/how-to-write-claude-md

CLAUDE.md is a plain Markdown file that Claude Code reads at the start of every session. It is the onboarding document for your AI teammate. Everything in this file becomes part of the context window - Claude sees it before you type your first message. Without a CLAUDE.md, Claude Code operates generically. It does not know your project structure, your coding conventions, your build commands, or your deployment process. With a CLAUDE.md, it operates as a teammate who has read all your docs. The file lives in your repo root. It gets version-controlled with your code. When the project evolves, the CLAUDE.md evolves with it. When a new developer joins, they get Claude Code pre-configured for your project automatically.

PATTERN

Claude Code loads CLAUDE.md from multiple locations, merging them in order: 1. ~/.claude/CLAUDE.md - Global config. Applies to every project. Put your personal preferences here: editor settings, commit style, communication preferences. 2. /project-root/CLAUDE.md - Project config. Applies to this repo. Put project-specific instructions here: build commands, coding standards, architecture overview. 3. /project-root/src/CLAUDE.md - Directory config. Applies when working in the src/ directory. Put module-specific instructions here: API conventions for the API module, component patterns for the UI module. Each level adds to the context. Global plus project plus directory. Use this to avoid repetition: global handles your personal style, project handles the codebase, directory handles the module. For monorepos: put shared conventions in the root CLAUDE.md. Put app-specific instructions in each app's directory. For example, website/apps/dashboard/CLAUDE.md might say "this app uses Tailwind CSS and shadcn/ui components" while the root CLAUDE.md covers the shared TypeScript config.

PATTERN

The most effective CLAUDE.md files cover six areas: 1. Build and test commands. The exact commands to build, test, lint, and deploy. Not "run the tests" but "npm run test" or "pytest -x tests/". Claude Code uses these directly. 2. Project structure. A brief map of the codebase. Where the source code lives, where tests go, where config files are. Two to five lines, not an entire directory tree. 3. Coding conventions. Indentation, naming patterns, import ordering, file naming. Specific and verifiable: "use 2-space indentation" not "format code nicely." 4. Safety rules. What to never do. "Never commit .env files." "Never push to main without tests passing." "Never delete migration files." These are guardrails that prevent costly mistakes. 5. Workflow instructions. How you want Claude Code to operate. "Run tests before marking a task complete." "Write a context handoff at the end of every session." "Enter plan mode for tasks with 3+ steps." 6. Key references. Pointers to important docs. "See docs/ARCHITECTURE.md for system design." "See .cursor/rules/ for file-pattern rules." Pointers, not copies - this keeps the CLAUDE.md lean.

ANTI-PATTERN

Common mistakes that make CLAUDE.md files worse: Do not paste large code blocks. They become stale when the code changes. Point to the file instead: "see src/lib/auth.ts for the authentication pattern." Do not exceed 200 lines. Every line consumes context tokens. A 500-line CLAUDE.md eats into the space available for actual code and conversation. If you need more detail, use the @import syntax to load files on demand. Do not write vague instructions. "Write good code" and "follow best practices" are meaningless to an AI. They get interpreted differently every session. "Use early returns instead of nested if-else" is specific and consistent. Do not duplicate documentation. If you have a CONTRIBUTING.md, point to it. Do not copy its contents into CLAUDE.md. One source of truth. Do not include secrets or environment variables. CLAUDE.md is version-controlled. If your build needs API keys, say "set OPENAI_API_KEY in .env" not the actual key value.

CODE

CLAUDE.md supports importing other files with the @path/to/file syntax. Imported files expand inline when Claude Code loads the context. Use imports for: - Architecture docs: @docs/ARCHITECTURE.md - Team conventions: @docs/CONVENTIONS.md - API documentation: @docs/API.md This keeps the root CLAUDE.md lean (under 200 lines) while giving Claude access to detailed references when needed. The imported files only load when the CLAUDE.md is processed, so they do not consume tokens until a session starts. A pattern that works: keep the CLAUDE.md as the table of contents and use imports for the chapters. The CLAUDE.md says "For deployment instructions, see @docs/DEPLOY.md." Claude sees the full deployment doc when it needs it.

PRO TIP

The fastest path: open Claude Code in your project and run /init. It generates a starter CLAUDE.md based on your project structure, package.json, and existing config files. Review it, trim the generic stuff, and add your project-specific instructions. If you want to start from scratch, create a CLAUDE.md at your project root with these three sections: ## Build Commands npm install npm run dev npm run test npm run build ## Project Structure - src/ - Application source code - tests/ - Test files - docs/ - Documentation ## Rules - Run tests before committing - Use TypeScript strict mode - Never commit .env files That is enough to make Claude Code significantly more useful. You can expand it over time as you notice patterns - every time Claude Code does something wrong, add a rule. Every time you re-explain something, add it to the file. The CLAUDE.md seasons with use, like a cast iron skillet.