Claude Code isn't just aware of your project root; it's sensitive to where you are within it. Path-specific rules allow you to enforce different coding standards, testing patterns, and architectural constraints based on the current active directory, enabling seamless transitions between diverse tech stacks in a single repository.
Imagine walking through a modern international airport. There is a "Global Protocol" for the whole airport (no smoking, be polite). However, as you move between zones, the specific rules change instantly:
You don't take your shoes off in the Food Court, and you don't show your boarding pass at the Information Desk. The path you take through the airport triggers different conditional rules. CLAUDE.md files do the same for Claude: moving into the /frontend directory triggers React rules, while entering /infra triggers Terraform rules.
Path-specific rules are implemented primarily through Subdirectory CLAUDE.md files. When Claude Code opens or analyzes a file, it builds its "active instruction set" by traversing the file path from the file's location back up to the project root (and finally the global config).
apps/api/src/handlers/user.py).../handlers/).../src/, .../api/, .../apps/)~/.claude/CLAUDE.md)Claude only re-evaluates this chain when the active task or current file set changes. This ensures that if you are working on a Python backend file, Claude isn't distracted by your React frontend's Tailwind conventions, even if they're in the same repository.
In large monorepos, keeping all rules in a single root CLAUDE.md is a recipe for context pollution. Path-specific rules solve this by delegating domain-specific expertise to the directories that actually use it.
| Project Path | Primary Purpose | Scoped Instructions |
|---|---|---|
/frontend/ |
Client-side React app | Vite commands, styling guidelines (Tailwind), component structure. |
/backend/ |
Python/FastAPI server | Alembic migrations, SQLAlchemy patterns, Pydantic validation rules. |
/shared/ |
Common JSON schemas | Versioning protocols, breaking change policies, export formats. |
/e2e/ |
Playwright tests | Cypress/Playwright run commands, CI environment setup, mock data strategy. |
Standard inheritance applies: The most local rule wins. This allows teams to set "Broad Defaults" at the root while allowing "Local Exceptions" for specialized modules.
# /CLAUDE.md (Root) - Naming: Use kebab-case for all file names. - Testing: All tests must run with `npm test`. # /services/legacy-auth/CLAUDE.md (Subdirectory) - Naming: Override root — use PascalCase for files to match legacy Java naming. - Testing: Override root — tests in this folder require `mvn test`, not npm.
On the exam, watch for questions about partial overrides. A subdirectory CLAUDE.md does NOT erase the root file. It only overrides the specific bullet points it targets. If the root says "Don't use wildcard imports" and the subdirectory doesn't mention it, the "Don't use wildcard imports" rule still effectively applies in the subdirectory.
# Frontend Guidelines ## Technology Stack - React 18, Tailwind CSS, TanStack Query. - Component structure: Functional components with hooks only. ## Path-Specific Rules - All components in `src/components/common` must be atomic and stateless. - Components in `src/pages` handle layout and data fetching. - Use `shadcn/ui` where possible. ## Testing Commands - Run unit tests: `npm run test:ui` - Run linting: `npm run lint:frontend`
# Backend Guidelines ## Technology Stack - Python 3.11+, FastAPI, PostgreSQL. - ORM: SQLAlchemy (Async mode always). ## Path-Specific Rules - API endpoints in `app/routers/` must have Pydantic response models. - DB models in `app/models/` must inherit from `Base` in `database.py`. - No raw SQL except in `app/migrations/`. ## Testing Commands - Run tests: `pytest -v app/tests` - Refresh DB mocks: `python scripts/seed_test_db.py`
Beyond tech stacks, path-specific rules are often used for security, performance, or "mode" switching:
/production-config/CLAUDE.md explicitly forbids any delete commands without human confirmation./performance-tests/ instruct Claude to use `hyperfine` for benchmarking instead of simple `time` commands./hr-data/ include strict headers: "NEVER output real names from this directory in chat history."Don't create a subdirectory CLAUDE.md for every folder. Use them only when the behavioral guidance needs to change. Over-fragmenting rules makes it harder for you to keep track of what instructions Claude is actually following.
Deleting a folder but leaving its CLAUDE.md in a parent directory. Claude will still try to apply those rules to things "near" it, causing confusion.
Duplicating 100% of the root rules in a subdirectory file. If you update the root, the subdirectory stays stuck in the past. Only put delta (changed) rules in subdirs.
Putting "Always use 2 spaces" in the /backend folder when the root already says it. It adds noise and consumes extra context tokens for no benefit.
Scenario: You have a monorepo with an /api (Java) and /web (React) directory. You want Claude to use Maven for the API and NPM for the web. Where do the commands go?
Answer: Create /api/CLAUDE.md with Maven commands and /web/CLAUDE.md with NPM commands. Do NOT put them in the root, as Claude would have to "guess" which command to use based on file extension alone, which is less reliable than path-based scoping.
CLAUDE.md file closest to the active file.