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

Most important rule
Second most important
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

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:

CLAUDE.md under 2KB
Every task type has priming command
No "just in case" loading
Progressive disclosure works
Common workflows smooth

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

context-hierarchy-design

Safety Notice

Copy this and send it to your AI assistant to learn