Skip to main content

Step 1 of 3 — Your operating manual

CLAUDE.md

Every new Claude Code session starts blank. CLAUDE.md fixes that. It's a file at the root of your project that Claude reads automatically on startup. Your preferences, your project structure, your rules — loaded every time.

What happens

  • Claude Code reads ~/.claude/CLAUDE.md (global) on every session start
  • Also reads project/CLAUDE.md (per-project) — stacks with global
  • Contains your stack, conventions, shortcuts, and rules
  • Defines how Claude should behave in YOUR codebase specifically
  • Eliminates the "please remember that..." preamble from every conversation

Real example

WITHOUT CLAUDE.MD

Every single session starts with:

WHAT HAPPENS

"Please use Tailwind not CSS modules, and my API is at /api/v2, and I prefer functional components, and never use default exports, and the database is Postgres not MySQL, and tests go in __tests__ not test/, and..." — repeated forever.

RESULT

With CLAUDE.md: Claude already knows all of this. You just say "build the feature" and it follows your conventions from line one.

Try it yourself

**Role**
Act as a senior developer advocate who writes concise, opinionated configuration files that eliminate ambiguity for AI coding assistants.

**Task**
Create a CLAUDE.md file for my project that Claude Code will read on every session start:
1. Document my tech stack (framework, styling, language, database)
2. List 5-8 coding conventions I enforce
3. List 5-8 things the AI must NEVER do
4. Add a shortcuts section for common commands
5. Add a project structure overview (key directories)

**Context**
- Framework: YOUR FRAMEWORK HERE (e.g. Next.js 15 App Router)
- Styling: YOUR STYLING APPROACH (e.g. Tailwind CSS)
- Language: YOUR LANGUAGE (e.g. TypeScript strict)
- Database: YOUR DATABASE (e.g. Postgres via Drizzle)
- Hosting: YOUR HOSTING (e.g. Vercel)
- This file is read automatically — no need to paste it into conversations
- Keep it under 100 lines — short enough to fit in context every time

**Output Format**
A markdown file with these exact sections:

## Stack
[Bulleted list of core technologies]

## Conventions
[Bulleted list of rules Claude must follow]

## Never
[Bulleted list of things Claude must not do]

## Shortcuts
[Common commands: dev, build, test, deploy]

## Structure
[Key directories and what lives in each]

**Stop Conditions**
Done when: you can start a new Claude Code session in your project and it immediately knows your stack, style, and constraints without any preamble.