CLAUDE.md

A markdown file that teaches Claude Code about a project. Turns generic AI output into project-aware AI output.

All Dictionary

In one sentence

CLAUDE.md is a plain markdown file that sits in my project and tells Claude Code exactly how this codebase works, what it cares about, and what rules to follow.

What it is

CLAUDE.md is a context file Claude Code reads automatically. It lives in the project root or in scoped folders. Inside, I describe the project’s structure, the tech stack, the conventions, the naming rules, the design tokens, the commands to run, and anything else Claude would otherwise have to guess.

Why it matters

Without CLAUDE.md, Claude inspects files on demand, infers patterns, and sometimes invents conventions that do not exist. With CLAUDE.md, Claude walks in with a briefing. The difference in output quality is hard to overstate. It is the closest thing to onboarding a new teammate in a single file.

Example

A short CLAUDE.md for a design system repo:

# CLAUDE.md

## Project
Design system for Acme. React + Tailwind. Tokens live in `src/tokens/`.

## Rules
- Never use raw hex. Always reference a semantic token.
- Component files use PascalCase. Story files end in `.stories.tsx`.
- Run `npm run tokens:build` after editing tokens.

## Commands
- `npm run dev` - start Storybook
- `npm run tokens:build` - rebuild CSS variables
- `npm test` - run Playwright + Jest

Dropped into the root, this file changes every future Claude session for this repo.

When to use it

  • You want Claude Code to follow your naming and token rules
  • You have commands or scripts that matter and should be reused
  • You are building a design system and want consistent AI output
  • You want to scope rules to subfolders with nested CLAUDE.md files

See also