Path-Specific Rules

Claude Code

Definition

CLAUDE.md files placed in subdirectories that extend or refine root-level configuration for that directory subtree. Enables per-team ownership in monorepos: different rules for tests/, src/auth/, and docs/ without one massive root config. Files compose (stack) from root down to the current directory — they do not replace each other.

Example Usage

Place a CLAUDE.md in tests/ specifying that Claude should always write assertion messages; the root CLAUDE.md's coding conventions still apply — both layers are active simultaneously.

Why It Matters for the CCA-F Exam

The CCA-F exam tests the composition model — a common distractor presents subdirectory CLAUDE.md files as *replacing* the root. The correct answer is always that they *compose*. Monorepo scenarios appear frequently: candidates must trace which CLAUDE.md files are active for a given file path and identify which rules apply when layers appear to conflict.

In Depth

Path-specific rules are CLAUDE.md files placed inside subdirectories. Claude Code walks the directory tree from the repository root down to the file being worked on, composing every CLAUDE.md it encounters along the way. Each layer adds to the layers above it; no layer silently erases a parent.

Hierarchy and Composition in Practice

The full resolution order, from broadest to most specific:

~/.claude/CLAUDE.md — machine-wide personal defaults
<repo>/CLAUDE.md — project-wide team conventions
<repo>/src/CLAUDE.md — source-directory rules
<repo>/src/auth/CLAUDE.md — sub-team rules for the auth module

All four are active simultaneously when Claude Code is editing a file inside src/auth/. A rule in layer 4 that contradicts layer 2 wins for that specific point; everything else from layers 1-3 remains in effect.

Worked Monorepo Example

monorepo/
  CLAUDE.md                  # "Use TypeScript strict; commit style: conventional commits"
  src/
    CLAUDE.md                # "No console.log; named exports only"
    auth/
      CLAUDE.md              # "Always validate JWT expiry; flag hardcoded secrets"
  tests/
    CLAUDE.md                # "Cover success + failure; use descriptive assert messages"
  data-science/
    CLAUDE.md                # "Python only; use pandas, not polars; no type hints required"
  docs/
    CLAUDE.md                # "Write in second person; no fenced code blocks"

Scenario: Claude edits tests/auth/test_login.py.

Active rules: root (TypeScript strict, conventional commits) + tests/ (success+failure, assert messages).
src/auth/CLAUDE.md is NOT active — the file is under tests/, not src/auth/.

Scenario: Claude edits data-science/models/train.py.

Active rules: root (conventional commits) + data-science/ (Python, pandas, no type hints).
src/ rules do NOT apply — data-science/ is a sibling, not a descendant of src/.

Per-Team Ownership Pattern

Path-specific rules let sub-teams own their slice of Claude's behavior without touching shared root config:

Team	Their CLAUDE.md	Root rules they still inherit
Auth	`src/auth/CLAUDE.md` — JWT validation, secret scanning	Commit style, TypeScript strict
QA	`tests/CLAUDE.md` — assertion style, coverage floor	Commit style
Data Science	`data-science/CLAUDE.md` — Python idioms, no TS	Commit style

Combining with @import to Avoid Duplication

When several directories share a rule subset, extract the shared rules into a fragment and import them:

# src/auth/CLAUDE.md
@import ../../.claude/rules/security-baseline.md

## Auth-Specific Rules
- Always check JWT expiry before trusting claims
- Use `AuthError`, never bare `Error`, for auth failures

This avoids copy-pasting the same security rules into src/payments/CLAUDE.md and src/admin/CLAUDE.md.

For details on the file format itself and what content belongs in CLAUDE.md vs. other config files, see CLAUDE.md.

How It Compares

Scope	File Location	Who Writes It	Typical Content
Global	`~/.claude/CLAUDE.md`	Individual developer	Personal style, default tools
Project root	`<repo>/CLAUDE.md`	Whole team	Commit conventions, architecture notes
Subdirectory	`<repo>/tests/CLAUDE.md`	Sub-team or CI owner	Test-specific style, coverage requirements
Imported fragment	`.claude/rules/*.md` + `@import`	Any owner	Shared rule snippets reused across directories

Example

A tests/ directory CLAUDE.md that adds test-specific rules on top of the project root CLAUDE.md — composition, not replacement.

markdown

# tests/CLAUDE.md
# Inherits ALL root CLAUDE.md rules. The following ADDS to them.

## Test Standards
- Every test must cover at least one success case and one failure/edge case.
- Use descriptive assertion messages: `assert result == expected, f"Got {result}, want {expected}"`
- Do not use `unittest.mock.patch` on public interfaces; mock at the boundary instead.
- Run `pytest -x` (fail-fast) before marking any test task complete.

How It's Tested & Common Confusions

Scenario question — composition:

A monorepo has CLAUDE.md ("follow PEP 8") and tests/CLAUDE.md ("always write assertion messages"). Which rules apply inside tests/?

Correct: Both — root rules plus test-directory refinement.
Distractor: Only the innermost CLAUDE.md applies.

Scenario question — path isolation:

Claude Code edits a file in data-science/. Active CLAUDE.md files?

Root CLAUDE.md + data-science/CLAUDE.md only. src/CLAUDE.md does NOT apply because data-science/ is not under src/.

Scenario question — conflict resolution:

Root says "use snake_case"; src/api/CLAUDE.md says "use camelCase for this module." Which wins in src/api/?

The more specific layer wins for that specific instruction; all other root rules remain active.

Directory-tree tracing: Candidates are shown a three-level tree and asked which CLAUDE.md files are active for a deeply nested file. Rule: every ancestor from repo root down to the file's directory is active — no skipping, no replacement.

Frequently Asked Questions

Does a subdirectory CLAUDE.md replace the root CLAUDE.md?

No. Claude Code composes every CLAUDE.md from root down to the current directory. A subdirectory file refines or overrides specific instructions but does not erase parent rules. Think of it as a cascade, not a replacement — like how CSS specificity works.

Do path-specific rules apply to sibling directories?

No. Rules in `src/auth/CLAUDE.md` only apply when Claude Code is working on files inside `src/auth/` or its descendants. A sibling like `src/payments/` does not inherit those rules — it only inherits from the common ancestors (root and `src/`).

Is .claude/rules/ the required location for path-specific rules?

No — it is a convention for reusable rule fragments that you pull in with @import. You can place a CLAUDE.md directly inside any subdirectory and Claude Code will pick it up automatically without any import statement. The tree walk happens regardless of where the file sits.

Referenced in These Lessons

Path-Specific Rules (.claude/rules/)

Claude Code & Workflows

Use .claude/rules/ with glob patterns for file-type-specific conventions

Related Terms

CLAUDE.md @import Directive

← Back to Glossary