Claude Code Context Guide

claude-code-context-guide.md

Claude Code Context Management Guide

Context Loading Overview

SESSION START (always in context)
├── CLAUDE.md                    → Full content loaded
├── .claude/rules/*.md           → Full content loaded
├── Skill metadata               → Names + descriptions only
└── Subagent metadata            → Names + descriptions only

ON-DEMAND (loaded when needed)
├── Skill content                → When invoked (/skill-name)
├── Subagent content             → Into isolated context when spawned
└── docs/*                       → When explicitly referenced

Note: Claude Code loads CLAUDE.md by default, not AGENTS.md. In this project, CLAUDE.md contains @AGENTS.md to maintain compatibility with other AI tools (GitHub Copilot, Cursor) that use AGENTS.md as their convention.

Component Comparison

Component	When Loaded	Context Impact	Best For
CLAUDE.md	Session start	Always in context	Project basics, commands
Rules	Session start	Always in context	Tiny conventions (~10 lines)
Skills	Metadata at start, content on-invoke	On-demand	Workflows, detailed guides
Subagents	Metadata at start, runs isolated	Zero on main	Heavy tasks, research
docs/	Never auto-loaded	On-demand	Extensive reference material

Rules (.claude/rules/)

Behavior: All rules load at session start. The paths: frontmatter controls when to apply, not when to load.

---
paths:
  - "**/*.liquid"
---
# Applied only when working on .liquid files
# But ALWAYS in context

Best practice: Keep rules tiny (<10 lines). No @ references.

Skills (.claude/skills/)

Structure:

.claude/skills/
└── skill-name/
    └── SKILL.md

Loading:

• Metadata (name, description) → Always in context
• Content (after ---) → Loaded only when invoked

Invocation:

• User: /skill-name
• Auto: Claude matches task to description

Best practice: Put @docs/... references in content, not metadata.

---
name: liquid-section
description: Create a new Shopify section
---
# Content below loads only when invoked

Reference: @docs/resources/liquid-patterns.md

[Instructions here...]

Subagents (.claude/agents/)

Structure:

.claude/agents/
└── agent-name.md

Key feature: Isolated context

Main Context
│
├── Spawn subagent
│   └── [ISOLATED CONTEXT]
│       ├── Reads files
│       ├── Does work
│       └── Returns SUMMARY only
│
└── Main context stays clean

What stays isolated:

• File reads, searches, verbose output
• Intermediate reasoning
• Error handling details

What returns to main:

• Final summary
• Key results

Best practice: Use for heavy research or multi-file operations.

The @path Syntax

Location	Behavior
In CLAUDE.md	Read at session start → in context
In rules	Read at session start → in context
In skill content	Read when skill invoked → on-demand
In subagent	Read into isolated context → cleanest

Recommendation: Use @ references in skill/subagent content only.

Optimal Structure for Clean Context

Always loaded (keep small):
├── AGENTS.md                    # ~40 lines
└── .claude/rules/
    └── liquid.md                # ~10 lines

On-demand (via skills):
└── .claude/skills/
    └── section-builder/
        └── SKILL.md             # References @docs/...

Isolated (via subagents):
└── .claude/agents/
    └── researcher.md            # Heavy work, summary returns

Reference material:
└── docs/
    └── resources/
        └── liquid-patterns.md   # Detailed guides

Context Cost Visualization

Every Request:
├── CLAUDE.md + rules        ████████████  ~300-500 tokens
├── Skill descriptions       ███░░░░░░░░░  ~50-100 tokens
└── Subagent metadata        █░░░░░░░░░░░  ~20-50 tokens

On-Demand:
├── Skill content            ████████      ~100-1000+ tokens
└── Subagent work            [ISOLATED]    no main context cost

Quick Reference

I want to...	Use
Always enforce a convention	Rule (keep tiny)
Load detailed docs on-demand	Skill with @ refs
Do heavy research/implementation	Subagent
Store reference material	docs/ folder
Keep context clean	Subagents for heavy work