CCA-F Study Day 10/20: CLAUDE.md Hierarchy
Domain 3: Claude Code Configuration & Workflows (~20% of exam)
📌 Today's Focus
Welcome to Domain 3 — the second-heaviest domain on the exam at 20%. Today we tackle the CLAUDE.md configuration hierarchy, which is the foundation for everything else in this domain. Think of CLAUDE.md as the "system prompt for Claude Code" — it tells Claude Code how to behave in your project, your organization, and for you personally. The exam tests your understanding of where files load from, in what order, and what goes where.
Why this matters for the exam: Two of the six exam scenarios ("Code Generation with Claude Code" and "Claude Code for CI/CD") directly test CLAUDE.md architecture. Questions will present you with monorepo configurations and ask which instruction takes precedence, or present a team problem and ask where to place a rule.
📚 Core Concepts
1. The CLAUDE.md Hierarchy (Load Order)
Claude Code loads CLAUDE.md files by walking UP the directory tree from your current working directory, then reading files in order from the filesystem root down. Here's the complete hierarchy from broadest to most specific scope:
| Priority | Scope | Location | Shared? |
|---|---|---|---|
| 1 (broadest) | Managed policy | /Library/Application Support/ClaudeCode/CLAUDE.md(macOS)/etc/claude-code/CLAUDE.md(Linux) | All org users |
| 2 | User | ~/.claude/CLAUDE.md | Just you (all projects) |
| 3 | Project root | ./CLAUDE.md or ./.claude/CLAUDE.md | Team (via git) |
| 4 | Project local | ./CLAUDE.local.md | Just you (gitignored) |
| 5 | Parent directories | Any CLAUDE.md in parent dirs above CWD | Monorepo teams |
| 6 | Child directories | ./subdirectory/CLAUDE.md | On-demand (loaded when files in that dir are accessed) |
🔑 Critical exam insight: All discovered files are concatenated into context — they do NOT override each other. Content is ordered root→CWD, and within each directory, CLAUDE.local.md appends after CLAUDE.md. Child directory files load on demand, not at startup.
2. CLAUDE.md vs Auto Memory
The exam distinguishes between these two memory systems:
| CLAUDE.md files | Auto Memory | |
|---|---|---|
| Who writes it | You (the developer) | Claude (automatically) |
| Contains | Instructions and rules | Learnings and patterns |
| Nature | Context (advisory), NOT enforced config | Context (advisory), NOT enforced config |
⚠️ Both are context, not enforced configuration! To block an action regardless of what Claude decides, you must use a PreToolUse hook (from Day 4). This is a classic exam trap — CLAUDE.mdinstructions are advisory; hooks are deterministic.
3. Import Syntax
CLAUDE.md files can reference other files using @path/to/import syntax:
# In your CLAUDE.md
See @README.md for project overview and @package.json for available commands.
# Additional Instructions
- Git workflow: @docs/git-instructions.md
- Personal overrides: @~/.claude/my-project-instructions.md
Key rules about imports:
- Relative paths resolve relative to the file containing the import, not CWD
- Recursive imports allowed, max depth of 4 hops
- Imported files are expanded and loaded at launch alongside the CLAUDE.md
- First encounter with external imports shows an approval dialog
4. What Goes IN vs OUT of CLAUDE.md
| ✅ Include | ❌ Exclude |
|---|---|
| Build/test commands Claude can't guess | Anything Claude can figure out by reading code |
| Code style rules that differ from defaults | Standard language conventions |
| Testing instructions and preferred test runners | Detailed API documentation (link instead) |
| Repo etiquette (branch naming, PR conventions) | Information that changes frequently |
| Architectural decisions specific to your project | Long explanations or tutorials |
| Common gotchas or non-obvious behaviors | File-by-file codebase descriptions |
Size target: Under 200 lines per CLAUDE.md file. Some teams go as low as 60 lines. The ceiling is ~300 lines before adherence drops.
5. .claude/rules/ Directory
For larger projects, organize instructions into modular files:
your-project/
├── .claude/
│ ├── CLAUDE.md # Main project instructions
│ └── rules/
│ ├── code-style.md # Code style guidelines
│ ├── testing.md # Testing conventions
│ └── security.md # Security requirements
Path-specific rules only load when Claude works with matching files — this saves context tokens:
---
paths:
- "src/api/**/*.ts"
---
# API Development Rules
- All API endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments
6. CLAUDE.md for Monorepos
In monorepos, the hierarchy becomes especially powerful:
monorepo/
├── CLAUDE.md # Shared: linting, git conventions, CI
├── frontend/
│ ├── CLAUDE.md # React rules, component patterns
│ └── src/
│ └── components/
│ └── CLAUDE.md # Component-specific conventions (on-demand)
├── backend/
│ ├── CLAUDE.md # Python/FastAPI rules
│ └── tests/
│ └── CLAUDE.md # Testing-specific rules (on-demand)
└── shared/
└── CLAUDE.md # Shared library conventions
Use claudeMdExcludes in settings to skip other teams' CLAUDE.md files that aren't relevant to your work.
🚫 Anti-Patterns & Exam Traps
| ❌ Anti-Pattern (WRONG answer) | ✅ Correct Approach | Why it's wrong |
|---|---|---|
| Bloated CLAUDE.md with everything (500+ lines) | Keep concise (<200 lines); use skills/rules for domain knowledge | Long files reduce adherence and waste context tokens |
| Relying on CLAUDE.md to enforce security rules | Use PreToolUse hooks for deterministic enforcement | CLAUDE.md is advisory context, not enforced config |
| Putting frequently-changing info in CLAUDE.md | Link to external docs; keep CLAUDE.md stable | CLAUDE.md should contain stable, durable rules |
| Using emphasis (IMPORTANT/MUST) in a bloated file | Keep the file short so rules aren't lost in noise | Emphasis doesn't fix information overload |
| Thinking CLAUDE.md files override each other | They concatenate — all are loaded into context | No "override" — if rules conflict, Claude picks arbitrarily |
| Putting personal preferences in project CLAUDE.md | Use CLAUDE.local.md(gitignored) for personal rules | Personal prefs don't belong in team-shared config |
💻 Code Example: Monorepo CLAUDE.md Design
Root CLAUDE.md (shared across all teams):
# Project: MyCompany Platform
## Build & Test
- CI runs on every PR: `make ci`
- Run targeted tests, not the full suite: `pytest tests/unit/test_specific.py`
## Git Conventions
- Branch naming: `feature/JIRA-123-description` or `fix/JIRA-456-description`
- Commits: conventional commits format (feat:, fix:, chore:)
- Squash merge to main
## Code Style
- Python: black + isort + ruff (configured in pyproject.toml)
- TypeScript: prettier + eslint (configured in .eslintrc)
- All code must pass `make lint` before committing
## Architecture
- Monorepo with packages: frontend/, backend/, shared/
- Shared types live in shared/types/
- API contracts defined in shared/api-schemas/
See @docs/architecture.md for system design overview.
backend/CLAUDE.md (Python-specific):
# Backend (Python/FastAPI)
## Testing
- Run: `pytest backend/tests/ -x --tb=short`
- Coverage: `pytest --cov=backend/src --cov-report=term`
- Always mock external API calls in tests
## Conventions
- Use Pydantic v2 models for all request/response schemas
- Database access through repository pattern (backend/src/repos/)
- Never import from frontend/
## Common Gotchas
- Alembic migrations must be reversible (include downgrade)
- Redis keys must use namespace prefix: `myapp:{entity}:{id}`
CLAUDE.local.md (personal, gitignored):
# Joe's personal preferences
- My local dev server: http://localhost:8080
- Test with: pytest -x -v (I like verbose output)
- I prefer type annotations on all function signatures
.claude/rules/security.md (path-scoped rule):
---
paths:
- "backend/src/api/**"
- "backend/src/auth/**"
---
# Security Rules
- Never log sensitive data (passwords, tokens, PII)
- All endpoints must validate input with Pydantic
- Auth endpoints must rate-limit (use @backend/src/middleware/rate_limit.py)
- Never hardcode secrets — use environment variables
🎬 Video to Watch
Claude Code in an Hour: A Developer's Intro — Official Anthropic webinar that walks through how Claude Code works under the hood with a live demo. Covers CLAUDE.md setup, configuration patterns, and real development workflows. Focus on the first 20 minutes where they explain the configuration layer.
Also recommended: Claude Code 101 (Anthropic's free Skilljar course) — covers installation through advanced customization including CLAUDE.md hierarchy.
📖 Reading
- Primary: How Claude remembers your project — Official Anthropic docs on CLAUDE.md (the source of truth for this topic)
- Secondary: Best Practices for Claude Code — Anthropic engineering blog covering effective CLAUDE.md patterns
- Reference: Explore the .claude Directory — How rules, skills, and commands work together
🛠️ Hands-On Exercise (20 min)
Design a CLAUDE.md hierarchy for a monorepo:
- Create a folder structure:
myapp/frontend/(React/TS),myapp/backend/(Python/FastAPI),myapp/shared/(shared types) - Write a root
CLAUDE.md(~30 lines) with: git conventions, global lint/test commands, architecture overview - Write
frontend/CLAUDE.md(~20 lines): React patterns, component testing commands, forbidden patterns - Write
backend/CLAUDE.md(~20 lines): Python conventions, pytest commands, database rules - Write a
CLAUDE.local.mdwith your personal dev preferences - Create one path-scoped rule in
.claude/rules/api-security.mdthat only applies tobackend/src/api/** - Bonus: Run
/initon an existing project and compare what Claude generates vs what you'd write
📝 Quick Quiz
Q1: A team wants to enforce that Claude Code never modifies .env files in their project. What is the BEST approach?
A) Add "Never modify .env files" to the project CLAUDE.md B) Configure a PreToolUse hook that denies write operations to .env files C) Add the rule to ~/.claude/CLAUDE.md so it applies everywhere D) Use CLAUDE.local.md with a strong instruction using IMPORTANT emphasis
Q2: In a monorepo, you run Claude Code from /repo/packages/api/. Which CLAUDE.md files are loaded at session start?
A) Only /repo/packages/api/CLAUDE.md
B) Only /repo/CLAUDE.md and /repo/packages/api/CLAUDE.md
C) All CLAUDE.md and CLAUDE.local.md files from root down to CWD, plus user and managed policy files
D) All CLAUDE.md files in the entire repository recursively
Q3: A developer's CLAUDE.md has grown to 450 lines and Claude is inconsistently following the instructions. What should they do?
A) Add "IMPORTANT:" prefix to critical rules
B) Move domain-specific content to .claude/rules/ with path scoping, and reduce CLAUDE.md to <200 lines
C) Split into multiple CLAUDE.md files in the same directory
D) Convert to CLAUDE.local.md which has higher priority
Answers:
Q1: B — CLAUDE.md is advisory context that Claude may not follow deterministically. For critical security enforcement, you MUST use a PreToolUse hook which provides deterministic, programmatic blocking. This is one of the exam's most-tested concepts.
Q2: C — Claude Code walks UP from CWD, collecting all CLAUDE.md and CLAUDE.local.md files along the way, plus user-level (~/.claude/CLAUDE.md) and managed policy files. They're concatenated (not overridden). Subdirectory files below CWD are loaded on-demand only.
Q3: B — The recommended size is <200 lines per file. Path-scoped rules in .claude/rules/ only load when relevant files are accessed, reducing noise and saving context. Emphasis words don't compensate for information overload.
👀 Tomorrow's Preview
Tomorrow is Day 11: Custom Commands, Skills & Plan Mode — you'll learn the three mechanisms for extending Claude Code's capabilities (slash commands, skills, and plan mode), when to use each, and the 4-phase plan mode workflow that the exam loves to test.