3.1 — CLAUDE.md Hierarchy, Scoping, and Modular Organisation

CCAR-F Domain 3 · Task 3.1

What You Need to Know

A CLAUDE.md file is a Markdown file of instructions for Claude Code. Claude Code reads these files at three levels.

The Three-Level Hierarchy

Level	Location	Scope
User	~/.claude/CLAUDE.md	Personal only; not version-controlled
Project	.claude/CLAUDE.md or root CLAUDE.md	Shared via git; team standards
Directory	subdirectory CLAUDE.md	Package-specific conventions

Loading Order and Conflict Handling

All discovered files are concatenated into context rather than overriding each other. Load order is broadest → most specific, but reading last does not win a conflict. If two rules contradict, Claude may pick one arbitrarily.

For rules that must hold on every run (blocked tools, formatters, permissions), use settings.json or a hook — not CLAUDE.md.

Modular Organisation with @ path imports

# .claude/CLAUDE.md
Coding standards:
@./standards/naming-conventions.md
@./standards/error-handling.md

CLAUDE.local.md

Local-only overrides. Gitignored by convention. Appended after CLAUDE.md at the same level.

The .claude/rules/ Directory

Topic-specific rule files. Can include YAML frontmatter with path scoping (Task 3.3).

What Survives Compaction

Project-root CLAUDE.md comes back intact after /compact. Nested CLAUDE.md and path-scoped rules load on demand.

Diagnosing What Loaded

• Exam answer: /memory
• Current product: /context shows what loaded at launch under Memory files

Exam Traps

• New team member not receiving instructions → conventions in user-level instead of project-level
• Thinking /memory triggers configuration loading
• Assuming directory-level CLAUDE.md is best for cross-directory conventions