# Context File Hierarchy How CLAUDE.md and [[AGENTS.md (File Convention)|AGENTS.md]] files at different directory levels compose to form the full project context. Files at the root define project-wide rules; files in subfolders specialize for that area; the AI tool merges them top-down. ## How it works In a typical project: ``` repo/ CLAUDE.md ← project-wide rules, architecture, team conventions AGENTS.md ← project-wide agent definitions src/ CLAUDE.md ← frontend-specific conventions components/ CLAUDE.md ← component library rules api/ CLAUDE.md ← backend-specific conventions, API design rules ``` When working on a file in `src/components/`, the AI loads context from all three levels: root → src → components. Each level adds specificity without repeating what the parent already covers. ## Inheritance and override logic - **Additive by default**: each level adds new rules and context on top of the parent - **Override by specificity**: a subfolder CLAUDE.md can override a root rule for that area (e.g., "in this folder, use tabs not spaces") - **No explicit merge syntax**: the AI interprets the combined context; there's no formal merge/override declaration yet - **Implicit priority**: more specific (deeper) files take precedence when rules conflict This mirrors [[Context Inheritance]] at the file system level: enterprise → team → project becomes root → subfolder → leaf. ## What goes where | Level | Content | |-------|---------| | **Root** | Project name, tech stack, architecture overview, team conventions, coding standards, CI/CD rules | | **Subfolder** | Area-specific patterns, framework conventions, module boundaries, local design decisions | | **Leaf** | Highly specific rules for a particular module or component | ## Design principles - **Don't repeat**: if the root says "use TypeScript", subfolders don't need to restate it - **Specialize, don't contradict**: subfolders should add detail, not fight the root - **Keep it lean**: each file should be as short as possible. [[Context Budget]] applies; every line costs tokens - **Progressive disclosure**: root gives the overview, subfolders give detail only when needed ([[Prompt Lazy Loading AI Design Pattern (PLL)]]) ## Connection to [[Claude Code Memory]] CLAUDE.md files are project-scoped context. [[Claude Code Memory]] (in `~/.claude/`) is user-scoped context that applies across all projects. Together they form the full context hierarchy: user → project root → subfolder → leaf. ## References - ## Related - [[AGENTS.md (File Convention)]] - [[Claude Code Memory]] - [[Context-as-Code]] - [[Context Inheritance]] - [[Context Layering]] - [[Context Budget]] - [[AI Skill Scoping]] - [[Prompt Lazy Loading AI Design Pattern (PLL)]] - [[Project Context Management (PCM)|Project Context Management]] - [[Claude Code]]