Skip to main content

Shopify 개발을 위한 CLAUDE.md 템플릿

CLAUDE.md 파일은 효과적인 Claude Code 사용의 기반입니다. 모든 세션 시작 시 Claude Code가 읽는 지속적인 컨텍스트를 제공하여, 매 프롬프트마다 프로젝트 세부정보를 반복할 필요를 없앱니다. 이 가이드는 Shopify 개발 프로젝트를 위한 완전하고 실전 검증된 템플릿을 제공합니다.

CLAUDE.md가 중요한 이유​

CLAUDE.md 파일이 없으면 모든 Claude Code 세션은 제로에서 시작합니다. Claude Code는 프로젝트 구조를 발견하고, 어떤 Shopify API 버전을 사용하는지 파악하고, 코딩 규칙을 배우고, 앱 아키텍처를 이해해야 합니다 -- 모두 파일을 읽고 질문하면서.

잘 작성된 CLAUDE.md가 있으면 Claude Code는 모든 세션에서 다음을 아는 완전히 브리핑된 팀 멤버로 시작합니다:

  • 정확한 Shopify 설정 (API 버전, 스코프, 앱 유형)
  • 코딩 표준과 아키텍처 결정
  • 프로젝트를 실행, 테스트, 배포하는 방법
  • 피해야 할 실수
5분 투자

좋은 CLAUDE.md를 작성하는 데 약 5분이 걸립니다. 매 세션에서 컨텍스트를 반복하는 것을 방지하여, 일주일의 개발 동안 쉽게 몇 시간의 프롬프트 엔지니어링을 절약합니다. Claude Code 워크플로우에서 할 수 있는 가장 높은 레버리지 작업입니다.

완전한 템플릿​

이 템플릿을 복사하고, 대괄호 섹션을 프로젝트에 맞게 커스터마이징하고, 프로젝트 루트에 CLAUDE.md로 저장하세요.

CLAUDE.md
# [Project Name]

## Overview
[이 프로젝트가 무엇을 하는지, 누구를 위한 것인지, 현재 상태를 설명하는 한 문단.]

Example: Remix-based Shopify app that enables merchants to create and manage
product bundles with automatic discount application. Currently in production
serving 200+ stores.

## Tech Stack
- **Framework**: Remix (Shopify app template)
- **Language**: TypeScript (strict mode)
- **Database**: Prisma ORM with PostgreSQL
- **UI**: Shopify Polaris v13 React components
- **Auth**: Shopify managed installation (app proxy + session tokens)
- **Testing**: Vitest (unit), Playwright (e2e)
- **Package Manager**: npm
- **Node Version**: 20 LTS

## Shopify Configuration
- **API Version**: 2025-01 (DO NOT use unstable or older versions)
- **App Type**: Embedded app (App Bridge 4)
- **Access Mode**: Online + Offline access tokens
- **Required Scopes**: read_products, write_products, read_orders, write_orders,
  read_inventory, write_inventory, read_customers
- **Webhooks**: ORDERS_CREATE, PRODUCTS_UPDATE, APP_UNINSTALLED
- **Extensions**: Theme app extension (product-bundle-block), Checkout UI extension

## Project Structure

app/ routes/ # Remix routes (app..tsx = authenticated app pages) graphql/ # GraphQL query and mutation strings queries/ # Read operations mutations/ # Write operations models/ # Prisma model helpers (.server.ts) components/ # Shared React components (Polaris-based) utils/ # Utility functions webhooks/ # Webhook handlers jobs/ # Background job processors extensions/ product-bundle/ # Theme app extension checkout-upsell/ # Checkout UI extension prisma/ schema.prisma # Database schema migrations/ # Migration files tests/ unit/ # Vitest unit tests e2e/ # Playwright e2e tests fixtures/ # Test data and mocks


