CLAUDE.md Configuration

CLAUDE.md is a special markdown file that Claude Code reads automatically at the start of every session. It acts as persistent project instructions — a way to give Claude the context it needs to work effectively in your codebase without repeating yourself.

Getting this file right is one of the highest-leverage things you can do with Claude Code. A well-crafted CLAUDE.md makes every session faster and more accurate. A bloated one gets ignored.

How CLAUDE.md Works

When Claude Code launches, it walks upward from your current working directory toward the filesystem root, loading every CLAUDE.md it finds along the way. It also loads your user-level file from ~/.claude/CLAUDE.md. All of these are merged together, with more specific (closer to CWD) instructions taking precedence.

CLAUDE.md files in subdirectories are loaded lazily — only when Claude reads files in that subtree. This means you can place directory-specific instructions that only activate when relevant.

File Locations and Scoping

Claude Code supports a five-level hierarchy of instruction files. Understanding where to put instructions is just as important as what you write.

Project Rules for Modularity

For larger projects, the .claude/rules/ directory lets you break instructions into focused files rather than cramming everything into one CLAUDE.md. Each rule file can be scoped to specific paths using YAML frontmatter:

---
paths:
  - "src/components/**"
  - "src/ui/**"
---

# Component Conventions

- Use functional components with hooks
- Keep components under 150 lines
- Colocate styles with components

This rule only loads when Claude works on files matching those glob patterns.

Hierarchical CLAUDE.md in Monorepos

For monorepos or large codebases, place CLAUDE.md files at each package or module boundary:

CLAUDE.md                  # Project-wide conventions (always loaded)
frontend/CLAUDE.md         # Frontend-specific patterns
backend/CLAUDE.md          # Backend-specific patterns
shared/CLAUDE.md           # Shared library conventions

Each file loads only when Claude operates within that directory, keeping context focused. One team reduced their CLAUDE.md from 47,000 words to 9,000 using this approach — an 80% reduction with no loss of guidance.

What to Include

A good CLAUDE.md covers what Claude cannot infer from reading your code. For each line, ask yourself: would removing this cause Claude to make mistakes? If not, cut it.

Essential Sections

Project context — a one-line orientation so Claude knows what it is working on:

# Acme Dashboard
Next.js e-commerce admin panel with Stripe billing and Convex backend.

Commands — exact commands Claude cannot guess, including flags and ports:

## Commands
- `npm run dev` — Dev server on port 3012
- `npm run test -- --watch` — Run tests in watch mode
- `npx convex dev` — Start Convex in development mode
- `./cli.sh vercel` — Deploy to Vercel (uses credential wrapper)

Tech stack — frameworks and key dependencies with versions when they matter:

## Tech Stack
- Next.js 15 with App Router
- Tailwind CSS 4 with shadcn/ui
- Convex for database/backend
- TypeScript with strict mode

Conventions that differ from defaults — only document rules Claude would not follow on its own:

## Conventions
- Prefer named exports over default exports
- Use server components by default, "use client" only when needed
- All database access goes through Convex, never direct DB calls
- Commit messages follow conventional commits format

Project-specific gotchas — non-obvious patterns, workarounds, or files that need special treatment:

## Important
- The `legacy/` directory is deprecated — do not import from it
- Auth tokens are in .envrc (loaded by direnv), never commit this file
- The Convex schema must be deployed before the frontend can query new tables

What to Exclude

• Anything Claude can infer from code. It can read your package.json, tsconfig.json, and directory structure.
• Standard language conventions. Claude already knows TypeScript best practices, React patterns, etc.
• Detailed API documentation. Link to docs instead of inlining them.
• Style rules enforced by tooling. If your linter or formatter handles it, Claude will match existing code.
• File-by-file descriptions. Claude can navigate the codebase on its own.
• Generic advice. "Write clean code" or "follow best practices" wastes context.
• Secrets. Never put API keys, tokens, or connection strings in a committed file.

Ideal Length

This is the most consistent finding across community research: shorter is better. Claude's adherence to your instructions drops as the file grows, because important rules get buried in noise.

If your CLAUDE.md exceeds 150 lines, it is time to restructure. Move detailed guidelines into .claude/rules/ files, reference documentation with brief descriptions, or use hierarchical files.

Progressive Disclosure

Rather than putting everything in CLAUDE.md, reference detailed docs and let Claude pull them in when needed:

## Architecture
This is a modular monolith. For detailed architecture decisions,
see docs/architecture.md. For testing patterns, see docs/testing.md.

You can also use the @ import syntax to include other files:

@docs/coding-standards.md

But be aware that @-imported files load at startup, so they still count against your context budget. For truly optional references, use plain text references instead — Claude will read the file only when working on a relevant task.

Writing Style That Works

Claude responds best to specific, directive language. A few formatting principles consistently improve results:

Use bullet points and short sentences. Paragraphs are harder to follow than lists.

