Path-Scoped Rules

Path-scoped rules are your way of telling Claude, "When you're looking at *this* part of the codebase, act *this* way." They are instructions or constraints embedded within CLAUDE.md files that live in specific subdirectories of your project. Unlike the main CLAUDE.md at your project's root, which applies globally, these rules only become active when Claude's context window includes files from their immediate directory or its subdirectories. Think of them as localized directives. When you open a file like /src/components/Button.tsx, Claude Code automatically loads the CLAUDE.md from /src/components/ (if one exists) and applies its specific guidelines. This means Claude's behavior dynamically shifts based on the exact code you are interacting with, allowing for highly granular control over its responses and code generation. They are designed for projects with distinct architectural layers, different tech stacks within a monorepo, or varying coding standards across teams. They are a powerful tool for maintaining consistency and specialized behavior without overwhelming Claude with a single, monolithic set of instructions.

Path-scoped rules are not global invariants. They are not a "set it and forget it" mechanism for project-wide mandates. If you define "always use TypeScript" in a /frontend/CLAUDE.md, that rule will not apply when you are editing a Python script in your /backend directory. Crucially, they are not persistent memory entries. Unlike the root CLAUDE.md or explicit memory entries, which are re-injected after a /compact or /clear, path-scoped rules are *dropped* from the context window during these operations. They only return when you explicitly re-read a file from their respective directory. This is a critical distinction. They do not magically survive context resets; they must be re-triggered by file access. They are also not a substitute for skill definitions or MCP tool configurations, which have their own injection mechanisms. They are purely about guiding Claude's *interpretation* and *generation* within a specific file context, not defining its capabilities or tools.

Consider a large-scale enterprise application, say, an internal tool at a company like Salesforce or Adobe, built as a monorepo. This project might have a /services directory for backend microservices written in Go, a /web-app directory for the main user interface using Next.js and Tailwind CSS, and a /mobile directory for a React Native application. Each of these sub-projects has its own specific conventions, linter rules, and preferred libraries.

Without path-scoped rules, your main CLAUDE.md would become a sprawling, unmanageable mess trying to cover all these disparate requirements. Instead, you create:

1. /services/CLAUDE.md: "When working in this directory, prioritize idiomatic Go. Use goroutines for concurrency. All API endpoints must be RESTful and include OpenAPI documentation. Ensure database transactions are atomic." 2. /web-app/CLAUDE.md: "When working in this directory, use React functional components with hooks. Apply Tailwind CSS classes for styling. All data fetching should use React Query. Ensure accessibility standards (WCAG 2.1 AA) are met." 3. /mobile/CLAUDE.md: "When working in this directory, use React Native components. Prefer react-navigation for routing. Ensure cross-platform compatibility for iOS and Android. Optimize for performance on low-end devices."

Now, when a developer opens /web-app/src/components/UserProfile.tsx, Claude automatically loads the /web-app/CLAUDE.md rules. It understands to suggest React hooks, Tailwind classes, and accessibility best practices. If the developer then switches to /services/pkg/auth/handler.go, Claude's context shifts. It now suggests Go idioms, goroutine patterns, and OpenAPI documentation. This dynamic adaptation prevents Claude from suggesting React components for a Go file or Go concurrency patterns for a React Native component, drastically improving its relevance and accuracy. It's like giving Claude a specialized instruction manual for each room in a large house.

**Use path-scoped rules when:** 1. **Monorepos with distinct sub-projects:** If your codebase contains multiple applications or libraries, each with unique tech stacks, coding standards, or architectural patterns. Think of projects like Microsoft's Visual Studio Code, which uses TypeScript for the UI and C++ for the core engine, or a large financial institution's codebase with separate modules for trading, risk management, and reporting. Each module benefits from its own localized guidelines. 2. **Enforcing localized conventions:** When you need to ensure specific design patterns, library choices, or security practices are applied only within a particular module or layer. For instance, a /security module might have rules like "always sanitize user input" and "never expose raw SQL queries," while a /ui module might focus on "always use Material Design components" and "ensure responsive layouts." 3. **Reducing global context clutter:** Instead of stuffing every possible rule into your root CLAUDE.md, which can make it unwieldy and dilute Claude's focus, path-scoped rules keep the relevant instructions close to the code they govern. This makes Claude more efficient and less prone to misinterpretations. 4. **Temporary, context-specific directives:** If you are debugging a specific module and need Claude to focus on logging, error handling, or performance optimization *only* within that module, you can drop a CLAUDE.md there temporarily.

**Do not use path-scoped rules when:** 1. **Global, project-wide invariants:** Rules that apply universally across your entire codebase, regardless of the file being edited, belong in the root CLAUDE.md. Examples include "always write unit tests for new features," "adhere to the company's code of conduct," or "use semantic versioning." These are foundational and should always be active. 2. **Rules that must persist across context resets:** If a rule is so critical that it absolutely cannot be dropped from Claude's awareness, even after a /compact or /clear, it should be in the root CLAUDE.md or explicitly managed as a memory entry. Path-scoped rules are volatile; they disappear when their associated files are no longer in the context. 3. **Small, monolithic projects:** For projects where the entire codebase adheres to a single, consistent set of rules, the overhead of managing multiple CLAUDE.md files might outweigh the benefits. A single root CLAUDE.md is sufficient. 4. **Defining tool capabilities or skill definitions:** Path-scoped rules are for *guidance*, not for *defining functionality*. Your MCP tool definitions or skill bodies have their own mechanisms for injection and persistence. Do not try to define a new tool within a path-scoped CLAUDE.md.

Path-scoped rules are Claude's localized instruction manuals, ensuring it speaks the right language for the specific code it is currently reading.