claudekit / guides / claude-md-best-practices
[ Guide · Practical · 10 min ]

Writing a Great CLAUDE.md

published · updated

How to write an effective CLAUDE.md at your project root. Covers where to put it, what to include, and how to keep it tight enough for your token budget.

Why CLAUDE.md matters

Claude Code auto-loads CLAUDE.md from your working directory and every directory above it at the start of every session. Files in subdirectories load on demand, once Claude works with files there. Write it well once and the same guidance applies to every session — no repeating yourself.

A good CLAUDE.md immediately improves answer quality and reduces wrong assumptions and repeated mistakes.

Four locations

The docs list four CLAUDE.md locations, in load order from broadest scope to most specific:

LocationScope
Managed policy (macOS /Library/Application Support/ClaudeCode/CLAUDE.md, Linux /etc/claude-code/CLAUDE.md)Organization-wide, managed by IT/DevOps
~/.claude/CLAUDE.mdUser instructions (all projects)
./CLAUDE.md or ./.claude/CLAUDE.mdProject instructions, shared with your team via source control
./CLAUDE.local.mdPersonal project-specific preferences (add to .gitignore)

These files don’t override each other. All discovered files are concatenated into context, so a project instruction simply appears after a user instruction. If two instructions contradict each other, Claude may pick one arbitrarily — keep your files free of conflicts.

For larger projects, organize instructions into topic-specific files under .claude/rules/. A rule with paths frontmatter only loads when Claude works with matching files. Personal rules in ~/.claude/rules/ apply to every project on your machine.

Bootstrap a draft

/init

Claude analyzes your codebase and creates a file with build commands, test instructions, and project conventions it discovers. If a CLAUDE.md already exists, /init suggests improvements rather than overwriting it. Refine from there with instructions Claude wouldn’t discover on its own.

For an interactive multi-phase flow, set CLAUDE_CODE_NEW_INIT=1 before running /init. It then asks which artifacts to set up: CLAUDE.md files, skills, and hooks.

Five principles

1. Short and structured

It’s loaded into every session, and longer files consume more context and reduce adherence. Target under 200 lines per CLAUDE.md file. @path/to/import imports help you organize a long file but don’t reduce its context cost, because imported files load together with the CLAUDE.md that imports them.

2. “How to handle it” beats “what’s there”

Skip the full directory tree — describe what each key directory is for and the commands you actually run. Claude can explore files itself.

3. State only the don’ts that matter

Spell out the rules where breaking them is hard to undo or project-specific.

## Rules
* Never commit or push without explicit user instruction
* Don't add error handling for impossible scenarios
* Don't introduce new dependencies without approval

Don’t let that list grow, though. Anthropic reports that with Claude 5 generation models, rigid rules conflict with what the user actually asks for and cost you more than they help. Drop taste-level rules like “never write comments” and keep the ones that cause real problems when violated — see Context engineering for Claude 5.

4. Put commands in code blocks

Build/dev/test commands should be in code blocks so Claude copies and runs them exactly.

## Commands
\```bash
npm run build       # production build
npm run dev         # dev server (port 3030)
npm test            # unit tests
\```

5. Document recurring workflows

Tasks like adding content, running migrations, or shipping a release belong here as procedures.

Solid structure example

# Project Name

## Overview
One paragraph on what the project does.

## Stack
* Frontend: Next.js 15, Tailwind CSS
* Backend: Node.js, Prisma, PostgreSQL
* Hosting: Cloudflare Pages

## Commands
\```bash
npm run dev
npm run build
npm test
\```

## Layout
* src/app — Next.js App Router pages
* src/components — UI components
* prisma/ — DB schema and migrations

## Conventions
* Function components only
* State via Zustand
* Tests with Vitest

## Rules
* Commit/push only on explicit instruction
* Confirm before adding new dependencies

Common mistakes

  • ❌ Pasting the full directory tree — Claude can explore
  • ❌ Mixing languages — pick one and stay consistent
  • ❌ Feature descriptions (those belong in the README)
  • ❌ Generic best practices (“write readable code”) — keep it project-specific
  • ❌ Long lists of taste-level don’ts — they conflict with the model’s judgment
  • ❌ Repeating instructions that already live in the system prompt or a skill — they drift apart

Move detailed rules into Skills and rules

When CLAUDE.md grows, extract multi-step workflows (content authoring, migration procedures) into separate Skill files. Leave a short pointer in CLAUDE.md saying “for X, invoke skill Y.” Instructions that matter for only part of the codebase belong in a path-scoped rule under .claude/rules/, which loads only when Claude works with matching files.

Check what loaded and audit for stale instructions

  • Run /context and check the list under Memory files to see which CLAUDE.md and rules files loaded at launch.
  • Run /doctor prompt-audit (Claude Code v2.1.283 or later) to check your CLAUDE.md, CLAUDE.local.md, and AGENTS.md files, plus rules, skills, and more under .claude/. It looks for instructions written for older models, references to files or commands that don’t exist, and files that contradict each other, and nothing changes until you ask Claude to apply the proposed edits.

Next steps

§ 10

Frequently Asked Questions

frequently asked
§ 10.1
What is CLAUDE.md?
A markdown file at the project root that Claude Code auto-loads as context every session. It tells Claude about the project's overview, structure, commands, and conventions upfront.
§ 10.2
Where do I put it?
Team-shared project instructions go in `./CLAUDE.md` or `./.claude/CLAUDE.md`, personal preferences for all projects in `~/.claude/CLAUDE.md`, and personal project-specific preferences in `./CLAUDE.local.md`. All discovered files are concatenated into context rather than overriding each other, and if two instructions contradict each other, Claude may pick one arbitrarily.
§ 10.3
What should it contain?
Project overview, tech stack, directory layout summary, common commands (build/dev/test), code conventions, and explicit "do not" rules. Keep it concise — longer isn't better.
§ 10.4
How do I bootstrap one?
Run `/init` in Claude Code. Claude analyzes your codebase and creates a file with build commands, test instructions, and project conventions it discovers. If a CLAUDE.md already exists, `/init` suggests improvements rather than overwriting it.
§ 10.5
Does a long CLAUDE.md cause problems?
Yes — longer files consume more context and reduce adherence. The docs recommend targeting under 200 lines per CLAUDE.md file. Move multi-step procedures into Skills and instructions that matter for only part of the codebase into path-scoped rules under `.claude/rules/`.