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.
The exam will likely test practical configuration judgment:
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 learnings 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 multi-step 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 Code lists user instructions at ~/.claude/CLAUDE.md, project instructions at ./CLAUDE.md or ./.claude/CLAUDE.md, and local personal project instructions at ./CLAUDE.local.md. (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.
Important exam point:
User-level instructions are not shared with teammates through version control.
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)
Exam trap
A senior engineer adds critical test instructions to:
A new teammate does not get those instructions.
Best fix:
2.2 Project-level: ./CLAUDE.md or ./.claude/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)
Root CLAUDE.md vs .claude/CLAUDE.md
For the exam, 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/
The exam is unlikely to ask you to choose between these two unless the scenario is about discoverability or repository organization.
2.3 Directory-level: subdirectory CLAUDE.md
Use directory-level files for package-specific or subsystem-specific conventions.
Example monorepo:
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; 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
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 or ./.claude/CLAUDE.md.
Commit it.
Ask the teammate to run /memory to verify it loaded.
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 or a path-scoped rule.
Move backend-specific conventions into packages/api/CLAUDE.md or a path-scoped rule.
Keep root CLAUDE.md limited to repository-wide standards.
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
The official guide calls this @import syntax. 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)
Example: modular root file
# Project Instructions
## Overview
@docs/architecture.md
## Commands
@docs/commands.md
## Git Workflow
@docs/git-workflow.md
## Testing
@docs/testing.md
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.
Exam point:
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
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.
api-conventions.md:
# API Conventions
- All endpoints must validate input.
- All errors must use the standard error envelope.
- Include OpenAPI comments for new routes.
Path-scoped rule example
---
paths:
- "src/api/**/*.ts"
---
# API Development Rules
- All API endpoints must include input validation.
- Use the standard error response format.
- Include OpenAPI documentation comments.
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 |
@path 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?
Exam diagnosis pattern
Problem:
Best next step:
Not:
Immediately add more examples to the prompt.
Assume Claude is broken.
Duplicate the rule everywhere.
10. Example good structure for a MonoRepo
repo/
CLAUDE.md
.claude/
rules/
testing.md
security.md
code-review.md
api-conventions.md
frontend-react.md
docs/
architecture.md
git-workflow.md
packages/
api/
CLAUDE.md
src/
web/
CLAUDE.md
src/
shared/
CLAUDE.md
src/
Root CLAUDE.md:
# Repository Instructions
@docs/architecture.md
@docs/git-workflow.md
## Repository Layout
- packages/api: Node.js API.
- packages/web: React frontend.
- packages/shared: shared TypeScript utilities.
## Global Rules
- Use pnpm.
- Run commands from the package directory.
- Do not edit generated files directly.
.claude/rules/testing.md:
# Testing Rules
- Add tests for bug fixes.
- Prefer focused tests over broad snapshots.
- Run the package's test command before finalizing changes.
packages/api/CLAUDE.md:
# API Package
@../../docs/api-auth.md
- Use the standard error envelope.
- Validate request bodies at route boundaries.
- Use repository methods instead of raw SQL in route handlers.
packages/web/CLAUDE.md:
# Web Package
- Use design-system components first.
- Use TanStack Query for server state.
- Avoid direct fetch calls inside components.
This structure keeps root guidance global, package guidance local, and topic rules modular.
11. Common exam 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:
12. Scenario-based practice questions
Question 1
A team lead adds the following instruction to ~/.claude/CLAUDE.md:
A new teammate clones the repository, but Claude keeps suggesting npm test.
What is the best fix?
A) Ask the teammate to copy the lead’s entire ~/.claude/CLAUDE.md.
B) Move the instruction into project-level CLAUDE.md or .claude/CLAUDE.md and commit it.
C) Add the instruction to every prompt manually.
D) Use .mcp.json.
Answer
B. User-level instructions are personal and not shared through version control. Team-wide instructions belong in project-level configuration.
Question 2
A monorepo has one huge root CLAUDE.md containing React, API, database, mobile, and deployment conventions. Claude often applies React conventions while editing API files.
What is the best redesign?
A) Add more examples to the root file.
B) Split package-specific conventions into directory-level CLAUDE.md files or path-scoped .claude/rules/ files.
C) Delete all instructions.
D) Move everything to ~/.claude/CLAUDE.md.
Answer
B. The problem is overly broad instruction scope. Directory-level files and path-scoped rules keep subsystem conventions attached to the code they govern.
Question 3
A package maintainer wants the API package to use shared TypeScript standards, API standards, and database standards, but not React standards.
What should they do?
A) Import every standards file into the package’s CLAUDE.md.
B) Use @ references in packages/api/CLAUDE.md to selectively include only the relevant standards files.
C) Put all standards in ~/.claude/CLAUDE.md.
D) Remove all standards.
Answer
B. Selective imports allow package owners to include only the standards relevant to their package.
Question 4
A team splits a 500-line CLAUDE.md into:
They expect this to reduce context usage, but Claude still loads all the imported content at session start.
What is the issue?
A) @ imports organize content but do not necessarily reduce loaded context.
B) Imports are unsupported.
C) Claude only reads JSON files.
D) The files need to be in ~/.claude.
Answer
A. Imports improve organization. If the goal is to reduce irrelevant context, use path-scoped rules or move task-specific workflows into skills.
Question 5
Claude behaves differently when launched from the repository root versus packages/api.
What should you check first?
A) The operating system.
B) Which CLAUDE.md and rules files are loaded using /memory.
C) Whether Grep is installed.
D) The package version of React.
Answer
B. Launch directory affects which instructions load at startup. /memory is the right diagnostic tool.
Question 6
A repository has:
You launch Claude Code from packages/api.
Which instructions are expected to load at launch?
A) Only packages/api/CLAUDE.md.
B) Only root CLAUDE.md.
C) Root CLAUDE.md and packages/api/CLAUDE.md.
D) All subdirectory CLAUDE.md files in the repo.
Answer
C. Claude Code walks up the directory tree from the working directory and loads relevant ancestor files. Sibling package files are not loaded just because they exist.
Question 7
A rule applies only to files under src/api/**/*.ts.
What is the best configuration?
A) Put the rule in root CLAUDE.md with no scoping.
B) Put it in .claude/rules/api.md with paths: ["src/api/**/*.ts"].
C) Put it in ~/.claude/CLAUDE.md.
D) Add it to .mcp.json.
Answer
B. Path-scoped rules are designed for file-pattern-specific instructions.
Question 8
Claude is not following an instruction that the team believes is in CLAUDE.md.
What is the best first diagnostic step?
A) Run /memory and verify the relevant file is loaded.
B) Increase the model temperature.
C) Add the instruction to the user’s prompt five times.
D) Build an MCP server.
Answer
A. If a file is not listed in /memory, Claude cannot see it in that session.
Question 9
A developer wants private sandbox URLs available only for their local work on one project.
Where should they put them?
A) Project CLAUDE.md committed to git.
B) CLAUDE.local.md added to .gitignore, or personal user-level configuration if appropriate.
C) .mcp.json committed to the repo.
D) README.md.
Answer
B. Private project-specific preferences should not be committed. Claude Code supports local personal project instructions through CLAUDE.local.md, which should be gitignored. (Claude)
Question 10
Two loaded instruction files conflict:
What is the best fix?
A) Leave the conflict and let Claude decide.
B) Clarify root instructions so they defer to package-specific package managers.
C) Put both rules in user-level ~/.claude/CLAUDE.md.
D) Delete /memory.
Answer
B. Conflicting instructions create inconsistent behavior. The root file should state general guidance and delegate package-specific details to directory-level files.
13. High-yield checklist for D3.1
Memorize this:
1. ~/.claude/CLAUDE.md is personal and not shared with teammates.
2. ./CLAUDE.md and ./.claude/CLAUDE.md are project-level and should be committed when team-shared.
3. Directory-level CLAUDE.md files hold subsystem/package-specific instructions.
4. Claude Code walks up the directory tree from the current working directory.
5. Loaded CLAUDE.md files are concatenated, not cleanly overridden.
6. More specific directory instructions appear later and should refine broader rules.
7. Use @path imports to keep CLAUDE.md modular.
8. @ imports help organization but do not necessarily reduce context.
9. Use .claude/rules/ for topic-specific rule files.
10. Use path-scoped rules for file-pattern-specific instructions.
11. Keep root CLAUDE.md global; move package-specific rules closer to the package.
12. Use /memory to verify which CLAUDE.md, CLAUDE.local.md, and rules files loaded.
13. If teammates are missing instructions, check whether the rule lives in user-level config.
14. If sessions behave differently, compare loaded memory files with /memory.
15. Avoid vague or conflicting instructions.
D3.1 mental model
User-level = my personal defaults.
Project-level = shared team defaults.
Directory-level = package or subsystem defaults.
@ imports = modular organization.
.claude/rules = topic/path-scoped organization.
/memory = loaded-instruction debugger.
The most exam-relevant diagnostic pattern is:
If Claude behaves inconsistently, first verify which instruction files are actually loaded and whether the instruction lives at the right scope.