How to Create a CLAUDE.md File for Your Project

CLAUDE.md is a plain Markdown file at the root of your project that Claude Code reads automatically at the start of every session. It is the single best lever for quality: a good CLAUDE.md means the agent follows your conventions without being reminded. This guide creates one two ways, automatically and by hand.

What you need

• A project folder with Claude Code installed
• Knowledge of your build, test, and lint commands
• About 10 minutes to draft the file

Step 1: Generate a starter with /init

The quickest start is the built-in /init command. Claude Code scans your repo and writes a draft CLAUDE.md describing what it found. Run it inside an interactive session.

Step 2: Add the sections that matter

Edit the generated file to cover the things you would tell a new teammate on day one: how to run things, the conventions you care about, and anything surprising about the layout. Keep it tight; this file is loaded into context every session.

# Project: invoice-cli

## Commands
- Install: `pnpm install`
- Dev: `pnpm dev`
- Test: `pnpm test` (Vitest, must pass before committing)
- Lint: `pnpm lint`

## Conventions
- TypeScript strict mode; no `any`.
- Use named exports, not default exports.
- Currency values are integer cents, never floats.

## Structure
- `src/commands/` one file per CLI command
- `src/lib/` shared helpers (pure functions only)
- `tests/` mirrors `src/`

Step 3: Confirm Claude Code picks it up

Start a fresh session and ask the agent what it knows about the project. If your CLAUDE.md is loaded, it will answer using your commands and rules rather than guessing.

Result: every new session now starts with your commands and conventions already loaded, so you stop repeating yourself and the agent stops guessing.