Learn how to write a CLAUDE.md file that makes Claude useful from the first message. Sections, examples, and common mistakes to avoid.
CLAUDE.md is the first file Claude reads when it starts a session. Think of it as your workspace's identity card. It tells Claude who you are, what you're working on, how you like things done, and where to find everything else.
A good CLAUDE.md covers five things. You don't need headers for every one, but the information should be there.
Too long. A CLAUDE.md that's 500 lines is too much. Claude reads it every session. Keep it under 200 lines and link to detailed docs in your context/ folder.
Here's a simplified CLAUDE.md for a marketing team:
The Froject generates a complete CLAUDE.md based on your wizard answers. It includes your project overview, tech stack, conventions, commands, skills, and directory structure.
Under 200 lines. Put detailed information in context files and reference them from CLAUDE.md. Claude reads it every session, so keep it focused.
Markdown. Use headers, bullet points, and tables for structure. Claude parses markdown well and the formatting helps both Claude and humans scan it quickly.
Yes. Claude reads CLAUDE.md files in the current directory and parent directories. You can have one at the project root and another in a subdirectory for specialized context.
Whenever your project structure, conventions, or tools change. A good habit is to review it at the start of each week. The /close command can help capture what needs updating.
Secrets, API keys, personal data, or anything sensitive. Also avoid putting detailed instructions that belong in skills or rules. CLAUDE.md is for orientation, not for everything.