Your First CLAUDE.md

What is CLAUDE.md?

CLAUDE.md is a simple text file that gives Claude persistent context about you and your work. Instead of explaining your preferences, folder structure, and how you like things done every conversation, you write it once and Claude reads it automatically.

Think of it as a briefing document for your AI assistant.

A simple example

Say you use Claude to help organize your notes. Your CLAUDE.md might look like:

# My Notes

## Structure
- `Journal/` — Daily entries, named YYYY-MM-DD.md
- `Projects/` — One folder per project with a plan.md
- `Reference/` — Saved articles and research

## Preferences
- I write in markdown
- Keep filenames lowercase with dashes
- When I say "today's note" I mean the journal entry for today

## Important
- Never delete files, only move them
- Ask before reorganizing anything

Now Claude knows where things go, how you name files, and that it should be careful with deletions.

Where it goes

Claude looks for CLAUDE.md in three places:

• ~/.claude/CLAUDE.md — Global settings, applies everywhere
• ./CLAUDE.md — In a specific folder, for that project
• ./.claude/CLAUDE.md — Local overrides you don’t want to share

All three are merged together, with more specific files taking precedence.

For developers

If you’re working on code, CLAUDE.md becomes even more powerful:

# Project: My App

## Tech Stack
- Next.js 14 with App Router
- TypeScript (strict mode)
- Tailwind CSS

## Conventions
- Use `bun` instead of npm
- Components go in `src/components/`
- Tests live next to the code they test

## Commands
- `bun dev` — Start dev server
- `bun test` — Run tests
- `bun lint` — Check for issues

Claude will use your package manager, follow your file structure, and run the right commands.

Tips

Be specific. “Put journal entries in Journal/” is better than “keep things organized.”

Include paths. If there’s a folder Claude should know about, tell it the exact location.

State your preferences. How do you name files? What should Claude ask about before doing? What should it never touch?

Keep it updated. When you change how you work, update the file.

When in doubt, just ask

Don’t overthink your CLAUDE.md. If you’re unsure what to include, just start a conversation. Claude will explain what it can see, what context it’s missing, and what would help.

Chat is a great interface when you don’t know what you want. Ask “what do you know about this project?” or “what would help you work here?” and iterate from there.

---

Official Documentation

• Memory files — How Claude Code discovers and uses CLAUDE.md files