How to Organize CLAUDE.md Files in Monorepos

A single CLAUDE.md at the root works for small projects. Once you have multiple packages, services, or domains, one file is not enough.

How the hierarchy works

Claude Code reads CLAUDE.md files from multiple directories:

• Root - Project-wide context, architecture, conventions
• Package or service - Rules and patterns specific to that area
• Nested directories - More specific context the deeper you go

When Claude works in a file, it reads every CLAUDE.md from that directory up to the project root. All of that context applies.

What goes where

Root CLAUDE.md:

• Tech stack and major dependencies
• Global conventions for naming, formatting, commits
• Build and test commands
• Links to docs that matter

Package CLAUDE.md:

• What this package does
• Key patterns used here
• Local dependencies
• Test conventions
• Common mistakes

Feature directory CLAUDE.md:

• Business context
• Data flow
• Integration points
• Edge cases

Example from a monorepo

/CLAUDE.md                    # pnpm workspace, project overview
/packages/
  /api/
    CLAUDE.md                 # Express patterns, auth, error handling
    /routes/
      CLAUDE.md               # Route conventions, validation
  /web/
    CLAUDE.md                 # React patterns, state management
    /components/
      CLAUDE.md               # Component structure, styling
    /features/
      /checkout/
        CLAUDE.md             # Payment integration, checkout flow

When Claude edits a file in /packages/web/features/checkout/, it sees all four levels. It knows the project uses pnpm, the web package uses React, components follow certain patterns, and checkout has payment integration rules.

What makes these files useful

Keep them short. Each file should be scannable in seconds. If you are writing paragraphs, that information probably belongs in actual documentation.

Focus on the non-obvious. Claude already knows React. Tell it about your React patterns. Tell it why you made unusual choices.

Include commands. If tests in a package run with pnpm test, say so. If there is a special dev script, include it.

Keep them current. A stale file is worse than no file. When patterns change, update the files.

When to add one

Add a CLAUDE.md when:

• A directory has conventions that differ from the parent
• There is domain knowledge Claude needs to work there
• You keep repeating the same context in prompts

Do not add one when:

• The directory follows parent conventions
• The code is clear enough on its own
• You are adding structure for the sake of it

Why it matters

With a good hierarchy, Claude arrives at each file already knowing what the code is for, what patterns to follow, what commands to run, and what to avoid.

You stop re-explaining your architecture. Claude stops guessing in ways that conflict with your conventions.

The alternative is repeating yourself every time you switch directories.