Scoping Instructions

Overview

Not all instructions belong in the same place. Some rules are specific to a single project, others reflect your personal preferences, and some apply universally across every codebase you work in. Putting the wrong instruction in the wrong scope leads to conflicts, noise, and wasted context.

This lesson covers the three scopes of CLAUDE.md -- project, user, and enterprise -- and how nested CLAUDE.md files work in monorepos. You will learn when to put instructions where, and how the scopes merge at runtime.

The Three Scopes

Claude Code reads instructions from multiple locations and merges them into a single set of context for each session. Understanding these scopes is essential for keeping your instructions clean and non-conflicting.

Four instruction scopes from broadest to narrowest: Enterprise/Organization (managed settings), User/Personal (~/.claude/CLAUDE.md), Project Root (./CLAUDE.md, checked into repo), and Subdirectory (e.g., ./packages/api/CLAUDE.md, package-specific). Each scope narrows from organization-wide to a single package.

When scopes overlap, all applicable CLAUDE.md files are concatenated into context. More-local files appear later in the context window, but this is concatenation, not a deterministic override. If two files contradict each other, the agent reads both and behavior is unpredictable. Remove contradictions rather than relying on file order.

Scope 1: Project Root CLAUDE.md

This is the most common and most important scope. It lives at the root of your repository and is checked into version control. Every team member and every CI agent session reads it.

What belongs here:

• Build, test, lint, and type-check commands
• Code style conventions the whole team follows
• Architecture overview and file structure
• Project-wide do's and don'ts

What does NOT belong here:

• Personal preferences ("I prefer verbose explanations")
• Secrets or API keys (these should be in .env, never in CLAUDE.md)
• Instructions that only apply to one subdirectory

Important: Because this file is checked into git, treat it as team documentation. Changes should go through code review, just like any other project file.

Scope 2: User-Level CLAUDE.md

Your personal CLAUDE.md lives at ~/.claude/CLAUDE.md. It applies to every project you work on but is not shared with your team.

What belongs here:

• Communication preferences (verbosity, explanation style)
• Workflow preferences (test-first, fix approach)
• Environment-specific information (OS, shell, installed tools)
• Personal shortcuts or aliases you expect the agent to know about

What does NOT belong here:

• Project-specific build commands (these go in the project CLAUDE.md)
• Team conventions (these should be shared via the project CLAUDE.md)
• Anything that would help other team members too (share it in the project CLAUDE.md instead)

Tip: If you find yourself putting the same instruction in your user CLAUDE.md for multiple projects, consider whether it belongs in a template that you use when starting new projects instead.

Scope 3: Enterprise Settings

Organizations using Claude for Business or Claude for Enterprise can set organization-wide policies through managed settings. These are the broadest scope and are controlled by administrators, not individual developers.

Enterprise settings typically cover:

• Security policies (do not access external URLs, do not install packages without approval)
• Compliance rules (do not generate code with certain licenses)
• Standard tooling requirements (always use the company's logging framework)
• Approved patterns and libraries

Individual developers usually do not need to manage this scope -- it is handled by the platform team or security team.

Nested CLAUDE.md in Monorepos

Monorepos present a unique challenge: different packages have different languages, conventions, and tooling. A single root CLAUDE.md cannot capture this diversity without becoming bloated.

The solution is nested CLAUDE.md files -- one at the root for shared conventions, and one in each package for package-specific rules.

Monorepo nesting: the repository root CLAUDE.md contains shared conventions and build commands, and feeds into package-level CLAUDE.md files for each package — packages/api (Python, FastAPI, pytest), packages/web (TypeScript, Next.js, vitest), packages/mobile (Kotlin, Android), and packages/shared (TypeScript, library conventions).

Here is how the root and package-level files might look:

When the agent works on a file in packages/api/, it reads both the root CLAUDE.md and the packages/api/CLAUDE.md. The package-level file provides specific context, while the root file provides the monorepo-wide rules.

How Scopes Merge

When multiple CLAUDE.md files apply, the agent concatenates them into a single context window:

Scope merge flow: the agent reads enterprise settings (broadest), then user CLAUDE.md, then project root CLAUDE.md, then checks if the working subdirectory has its own CLAUDE.md. All instructions are concatenated into a single context. More-local files appear later, but contradictions are not resolved automatically.

For example, if your root CLAUDE.md says "use named exports" and a package-level CLAUDE.md says "use default exports for React components in this package," the agent reads both. In practice, the more-local instruction often guides behavior because it appears later in context -- but this is not a guaranteed override. If the instructions directly contradict each other, the agent may follow either one. Write package-level instructions as refinements ("in this package, prefer default exports for React components") rather than contradictions.

Modern alternative: Claude Code also supports .claude/rules/ files with a paths frontmatter field (e.g., paths: ["packages/web/**"]). These provide targeted, per-path instructions without relying on nested CLAUDE.md files. See the Claude Code documentation for details.

Deciding Where to Put an Instruction

Use this decision framework to determine the right scope for any instruction:

Rule of thumb: Start by putting instructions in the project CLAUDE.md. Only move them to a different scope if you have a clear reason. Project-level is the safest default because it is version-controlled and team-shared.

Common Scoping Mistakes

Mistake 1: Project rules in user settings

If you put project-specific build commands in ~/.claude/CLAUDE.md, your teammates will not benefit from them, and the instructions will interfere when you work on a different project.

Mistake 2: Personal preferences in the project CLAUDE.md

Instructions like "always give verbose explanations" or "prefer concise responses" are personal. Putting them in the project CLAUDE.md imposes your preference on the whole team.

Mistake 3: Everything in the root of a monorepo

When a monorepo root CLAUDE.md tries to document conventions for every package, it becomes hundreds of lines long. This wastes context window for agents working on a single package that only needs 20 lines of specific instructions.

Mistake 4: Duplicating rules across scopes

If both the root and a package CLAUDE.md say "run pnpm test before committing," you now have two places to update when you change the test command. Let the root handle shared rules and packages handle only their refinements.

Mistake 5: Relying on "override" behavior to resolve contradictions

Conflicting instructions are not resolved through a deterministic override rule. If the root says "never use default exports" and a package says "always use default exports," the agent reads both and behavior is unpredictable. Instead of contradicting a root-level rule, refine it: "in this package, prefer default exports for React components." When instructions cannot be reconciled, remove the contradiction from one scope.

Summary

• CLAUDE.md has three scopes: project (checked into repo), user (~/.claude/CLAUDE.md), and enterprise (managed by admins)
• The project root CLAUDE.md is the most important -- it contains build commands, code style, architecture, and team-wide rules
• The user-level CLAUDE.md is for personal preferences and environment-specific details
• Monorepos use nested CLAUDE.md files -- one root for shared conventions, one per package for specifics
• Scopes are concatenated -- all applicable files are read, with more-local files appearing later in context, but contradictions are not resolved automatically
• Conflicting instructions are not resolved through a deterministic override rule -- remove contradictions rather than relying on file order
• Put instructions at the narrowest scope where they apply, defaulting to project level when in doubt
• .claude/rules/ files with paths frontmatter offer an alternative to nested CLAUDE.md for per-path scoping
• Avoid common mistakes: project rules in user settings, personal preferences in project files, duplicating rules, and relying on override behavior for contradictions