Claude Code를 활용한 Shopify 개발 워크플로우
이 섹션에서는 Claude Code를 Shopify 개발에 필수적으로 만드는 실전 워크플로우를 다룹니다. 각 워크플로우는 반복적으로 사용하게 될 패턴입니다 -- 새 앱 스캐폴딩부터 새벽 2시에 프로덕션 Webhook 장애를 디버깅하는 것까지.
자연어로 앱 스캐폴딩
기존의 Shopify 앱 시작 방법은 문서를 탐색하고, 템플릿을 선택하고, 보일러플레이트를 수동으로 설정하는 것이었습니다. Claude Code를 사용하면 원하는 것을 일반 영어(또는 한국어)로 설명하면 됩니다.
새 Remix 앱 시작하기
> Create a new Shopify Remix app for managing product bundles.
It should have:
- A page listing all products with bundle tagging
- A bundle creation form using Polaris
- GraphQL queries for product listing and metafield management
- A webhook handler for orders containing bundles
- Prisma schema for storing bundle configurations
Claude Code는 완전한 파일 구조를 생성하고, 각 파일을 작성하고, Prisma 스키마를 설정하고, GraphQL 쿼리 파일을 만들고, 모든 것을 연결합니다. Shopify Remix 앱 템플릿 규칙을 알고 이를 따릅니다.
최상의 결과를 위해 먼저 Shopify CLI로 기본 앱을 스캐폴딩한 다음 Claude Code를 사용하여 그 위에 기능을 구축하세요:
shopify app init --template remix
cd my-app
claude
이렇게 하면 Claude Code에 인증, 세션 처리, App Bridge가 이미 설정된 적절한 기반을 제공합니다.
앱 Extension 스캐폴딩
앱 Extension(테마 Extension, 결제 UI Extension, 관리자 UI Extension)에는 특정 파일 구조 요구사항이 있습니다. Claude Code는 이를 기본적으로 처리합니다:
> Create a checkout UI extension that displays a loyalty points
summary. It should show the customer's current points balance
and how many points they'll earn from this purchase. Use the
Checkout UI extensions API with React.
Claude Code는 shopify.extension.toml 설정, 결제 UI 컴포넌트(Banner, Text, BlockStack)를 사용하는 React 컴포넌트, 필요한 유틸리티 함수를 생성합니다.
GraphQL 쿼리 생성
Shopify의 Admin API는 GraphQL 우선이며, 올바른 쿼리 작성은 가장 일반적인 작업 중 하나입니다. Claude Code는 Shopify GraphQL 스키마를 깊이 이해하기 때문에 여기서 뛰어납니다.
상품 쿼리
> Write a GraphQL query to fetch products with their variants,
prices, inventory levels, and metafields. Include cursor-based
pagination. Use the 2025-01 API version.
Claude Code가 생성하는 결과:
export const PRODUCTS_QUERY = `#graphql
query GetProducts($first: Int!, $after: String) {
products(first: $first, after: $after) {
edges {
cursor
node {
id
title
status
totalInventory
variants(first: 10) {
edges {
node {
id
title
price
inventoryQuantity
selectedOptions {
name
value
}
}
}
}
metafields(first: 5) {
edges {
node {
namespace
key
value
type
}
}
}
}
}
pageInfo {
hasNextPage
endCursor
}
}
}
`;
뮤테이션 생성
> Write a GraphQL mutation to update product metafields in bulk,
including the TypeScript types for the variables and response.
userErrors누락: Claude Code는 항상 뮤테이션 응답에userErrors { field, message }를 포함합니다- 잘못된 ID 형식: 올바른
gid://shopify/Product/123형식을 사용합니다 - 페이지네이션 누락: 무한 목록을 조회하는 대신 커서 기반 페이지네이션을 기본으로 사용합니다
- API 버전 불일치: CLAUDE.md에서 API 버전을 지정하면 해당 버전의 스키마를 따릅니다
Claude Code를 사용한 테마 개발
테마 개발은 Liquid 템플릿, JSON 스키마, CSS, JavaScript가 모두 함께 작동하는 것을 포함합니다. Claude Code는 이 다중 언어 환경을 원활하게 탐색할 수 있습니다.
커스텀 섹션 만들기
> Create a Liquid section called "featured-collection-tabs" that
displays products from multiple collections in a tabbed interface.
Include the section schema with settings for:
- Up to 5 collection pickers
- Tab style (underline, pill, boxed)
- Products per tab (4, 8, 12)
- Mobile layout option (scroll, stack)
Make it accessible and performant.
Claude Code는 적절한 {% schema %} 블록이 있는 Liquid 템플릿, 반응형 디자인의 CSS, 탭 기능을 위한 바닐라 JavaScript, ARIA 속성이 있는 시맨틱 HTML로 완전한 섹션을 생성합니다.
테마 블록 및 앱 블록
> Create a theme app extension block that displays real-time
inventory status on product pages. It should show "In Stock",
"Low Stock" (under 5), or "Out of Stock" badges with appropriate
colors. Include the block schema and Liquid template.
JSON 템플릿 작업
Shopify Online Store 2.0은 JSON 템플릿을 사용합니다. Claude Code는 이 구조를 이해합니다:
> Add our new featured-collection-tabs section to the homepage
template. Place it between the hero banner and the newsletter
signup sections.
Claude Code는 templates/index.json을 읽고, 섹션 순서를 이해하고, 참조를 올바르게 삽입합니다.
코드 리뷰 및 리팩토링
Claude Code는 Shopify 코드의 정확성, 성능, 모범 사례 준수 여부를 검토하는 데 뛰어납니다.
Liquid 코드 검토
> Review sections/product-main.liquid for:
- Performance issues (N+1 queries, unnecessary Liquid loops)
- Accessibility problems
- Missing null checks on objects
- SEO metadata gaps
- Mobile responsiveness issues
레거시 테마 리팩토링
많은 Shopify 스토어가 Online Store 2.0 이전의 오래된 테마를 실행하고 있습니다. Claude Code는 이를 현대화할 수 있습니다:
> Refactor this product template from a sectioned theme (1.0) to
Online Store 2.0 format. Convert hardcoded content to section
settings and blocks. Preserve all existing functionality.
앱 코드 리뷰
> Review the webhook handlers in app/webhooks/ for:
- HMAC verification on all endpoints
- Proper error handling and retry logic
- Idempotency (handling duplicate webhook deliveries)
- Response time (must respond within 5 seconds)
- Logging for debugging
코드를 검토할 때 Claude Code는 Shopify의 실제 요구사항을 기준으로 확인합니다 -- 5초 Webhook 응답 기한, 필수 HMAC 검증, 레이트 리밋 임계값 등. 구문만 확인하는 것이 아니라 Shopify 전용 정확성을 확인합니다.
테스트 작성
Shopify 앱 테스트에는 Shopify의 API 응답, 세션 처리, Webhook 페이로드를 모킹하는 것이 필요합니다. Claude Code는 포괄적인 테스트 스위트를 생성합니다.
GraphQL 핸들러의 단위 테스트
> Write Vitest tests for the products loader in app/routes/app.products.tsx.
Mock the GraphQL admin client and test:
- Successful product listing with pagination
- Empty product list handling
- GraphQL error responses
- Unauthenticated session redirect
Webhook 핸들러 테스트
> Write tests for the ORDER_CREATED webhook handler. Include:
- Valid HMAC verification test
- Invalid HMAC rejection test
- Duplicate webhook idempotency test
- Malformed payload handling
- Database error recovery
End-to-End 테마 테스트
> Write Playwright tests for the product page that verify:
- Variant selector updates price display
- Add to cart works and updates cart count
- Quantity selector respects inventory limits
- Image gallery navigation works
- Mobile responsive layout at 375px width
프로덕션 이슈 디버깅
프로덕션에서 문제가 발생하면 Claude Code가 디버깅 파트너가 됩니다. 오류 로그를 제공하면 문제를 추적합니다.
Webhook 실패
> Here are the last 5 failed webhook deliveries from Shopify:
[paste webhook delivery details from Partner Dashboard]
Diagnose why these are failing and fix the issue.
Claude Code는 오류 패턴을 분석하고, Webhook 핸들러 코드를 확인하고, 근본 원인(타임아웃, HMAC 불일치, 처리되지 않은 페이로드 구조)을 식별하고, 수정 사항을 구현합니다.
GraphQL 레이트 리밋
> Our app is hitting Shopify's GraphQL rate limit during bulk
product syncs. The current code fetches products in a loop
without throttling. Fix this to respect the 2000-point bucket
with leak rate, and add proper cost tracking.
테마 렌더링 이슈
> Customers report that product metafields show as blank on
some products but work on others. Here's the Liquid code:
{{ product.metafields.custom.care_instructions.value }}
Debug why this would be intermittent.
Shopify 프로젝트용 CLAUDE.md 템플릿 만들기
위의 워크플로우를 기반으로 Shopify 프로젝트의 CLAUDE.md에 권장하는 구조입니다. 자세한 템플릿은 CLAUDE.md 템플릿 섹션에서 다루지만, 여기 상위 수준 구조가 있습니다:
# Project Name
## Overview
간략한 프로젝트 설명 및 목적.
## Tech Stack
프레임워크, 언어, 데이터베이스, UI 라이브러리.
## Shopify Configuration
API 버전, 앱 유형, 스코프, Extension.
## Commands
개발 서버, 빌드, 테스트, 배포 명령.
## File Structure
주요 디렉토리 및 목적.
## Coding Standards
언어별 규칙 및 Shopify 규칙.
## Testing Requirements
테스트 프레임워크, 커버리지 기대치, 무엇을 테스트할지.
## Common Patterns
프로젝트에 특화된 반복 패턴.
## Known Issues
Claude가 알아야 할 활성 버그 또는 해결 방법.
항상 CLAUDE.md에 Shopify API 버전을 포함하세요. 이것이 없으면 Claude Code가 다른 버전으로 기본 설정하여 폐기되었거나 존재하지 않는 필드를 참조하는 코드를 생성할 수 있습니다. API Version: 2025-01이라는 한 줄이 몇 시간의 디버깅을 방지합니다.
워크플로우 치트시트
| 작업 | 프롬프트 패턴 |
|---|---|
| 새 섹션 | "Create a Liquid section called X that..." |
| GraphQL 쿼리 | "Write a GraphQL query to fetch X with Y..." |
| Webhook 핸들러 | "Create a webhook handler for X that..." |
| 버그 수정 | "This error occurs when... [오류 붙여넣기]. Fix it." |
| 테스트 스위트 | "Write tests for X covering Y, Z scenarios" |
| 리팩토링 | "Refactor X to follow [pattern/standard]" |
| 코드 리뷰 | "Review X for [specific concerns]" |
| 마이그레이션 | "Migrate X from [old] to [new]" |
이러한 패턴이 작동하는 이유는 Claude Code가 코드베이스에 대한 전체 접근 권한을 가지고 있기 때문입니다. 관련 파일을 읽고, 컨텍스트를 이해하고, 프로젝트의 나머지 부분과 일관된 변경을 수행합니다.
다음 단계
핵심 워크플로우를 이해했으니, 프롬프트 엔지니어링으로 진행하여 Claude Code를 사용한 Shopify 개발을 강화하는 바로 사용 가능한 프롬프트 템플릿을 알아보세요.