CLAUDE.md Architecture

Introduction

CLAUDE.md is not a single file — it is a hierarchy of files that combine to form the complete context Claude receives before it reads your first message. Understanding the load order and override semantics is the difference between context that compounds cleanly and context that contradicts itself.

Knox's stack has a four-level hierarchy that illustrates the pattern:

1. Enterprise / User level — two distinct outer layers that both load globally: managed enterprise policy (an org-deployed CLAUDE.md, outermost) and your personal user memory (~/.claude/CLAUDE.md), which applies in every session on your machine. Knox's stack uses the user-memory layer.
2. Project level (<repo>/CLAUDE.md) — rules specific to one repository
3. Sub-directory level (<dir>/CLAUDE.md) — rules that apply only to files in that directory and below
4. Session/Inline level — instructions given in the conversation, overriding everything for this turn only

The Four Levels in Detail

Level 1: Enterprise / User Level

This layer is really two: a managed enterprise policy file (deployed centrally by an org, outermost and not overridable by the user) and the user-memory file ~/.claude/CLAUDE.md on Knox's laptop and production server. Knox's stack uses the user-memory file; it loads in every session, regardless of which project Claude is working in.

Knox's global CLAUDE.md contains the non-negotiables:

• NEVER commit directly to main — always feature branch → PR via gh pr create
• Run git branch --show-current before any Write, Edit, commit, or push
• Run tests before every PR
• Post-PR retro is mandatory — retro → lessons.md → memory_remember → THEN notify
• 90% coverage floor (for all repos with CI)

These rules are timeless. They have never been project-specific. They earn their global slot.

Level 2: Project Level

The academy project's CLAUDE.md (at the repo root) contains academy-specific rules that override or extend the global defaults:

• Bi-modal design — every component works in both dark and light mode
• Use CSS vars — never hard-code dark hex values
• Supabase is the only auth stack — no custom JWT
• Vitest + Playwright — specific test stack requirements
• Adding a lesson — exact four-step process

When a Claude Code session is opened in the academy directory, both the global and project CLAUDEs load. If a global rule says "body text >= 16px" and the project rule says "code annotations at 14px," the project rule wins for code annotations specifically.

Level 3: Sub-directory Level

A CLAUDE.md inside a subdirectory applies only to files within that directory tree. This is the most targeted level of the hierarchy.

In Knox's stack, components/CLAUDE.md could specify:

• Never hard-code hex values in TSX files — use CSS vars only
• All new components are RSC-safe by default — no client hooks unless explicitly required
• Read design-system/MASTER.md before creating any new component

These rules do not apply to lib/, app/, or content/ — only to components/ and its subdirectories.

Level 4: Session / Inline

Instructions given in the conversation itself — "for this task only, output as JSON" — override the full hierarchy for their scope. This is the most powerful override but also the most ephemeral: it exists only for the current conversation.

The Load Order and Override Semantics

The five-step load sequence runs before Claude processes your first message:

1. Enterprise CLAUDE.md loads — global rules enter context
2. Project CLAUDE.md merges — project rules append, conflicts override global
3. Sub-directory CLAUDE.md merges (if present) — dir rules append, conflicts override project
4. @import references are resolved — referenced sub-docs are pulled in eagerly as part of this load (task-conditional loading happens later, via agent-initiated reads)
5. User's turn begins — inline instructions override for this turn only

This load order is deterministic — the layers are concatenated outermost-to-innermost every time. The override itself, though, is a convention the model follows, not an enforced engine: all the layers sit in the same prompt as text, and "innermost wins" holds reliably when the inner rule is explicit and scoped. Write the override as an explicit statement ("this overrides the global 16px rule for code annotations") and the model honors it consistently; leave two rules silently contradicting each other and the model has to guess (the failure mode the Context Rot lesson covers). To know which rule should win, trace the stack — the innermost, most specific rule — and make that precedence explicit in the text.

Practical Hierarchy Design

The most common mistake is treating CLAUDE.md as a monolith — one enormous file that tries to cover every scenario. The hierarchy system is designed to let you decompose this:

Global CLAUDE.md (~120 lines):

• Non-negotiable rules that apply everywhere
• Security constraints (never tokens in URLs, never dangerouslySetInnerHTML without sanitization)
• Git workflow (never commit to main, always test first)
• Communication style (peer-level, no hedging, push back when needed)

Project CLAUDE.md (~80 lines per repo):

• Tech stack choices (Supabase not custom JWT, Vitest not Jest)
• Quality gates (coverage floor, specific CI requirements)
• Domain-specific constraints (Phemex USDT-margined only, or bi-modal design requirement)
• Key files reference table

Sub-directory CLAUDE.md (optional, ~40 lines):

• File-type-specific rules (RSC-safe in components/, no mutations in lib/)
• Tool-specific constraints (only read, no writes in scripts/)
• Import patterns (all cross-cutting concerns go through barrel exports)

What Does NOT Belong in CLAUDE.md

The hierarchy is a budget (the previous lesson). Every line costs tokens on every turn. Rules that do not belong:

• Reference documentation — API specs, design tokens, component catalogs belong as @imported sub-docs
• Examples and templates — store in docs/ or templates/, reference with @import
• Historical context — "we decided X because Y" belongs in lessons.md or Semantic Memory Layer
• Procedural workflows — multi-step processes belong in skill files (~/.claude/skills/)
• Tier 2/3 content — anything not needed on every single turn

The 200-line discipline is the engineering constraint that keeps CLAUDE.md from becoming a dumping ground. When a file grows past 200 lines, it almost certainly contains Tier 2 or Tier 3 content that should be moved to an @import or Semantic Memory Layer.

Summary

• Four levels: enterprise → project → sub-directory → session; inner overrides outer on conflict
• The load order is deterministic and additive — all levels load, innermost wins on conflict
• Global CLAUDE.md: timeless non-negotiables; Project CLAUDE.md: repo-specific tech choices; Sub-dir: file-type rules
• The 200-line discipline enforces the hierarchy — over-long files contain Tier 2/3 content that belongs elsewhere
• @imports resolve sub-documents at load time — a clean alternative to inlining long reference docs

What's Next

The next lesson breaks down the content inside a single CLAUDE.md — the three-tier importance model that determines what belongs in the first 80 lines versus what belongs in @imports or Semantic Memory Layer.