The problem CLAUDE.md solves

Without CLAUDE.md, a typical conversation looks like this:

You: "Add a new API endpoint for user profiles"
Claude: *creates a REST endpoint using Express*
You: "No, we use Hono, not Express. And we use snake_case for routes."
Claude: "Sorry! Let me redo that with Hono and snake_case..."
You: "Also, all endpoints need Zod validation."
Claude: "Got it, let me redo that again..."

Three rounds of corrections for one task. With a CLAUDE.md, Claude would have known all of this from the start.

How CLAUDE.md works

When Claude Code opens in a directory, it automatically looks for CLAUDE.md files and loads them into its context. Claude reads these files before doing anything else, so the instructions are available from the very first message.

The file is plain markdown. No special syntax required. Just write instructions the way you would explain your project to a new team member.

The file hierarchy

CLAUDE.md files follow a hierarchy that lets you layer instructions at different levels:

Project-level: ./CLAUDE.md

This lives in your project root. It contains team-wide conventions that everyone shares: tech stack, commands, coding standards, architecture decisions.

# CLAUDE.md

## Stack
- Frontend: Next.js 14 with App Router
- Backend: Hono on Cloudflare Workers
- Database: PostgreSQL with Drizzle ORM

## Commands
- npm run dev - start dev server on port 3000
- npm test - run Vitest test suite
- npm run db:push - push schema changes

This file gets committed to git. Every developer on the team benefits from it.

User-level: ~/.claude/CLAUDE.md

This lives in your home directory. It contains personal preferences that apply to every project you work on.

# Personal CLAUDE.md

- I prefer concise responses, skip long explanations
- Always suggest the terminal command, don't just describe what to do
- When writing TypeScript, use explicit return types on all functions

This file is not committed to any repo. It is your personal configuration.

Folder-level: src/api/CLAUDE.md

You can place CLAUDE.md files in subdirectories for area-specific instructions.

# API conventions

- All route handlers follow the pattern: validate -> authorize -> execute -> respond
- Error responses use { error: string, code: string } format
- Every endpoint must have a corresponding test file in __tests__/

When Claude is working in a subdirectory, it loads both the project-level and the folder-level CLAUDE.md, combining their instructions.

How Claude prioritizes instructions

When multiple CLAUDE.md files exist, Claude loads all of them. The priority order is:

1. Project-level CLAUDE.md (highest priority for project-specific rules)
2. User-level ~/.claude/CLAUDE.md (personal preferences, lower priority)
3. Folder-level CLAUDE.md files (supplement the project-level instructions)

If a project-level file says "use tabs for indentation" and your user-level file says "use spaces", the project-level instruction wins. This ensures team consistency.

What CLAUDE.md is NOT

It is important to understand the boundaries:

• Not a replacement for documentation. Your README, APIWhat is api?A set of rules that lets one program talk to another, usually over the internet, by sending requests and getting responses. Ask AI for more docs, and architecture decision records still matter. CLAUDE.md is specifically for Claude, not for humans.
• Not a place for secrets. CLAUDE.md is typically committed to git. Never put API keys, database passwords, or other credentials in it.
• Not a novel. Every line in CLAUDE.md uses tokens from Claude's context windowWhat is context window?The maximum amount of text an AI model can consider at once, including your conversation history and any files it has read. Ask AI for more. Be concise. If your CLAUDE.md is longer than 200 lines, you are probably including too much.
• Not a tutorial. Claude already knows JavaScript, React, Python, and hundreds of other technologies. You do not need to explain how a for loop works. Focus on what is unique to YOUR project.