context-hierarchy-design

# 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

```text
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:

1. Measure CLAUDE.md size
2. Count imports and their sizes
3. Review command coverage
4. Identify task types

```text
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:

```markdown
# 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 p