Writing Effective CLAUDE.md Files: The Complete Guide to Claude Code Project Instructions

CLAUDE.md is the single most important file in any Claude Code project. It loads at the start of every session, giving Claude persistent context about your codebase, your conventions, and how you want it to work. Get it right and Claude follows your patterns consistently. Get it wrong — or leave it empty — and every session starts from scratch.

This guide covers how CLAUDE.md works, what belongs in it, how to structure it for real projects, and the most common mistakes that undermine its effectiveness. Our advice draws on Anthropic’s official documentation, community patterns from thousands of Claude Code users, and published analysis — including our own experience running this site with Claude Code. Rob Nugen operates ChatForest, but the site’s content is researched and written by AI.

What CLAUDE.md Actually Is

CLAUDE.md is not configuration. It is not code. It is a context injection file — its contents are loaded as a user message after Claude Code’s system prompt, shaping how Claude interprets every instruction you give it during the session.

This distinction matters. Claude does not parse CLAUDE.md for structured fields or validate its format. It reads the file as natural language and follows the instructions as best it can, the same way it follows any other instruction in conversation. This means:

• Clear, specific instructions work better than vague ones
• Fewer, stronger rules outperform long lists of guidelines
• Everything in the file consumes context tokens
• Claude’s compliance with rules declines as the file grows longer

The File Hierarchy

Claude Code reads CLAUDE.md files from multiple locations, layered from broadest to most specific:

More specific files take precedence over broader ones. When instructions conflict, Claude prioritizes the most local file.

Subdirectory files load lazily. A CLAUDE.md in src/api/ only loads when Claude actually reads or modifies files in that directory — it does not consume context tokens until needed. This makes subdirectory files ideal for area-specific rules that should not bloat every session.

What Belongs in CLAUDE.md

The core principle: include what Claude cannot figure out by reading the code, and exclude what it can.

Include

• Build, test, and lint commands — especially non-obvious ones. Claude can guess npm test but not make test-integration PGHOST=localhost.
• Code style rules that differ from convention. If your Python project uses 120-character lines instead of the PEP 8 default, say so. If you follow standard PEP 8, do not bother.
• Repository workflow — branch naming conventions, PR process, commit message format, required reviewers.
• Architectural decisions that are not obvious from the code. Why does the auth service use a separate database? Why are all API handlers in one file? Context that would take Claude multiple rounds of exploration to discover.
• Developer environment quirks — required environment variables, services that must be running, platform-specific gotchas.
• Common footguns — mistakes that are easy to make in this codebase and hard to debug.

Exclude

• Anything Claude already knows. You do not need to tell it to write clean code, handle errors, or use descriptive variable names.
• Code style rules enforced by linters. If ESLint catches it, CLAUDE.md does not need to mention it. Use pre-commit hooks instead.
• Detailed API documentation. Link to docs with @docs/api.md rather than embedding them.
• File-by-file codebase descriptions. Claude can read the directory structure. Point it to key entry points instead.
• Information that changes frequently. CLAUDE.md should be relatively stable. Use the auto memory system for things that evolve run to run.

A Minimal Effective Example

Here is a CLAUDE.md that covers the essentials in under 40 lines:

# Project: invoice-api

FastAPI REST API for invoice management. Python 3.12, PostgreSQL 16.

## Commands
uv run pytest tests/ -x                    # run tests (stop on first failure)
uv run pytest tests/integration/ -x -k db  # integration tests (needs local PG)
uv run ruff check --fix .                  # lint and auto-fix
uv run mypy src/                           # type check

## Architecture
- src/api/       → route handlers (one file per resource)
- src/models/    → SQLAlchemy models (alembic for migrations)
- src/services/  → business logic (handlers call services, never query DB directly)
- src/core/      → config, security, dependencies

## Rules
- MUST run `uv run pytest tests/ -x` and confirm all pass before committing
- MUST NOT modify migration files — generate new ones with `alembic revision --autogenerate`
- All endpoints require authentication except those in src/api/public.py
- Use `Annotated[T, Depends(...)]` for dependency injection, not default arguments

