File Responsibilities

CLAUDE.md — Project Rules for Claude Code

The only file Claude Code auto-loads at session start. Contains project-specific instructions and base coding rules.

A typical CLAUDE.md includes:

Project type — “This is a Shopify Hydrogen storefront” or “This is a Shopify Liquid theme”
Design source — “Designs are in Figma. Use the Figma MCP to read design context.”
Tech stack — the framework, styling system, and key dependencies
File conventions — where components go, naming patterns
Development server — local preview URL
Responsive breakpoints

Update when: dev server URL changes, tech stack changes, project-specific workflow instructions change.

Platform Agent — How to Build

Activated at session start via activate_agent. Carries all platform-specific conventions (~300-500 lines):

Component taxonomy, build order, and creation rules with code examples
Token system, CSS/JS patterns, translation rules
File mapping, fix cascade order
Validation command and per-type checklists
Performance patterns and anti-patterns
Figma MCP configuration values

The platform agent is the primary source of truth for how to write code on this stack. Commands reference “the active agent” for all platform-specific details.

Update cycle: Managed centrally on the Dev MCP server. Changes propagate to all engineers on next session — no local file updates needed.

See How Agents Work for details on each agent.

Dev MCP Conventions — Universal Rules

Loaded via get_conventions from the Dev MCP server. Contains rules that apply to all projects regardless of platform:

Mandatory rules — no em dashes, no hardcoded values, no hand-drawn icons, feature branches
Build philosophy — design-system-first, bottom-up composition
Design tokens — naming conventions (--color-*, --space-*, --text-*)
MCP toolchain — Figma Desktop, Playwright CLI, Context7, Serena usage
Communication style — explain decisions, flag deviations, show plans

Update cycle: Managed on the Dev MCP server. Content changes are live immediately after pnpm run upload-content.

CONVENTIONS.md — Project-Specific State

A living index that reflects the current state of the project. Sections include:

Design tokens — colours, spacing, typography, radius, shadows, transitions, breakpoints
Component library — quick-reference table of all components and their APIs
Icons — organised by category
Logos — all brand assets
Platform-specific sections — GraphQL fragments (Hydrogen), Sanity schemas (Hydrogen), route structure, etc.

Update when:

A new component is created
Component parameters or visual specs change
Design tokens are added or modified
New icons or logos are exported from Figma
Figma design system rules are regenerated (via Phase 8 of design-system)