How to Write an Effective CLAUDE.md File: The Complete Guide

What is CLAUDE.md?

CLAUDE.md is the instruction file that Claude Code reads to understand your project. Think of it as onboarding documentation for your AI coding assistant. When Claude Code starts a session, it reads your CLAUDE.md files to learn about your codebase, your preferences, and the rules it should follow.

Without a CLAUDE.md, Claude Code starts every session from scratch. It does not know your framework conventions, your team's coding standards, or the sharp edges in your codebase. With a well-written CLAUDE.md, it picks up where your documentation leaves off and writes code that fits your project from the first prompt.

Where CLAUDE.md Lives: The 5-Layer Hierarchy

Claude Code reads CLAUDE.md files from multiple locations, each with a different scope. Understanding this hierarchy is essential for writing effective instructions.

Layer 1: Global (~/.claude/CLAUDE.md)

Your global CLAUDE.md applies to every project Claude Code works on. This is where you put your personal preferences, universal rules, and identity information.

What to include:

Example:

Layer 2: Workspace (parent directory CLAUDE.md)

If you organize projects under a common parent directory, a CLAUDE.md there applies to all child projects. This is useful for monorepos or workspaces where multiple projects share conventions.

Use case: You have a ~/code/work/ directory with multiple client projects that all use the same tech stack. A CLAUDE.md at ~/code/work/ can define the shared conventions.

Layer 3: Project Root (repo CLAUDE.md)

The most common location. A CLAUDE.md at the root of your repository defines project-specific instructions. This is checked into version control and shared with your team.

What to include:

Layer 4: Per-Directory Overrides

You can place CLAUDE.md files in subdirectories to override or supplement project-level instructions for specific parts of the codebase.

Use case: Your src/api/ directory has different conventions than src/frontend/. A CLAUDE.md in each directory can specify the relevant patterns.

Layer 5: Memory Files (~/.claude/projects/)

Claude Code also reads memory files that persist across sessions. These are typically auto-generated but can be manually edited. They store patterns Claude has learned about your workflow.

What to Include: The Essential Sections

A good CLAUDE.md balances completeness with conciseness. Every token in your CLAUDE.md counts against your context window, so include what matters and skip what doesn't.

Project Architecture

Give Claude the 30-second elevator pitch of your project. What is it? What technology does it use? How is it structured?

Example:

Build and Test Commands

Claude needs to know how to validate its work. List the exact commands.

Example:

Coding Conventions

Be specific. "Write clean code" is useless. "Use named exports, not default exports" is actionable.

Examples of good conventions:

Known Gotchas

Every codebase has sharp edges. Document them so Claude does not cut itself.

Examples:

Safety Rules

Define what Claude should never do. These are your guardrails.

Examples:

Common Mistakes

Too Vague

A CLAUDE.md that says "write good code" or "follow best practices" provides no value. Claude already tries to write good code. Your CLAUDE.md should tell it what "good" means in your specific context.

Bad: Use best practices for error handling

Good: Wrap all async operations in try/catch. Log errors to src/lib/logger.ts. Return structured error responses with { error: string, code: number } shape.

Too Long

Every line in your CLAUDE.md consumes tokens from your context window. A 5,000-word CLAUDE.md eats into the space available for your actual conversation. Be concise.

Rule of thumb: If your CLAUDE.md is longer than 200 lines, you are probably including information that belongs in your actual documentation, not in your AI instructions.

Outdated Instructions

A CLAUDE.md that references a framework version you upgraded three months ago or a directory structure that no longer exists causes Claude to write code that does not work. Review your CLAUDE.md when you make significant changes to your project.

Missing Safety Rules

The most common regret people have with Claude Code is not telling it what NOT to do. Add explicit safety rules about destructive operations, secret files, and irreversible actions.

Templates for Different Project Types

Next.js App Router

Python / Django

React Native / Expo

Monorepo

Managing CLAUDE.md at Scale

The real challenge with CLAUDE.md is not writing one file. It is maintaining context files across multiple projects, especially if you use multiple AI tools.

If you work on 5+ projects and use Claude Code alongside Cursor or GitHub Copilot, you end up maintaining 10-15 config files across different formats. They drift out of sync. Some get stale. You lose track of which project has which instructions.

This is exactly the problem [TokenCentric](https://tokencentric.app) solves. It scans all your projects, shows every AI context file in one dashboard, and lets you edit them with real-time token counting so you know exactly how much context space each file consumes.

Conclusion

A well-written CLAUDE.md is the single highest-leverage thing you can do to improve your Claude Code experience. It transforms Claude from a generic coding assistant into a teammate who understands your project.

Start with the basics: architecture, commands, conventions, gotchas, and safety rules. Keep it concise. Review it regularly. And if you manage multiple projects, consider using [TokenCentric](https://tokencentric.app) to keep everything organized.