CLAUDE.md and project-level instructions
Jump to section
What is CLAUDE.md and why you need it
CLAUDE.md is an instruction file that automatically loads into the context of every Claude Code conversation. It's your way of telling the model: 'this is how we work in this project'. Without it, every conversation starts from scratch. With it, the model has context before your first prompt.
The hierarchy of CLAUDE.md files
You can have multiple levels: global (~/.claude/CLAUDE.md) for your personal preferences, project-level (in the repo root) for team conventions, and local (.claude/CLAUDE.md) for things you don't want to commit. The model merges them all — more specific takes precedence.
Global CLAUDE.md is ideal for things like 'communicate in English', 'use functional style'. Project CLAUDE.md for 'we use Next.js 16, Tailwind 4, tests in Playwright'.
Anatomy of an effective CLAUDE.md
# My Project
## Quick Start
npm run dev # Dev server
npm run test # Vitest
npm run lint # ESLint + Prettier
## Stack
- Next.js 16 (App Router), React 19, TypeScript 5.7
- Tailwind CSS 4, class-based dark mode
- Drizzle ORM + PostgreSQL
- Vitest + Playwright
## Conventions
- Functional components, no class components
- Server Components by default, 'use client' only when needed
- Collocate tests: `foo.ts` -> `foo.test.ts`
- Prefer named exports over default exports
- Error boundaries at route level, not component levelWhat doesn't belong in CLAUDE.md
The most common mistake: a CLAUDE.md that's too long. Every token in it takes space in the context window. Don't include: full API docs (link to files instead), change history (that's git), detailed tutorials, or things the model can derive from the code.
Key rule: CLAUDE.md should only contain information the model can't figure out from the code or git history. 'We use React' — it can see that in package.json. 'We prefer Server Components over Client Components due to performance budgets' — that you need to say.
Directives vs. information
Distinguish two types of content. Directives are instructions: 'Never use any in TypeScript', 'Every commit must pass lint'. Information is facts: 'API runs on port 3001', 'Env variables are in .env.local'. Write directives imperatively and clearly — the model treats them as instructions.
References and sharing
CLAUDE.md supports @file references to load additional files — instead of copying entire documentation, write '@docs/architecture.md'. Commit project-root CLAUDE.md to git as a team document. Put personal preferences in global CLAUDE.md. For other tools, equivalents exist: .cursorrules (Cursor), .github/copilot-instructions.md (Copilot), .windsurfrules (Windsurf).
Add a 'What NOT to do' section to CLAUDE.md — explicit prohibitions are stronger than general instructions. 'Never use any' is more effective than 'use explicit types'.
Pick your current project and create a CLAUDE.md with these sections: 1. Quick Start (3-5 commands to run the project) 2. Stack (technologies + versions) 3. Conventions (5-10 rules the model can't derive from code) 4. Architecture (1-2 paragraphs about key decisions) Then open a new conversation and enter a simple prompt. Compare the output with and without CLAUDE.md.
Hint
Good test: prompt 'add a new API route' and compare output. With CLAUDE.md, the model should use the correct framework, correct naming conventions, and correct error handling pattern.
Pick an open-source project you contribute to (or want to). Clone the repo and create a CLAUDE.md that would help an AI assistant understand the project. Include: project purpose, how to run tests, coding style, PR conventions, key abstractions. Test: ask AI to implement a small feature with your CLAUDE.md as context.
Hint
Document your process and results — they'll serve as reference for similar future tasks.
Create two versions of CLAUDE.md for your project — minimal (stack + 3 conventions) and detailed (stack + 10 conventions + architecture + anti-patterns). Give the same task with both versions 5 times. Compare: 1) How often was output immediately usable? 2) How many manual fixes were needed? 3) Which version produces more consistent output? Choose the optimal version based on data.
Hint
Detailed CLAUDE.md usually wins for complex tasks (multi-file, architecture), minimal for simple ones (utility functions, formatting).
- CLAUDE.md loads automatically into every conversation — the most powerful context tool
- Hierarchy: global > project > local, more specific takes precedence
- Only write what the model can't derive from code
- Directives (instructions) and information (facts) are two different content types
- Commit project CLAUDE.md to git — it's a team document
In the next lesson, we dive into Code generation prompt templates — a technique that gives you a clear edge. Unlock the full course and continue now.
2/7 complete — keep going!