## Commands
```bash
# Development
npm run dev              # Start Remix dev server
shopify app dev          # Start with Shopify CLI (ngrok tunnel + auth)
npm run dev:extensions   # Develop extensions locally

# Database
npx prisma db push       # Apply schema changes (development)
npx prisma migrate dev   # Create and apply migration
npx prisma studio        # Open database GUI

# Testing
npm test                 # Run all Vitest tests
npm test -- --watch      # Watch mode
npm run test:e2e         # Run Playwright tests
npm run test:coverage    # Generate coverage report

# Build & Deploy
npm run build            # Production build
shopify app deploy       # Deploy to Shopify
npm run lint             # ESLint check
npm run typecheck        # TypeScript type checking

Coding Standards​

TypeScript​

  • Strict mode enabled, no any types (use unknown and narrow)
  • Prefer interface over type for object shapes
  • All functions must have explicit return types
  • Use barrel exports (index.ts) for directories

React / Polaris​

  • Use Polaris components exclusively for UI -- no custom CSS for standard patterns (buttons, forms, cards, modals, data tables)
  • Follow Polaris design patterns: Page > Layout > Card hierarchy
  • Use useAppBridge() for App Bridge interactions
  • Toast for success messages, Banner for persistent info/errors
  • Loading states: use Polaris SkeletonPage/SkeletonBodyText

GraphQL​

  • All queries go in app/graphql/queries/ as exported template literals
  • All mutations go in app/graphql/mutations/
  • Always include userErrors { field message } in mutations
  • Use cursor-based pagination (never offset-based)
  • Prefix query names with operation: GetProducts, CreateBundle
  • Always specify the exact fields needed (no over-fetching)

Remix Patterns​

  • Loaders return json() responses with typed data
  • Actions handle form submissions with proper validation
  • Use authenticate.admin(request) at the start of every loader/action
  • Redirect to /auth/login on authentication failures
  • Use defer() for non-critical data that can stream

Database​

  • All database operations in *.server.ts files (never in components)
  • Use Prisma transactions for multi-table operations
  • Always include shopDomain in queries (multi-tenant isolation)
  • Soft delete with deletedAt timestamp (never hard delete)

Webhooks​

  • Verify HMAC on all webhook endpoints
  • Respond within 1 second (offload heavy work to background jobs)
  • Implement idempotency using webhook ID tracking
  • Log webhook receipt with shop domain, topic, and webhook ID

Error Handling​

  • Never swallow errors silently -- always log with context
  • Use Remix CatchBoundary/ErrorBoundary for route-level errors
  • GraphQL errors: check userErrors array first, then network errors
  • External API calls: retry with exponential backoff (max 3 attempts)

Shopify-Specific Rules​

API Usage​

  • ALWAYS use API version 2025-01
  • Use the authenticated admin client from authenticate.admin(request)
  • Never hardcode shop domains or access tokens
  • Rate limiting: track GraphQL cost points, throttle at 80% capacity
  • Use bulk operations for large data sets (1000+ items)

Polaris Guidelines​

  • Follow the Shopify App Design Guidelines for UX patterns
  • Use the AppProvider at the app root with i18n configuration
  • Navigation via Polaris NavMenu component
  • Forms use Polaris FormLayout with inline validation
  • Tables use IndexTable with bulk actions

App Bridge 4​

  • Do NOT use createApp() (that's App Bridge 3)
  • Session tokens are available via the Remix authenticate helper
  • Navigation: use standard links, App Bridge handles framing
  • Resource pickers: use the app bridge resource picker API
  • Title bar: set via Remix route meta or ui.title-bar component

Theme Extensions​

  • App blocks must be self-contained (own CSS/JS, no global pollution)
  • Use CSS custom properties for theme-aware colors
  • Liquid: always null-check objects before accessing properties
  • Schema settings must have sensible defaults
  • Test with multiple themes (Dawn, Refresh, and one vintage theme)

Testing Requirements​

  • All new features must have unit tests
  • Critical paths (checkout, payments, inventory) need e2e tests
  • Minimum 80% code coverage on models and utils
  • Mock the Shopify admin client in tests (never call real API)
  • Test webhooks with sample payloads from tests/fixtures/webhooks/
  • Run npm test before committing (pre-commit hook enforces this)

Deployment Checklist​

  1. All tests pass (npm test && npm run test:e2e)
  2. TypeScript compiles without errors (npm run typecheck)
  3. Lint passes (npm run lint)
  4. Database migrations are committed
  5. Environment variables are set in production
  6. Webhook URLs are registered for production domain
  7. Extensions are deployed (shopify app deploy)
  8. App review checklist completed (if submitting to app store)

Environment Variables​

  • SHOPIFY_API_KEY - App API key (from Partner Dashboard)
  • SHOPIFY_API_SECRET - App secret key
  • DATABASE_URL - PostgreSQL connection string
  • REDIS_URL - Redis connection for background jobs
  • SENTRY_DSN - Error tracking (optional)

DO NOT commit .env files. Use .env.example as a template.

Known Issues​

  • [활성 버그, 해결 방법 또는 기술 부채 항목을 나열하세요]
  • Bulk operations occasionally timeout for shops with 50k+ products; current workaround is to chunk into batches of 10k
  • The checkout extension doesn't render in Safari < 16 due to a known Shopify bug (tracked in their issue tracker)

Architecture Decisions​

  • We use offline access tokens for background jobs and online tokens for interactive sessions
  • Bundle pricing is calculated server-side and applied via Shopify Functions (not manual discount codes) for checkout integrity
  • Customer data is NOT stored locally; always fetch fresh from Shopify to maintain compliance with data protection requirements

## 템플릿 변형

### 테마 전용 프로젝트

Shopify 테마(앱이 아닌)를 작업하는 경우, 이 간소화된 버전을 사용하세요:

```markdown title="테마 프로젝트용 CLAUDE.md"
# [Theme Name]