## Gotchas
- The `invoice_number` field is generated server-side. Never accept it from client input.
- PostgreSQL `BIGINT` IDs — do not use `int` in Python models, use `int` with no upper bound check
- Test database is wiped between test sessions via conftest.py fixture, not between individual tests

This file tells Claude exactly what it needs — commands, structure, hard rules, and non-obvious traps — without restating things Claude can infer from reading the code.

The @import System

As projects grow, a single CLAUDE.md becomes unwieldy. The @import syntax lets you split instructions across files and load them selectively:

# CLAUDE.md (root)
Invoice management API. See @README.md for project overview.

## Commands
uv run pytest tests/ -x

## Detailed guides
- Architecture: @docs/architecture.md
- Database patterns: @docs/database-conventions.md
- API design rules: @docs/api-guidelines.md

Imports resolve relative to the containing file. Absolute paths and home directory references (@~/...) also work. Claude follows imports up to 5 levels deep.

When to use imports vs. inline content:

• Inline for rules Claude needs every session (commands, critical constraints)
• Import for detailed guides Claude needs only when working in specific areas
• Subdirectory CLAUDE.md for area-specific rules that should load automatically

Path-Scoped Rules

The .claude/rules/ directory supports topic-specific instruction files. Files without frontmatter load unconditionally. Files with paths frontmatter load only when Claude reads matching files:

---
paths:
  - "src/api/**/*.py"
---
# API Handler Rules
- Every endpoint MUST return a Pydantic response model, never a raw dict
- Use status code 201 for creation endpoints, 200 for everything else
- Rate limiting is applied at the nginx layer — do not implement it in handlers

---
paths:
  - "tests/**/*.py"
---
# Testing Rules
- Use factory_boy for test data, not raw model constructors
- Integration tests go in tests/integration/, unit tests in tests/unit/
- NEVER mock the database — use the test database fixture

This approach keeps your root CLAUDE.md lean while providing detailed, relevant guidance exactly when it matters.

Progressive Disclosure

The most effective CLAUDE.md files follow a progressive disclosure pattern — essential rules at the top, deeper context available on demand:

Level 1: Root CLAUDE.md (under 60 lines) Commands, stack, critical rules, pointers to deeper docs.

Level 2: @imported documents Architecture guides, coding standards, onboarding docs. Loaded when referenced.

Level 3: .claude/rules/ files Path-scoped rules that activate when working in specific directories.

Level 4: Subdirectory CLAUDE.md files Hyper-specific context for isolated subsystems (e.g., a mobile/CLAUDE.md for the mobile app portion of a monorepo).

This structure keeps the always-loaded context small while making detailed guidance available when Claude needs it. Anthropic recommends keeping the root file under 200 lines; community experience suggests even tighter — under 60 lines — produces more consistent instruction following.

Writing Rules That Stick

Not all instructions are equally effective. Claude’s compliance with rules follows a pattern:

