CLAUDE.md — Project Instructions for Claude

CLAUDE.md is a markdown file that gives Claude Code persistent context about your project. It’s read automatically on every interaction, giving Claude knowledge about your codebase’s conventions, architecture, and workflow preferences without you having to repeat instructions.

What problem does it solve?

Every time you start a new Claude Code session, the agent doesn’t remember your project’s build system, testing conventions, or coding style. CLAUDE.md solves this by providing always-on instructions — “this project uses pnpm, not npm”, “always run tests before committing”, “we use server components by default”. Once written, you never have to repeat these instructions again.

How it works

Place a CLAUDE.md file at your project root. Claude Code reads it automatically at the start of every conversation. You can also have a personal ~/.claude/CLAUDE.md for global preferences that apply across all projects.

# CLAUDE.md

## Project

Next.js 14 App Router + Supabase + Tailwind CSS.

TypeScript strict mode. No `any` types.

## Commands

- `npm run dev` — development server (port 3002)

- `npm run build` — production build

- `npm test` — run tests

## Code Style

- Prefer server components; mark 'use client' explicitly

- Use Lucide for icons, not emoji

- Keep components small and focused

- Use `@/` path alias for imports

## Don't

- Don't add README files unless asked

- Don't commit .env files

- Don't use default exports

CLAUDE.md locations

Claude Code looks for CLAUDE.md in multiple locations, with more specific files taking precedence:

Location	Scope
~/.claude/CLAUDE.md	Global — applies to all projects
./CLAUDE.md	Project root — applies to the current project
./src/CLAUDE.md	Subdirectory — applies when working in that directory

Tips for effective CLAUDE.md

Keep it concise — it’s loaded every prompt, so long files waste context
Focus on what’s unique to your project, not general knowledge
Include build/test commands so Claude can verify its work
List explicit “don’t” rules to prevent common mistakes
Update it as your project evolves

CLAUDE.md vs SKILL.md

CLAUDE.md is for always-on project context — rules that apply to every task (“use TypeScript strict mode”, “run tests before committing”). SKILL.md is for on-demand capabilities — instructions loaded only when relevant (“how to generate PDFs”, “how to build a design system”).

Related specs

.cursorrules — Cursor’s equivalent project rules format
AGENTS.md — cross-platform project context (Linux Foundation)
SKILL.md — for modular, on-demand capabilities

Official Documentation

Learn more about CLAUDE.md in the Anthropic documentation.

Read the Claude Code docs