Claude Code Configuration

CLAUDE.md

CLAUDE.md is a special markdown file that Claude reads automatically at the start of every session. It gives Claude persistent context about your project — coding conventions, build commands, architecture decisions, and gotchas — without you having to repeat them.

Think of it as a README specifically for Claude. You write it once, check it into git, and every team member's Claude sessions benefit.

Where It Lives

CLAUDE.md files form a hierarchy, from broadest to most specific:

Location	Scope	Shared?
Managed policy file	Your whole organization, deployed by IT	Everyone in the org
`~/.claude/CLAUDE.md`	All your projects	Just you
`./CLAUDE.md` or `./.claude/CLAUDE.md`	This project	Team (via git)
`./CLAUDE.local.md`	This project, personal	Just you (add it to `.gitignore`)
`./.claude/rules/*.md`	Topic- or path-specific rules	Team (via git)
`./subdir/CLAUDE.md`	Loaded when Claude reads, edits or creates files in that directory	Team

Files in your working directory and every directory above it load at launch. They don't override one another — they're all concatenated, broadest first, so the instructions closest to where you launched are read last, and CLAUDE.local.md comes after CLAUDE.md at each level. If two files contradict each other, Claude may pick either, so keep them consistent.

If a repository has an AGENTS.md and no CLAUDE.md, Claude Code reads the AGENTS.md instead, so projects set up for other coding agents work as they are.

What to Put In It

Focus on things Claude can't infer from your code:

# Code Style
- Use ES modules (import/export), not CommonJS
- 2-space indentation for TypeScript

# Testing
- Run single test files: `npm test -- src/foo.test.ts`
- Do NOT run the entire test suite (too slow)

# Architecture
- All API responses include `_meta.timestamp`
- Database queries only in `src/db/` modules

# Important
- NEVER edit files in `generated/` (auto-created)
- Run `npm run typecheck` after code changes

Don't include things Claude already knows — standard language conventions, obvious patterns, or detailed API docs (link to those instead). Aim for under 200 lines; multi-step procedures belong in skills, and guidance for one part of the codebase belongs in a path-scoped rule that loads only when needed.

Block-level HTML comments () are stripped before the file reaches Claude, so you can leave notes for humans at no context cost.

Imports

Reference other files to keep CLAUDE.md organized:

See @docs/git-conventions.md for commit rules.
@~/.claude/my-personal-prefs.md

Imported files load at launch too, so they organize a long file without making it cheaper. Imports nest up to four hops deep, and @paths inside code spans or code blocks are ignored.

Try It Now

Look at the CLAUDE.md in this very project — you're benefiting from it right now! It tells Claude about the file structure, available commands, and how the skill tree works.

To create your own:

In any project, run /init — Claude analyzes the codebase and drafts a CLAUDE.md with the build commands and conventions it discovers (or suggests improvements if one exists).
Trim it to your most important conventions and add what Claude couldn't discover.
Start a new session and run /context — your file should be listed under Memory files.

Pro tip: Start small. Add rules only when Claude makes a mistake you want to prevent. A 20-line CLAUDE.md that's all signal beats a 500-line one full of noise. Every so often, run /doctor prompt-audit to find instructions that are stale or contradict each other.

@import in CLAUDE.md — Pull in other files to keep things modular
~/.claude/rules/ — Organize rules by topic with optional path-specific filtering
AGENTS.md — Use an AGENTS.md file as project instructions
/memory — Open and edit any of these files from inside a session
Auto memory — Claude's own persistent notes that complement CLAUDE.md