Claude Information
Hierarchy

Three Core Dimensions

Every piece of information you give Claude Code can be evaluated on three axes:

1
Recall Likelihood Claude will load this information into context at all. Claude can't apply information it doesn't recall.
2
Attention Likelihood Claude will skillfully apply the information once it's loaded. If Claude ignores information, it might as well not recall it.
3
Context Load How much token budget this information consumes. Higher context load means higher cost, worse attention, slower speed.

No single tier of the hierarchy wins on all three dimensions. That's why you need the hierarchy rather than putting everything in one place.

The Hierarchy

Root CLAUDE.md Always in context
Recall
Highest
Always loaded
Attention
Degrades
Worsens with context size
Context Load
High
Always consuming tokens
Sub-dir CLAUDE.md Loaded on file access in that directory
Recall
High
Loaded on file access
Attention
Higher
Less noise than root
Context Load
Medium
Only when relevant
Skills Loaded only when invoked
Recall
Lower
But user can manually invoke
Attention
Highest
Fresh, focused context
Context Load
Lowest
On-demand only

Loading Triggers

Mechanism When It's Loaded Who Triggers It
Root CLAUDE.md Always Automatic
Sub-dir CLAUDE.md Claude reads a file in that directory or below Claude's file access
Skill (claude-invoked) Claude decides the skill is valuable based on its description Claude's judgment
Skill (user-invoked) User runs a command User

Progressive Disclosure (Skills)

Skills can contain reference documents that are conditionally loaded into context, adding further efficiency within the most efficient tier:

Layer 1 Skill Description cheap
Always visible to Claude for routing decisions
↓
Layer 2 Skill Content moderate
Loaded when skill is invoked
↓
Layer 3 Referenced Documents expensive
Loaded only if Claude decides the reference is valuable

Practical Decision Flow

When adding new information, ask:

Does Claude need this on MOST interactions?
YES
Root CLAUDE.md
NO
Does Claude need this to work with MOST files in this directory?
YES
Sub-dir CLAUDE.md
NO
Skill

CLAUDE.md Maintenance

CLAUDE.md grows too large
Audit: For each item, ask "always needed?"
NO, directory
Sub-dir CLAUDE.md
NO, workflow
Skill
YES
Keep in root

Sub-dir CLAUDE.md files are loaded less often, so are lower priority to optimize.

Skill Maintenance

Skill grows too large
Audit: For each item, ask "always needed when this skill is invoked?"
NO
Referenced document
YES
Keep in skill

Key Tradeoff Summary

Recall Attention Context Load Design Effort
Root CLAUDE.md Highest — always in context Degrades with context size High — always loaded Low
Sub-dir CLAUDE.md High — loaded on file access Higher — less noise Medium Low
Skills Lower — but user can manually invoke Highest — fresh, focused Lowest — on-demand Highest