## Overview
Custom Shopify theme based on Dawn 13.0 for [store name].
Online Store 2.0 compatible with full section-everywhere support.

## Tech Stack
- **Base Theme**: Dawn 13.0
- **Liquid**: Shopify Liquid (OS 2.0)
- **CSS**: Vanilla CSS with custom properties (no preprocessor)
- **JavaScript**: Vanilla ES6+ (no jQuery, no build step)
- **Icons**: Inline SVG from a central snippet

## Structure

assets/ # CSS, JS, and static files config/ # settings_schema.json and settings_data.json layout/ # theme.liquid and password.liquid locales/ # Translation files sections/ # All sections (reusable across templates) snippets/ # Reusable Liquid snippets templates/ # JSON templates (OS 2.0) customers/ # Account page templates


## Commands
```bash
shopify theme dev --store=mystore    # Local development
shopify theme push                    # Push to theme
shopify theme pull                    # Pull remote changes
shopify theme check                   # Run Theme Check linter

Coding Standards​

  • Sections must have complete schemas with sensible defaults
  • Always null-check Liquid objects: {% if product.metafields.custom.x %}
  • Use loading="lazy" on all images below the fold
  • CSS: mobile-first, use custom properties for colors/spacing
  • JavaScript: no global scope pollution, use IIFE or modules
  • Accessibility: all interactive elements must be keyboard navigable
  • Performance: no render-blocking JS, minimize Liquid loops

Shopify-Specific Rules​

  • Use {{ image | image_url: width: 800 }} (not img_url filter)
  • Preload critical images with fetchpriority="high"
  • Use {% render 'snippet' %} (not include)
  • Section schema: always include "class" for wrapper styling
  • Test with Theme Check: shopify theme check --fail-level error

Known Issues​

  • [테마별 버그 또는 브라우저 호환성 참고 사항을 나열하세요]

### Hydrogen / 헤드리스 프로젝트

```markdown title="Hydrogen 프로젝트용 CLAUDE.md"
# [Project Name] - Hydrogen Storefront

## Overview
Headless Shopify storefront built with Hydrogen 2024.10 and Remix.

