The Most
Important File

Tip 1

Know What It Actually Is

Your CLAUDE.md is the table of contents for your project. You might have hundreds of files, but this is the index Claude reads first to know where everything lives and how you like things done.

So it's not a place to dump everything. It's a map that points to everything else. Think build commands, your folder layout, your conventions, and short pointers to the deeper docs. A good CLAUDE.md doesn't try to hold all the detail. It tells Claude where the detail is.

Tip 2

Don't Write It From Scratch

This is where people freeze, staring at a blank file. You don't have to write it yourself. Claude Code can write the first draft for you.

Open your project in Claude Code and run the slash command /init. It reads through your project and generates a starter CLAUDE.md based on what it actually finds: your stack, your scripts, your structure. Thirty seconds, and you go from a blank file to a real draft.

Run this in your project

/init

Tip 3

Treat The Starter As A Draft

The /init output is a starting point, not gospel. Read it yourself. Claude guessed at some things, and it won't know the unwritten rules in your head.

Go through it line by line. Fix anything wrong, delete anything generic, and add the stuff Claude couldn't know, like "always run the tests before committing" or "never touch the files in /legacy." Then keep updating it over time as your project changes. The best CLAUDE.md files are owned and reviewed like code, not written once and forgotten.

Tip 4

Give Claude A Map

The single highest-value thing you can add is a quick summary of the project plus a simple folder tree showing where the important stuff lives. Now Claude knows exactly where to look instead of digging around blind, which wastes time and tokens.

Paste a block like this into your CLAUDE.md

# Project: [your project name]

What it is: [one or two sentences on what this project does]

## Commands
- Install:  [e.g. npm install]
- Run:      [e.g. npm run dev]
- Test:     [e.g. npm test]
- Build:    [e.g. npm run build]

## Where things live
- src/components/   UI components
- src/lib/          shared helpers and utilities
- src/api/          API routes and handlers
- data/             config and seed data
- tests/            test files

## Rules
- Run the tests before committing.
- Match the style of the file you're editing.
- Don't touch anything in /legacy.

## Deeper docs (read when relevant)
- Architecture notes: docs/architecture.md
- Deploy steps:       docs/deploy.md

Swap in your real folders and commands. Even this much turns Claude from guessing into navigating.

Tip 5

Keep It Under 200 Lines

This is the one almost everyone skips. Because this file loads into every session, a bloated CLAUDE.md actually backfires. When it gets too long, the important instructions get diluted, and Claude pays less attention to what really matters.

Keep it lean. Anthropic's own rule of thumb is under 200 lines. If a section is getting long, move the detail into a separate doc and leave a one-line pointer to it in CLAUDE.md. Remember tip one: this is a table of contents, not the whole book. Lean is more productive, every time.