The Complete Guide to CLAUDE.md

What is CLAUDE.md?

CLAUDE.md is a plain markdown file that Claude Code (Anthropic's CLI coding agent) reads automatically every time it starts a new session in your project. The file contains instructions, context, and rules written in natural language. Claude treats its contents as high-priority system context, similar to how a new developer would read a project's contributing guide before writing their first pull request.

The concept is simple but powerful. Without CLAUDE.md, you start every Claude Code session from scratch. Claude has no memory of your preferences, your project's architecture, or the conventions your team follows. You end up repeating the same instructions: "Use TypeScript strict mode," "We use Tailwind, not CSS modules," "Always write tests for new functions." CLAUDE.md eliminates that friction entirely.

Once you add a CLAUDE.md file to your project, Claude Code reads it before processing your first prompt. Every instruction in the file shapes how Claude writes code, responds to questions, and makes decisions throughout the session. It is persistent, versioned (since you commit it to git), and shared across your entire team.

Why You Need a CLAUDE.md File

The benefits compound quickly once you start using CLAUDE.md. Here is what changes:

Where to Put Your CLAUDE.md

CLAUDE.md supports three placement levels, each with a different scope. You can use all three simultaneously; they merge together when Claude Code starts.

~/.claude/CLAUDE.md

/your-project/CLAUDE.md

/your-project/src/CLAUDE.md /your-project/api/CLAUDE.md /your-project/packages/auth/CLAUDE.md

How CLAUDE.md Gets Loaded

Understanding the loading hierarchy helps you decide what goes where. When Claude Code starts a session, it follows this order:

1. Global CLAUDE.md loads first from ~/.claude/CLAUDE.md. This sets your baseline personal preferences.
2. Project root CLAUDE.md loads next. Its instructions layer on top of (and can override) the global file.
3. Subdirectory CLAUDE.md files load as Claude navigates into specific folders. These add folder-specific context on top of everything above.

All three levels combine into a single context that Claude uses throughout the session. There is no conflict resolution needed in most cases because each level typically covers different concerns. Your global file handles personal style, the project root handles architecture, and subdirectory files handle folder-specific details.

If instructions genuinely conflict (for example, your global file says "use spaces" but the project file says "use tabs"), the more specific file wins. Project-level overrides global, and subdirectory-level overrides project-level.

What to Include in CLAUDE.md

A good CLAUDE.md covers the information that actually changes how Claude writes code. Here are the key sections with examples you can copy and adapt.

Project overview

Start with a two to three sentence summary of what the project is, who it is for, and what stage it is in. This gives Claude the high-level context it needs to make appropriate decisions.

# Project Overview
TensorFeed.ai is an AI news aggregator and data hub.
Built with Next.js 14 (App Router), deployed on Cloudflare Pages.
Currently in production with 40+ pages and growing.

Tech stack

List your core technologies. This prevents Claude from suggesting incompatible tools or libraries.

## Stack
- Framework: Next.js 14 (App Router, static export)
- Language: TypeScript (strict mode)
- Styling: Tailwind CSS
- Database: Cloudflare Workers KV
- Hosting: Cloudflare Pages
- Auth: Firebase Auth
- Testing: Vitest + React Testing Library

Architecture notes

Document the decisions that are not obvious from the code alone. This is especially valuable for patterns that Claude might otherwise override with "better" alternatives.

## Architecture
- All pages are server components by default
- Only add 'use client' when truly needed (interactivity, hooks)
- API routes proxy to Cloudflare Workers (not Next.js API routes)
- Static export means no SSR; all data fetching is client-side
- KV operations are batched to stay under 100k/day free tier limit

Common commands

Give Claude the commands it needs to build, test, and deploy your project.

## Commands
- Dev server: npm run dev
- Build: npm run build
- Type check: npx tsc --noEmit
- Lint: npm run lint
- Deploy: git push origin main (auto-deploys via Cloudflare Pages)
- Worker deploy: cd worker && npx wrangler deploy

Code style rules

These are the rules that matter most for consistency. Focus on conventions that Claude might not infer from existing code.

## Code Style
- TypeScript strict mode, never use `any` types
- React functional components with hooks (no class components)
- Tailwind CSS for all styling (no CSS modules, no styled-components)
- Semantic HTML: use article, nav, aside, main, section
- Include ARIA labels on all interactive elements
- Handle loading states with skeleton loaders
- Handle errors gracefully with fallback UI

Workflow rules

Define how Claude should behave when completing tasks. This covers the "process" side rather than the code side.

## Workflow
- Always commit and push after completing changes
- Run the type checker before committing
- Add new pages to sitemap.xml
- Every new page needs a unique title tag and meta description
- Every new API endpoint must be documented in /developers

Permission rules

By default, Claude Code asks for permission before running commands or modifying files. You can reduce friction by pre-authorizing routine operations.

## Permissions
- Always allow file creation and editing without asking
- Always allow npm, git, and build commands without asking
- Only ask permission for genuinely destructive operations
  (deleting databases, revoking keys, force-pushing to main)

What NOT to Include

A bloated CLAUDE.md is almost as bad as no CLAUDE.md. When the file gets too long, key instructions get diluted and Claude is more likely to miss them. Here is what to leave out:

• ✗Things Claude already knows. You do not need to explain what React is or how TypeScript generics work. Claude has extensive knowledge of programming languages, frameworks, and tools.
• ✗Linter and formatter configuration. Claude reads your .eslintrc, .prettierrc, and tsconfig.json files directly. Duplicating those rules in CLAUDE.md adds noise without adding value.
• ✗Overly detailed instructions. Rules like "always put a blank line after imports" are better handled by your formatter. CLAUDE.md should cover architectural and behavioral rules, not micro-formatting.
• ✗Frequently changing data. API keys, version numbers, or deployment URLs that change often will make your CLAUDE.md a maintenance burden. Reference these from config files or environment variables instead.
• ✗Entire API documentation. Claude can read your source files. Instead of pasting your full API spec into CLAUDE.md, point Claude to the file: "API docs are in /docs/api.md."

CLAUDE.md vs AGENTS.md

If you have explored AI coding tools beyond Claude Code, you may have seen AGENTS.md mentioned alongside tools like Cursor, Windsurf, Zed, and OpenCode. Here is how the two files compare.

The content format is nearly identical. If your team uses multiple AI coding tools, the simplest approach is to maintain both files with the same content. Some developers create one file and symlink the other. Others maintain a single AGENTS.md and a minimal CLAUDE.md that points to it.

Claude Code reads CLAUDE.md by default. It does not currently read AGENTS.md unless you configure it to. If you only use Claude Code, CLAUDE.md is all you need.

Real-World CLAUDE.md Examples

The best way to learn is by reading real files from real projects. We have compiled full, annotated examples for common project types. Here is a preview of each.

Each example includes inline annotations explaining why specific rules are included. Visit the full examples page to see them all.

CLAUDE.md Template Generator

Do not want to start from a blank file? Our interactive CLAUDE.md generator asks a few questions about your project (framework, language, hosting, testing tools) and produces a ready-to-use CLAUDE.md file. You can copy the output directly into your project or use it as a starting point to customize.

Best Practices

• ✓Keep it between 40 and 80 lines. Long enough to cover important context, short enough that every line carries weight. If your file exceeds 100 lines, break it into project root and subdirectory files.
• ✓Prune regularly. Review your CLAUDE.md every few weeks. Remove rules that Claude now follows naturally, update outdated information, and add rules for new patterns you have introduced.
• ✓Use emphasis sparingly. If you mark everything as CRITICAL or IMPORTANT, nothing stands out. Reserve bold, caps, and emphasis for the one or two rules that truly matter most.
• ✓Test by observing Claude's behavior. After adding a new rule, use Claude Code on a few tasks and see if the rule is being followed. If not, rephrase the instruction to be more direct and specific.
• ✓Commit it to version control. Your project CLAUDE.md belongs in git. It is part of your project's configuration, just like tsconfig.json or .eslintrc. Track changes, review in PRs, and keep it in sync with your codebase.
• ✓Use /init to bootstrap. If you are starting fresh, run /init inside Claude Code. It analyzes your project structure and generates a starter CLAUDE.md that you can refine.
• ✓Write for a new teammate, not for a machine. The best CLAUDE.md files read like something you would give a new developer joining the team. Natural language works better than rigid syntax or JSON-like formatting.

Common Mistakes

Frequently Asked Questions

Continue Learning