CLAUDE.md, explained

CLAUDE.md is a file you put in your project root that tells Claude Code how to work with your codebase. It's read at the start of every session. Think of it as the onboarding doc you'd write for a new team member, except the team member is an AI that forgets everything between sessions.

Why it matters

Without a CLAUDE.md, Claude Code will make assumptions about your project. It'll use default conventions, pick its own patterns, and sometimes do things in a way that doesn't match how your team works. That's not a bug in Claude Code. It just doesn't know your rules yet.

A good CLAUDE.md fixes this. Claude Code reads it, internalizes the rules, and follows them for the rest of the session. The difference in output quality between "no CLAUDE.md" and "good CLAUDE.md" is noticeable immediately.

What to put in it

Keep it short. Under 50 lines is a good target. Here's what actually matters:

Project overview. One or two sentences. "This is a Next.js e-commerce site with Stripe payments and MongoDB." That's enough for Claude Code to understand the context.

Coding conventions. The rules that are true for every file in your project. Formatting preferences (tabs, semicolons, trailing commas). Import style (named exports, path aliases). Error handling patterns.

Testing approach. Which framework. Whether you do TDD. Where tests live. How to run them.

File structure. Where things go. "API routes in app/api/. Components in components/. Utils in lib/."

Anti-patterns. Things Claude Code might do that you don't want. "Don't use any type." "Don't commit directly to main." "Don't use console.log in production code."

What to leave out

Task-specific instructions. If it's only relevant when you're doing a particular thing (writing migrations, setting up CI, debugging memory leaks), put it in a skill file instead. Your CLAUDE.md should only contain rules that apply every session.

Not sure which is which? Describe it and ClaudeOrNot will tell you.

CLAUDE.md vs agents.md

They do the same thing. CLAUDE.md is Claude-specific. agents.md is the agent-agnostic version that works with multiple AI coding tools. If you only use Claude Code, either works. If you use Claude Code and Cursor and Windsurf, use agents.md.

More on this in the agents.md vs CLAUDE.md comparison.