Be specific and actionable. "Use v.string() validators for all Convex schema fields" beats "validate your schema."

Pair constraints with alternatives. Never say "don't do X" without saying what to do instead:

# Bad
- Never use the --force flag

# Good
- Do not use `--force` for git push. Use `--force-with-lease` instead.

Use emphasis for critical rules. Claude pays more attention to instructions marked with IMPORTANT or YOU MUST:

**IMPORTANT:** Never modify files in the `generated/` directory.
These are auto-generated and will be overwritten.

Include examples of correct patterns. A short code sample is more effective than a paragraph of explanation:

## API Routes
Always return typed responses:

​```ts
export async function GET() {
  const data = await fetchItems();
  return Response.json({ items: data });
}
​```

Keeping CLAUDE.md Updated

The biggest mistake is treating CLAUDE.md as a write-once file. It should evolve with your project. Here are the most effective maintenance strategies.

The # Shortcut

During any Claude Code session, prefix a message with # and Claude will offer to save it to your CLAUDE.md. You choose the destination:

# Always run tests before suggesting commits
# Our database is Convex, not Supabase
# Use kebab-case for file names in the components directory

Over weeks and months, this builds an organic record of project knowledge captured in the moment you discover something matters.

Review When Things Go Wrong

When Claude makes a mistake — uses the wrong pattern, runs the wrong command, misunderstands your architecture — that is a signal to add a rule. Ask yourself: could a line in CLAUDE.md have prevented this? If yes, add it.

Prune Regularly

Set a reminder to review CLAUDE.md monthly. Remove rules that:

• Duplicate what linters or formatters enforce
• Reference files or patterns that no longer exist
• State obvious conventions Claude follows anyway
• Were added as temporary fixes that are no longer relevant

Use Claude to Maintain It

After encountering repeated issues, ask Claude to suggest CLAUDE.md updates. Then edit its suggestions down to concise bullet points. Claude tends to write verbose instructions — your job is to distill them.

Version Control It

Treat CLAUDE.md changes like code changes. Review diffs in PRs. If a teammate adds a rule, make sure it is clear, actionable, and not redundant.

Example: Before and After

Before (too long, too vague)

# Project

This is a web application built with modern technologies.
We use React for the frontend and have a backend API.
Please write clean, well-documented code following best
practices. Make sure to handle errors properly and write
tests for new features. The project structure follows
standard conventions.

## Getting Started
To start the project you need to have Node.js installed
on your machine. Then you can run npm install to install
all the dependencies. After that you can start the dev
server with npm run dev. The server will start on the
default port.

After (concise, actionable)

# Acme Dashboard
Next.js 15 App Router + Convex + Tailwind CSS 4

## Commands
- `npm run dev` — Dev server on port 3012
- `npx convex dev` — Convex dev mode
- `npm test` — Vitest with coverage

## Conventions
- Server components by default, "use client" only when needed
- Named exports, no default exports
- All data access through Convex (never direct DB)
- Conventional commits (`feat:`, `fix:`, `docs:`)

## Gotchas
- Auth handled by .envrc / direnv — never commit
- Deploy Convex schema before frontend can use new tables
- The `legacy/` directory is deprecated, do not import from it

The second version is 15 lines, instantly scannable, and covers everything Claude actually needs.

Quick Start Checklist

If you are setting up CLAUDE.md for the first time:

1. Run /init to generate a starter template, then delete everything obvious
2. Add your commands — dev, test, build, deploy with exact syntax
3. List conventions that differ from defaults — only rules Claude would not follow on its own
4. Note project gotchas — things that have tripped you up before
5. Keep it under 60 lines for a standard project
6. Commit it so your team gets the same instructions
7. Create CLAUDE.local.md for personal preferences (auto-gitignored)
8. Use # during sessions to capture learnings as they come up

Sources

These best practices were consolidated from the following resources:

• Claude Code Best Practices — Anthropic official documentation on writing effective instructions
• Claude Code Memory — Anthropic documentation on the CLAUDE.md hierarchy and scoping
• Using CLAUDE.md Files — Anthropic blog on effective project configuration
• Writing a Good CLAUDE.md — HumanLayer guide with the WHAT/WHY/HOW framework and progressive disclosure pattern
• The Complete Guide to CLAUDE.md — Builder.io comprehensive guide covering file locations and must-include sections
• Building an Effective CLAUDE.md — Maxitect blog on ideal length, structure, and the review process
• Creating the Perfect CLAUDE.md — Dometrain guide on workflows, terminology, and treating it as a living document
• How I Use Every Claude Code Feature — Practical size guidelines and anti-patterns from production use
• Organizing CLAUDE.md in a Monorepo — DEV Community article on reducing a 47k-word CLAUDE.md by 80%
• Teaching Claude Code Consistency — Directory-level CLAUDE.md strategy with positive and negative examples
• Claude Code Hash Memory Shortcut — Guide to using the # shortcut for ongoing maintenance