| name | context-hierarchy-design |
| description | Design memory hierarchy with progressive loading for optimal context management. Use when organizing CLAUDE.md imports, implementing just-in-time context loading, or designing priming hierarchies for agents. |
| allowed-tools | Read, Grep, Glob |
Context Hierarchy Design Skill
Design a memory hierarchy that loads context progressively based on task needs.
Purpose
Not all context is needed all the time. A well-designed hierarchy ensures agents get exactly the context they need without bloat.
When to Use
- Setting up a new project's context infrastructure
- Refactoring bloated CLAUDE.md files
- Creating task-specific context loading
- Optimizing agent startup time
- Scaling context for multiple task types
The Three-Tier Memory Strategy
Tier 1: CLAUDE.md (minimal, always loaded)
|
v
Tier 2: Priming Commands (task-specific, on-demand)
|
v
Tier 3: File Reads (just-in-time, as needed)
Design Process
Step 1: Audit Current State
Analyze existing context infrastructure:
- Measure CLAUDE.md size
- Count imports and their sizes
- Review command coverage
- Identify task types
Checklist:
- [ ] CLAUDE.md token count
- [ ] Import count and total
- [ ] Task types identified
- [ ] Command coverage mapped
Step 2: Categorize Context
For each piece of existing context, ask:
| Question | If Yes -> |
|---|
| Needed for EVERY task? | Tier 1 (CLAUDE.md) |
| Needed for task TYPE? | Tier 2 (Priming) |
| Needed for specific work? | Tier 3 (On-demand) |
Step 3: Design Tier 1 (CLAUDE.md)
Minimal essentials only:
# Project Name
## Context
One-sentence project description.
## Tooling
- Language: X
- Runtime: Y
- Package Manager: Z
## Key Commands
- `cmd test` - Run tests
- `cmd build` - Build project
## Critical Rules
1. Most important rule
2. Second most important
3. Third most important (max 5)
Target size: less than 2KB.
Step 4: Design Tier 2 (Priming Commands)
Create commands for each task type:
| Task Type | Command | Context Loaded |
|---|
| General | /prime | README, git status |
| Bug Fix | /prime-bug | Recent commits, test files |
| Feature | /prime-feature | Architecture, API patterns |
| Review | /prime-review | Style guide, PR diff |
| Docs | /prime-docs | Existing docs, API surface |
Priming Command Template:
# Prime: [Task Type]
## Run
[Discovery commands for current state]
## Read
[Essential files for this task type]
## Report
[Summary prompt for understanding]
Step 5: Design Tier 3 (On-Demand)
Identify files loaded during work:
| Category | Loading Strategy |
|---|
| Source files | Read specific file when editing |
| Test files | Read when running tests |
| Configs | Read when configuring |
| Dependencies | Read when debugging deps |
Principle: Never pre-load what can be loaded on-demand.
Output Format
Design document structure:
# Context Hierarchy Design: [Project]
## Tier 1: CLAUDE.md (Always Loaded)
**Target Size:** <2KB
**Content:**
- Project context (1 sentence)
- Tooling (language, runtime, PM)
- Key commands (3-5)
- Critical rules (3-5)
## Tier 2: Priming Commands (Task-Specific)
### /prime
**Purpose:** General codebase understanding
**Loads:** README, git status, project structure
### /prime-bug
**Purpose:** Bug fixing context
**Loads:** Recent commits, test patterns, error logs
### /prime-feature
**Purpose:** Feature development context
**Loads:** Architecture, API patterns, similar features
## Tier 3: On-Demand (Just-in-Time)
**Strategy:** Load during execution, not pre-emptively
- Source files: Read when editing
- Tests: Read when testing
- Configs: Read when configuring
## Migration Plan
1. [ ] Backup current CLAUDE.md
2. [ ] Create minimal CLAUDE.md
3. [ ] Create priming commands
4. [ ] Test with common task types
5. [ ] Iterate based on usage
Design Patterns
Pattern: Import Hierarchy
CLAUDE.md (always)
-> imports/core.md (always, if large)
-> imports/tooling.md (conditional)
-> imports/workflows.md (conditional)
Pattern: Directory-Scoped Memory
/project
CLAUDE.md (project-wide)
/frontend
CLAUDE.md (frontend-specific)
/backend
CLAUDE.md (backend-specific)
Pattern: Task-Type Priming
/prime -> Base context
/prime-{type} -> Type-specific context
Validation Criteria
After design, verify:
Anti-Patterns to Avoid
| Anti-Pattern | Problem | Solution |
|---|
| Everything in CLAUDE.md | Bloat | Move to priming |
| No priming commands | Static context | Add task-type priming |
| Import everything | Wasted tokens | Conditional imports |
| Directory CLAUDE.md bloat | Compounding | Keep scoped minimal |
Key Quote
"Use context priming over CLAUDE.md or similar auto-loading memory files. Engineering work constantly changes, but memory files only grow."
Cross-References
- @context-priming-patterns.md - Priming command patterns
- @rd-framework.md - Reduce unnecessary context
- @context-layers.md - What loads into context
- @minimum-context-principle.md - Include only what's necessary
Version History
- v1.0.0 (2025-12-26): Initial release
Last Updated
Date: 2025-12-26
Model: claude-opus-4-5-20251101
