CLAUDE.md File

The project-level instructions file that Claude Code reads automatically at the start of every session. Contains tech stack, coding conventions, project structure, commands, workflow rules, and constraints. The single most important configuration file for consistent Claude Code sessions.

Syntax

claude-code

# [Project Name] - Claude Code Instructions

## Tech Stack
- [Framework + version]
- [CSS approach]
- [Database/auth]
- [Test framework]
- [Icon library — specify ONE]

## Conventions
- [Rule 1]
- [Rule 2]

## Project Structure
src/
  [dir]/  # [purpose]

## Commands
- Test: [command]
- Typecheck: [command]
- Build: [command]

## Workflow
- [What to run before reporting complete]
- [Escalation rules]

## Constraints
- [What NOT to do]
- [Frozen files/directories]

Example

claude-code

# TaskFlow — Claude Code Instructions

## Tech Stack
- React 18 + TypeScript (strict)
- Tailwind CSS — utility classes only
- Supabase v2 for database and auth
- TanStack Query v5 for server state
- Vitest + Testing Library for tests
- Lucide React for icons only

## Conventions
- One component per file, PascalCase
- All Supabase calls in src/services/
- No any/unknown types
- Named exports only from utilities

## Commands
- Test: npm run test
- Typecheck: npm run typecheck

## Workflow
- Run typecheck before marking complete
- Fix failing tests before proceeding

## Constraints
- Do not add npm packages without permission
- Do not modify src/legacy/ (frozen)