AI Coding Guide

When does Claude Code load a CLAUDE.md in a subdirectory? Monorepo layout and how to check

Claude Code Published:

When Claude Code loads a CLAUDE.md in a subdirectory, how it combines with the root file, a monorepo layout that keeps context small, and how to check with /memory.

Verified on Sep 10, 2026 These tools change quickly. Please also check the latest official documentation.
#Claude Code#CLAUDE.md#monorepo#subdirectory
Contents
  1. Two loading moments
  2. A monorepo layout
  3. Checking what is loaded
  4. When it is not loaded
  5. Related
  6. Summary

You added packages/api/CLAUDE.md in a monorepo and it does not seem to apply, or rules from an unrelated package show up where they should not. Both confusions disappear once you know when Claude Code loads a subdirectory CLAUDE.md.

In short: at startup Claude Code loads the CLAUDE.md files from the current directory upward; files below the current directory are loaded when Claude touches files in that directory.

KEY POINT

What you will learn

  • Which CLAUDE.md files load at startup and which load later
  • A monorepo layout that splits root and package rules
  • Checking with /memory, and what to fix when a file is not loaded

Two loading moments

Location of CLAUDE.mdLoaded when
Current directory and its parents, up to the repository rootSession start
~/.claude/CLAUDE.md (user level)Session start
A subdirectory below the current directoryWhen Claude reads or edits files in that directory

Start claude at the repository root and the root CLAUDE.md is loaded immediately, while packages/api/CLAUDE.md is loaded the first time Claude touches something under packages/api/. Start inside packages/api/ instead and both the package file and the root file load at once.

用語解説

Upward search: Claude Code walks from the starting directory up through its parents looking for CLAUDE.md, so the root file is loaded wherever you start inside the repository.

A monorepo layout

repo/
├── CLAUDE.md                 # overall policy, shared commands, rules for every package
├── packages/
│   ├── api/
│   │   └── CLAUDE.md         # API-specific: migration steps, no-go areas
│   └── web/
│       └── CLAUDE.md         # front-end-specific: component and styling rules
└── docs/

Keep only what applies to every package at the root and put package-specific details in each package. Working in web then never pulls the api migration procedure into context.

Root CLAUDE.md:

## Shared commands
- All tests: `pnpm -r test`
- Lint: `pnpm lint`

## Shared conventions
- Cross-package imports go through `packages/shared`; never import packages directly
- See packages/*/CLAUDE.md for package details

packages/api/CLAUDE.md:

## This package
- Tests: `pnpm --filter api test` (needs the Docker database: `docker compose up db`)
- Add new files under `prisma/migrations/`; never edit existing migrations

Checking what is loaded

Run /memory during a session to list the memory files loaded so far. A subdirectory file is expected to be absent until Claude touches that directory. Ask Claude to read packages/api/src/user.ts, run /memory again, and packages/api/CLAUDE.md should now appear.

When it is not loaded

  • File name: use exactly CLAUDE.md, including case. claude.md or Claude.md may be ignored on some systems
  • Location: packages/api/.claude/CLAUDE.md also works, but keeping both variants loads the content twice. Choose one
  • Not touched yet: lower-level files load when Claude works with files there. To load one up front, say "read packages/api/CLAUDE.md before starting", or start Claude inside that directory
  • Conflicting instructions: opposite rules at the root and in a subdirectory make behavior unstable. Put only additional information in subdirectory files and do not override root rules

Subdirectory files cost context too

Once loaded, a CLAUDE.md stays in context for the rest of the session. Work that spans several packages accumulates each package's file, so keep every one of them short.

The three levels of CLAUDE.md (user, project, personal) and what to write are covered in How to write CLAUDE.md. For keeping context small in general, see Managing context in Claude Code.

Summary

  • At startup Claude Code loads CLAUDE.md from the current directory upward; lower files load when their directory is touched
  • In a monorepo, keep shared rules at the root and package-specific rules in each package
  • Check with /memory; to load a file early, ask for it explicitly or start inside that directory
  • Subdirectory files should add information, not contradict the root

FAQ

Are all subdirectory CLAUDE.md files loaded at startup?
No. At startup Claude Code loads the CLAUDE.md files from the current directory upward. Files in lower directories are loaded when Claude works with files in that directory.
If the root and a subdirectory disagree, which wins?
Both are loaded and the more specific instruction tends to win. To avoid ambiguity, put only additional information in subdirectory files rather than overriding root rules.
How do I see which CLAUDE.md files are active?
Run /memory during a session; it lists the memory files currently loaded.

Primary sources

This article was drafted by AI from official documentation and reviewed by the site operator before publishing. Found a mistake? Let us know via the contact page.

Related articles