Context File Hierarchy
Structured organization of context files like CLAUDE.md and AGENTS.md at different directory levels that compose into layered AI instructions through top-down merging.
Category: AI
Tags: ai, context-engineering, context-management, ai-context-patterns, software-development
Explanation
The context file hierarchy describes how CLAUDE.md and 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, the root CLAUDE.md defines project-wide rules, architecture, and team conventions. Subfolder CLAUDE.md files add area-specific conventions (e.g., frontend patterns in `src/`, API design rules in `api/`). When working on a file in a deep directory, the AI loads context from all levels: root to subfolder to leaf. 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 is 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 to team to project becomes root to subfolder to leaf.
## Design Principles
- **Do not repeat**: if the root says "use TypeScript", subfolders do not need to restate it
- **Specialize, do not contradict**: subfolders should add detail, not fight the root
- **Keep it lean**: each file should be as short as possible; context budget applies since every line costs tokens
- **Progressive disclosure**: root gives the overview, subfolders give detail only when needed
## Connection to User Context
CLAUDE.md files are project-scoped context. User-level configuration (e.g., `~/.claude/`) is user-scoped context that applies across all projects. Together they form the full context hierarchy: user to project root to subfolder to leaf.
Related Concepts
← Back to all concepts