Configure Claude.md Files: Hierarchy, Scoping, and Modular Organization
This module is about where Claude Code gets persistent instructions, how those instructions layer, and how to diagnose why Claude is or is not following them.
Where should this instruction live?
Why did a teammate not receive the instruction?
Why is Claude following a frontend rule in the backend package?
How do we split a huge CLAUDE.md?
How do we verify which instruction files loaded?
Claude Code uses CLAUDE.md files for persistent instructions that you write, while auto memory is a separate mechanism where Claude records learning from prior sessions.
Claude reads CLAUDE.md at the start of sessions, but these instructions are context, not hard enforcement; if something must execute deterministically, use hooks or other controls instead. (Claude)
1. Core Mental Model
Think of CLAUDE.md as the project’s agent operating manual.
It should contain durable context such as:
Build commands
Test commands
Repository layout
Coding standards
Architecture decisions
Naming conventions
Review expectations
Common workflows
Package-specific conventions
It should not become a dumping ground for every preference, scratch note, or one-off task.
Claude Code’s docs recommend adding information that a new teammate would need or that Claude repeatedly gets wrong, while moving multistep procedures or narrow codebase instructions into skills or path-scoped rules where appropriate. (Claude)
2. The CLAUDE.md Hierarchy
The official exam statement focuses on three layers:
User-level: ~/.claude/CLAUDE.md
Project-level: ./CLAUDE.md or ./.claude/CLAUDE.md
Directory-level: subdirectory CLAUDE.md files
Current Claude Code docs also mention managed organization-level and local personal project files, but the exam’s main focus is user, project, and directory-level scoping. (Claude)
2.1 User-Level: ~/.claude/CLAUDE.md
Use this for personal preferences that apply across your projects.
Examples:
# Personal Claude Code Preferences
- Prefer pnpm over npm when both lockfiles are absent.
- When proposing refactors, show a concise plan before editing.
- Use my preferred commit message format: type(scope): summary.
Heuristic:
User-level instructions are not shared with teammates.
Claude Code docs state that files under ~/.claude are personal configuration that applies across your projects, while project files should be committed if they are meant to be shared with the team. (Claude)
2.2 Project-Level: ./CLAUDE.md
Use this for instructions everyone working on the project should share.
Examples:
# Project Instructions
## Repository Layout
- packages/api contains the Node.js API.
- packages/web contains the React frontend.
- packages/shared contains cross-package TypeScript utilities.
## Build and Test
- Run package commands from the package directory, not the repo root.
- API tests: cd packages/api && pnpm test
- Web tests: cd packages/web && pnpm test
## Coding Standards
- Use TypeScript strict mode.
- Prefer existing service abstractions over direct database access.
- Add tests for bug fixes.
Claude Code docs say project instructions can live in either ./CLAUDE.md or ./.claude/CLAUDE.md, and should contain project-level standards such as build/test commands, coding standards, architectural decisions, naming conventions, and common workflows. (Claude)
2.3 Root CLAUDE.md Vs .claude/CLAUDE.md
Treat both as project-level.
A common pattern:
CLAUDE.md # visible at repo root, good for quick discovery
.claude/CLAUDE.md # keeps Claude-specific config under .claude/
2.3 Directory-Level: Subdirectory CLAUDE.md
Use directory-level files for package-specific or subsystem-specific conventions.
Example mono-repo:
Root CLAUDE.md:
# Repository-wide Instructions
- This is a TypeScript monorepo.
- Use pnpm workspaces.
- Run commands from the package directory.
- Do not modify generated files directly.
packages/api/CLAUDE.md:
# Package Instructions
- Use Express middleware for request validation.
- All API endpoints must return the standard error envelope.
- Add or update OpenAPI comments when changing routes.
- API tests use Vitest and testcontainers.
packages/web/CLAUDE.md:
# Package Instructions
- Use React function components.
- Use TanStack Query for server state.
- Keep component tests next to components.
- Use design-system components before creating new primitives.
Claude Code docs for large codebases recommend root instructions for repository-wide rules and per-subdirectory CLAUDE.md files for package or subsystem-specific conventions; they also state that subdirectory files load on demand when Claude reads files in those subdirectories. (Claude)
3. How Loading Works
Claude Code reads CLAUDE.md files by walking up the directory tree from the current working directory. If you launch Claude Code in foo/bar/, it loads foo/bar/CLAUDE.md, foo/CLAUDE.md, and relevant local files alongside them. All discovered files are concatenated into context rather than replacing one another. (Claude)
Important consequences:
1. Instructions layer over each other; they do not simply override.
2. More specific directory instructions appear later in context.
3. Conflicting instructions can cause inconsistent behavior.
4. Where you launch Claude Code matters.
5. Subdirectory CLAUDE.md files may load only when Claude works in those directories.
Claude Code docs also say that if you launch from a repository root, root instructions load at launch, while subdirectory instructions load when Claude reads files there. If you launch from a subdirectory, that directory’s instructions and its ancestors load at launch. (Claude)
4. Diagnosing Hierarchy Issues
4.1 Scenario A: New Teammate Does Not Get Instructions
Problem:
A maintainer added “always use pnpm test” to ~/.claude/CLAUDE.md.
A new teammate clones the repo and Claude keeps suggesting npm test.
Diagnosis:
Fix:
Move the instruction to project-level ./CLAUDE.md
Commit it.
Ask the teammate to run /memory to verify it loaded.
4.2 Scenario B: Claude Follows Wrong Package Conventions
Problem:
Likely causes:
The frontend rule lives in root CLAUDE.md.
The backend package lacks its own CLAUDE.md.
Instructions are too broad.
A conflicting instruction exists in another loaded file.
Fix:
Move frontend-specific conventions into packages/web/CLAUDE.md.
Move backend-specific conventions into packages/api/CLAUDE.md.
Keep root CLAUDE.md limited to repository-wide standards.
4.3 Scenario C: Behavior Differs Depending on Launch Directory
Problem:
Diagnosis:
Fix:
Use /memory to inspect loaded instruction files.
Put truly global project rules at the root.
Put package-specific rules in the package directory.
Start Claude Code from the directory that matches the task scope.
5. Modular Organization with @ Imports
In actual Claude Code files, the syntax is a direct @path reference, such as:
- See @README.md for project overview.
- See @package.json for available scripts.
- @docs/git-workflow.md
Claude Code docs say you can reference files with @ syntax anywhere in CLAUDE.md. They also note that wrapping a path in backticks keeps it literal rather than importing it. (Claude)
5.1 Example: Modular Root File
# Project Instructions
## Overview
@docs/architecture.md
## Commands
@docs/commands.md
## Git Workflow
@docs/git-workflow.md
## Testing
@docs/testing.md
5.2 Why Use Imports?
Use imports when the information already exists in focused files.
Good import targets:
Bad import targets:
Huge historical docs
Stale design documents
Generated API output
Broad files unrelated to most sessions
Important nuance: imports help in organization, but they do not reduce context if they load at session start.
Claude Code docs explicitly warn that splitting into @path imports helps organization but does not reduce context; path-scoped rules are better when the goal is to load instructions only for matching files. (Claude)
6. Selective Imports by Package
The official guide specifically says to use @import based on maintainer domain knowledge.
Example:
repo/
CLAUDE.md
standards/
typescript.md
react.md
api.md
database.md
testing.md
deployment.md
packages/
api/
CLAUDE.md
web/
CLAUDE.md
packages/api/CLAUDE.md:
# API Package Instructions
@../../standards/typescript.md
@../../standards/api.md
@../../standards/database.md
@../../standards/testing.md
## Package-specific Notes
- API routes live under src/routes.
- Use the standard error envelope for all responses.
packages/web/CLAUDE.md:
# Web Package Instructions
@../../standards/typescript.md
@../../standards/react.md
@../../standards/testing.md
## Package-specific Notes
- Use design-system components before creating new UI primitives.
- Use TanStack Query for server state.
Heuristic:
Do not import every standards file into every package. Import the standards relevant to that package.
7. .claude/rules/ For Topic-Specific Rules
Use .claude/rules/ when CLAUDE.md is becoming too large or when rules should be organized by topic.
Claude Code docs say .claude/rules/ can hold multiple markdown rule files, all markdown files are discovered recursively, and descriptive filenames like testing.md or api-design.md are recommended.
Rules can be unconditional or path-scoped with YAML frontmatter. (Claude)
Example:
.claude/
CLAUDE.md
rules/
testing.md
api-conventions.md
deployment.md
security.md
frontend/
react.md
backend/
database.md
Unconditional testing.md:
# Testing Rules
- Add regression tests for bug fixes.
- Prefer unit tests for pure functions.
- Prefer integration tests for API behavior.
- Do not skip tests without documenting why.
Unconditional api-conventions.md:
# API Conventions
- All endpoints must validate input.
- All errors must use the standard error envelope.
- Include OpenAPI comments for new routes.
7.1 Path-Scoped Rule Example
Path scoped rule example:
---
paths:
- "src/api/**/*.ts"
---
# API Development Rules, loads only when above path matches
- All API endpoints must include input validation.
- Use the standard error response format.
- Include OpenAPI documentation comments.
Path-scoped rules reduce baseline context usage because they are not loaded at the start of every session. Claude loads them only when it works with files matching the rule’s paths glob.
Claude Code docs say path-specific rules use a paths field in YAML frontmatter, match glob patterns, and trigger when Claude reads files matching those paths rather than loading on every tool use. (Claude)
When to Use .claude/rules/ Instead of a Monolithic CLAUDE.md
Use rules when:
CLAUDE.md is too long.
Different topics have different maintainers.
Rules apply only to specific file paths.
A monorepo has multiple stacks.
You want to reduce irrelevant instructions.
You want reviewable, topic-specific files.
8. @ Imports Vs .claude/rules/
| Need | Best mechanism |
|---|---|
Keep root CLAUDE.md organized by referencing existing docs |
@ import |
| Reuse README or package scripts as context | @README.md, @package.json |
| Apply API rules only to API files | .claude/rules/api.md with paths |
| Split a huge instruction file by topic | .claude/rules/*.md |
| Keep instructions relevant only when touching matching files | Path-scoped rules |
| Add one package-specific standards bundle | Package CLAUDE.md with selected imports |
Key exam distinction:
9. /memory Command
The official guide calls out /memory as the diagnostic tool for verifying which memory files are loaded.
Claude Code docs say /memory lists all CLAUDE.md, CLAUDE.local.md, and rules files loaded in the current session, lets you toggle auto memory, and provides access to the auto memory folder. The docs also recommend running /memory when Claude is not following instructions to verify whether the relevant files are loaded. (Claude)
Use /memory to answer:
Which CLAUDE.md files loaded?
Did the package-level CLAUDE.md load?
Did the rules file load?
Is this instruction only in user-level memory?
Is a local file affecting this session?
Are two files giving conflicting instructions?
10. Common Traps
Trap 1: User-Level Instructions for Team Policy
Wrong:
Right:
Trap 2: Monolithic Root File for a Large Monorepo
Wrong:
Right:
Keep root instructions global.
Move package-specific rules into package CLAUDE.md files or path-scoped .claude/rules files.
Trap 3: Imports to Reduce Context
Wrong:
Right:
Trap 4: Conflicting Instructions
Wrong:
Right:
Root says “use the test runner specified by each package.”
API package says “this package uses Vitest.”
Trap 5: Not Verifying Loaded Files
Wrong:
Right: