Domain 3 · Lesson 1 · Claude Code Config (20%)

CLAUDE.md Hierarchy & Path-Specific Rules

Task Statements 3.1 & 3.3 — where config lives, why it's not shared, and glob-scoped rules.

Course progress: Domain 3 ▸ lesson 1 of ~4

The CLAUDE.md hierarchy

Level	Location	Shared via VCS?
User	`~/.claude/CLAUDE.md`	No — personal only
Project	`.claude/CLAUDE.md` or root `CLAUDE.md`	Yes — committed, team-wide
Directory	subdirectory `CLAUDE.md`	Yes, but scoped to that directory

The #1 diagnostic question A new teammate doesn't get the team's instructions. Why? They were placed in user-level ~/.claude/CLAUDE.md (personal, not version-controlled) instead of project-level config. Fix = move them to project scope so they ship with the repo.

Keeping CLAUDE.md modular

@import: reference external files so CLAUDE.md stays lean — e.g., import only the standards relevant to each package.
.claude/rules/: split a monolithic CLAUDE.md into topic files (testing.md, api-conventions.md, deployment.md).
/memory: command to verify which memory files are actually loaded — use it to debug inconsistent behavior across sessions.

Path-specific rules (the glob trick)

.claude/rules/ files can carry YAML frontmatter with a paths: field of glob patterns. The rule loads only when editing matching files — reducing irrelevant context and token usage.

---
paths: ["**/*.test.tsx"]
---
# Testing conventions
Use React Testing Library; one describe block per component; …

When glob rules beat a directory CLAUDE.md When a convention must apply to files spread across many directories (test files sitting next to their components everywhere), a glob-scoped rule (**/*.test.tsx) applies by file type regardless of location. A directory CLAUDE.md is directory-bound and can't follow files scattered across the tree.

Check yourself

A newly onboarded developer isn't receiving the team's coding instructions that everyone else has. The most likely cause is that the instructions live in:

The project root CLAUDE.md that ships with every repo clone
User-level ~/.claude/CLAUDE.md, which is personal and unshared
A .claude/rules/ file whose glob paths matched every file
An @imported standards file committed in the repository

Correct: option 2. User-level config is personal and not version-controlled, so teammates never receive it. The fix is to move the instructions to project scope. The other locations are all shared via the repo.

Test files sit beside the code they test throughout the codebase, and all tests must follow one convention regardless of directory. Most maintainable approach:

A .claude/rules/ file with a paths: ["**/*.test.tsx"] glob
One consolidated root CLAUDE.md relying on Claude to infer sections
A separate CLAUDE.md placed in every subdirectory that has tests
A skill per code type that must be manually invoked before editing

Correct: option 1. Glob-scoped rules apply by file type across all directories automatically. Inference (2) is unreliable; per-directory CLAUDE.md (3) can't follow scattered files; manual skills (4) aren't automatic.

Decision rules Team must share it → project scope. Personal only → user scope. Convention spans scattered files → glob rule in .claude/rules/. Behavior inconsistent → /memory to see what loaded. Bloated CLAUDE.md → @import / split into rules.

Ask your teacher. Want load-order/precedence between user, project, and directory CLAUDE.md? Ask.