Context Architecture

Every Claude Code session draws context from multiple sources that layer on top of each other. Understanding how they relate is critical.

CLAUDE.md — The Only File Auto-Loaded

Claude Code auto-loads only CLAUDE.md from the project root at session start. This is Claude Code’s built-in mechanism for persistent project context. AGENTS.md is not auto-loaded — despite the name suggesting otherwise.

Our recommended approach is to create AGENTS.md using Shopify’s official Liquid rules from theme-liquid-docs/ai/liquid.mdc as a starting point, then symlink CLAUDE.md to it:

ln -s AGENTS.md CLAUDE.md

This ensures Claude Code loads your rules (via the CLAUDE.md symlink) while keeping AGENTS.md as the editable source of truth.

The Agent-First Context Model

Context comes from four layers. The platform agent is the key differentiator — it carries all platform-specific conventions that commands reference at runtime.

Layer	Source	Question It Answers	Maintained By
1	CLAUDE.md	”What is this project? What are the base coding rules?”	Engineers (local)
2	Platform agent	”How do I build for this stack? What are the component patterns, file structure, validation rules?”	Engineering Leadership (MCP server)
3	Dev MCP conventions	”What universal rules apply to all projects? How do I use the MCP toolchain?”	Engineering Leadership (MCP server)
4	CONVENTIONS.md	”What exists in this project right now? What are the token values, component APIs, icons?”	Claude Code + Engineers (local)

What lives where

Knowledge type	Where it lives	Why
Liquid snippet/block/section rules	`theme-developer` agent	Platform-specific — only relevant for Liquid themes
React/Remix component rules	`hydrogen-developer` agent	Platform-specific — only relevant for Hydrogen
GraphQL organization, Sanity patterns	`hydrogen-developer` agent	Platform-specific
”No hardcoded values”, “extract icons from Figma”	Dev MCP conventions	Universal — applies to all platforms
MCP toolchain (Figma, Playwright, Context7)	Dev MCP conventions	Universal — same tools for all projects
Project token values, component inventory	CONVENTIONS.md	Project-specific — varies per project

How the architecture works end-to-end

Session starts
  │
  ▼
CLAUDE.md auto-loaded → project type, tech stack, base rules
  │
  ▼
Platform agent activated → component patterns, build rules, validation
  │
  ▼
get_conventions loaded → universal rules, MCP toolchain, communication style
  │
  ▼
CONVENTIONS.md read → tokens, component library, icons, logos
  │
  ▼
Engineer runs a command (e.g. "build")
  │  → Command references "the active agent" for platform details
  │
  ▼
Composition plan output
  │  → Uses the agent's component taxonomy and plan fields
  │
  ▼
Build phase (composing from existing primitives, bottom-up)
  │  → Follows the agent's build order and creation rules
  │
  ▼
CONVENTIONS.md updated (if new components were created)
  │
  ▼
Playwright visual QA against design reference