Write an Effective CLAUDE.md

Why CLAUDE.md matters

CLAUDE.md is the first file AI agents read when entering your project. A good one saves minutes per session by eliminating repeated questions.

Auto-generate with /init

Generate a starter CLAUDE.md automatically. Run this in your project:

claude /init

Claude scans your codebase and generates a starter CLAUDE.md with structure, commands, and conventions. Review and customize it from there.

Essential sections

# CLAUDE.md

## Project Overview
One paragraph: what this project does, who uses it, core tech stack.

## Architecture
Key directories, file naming patterns, data flow summary.

## Commands
How to run, test, build, deploy.

## Conventions
Coding style, naming rules, patterns to follow.

## Gotchas
Non-obvious behaviors, known issues, things that break easily.

Tips for great CLAUDE.md files

Be specific: "Use camelCase for JS variables" beats "follow conventions"
Include run commands: agents need exact commands, not vague instructions
List file paths: reference actual files, not abstract concepts
Update regularly: stale context is worse than no context
Keep it under 500 lines: progressive disclosure beats a wall of text

Progressive disclosure pattern

Put details in separate files, reference them from CLAUDE.md:

See `docs/api.md` for endpoint details.
See `docs/deployment.md` for deploy steps.