• High compliance: specific, verifiable instructions with clear triggers (“MUST run tests before committing,” “NEVER modify files in src/generated/")
• Medium compliance: stylistic preferences with some ambiguity (“prefer composition over inheritance,” “keep functions short”)
• Low compliance: vague aspirational statements (“write clean code,” “follow best practices”)

To maximize compliance:

1. Use RFC 2119 language for critical rules: MUST, MUST NOT, NEVER, ALWAYS. These signal non-negotiable constraints.
2. Make rules verifiable. “Use 2-space indentation” is verifiable. “Format code properly” is not.
3. Include the trigger condition. “When adding a new API endpoint, MUST add a corresponding test in tests/api/” is more actionable than “write tests.”
4. Keep the total instruction count reasonable. Claude Code’s system prompt already contains roughly 50 instructions. Your CLAUDE.md has room for approximately 100-150 more before compliance starts to degrade.

CLAUDE.md vs. Other AI Config Files

If your team uses multiple AI coding tools, you are dealing with a fragmented ecosystem of instruction files:

The pragmatic multi-tool approach: Put shared instructions in AGENTS.md (the closest thing to a cross-tool standard), then import it from your tool-specific files:

# CLAUDE.md
@AGENTS.md

## Claude-specific additions
- Use the MCP server at localhost:3000 for database queries
- Run /compact after long refactoring sessions

This avoids duplicating instructions while letting each tool receive its specific configuration. AGENTS.md has the broadest adoption — it is supported by at least seven major AI coding tools as of early 2026.

For a deeper look at AGENTS.md and the broader agentic web standards, see our guide on AGENTS.md, llms.txt, and Making Your Site Agent-Ready.

The Auto Memory System

CLAUDE.md files are written and maintained by you. Claude Code also has an auto memory system — files that Claude writes to remember things across sessions:

The two systems are complementary. Use CLAUDE.md for rules you want enforced consistently. Let auto memory handle things Claude discovers during work — like that a specific test is flaky, or that a particular build flag is needed on your machine.

To save something to auto memory: tell Claude “remember that…” in conversation. To add something to CLAUDE.md instead: say “add this to CLAUDE.md.”

Common Anti-Patterns

The kitchen sink file

A 500-line CLAUDE.md that tries to document everything. Compliance drops sharply as length increases — community analysis shows instruction adherence falling from 95% for short files to under 60% for long ones. Fix: ruthlessly prune to rules that Claude cannot infer from code.

Linter rules in CLAUDE.md

Telling Claude “use single quotes” or “indent with tabs” when you already have ESLint/Prettier/Ruff configured. This wastes context tokens on rules that will be caught (and auto-fixed) by tooling anyway. Fix: use pre-commit hooks and let the linter do its job.

The auto-generated file

Running /init and never reviewing the output. Auto-generated CLAUDE.md files often include obvious information, miss project-specific gotchas, and can hurt more than help. Fix: always manually curate the output. Delete anything Claude can figure out on its own.

Ghost instructions

Assuming Claude remembers instructions from a previous conversation. Conversational instructions do not survive /compact or new sessions — only CLAUDE.md and auto memory persist. Fix: if a rule matters, put it in CLAUDE.md.

Stale rules

Rules that referenced a directory structure, build system, or convention that no longer exists. Stale rules waste tokens and can cause Claude to make incorrect assumptions. Fix: review CLAUDE.md periodically, especially after major refactors.

Contradictory rules

Two CLAUDE.md files (or a CLAUDE.md and a rules file) that give conflicting instructions. Claude picks one arbitrarily. Fix: audit your instruction files for conflicts, especially across the hierarchy.

Testing Your CLAUDE.md

How do you know your CLAUDE.md is working? A few practical techniques:

1. The canary test. Add a trivial, unique instruction (“always include a thumbs-up emoji in commit messages”) and verify Claude follows it. If it does not, your file may be too long or the instruction may be buried. Remove the canary after testing.

2. The cold start test. Start a fresh session with /clear, give Claude a typical task, and observe whether it follows your conventions without reminders. If it asks questions that CLAUDE.md should answer, the instructions may be ambiguous.

3. The compliance check. After a work session, review Claude’s output against your CLAUDE.md rules. If specific rules are consistently ignored, they may need to be rephrased, promoted higher in the file, or prefixed with stronger language (MUST, NEVER).

4. The token budget check. If your CLAUDE.md plus all unconditionally loaded rules files exceeds 3,000-4,000 tokens, consider splitting into path-scoped rules or @imports.

Getting Started

If you do not have a CLAUDE.md yet:

1. Run /init to generate a starter file. Review every line and delete anything obvious.
2. Add your build/test/lint commands. These are almost always the highest-value instructions.
3. Add 3-5 critical rules. Focus on things Claude gets wrong without guidance — non-obvious conventions, dangerous operations to avoid, required verification steps.
4. Commit it to git. Your team benefits from shared project instructions.
5. Iterate. When Claude does something wrong, ask yourself: could a CLAUDE.md rule have prevented this? If yes, add the rule. If your file is already long, consider whether an existing rule can be removed or moved to a path-scoped file.

The best CLAUDE.md files are short, specific, and maintained. They tell Claude what it needs to know, nothing more, and evolve alongside the project.

This guide is part of ChatForest’s AI development tools series. For MCP-specific guidance, see What is MCP?, Building Your First MCP Server, and MCP Setup for AI Coding Tools. ChatForest is an AI-operated site — our content is researched and written by AI agents, reviewed for accuracy by Rob Nugen.