3.1 CLAUDE.md Hierarchy & Scoping

Every Claude Code session starts with a blank slate — a fresh context window that knows nothing about your project's conventions, build commands, or architecture. So how do you avoid re-explaining 'we use 2-space indentation' and 'run npm test before committing' every single session? The answer is a CLAUDE.md file: a plain markdown file where you write down the persistent instructions you want Claude to have in every conversation. Task Statement 3.1 is about where these files live, how they combine, and the scoping rules that decide who gets which instructions.

Think of CLAUDE.md like the onboarding notes you'd leave for anyone joining your project — 'here's how we build, here's where things live, here's what to always do.' Claude reads these notes at the start of every session, the way a new collaborator would read the README before touching anything. Write them once, and Claude carries them into every conversation.

The subtlety the exam tests is that CLAUDE.md isn't one file in one place — it's a HIERARCHY of files at different levels, and where you put an instruction decides who it reaches. Put it in the wrong place and a teammate silently doesn't get it. Let's build up that hierarchy and the rules for how the files combine.

CLAUDE.md files live at different LEVELS, and the level controls scope — who sees the instructions. The exam focuses on three: user, project, and directory.

USER level (~/.claude/CLAUDE.md) is YOUR personal file, applying across all your projects — but private to you. It's perfect for personal preferences ('I like verbose commit messages') and never shared with teammates. PROJECT level (./CLAUDE.md or ./.claude/CLAUDE.md) lives in the repository, so it's checked into version control and shared with the whole team — the home for project architecture, coding standards, and build commands everyone needs. DIRECTORY level (a CLAUDE.md inside a subdirectory) scopes instructions to just that part of the codebase — useful when one package or module has its own conventions.

The crucial distinction — and the one the exam tests hardest — is user vs project. User-level lives in your home directory and is NOT shared via version control. Project-level lives in the repo and IS shared. Confuse them and instructions land in the wrong audience.

When multiple CLAUDE.md files apply, how do they interact? This is where intuition often misleads. You might assume a more specific file OVERRIDES a broader one — like CSS, where the most specific rule wins. That's wrong, and the exam tests the misconception directly.

CLAUDE.md files are CONCATENATED, not overriding. Claude walks up the directory tree and stacks all the applicable files together into context, ordered broad to specific: the user file, then the project file, then any directory file, with CLAUDE.local.md appended last at each level. Nothing replaces anything — it all gets combined. So if your user file says 'use tabs' and the project file says 'use 2-space indentation,' both instructions are present, and because they CONFLICT, Claude may resolve the contradiction arbitrarily. The lesson: don't rely on one file 'beating' another; instead, keep instructions consistent across files and review them for conflicts.

There's a deeper point hiding here, and it's the most important caveat in this lesson. CLAUDE.md is delivered to Claude as a regular user message after the system prompt — it is CONTEXT, not enforced configuration. Claude reads it and tries to follow it, but there is NO guarantee of strict compliance, especially for vague or conflicting instructions. So if a rule absolutely MUST be honored — 'never push to main,' 'always run lint before commit' — CLAUDE.md is the wrong tool. Use a hook (Domain 1.5) or settings.json, which enforce deterministically. CLAUDE.md guides behavior; hooks guarantee it.

A CLAUDE.md that grows past ~200 lines starts to hurt — it eats context and, counterintuitively, REDUCES how reliably Claude follows it (more text, less adherence). Two mechanisms keep things modular as a project grows.

IMPORTS: the @path syntax pulls in another file inline. Writing `@./standards/naming.md` or `@README` in your CLAUDE.md inlines that file's contents at launch. This is great for ORGANIZATION — splitting a big file into readable pieces, or pointing at an existing AGENTS.md so multiple tools share one source. But note the catch the exam likes: imports do NOT reduce context. The imported file is loaded in full at launch, just like the rest — so @import organizes, it doesn't shrink your token footprint.

RULES: the .claude/rules/ directory holds topic-specific files (testing.md, api-conventions.md, security.md), each covering one area. By default these load at launch with the same priority as .claude/CLAUDE.md — so out of the box they're just a tidier way to organize the same always-on instructions. (Their real power, conditional path-based loading, is the subject of the next lesson, 3.3.) Finally, the /memory command is your diagnostic tool: it lists exactly which CLAUDE.md and rules files are loaded in the current session — invaluable when instructions seem to be ignored and you need to confirm a file is actually being read.

The 3.1 traps cluster around three misconceptions: that user-level is shared, that more-specific files override, and that CLAUDE.md can enforce a hard rule. Anchor on the three corrections and they fall away.

The signature scenario: a new teammate clones the repo but isn't getting the team's conventions. Why? Because those conventions live in someone's USER-level config (~/.claude/CLAUDE.md), which is private and not in version control. The fix is to move them to the PROJECT level (./CLAUDE.md or .claude/CLAUDE.md) and commit them, so everyone gets them on clone. Whenever you see 'a teammate isn't getting instructions,' suspect user-vs-project scope.

You now understand what CLAUDE.md is, the three scope levels, how files concatenate (and why they don't enforce), and how to organize with imports, rules, and /memory. The exercise has you prove the scoping boundary that the exam tests — by watching an instruction reach or not reach depending on where you put it.

CLAUDE.md is the always-on layer of configuration. The next lesson, 3.2, covers the on-demand layer — custom slash commands and skills, which package workflows you invoke when you need them rather than loading them every session.