## Tech Stack
- **Framework**: Hydrogen (Remix-based)
- **Language**: TypeScript
- **Styling**: Tailwind CSS
- **API**: Shopify Storefront API (2025-01)
- **Hosting**: Oxygen (Shopify's edge hosting)
- **Cache**: Hydrogen's built-in caching strategies

## Shopify Configuration
- **API Version**: 2025-01 (Storefront API)
- **Storefront Access Token**: In environment variables
- **Customer Account API**: Enabled for account features

## Key Patterns
- Use Hydrogen's `<Await>` for deferred data loading
- Cache strategies: CacheLong for collections, CacheShort for cart
- SEO: Use Hydrogen's `getSeoMeta()` helper for all routes
- Analytics: Use Hydrogen's built-in Shopify analytics
- Use `<Money>` and `<Image>` components from @shopify/hydrogen

Claude Code가 CLAUDE.md를 사용하는 방법​

Claude Code가 CLAUDE.md를 처리하는 방식을 이해하면 더 좋은 것을 작성할 수 있습니다:

  1. 세션 시작 시 읽기: Claude Code는 첫 프롬프트 전에 CLAUDE.md를 읽습니다
  2. 항상 컨텍스트에 유지: 내용은 전체 세션 동안 컨텍스트 윈도우에 유지됩니다
  3. 계층적 병합: 전역(~/.claude/CLAUDE.md) + 프로젝트 루트 + 하위 디렉토리 파일이 병합됩니다
  4. 토큰 비용: CLAUDE.md는 컨텍스트 토큰을 소비하므로 간결하게 작성하세요. 500단어 CLAUDE.md는 약 700토큰 -- 컨텍스트 윈도우의 작은 부분입니다
간결하게 유지하세요

너무 긴 CLAUDE.md는 모든 상호작용에서 컨텍스트 토큰을 낭비합니다. 300-800단어를 목표로 하세요. 자세한 문서는 별도의 문서에 넣으세요 -- CLAUDE.md는 빠른 참조여야 하지 소설이 아닙니다. 모든 단어가 자리를 차지할 가치가 있어야 합니다.

모범 사례 체크리스트​

CLAUDE.md를 작성하거나 검토할 때 이 체크리스트를 사용하세요:

  • API 버전이 지정됨 (가장 중요한 단일 라인)
  • 기술 스택이 나열됨 (프레임워크, 언어, 데이터베이스, UI)
  • 모든 개발 명령이 문서화됨 (dev, test, build, deploy)
  • 파일 구조가 설명됨 (주요 디렉토리와 목적)
  • 코딩 표준이 명시적 (모호한 "깨끗한 코드를 작성하세요"가 아님)
  • Shopify 전용 규칙이 명시됨 (스코프, 앱 유형, Extension)
  • 테스팅 기대치가 명확함 (무엇을 테스트할지, 어떻게 실행할지)
  • 알려진 이슈가 문서화됨 (Claude Code가 같은 벽에 부딪히는 것을 방지)
  • 환경 변수가 나열됨 (실제 값 없이)
  • 민감한 데이터 없음 (API 키, 토큰, 비밀번호 없음)
CLAUDE.md에 절대 비밀을 넣지 마세요

CLAUDE.md는 버전 관리에 커밋되는 일반 파일입니다. API 키, 액세스 토큰, 데이터베이스 비밀번호 또는 민감한 자격 증명을 절대 포함하지 마세요. 변수 이름(예: SHOPIFY_API_KEY)은 나열하되 값은 포함하지 마세요.

CLAUDE.md 발전시키기​

CLAUDE.md는 프로젝트와 함께 발전해야 합니다. 다음과 같은 경우에 업데이트하세요:

  • Shopify API 버전을 업그레이드할 때
  • 새로운 Extension이나 Webhook을 추가할 때
  • 아키텍처 패턴을 변경할 때
  • 시간을 낭비하는 새로운 "함정"을 발견할 때
  • 개발 명령을 추가하거나 변경할 때
  • 팀 코딩 표준이 발전할 때

오래된 CLAUDE.md는 CLAUDE.md가 없는 것보다 나쁩니다. 왜냐하면 Claude Code에 자신 있게 잘못된 컨텍스트를 제공하기 때문입니다. 현재 상태를 유지하고, 간결하게 유지하고, 프로젝트의 실제 상태에 대해 정직하게 유지하세요.

다음 단계​

CLAUDE.md가 준비되었으니, MCP 기초로 진행하여 Model Context Protocol이 Shopify 개발을 위한 Claude Code의 기능을 어떻게 더 확장할 수 있는지 알아보세요.