Shopify 개발을 위한 프롬프트 엔지니어링

답답한 Claude Code 세션과 생산적인 세션의 차이는 프롬프트를 어떻게 작성하느냐에 따라 결정되는 경우가 많습니다. 이 가이드는 Shopify 개발에 특화된 실전 검증된 프롬프트 템플릿과 기법을 제공합니다.

효과적인 Shopify 프롬프트의 원칙

템플릿에 들어가기 전에, 프롬프트를 효과적으로 만드는 네 가지 원칙을 이해하세요:

1. Shopify 컨텍스트를 구체적으로 명시하기: API 버전, 앱 유형(Remix, 커스텀), 테마 버전(OS 2.0), 관련 Shopify 개념을 언급하기
2. 제약 조건 포함하기: 무엇을 해야 하는지뿐만 아니라 무엇을 하지 말아야 하는지도 명시하기 -- "Polaris를 사용하고, 커스텀 UI 컴포넌트는 사용하지 마세요"
3. 예상 출력의 예시 제공하기: 형식이 중요할 때 원하는 것의 스니펫을 보여주기
4. "왜"를 설명하기: Claude Code는 비즈니스 로직을 이해할 때 더 나은 결정을 내립니다

CLAUDE.md의 장점

CLAUDE.md 파일에 프로젝트 컨텍스트가 이미 포함되어 있으면 이러한 프롬프트의 많은 부분이 더 짧아집니다. CLAUDE.md에 "API version: 2025-01"과 "UI: Polaris"가 지정되어 있다면, 모든 프롬프트에서 이를 반복할 필요가 없습니다. 아래 템플릿은 독립적으로 사용할 수 있도록 전체 컨텍스트를 포함하고 있습니다 -- CLAUDE.md가 이미 다루고 있는 내용에 따라 줄여서 사용하세요.

즉시 사용 가능한 프롬프트 템플릿

App Extensions

1. Theme App Extension 구축하기

Prompt: Theme App Extension

Build a Shopify theme app extension that displays product reviews
as a star rating and review list on product pages.

Requirements:
- App block with schema settings for: reviews per page (default 5),
  show star rating (boolean), color scheme selector
- Liquid template that renders review data from metafields
- CSS that matches common Shopify theme styles
- JavaScript for "Load More" pagination
- Accessible: screen reader support for star ratings

Put the extension in extensions/product-reviews/.
Use the theme app extension file structure.

2. Checkout UI Extension 구축하기

Prompt: Checkout Extension

Build a Shopify checkout UI extension (checkout_ui) that shows
a free shipping progress bar.

Requirements:
- React component using @shopify/ui-extensions-react/checkout
- Show current cart total vs free shipping threshold ($75)
- Progress bar with percentage filled
- Dynamic messaging: "$X away from free shipping!" or "You qualify!"
- Use the Banner and ProgressBar checkout components
- Extension target: purchase.checkout.block.render
- Include shopify.extension.toml configuration

3. Admin Action Extension 구축하기

Prompt: Admin Action Extension

Build a Shopify admin action extension that lets merchants bulk-tag
products based on inventory level.

Requirements:
- Admin action that appears on the Products index page
- React UI with Polaris components (Modal, TextField, Select)
- Options: tag name input, threshold selector (< 10, < 50, < 100)
- GraphQL mutation to add tags to matching products
- Loading states and success/error feedback
- Handle pagination for stores with 1000+ products

GraphQL 쿼리와 Mutation

4. 페이지네이션 쿼리 작성하기

Prompt: Paginated GraphQL Query

Write a GraphQL query to fetch all orders from the last 30 days
with their line items, fulfillment status, and customer email.

Requirements:
- Cursor-based pagination with first: 50
- Filter by created_at >= 30 days ago using query parameter
- Include financial_status and fulfillment_status
- Include line items with product title, variant title, quantity, price
- Include customer email and order name
- Write the TypeScript types for the response shape
- API version 2025-01

5. 복잡한 Mutation 작성하기

Prompt: GraphQL Mutation

Write a GraphQL mutation to create a product with variants and
set metafields in a single API call.

Requirements:
- ProductCreate mutation with product title, description, vendor
- Include 3 variants with prices and inventory quantities
- Set a custom metafield (namespace: "custom", key: "material", type: "single_line_text_field")
- Include media (image URLs) attachment
- Handle userErrors in the response
- Write the TypeScript variables type
- Wrap it in a reusable async function that takes the admin client

6. Bulk Operation 쿼리 작성하기

Prompt: Bulk Operation

Write a Shopify bulk operation query to export all products with
their variant inventory levels across all locations.

Requirements:
- Use bulkOperationRunQuery mutation
- Include the JSONL polling logic to check completion
- Parse the JSONL response into structured data
- Handle the bulk operation lifecycle: CREATED -> RUNNING -> COMPLETED
- Include error handling for FAILED status
- Write this as a complete utility module I can import

Liquid와 테마 개발

7. Liquid Section 생성하기

Prompt: Liquid Section

Create a Liquid section called "collection-filter-grid" that displays
a filterable product grid.

Requirements:
- Collection picker in schema settings
- Filter by product type, vendor, and price range
- CSS Grid layout: 4 columns desktop, 2 tablet, 1 mobile
- Lazy-loaded product images with aspect ratio preservation
- Quick-add-to-cart button on hover
- Section schema with settings for: columns per row,
  show vendor, show price, enable quick add
- Use section blocks for promotional cards between products
- No external JavaScript dependencies

8. Mega Menu Snippet 생성하기

Prompt: Mega Menu

Create a Liquid snippet for a mega menu navigation that supports:

Requirements:
- 3 levels of navigation from linklists
- Desktop: full-width dropdown with columns
- Mobile: accordion-style expand/collapse
- Featured image area per top-level menu item (using metafields)
- Keyboard navigation (arrow keys, escape to close)
- ARIA roles and labels for accessibility
- Smooth CSS transitions (no jQuery)
- works with the "header" section's schema to configure menu handle

9. 동적 장바구니 드로어 구축하기

Prompt: Cart Drawer

Create a cart drawer (slide-out panel) using Liquid, CSS, and
vanilla JavaScript.

Requirements:
- Opens from right side on add-to-cart
- Real-time updates via Cart AJAX API (/cart.js, /cart/add.js)
- Line item quantity adjustment with +/- buttons
- Line item removal with undo option (3 second window)
- Free shipping progress bar
- Cart note textarea
- Upsell product recommendation (last item in a specific collection)
- Accessible: focus trap when open, escape to close
- CSS animations for open/close (transform, not left/right)

Shopify Functions

10. Rust로 할인 Function 생성하기

Prompt: Discount Function (Rust)

Generate a Shopify Function in Rust that implements a "Buy X Get Y"
discount.

Requirements:
- Function API: product_discounts
- Input: cart lines, discount configuration from metafields
- Logic: if cart contains product X (by tag), apply percentage
  discount to product Y (by tag)
- Handle edge cases: multiple qualifying items, quantity limits
- Include the shopify.extension.toml configuration
- Include run.graphql input query
- Write the Cargo.toml with correct Shopify Function dependencies
- Include unit tests for the discount logic

11. Delivery Customization Function 생성하기

Prompt: Delivery Function

Generate a Shopify Function for delivery customization that hides
express shipping for orders containing oversized items.

Requirements:
- Function API: delivery_customization
- Check line items for a "oversized" tag
- If any oversized item exists, rename and reorder delivery options
  to remove/hide express options
- Include input query, Rust implementation, and tests
- Handle the case where all items are oversized vs mixed carts

Webhook 핸들러

12. Webhook 핸들러 디버깅하기

Prompt: Debug Webhook

Debug this webhook handler for orders/create that's returning 500
errors intermittently:

[paste your webhook handler code here]

The error logs show: "Cannot read property 'id' of undefined"
on line 47. This happens on roughly 20% of webhook deliveries.

Check for:
- Payload structure differences between API versions
- Missing null checks on nested objects
- Race conditions with database writes
- Whether the 5-second timeout could be causing issues

13. 재시도 로직이 포함된 Webhook 핸들러 생성하기

Prompt: Webhook with Retries

Create a webhook handler for PRODUCTS_UPDATE that syncs product
data to an external inventory system.

Requirements:
- HMAC verification using Shopify webhook secret
- Idempotency: track processed webhook IDs to skip duplicates
- Respond to Shopify within 1 second (use background job for heavy work)
- Retry external API calls with exponential backoff (3 attempts)
- Dead letter queue for permanently failed syncs
- Structured logging with webhook ID, product ID, and timing
- Use the Remix webhook handling pattern

테스트

14. 포괄적인 테스트 스위트 생성하기

Prompt: Test Suite

Write a complete Vitest test suite for the product bundle
creation flow.

Files to test:
- app/routes/app.bundles.new.tsx (form submission)
- app/models/bundle.server.ts (database operations)
- app/graphql/mutations/bundleCreate.ts (GraphQL mutation)

Cover:
- Happy path: create bundle with 3 products
- Validation: empty title, too few products, duplicate products
- Auth: redirect when session expires
- Error: GraphQL errors, database constraint violations
- Edge: Unicode titles, maximum products (20), zero-price variants

Mock the Shopify admin GraphQL client and Prisma.

15. Playwright E2E 테스트 생성하기

Prompt: E2E Tests

Write Playwright end-to-end tests for our Shopify theme's
product page.

Test scenarios:
- Product page loads with correct title and price
- Variant selector changes price and image
- Add to cart with quantity > 1
- Cart drawer opens after add to cart
- Inventory limit prevents over-ordering
- Product with no variants shows simplified UI
- Mobile: variant selector works on touch devices
- Accessibility: page passes axe-core audit

Use Page Object pattern. Base URL: http://localhost:9292

코드 생성과 리팩토링

16. Polaris CRUD 인터페이스 생성하기

Prompt: Polaris CRUD

Create a complete CRUD interface for managing shipping zones using
Shopify Polaris components.

Requirements:
- Index page with ResourceList showing all zones
- Filters: active/inactive, country
- Create/Edit form with: zone name, countries (multi-select),
  rate conditions (price-based and weight-based)
- Delete confirmation modal
- Toast notifications for success/error
- Loading skeletons during data fetches
- Empty state with illustration
- Use Remix loader/action pattern for data flow

17. App Bridge 4로 리팩토링하기

Prompt: App Bridge Migration

Refactor our embedded app from App Bridge 3 to App Bridge 4.

Current code uses:
- createApp() initialization
- getSessionToken() for auth
- Redirect.create() for navigation
- ResourcePicker.create() for product selection

Migrate to App Bridge 4 patterns:
- Direct token access from shopify.idToken()
- URL-based navigation via app bridge
- New resource picker API
- Update all import paths
- Remove the app bridge provider wrapper if using Remix template

18. API 속도 제한 미들웨어 생성하기

Prompt: Rate Limiting

Create rate limiting middleware for our Shopify app's API calls.

Requirements:
- Track Shopify's GraphQL cost points (2000 point bucket)
- Parse X-Shopify-Shop-Api-Call-Limit headers for REST
- Implement leaky bucket algorithm for request throttling
- Queue system for bulk operations
- Per-shop rate tracking (multi-tenant)
- Logging when approaching limits (> 80% consumed)
- Automatic retry with backoff when rate limited
- TypeScript, works with our Remix app structure

19. Shopify App OAuth 플로우 생성하기

Prompt: Custom OAuth

Implement a complete Shopify OAuth flow for a custom (non-Remix
template) Node.js app.

Requirements:
- Install endpoint: generate auth URL with required scopes
- Callback endpoint: exchange code for access token
- HMAC validation on the callback
- Store tokens securely (encrypted at rest in PostgreSQL)
- Handle token refresh for online access mode
- Verify installed shops on subsequent requests
- Handle app uninstall webhook to clean up data
- Include CSRF protection with state parameter

20. 다중 위치 재고 동기화 생성하기

Prompt: Inventory Sync

Build an inventory synchronization system that keeps Shopify
inventory in sync with an external warehouse API.

Requirements:
- Scheduled job (runs every 15 minutes)
- Fetch inventory levels from external API (REST, paginated)
- Compare with Shopify inventory via GraphQL bulk query
- Calculate deltas and apply adjustments
- Use inventoryAdjustQuantities mutation (not deprecated individual)
- Handle multiple locations (map external warehouse IDs to Shopify location IDs)
- Conflict resolution: external system is source of truth
- Detailed sync log with item-level results
- Alert on sync failures via webhook to Slack

보너스 프롬프트

21. Metafield 정의 생성하기

Prompt: Metafield Setup

Create a migration script that sets up all required metafield
definitions for our product customization app.

Metafields needed:
- products: custom.material (single_line_text_field)
- products: custom.care_instructions (multi_line_text_field)
- products: custom.size_chart (json, with validation)
- variants: custom.weight_grams (number_integer)
- orders: custom.gift_message (single_line_text_field)

Use the metafieldDefinitionCreate mutation. Make it idempotent
(skip if definition already exists). Include validation rules.

22. Hydrogen으로 커스텀 스토어프론트 구축하기

Prompt: Hydrogen Component

Create a Hydrogen (Remix + Storefront API) product page component
that includes:

- Product image gallery with zoom
- Variant selector with option swatches
- Price display with compare-at-price
- Dynamic add-to-cart with cart optimization
- SEO meta tags and structured data (JSON-LD)
- Streaming with Suspense boundaries for deferred data
- Use Hydrogen's built-in components where available

반복 프롬프트 기법

단일 프롬프트도 강력하지만, 반복 프롬프트야말로 복잡한 Shopify 프로젝트에서 Claude Code가 진정한 위력을 발휘하는 부분입니다.

구축-테스트-개선 루프

Step 1: Build

> Create a webhook handler for ORDERS_CREATE that calculates
  loyalty points and stores them in customer metafields.

# Claude Code writes the initial implementation

> Step 2: Test
> Write tests for this handler covering the edge cases we discussed.

# Claude Code writes tests, some may fail

> Step 3: Refine
> The test for zero-dollar orders is failing. The handler should
  award 0 points but still update the metafield. Fix the handler.

# Claude Code fixes the specific issue

점진적 향상

간단하게 시작하고 점진적으로 복잡성을 추가합니다:

Progressive prompting

> Create a basic product recommendation section that shows
  4 related products from the same collection.

# Get the basics working first

> Now enhance it: add a "You might also like" heading, lazy-load
  the images, and add quick-add-to-cart buttons.

# Layer on features

> Now make it personalized: use the customer's order history
  (via Storefront API) to weight recommendations. Fall back to
  collection-based if no history exists.

# Add sophisticated logic

반복이 일괄보다 나은 이유

모든 기능을 한 번에 요청하는 거대한 프롬프트는 문제가 발생했을 때 디버깅하기 어려운 코드를 생성하는 경향이 있습니다. 반복적으로 구축하면 다음 레이어를 추가하기 전에 각 레이어가 정상적으로 작동하는 것을 확인할 수 있습니다. 또한 Claude Code의 응답을 집중적이고 관리하기 쉽게 유지합니다.

다중 파일 프로젝트 프롬프트

작업이 여러 파일에 걸쳐 있을 때는 범위를 명시적으로 설명하세요:

Multi-file prompt

> This change needs to touch multiple files:
  1. Add a new GraphQL query in app/graphql/queries/loyaltyPoints.ts
  2. Create a new route at app/routes/app.loyalty.tsx
  3. Add a Prisma model for LoyaltyTransaction in prisma/schema.prisma
  4. Create a background job in app/jobs/calculatePoints.server.ts
  5. Add the webhook handler in app/webhooks/orders-create.ts
  6. Write tests for the calculation logic

  Start with the Prisma model, then the GraphQL query, then build
  up from there. Run prisma db push after creating the model.

세션 관리 명령어

/compact -- 컨텍스트 회수하기

한동안 작업하여 컨텍스트가 커졌을 때 /compact를 사용합니다:

> /compact
# Summarizes the conversation, freeing up context space
# Your CLAUDE.md context is preserved
# Continue working on the same task with full project awareness

사용 시점: 기능을 완성한 후, 같은 세션에서 다음 기능을 시작하기 전.

/clear -- 새로 시작하기

완전히 다른 작업으로 전환할 때 /clear를 사용합니다:

> /clear
# Wipes all conversation context
# CLAUDE.md is re-read on next prompt
# Perfect for switching from theme work to app work

사용 시점: 관련 없는 작업 간에 전환할 때 (예: 테마 개발에서 앱 백엔드 작업으로).

/cost -- 비용 모니터링하기

> /cost
# Shows tokens consumed and estimated cost
# Use this periodically during long sessions

사용 시점: 활발한 개발 중 30-60분마다, 또는 대규모 작업을 시작하기 전.

컨텍스트 윈도우 제한

Claude Code의 응답이 일관성을 잃기 시작하거나 이전 결정을 "잊어버리는" 경우, 컨텍스트 윈도우가 가득 찼을 가능성이 있습니다. 즉시 /compact를 사용하세요. 그래도 해결되지 않으면 /clear를 사용하고 집중된 프롬프트와 좋은 CLAUDE.md 컨텍스트로 다시 시작하세요.

피해야 할 안티패턴

안티패턴	실패하는 이유	더 나은 접근법
"전체 앱을 만들어줘"	너무 모호하고 너무 큼	기능 단위의 프롬프트로 분할
"더 좋게 만들어줘"	구체적인 방향이 없음	"페이지네이션을 추가하여 성능을 개선해줘"
"버그를 고쳐줘" (컨텍스트 없음)	Claude Code에 오류 상세 정보가 필요함	오류 메시지와 관련 코드를 붙여넣기
매 프롬프트마다 컨텍스트 반복	토큰 낭비	안정적인 컨텍스트는 CLAUDE.md에 넣기
/compact를 사용하지 않음	컨텍스트 오버플로우	기능 완성할 때마다 압축하기

다음 단계

이러한 프롬프트 템플릿을 갖추었으니, CLAUDE.md 템플릿으로 이동하여 Shopify 개발에 최적화된 완전한 복사-붙여넣기 가능한 프로젝트 설정 파일을 확인하세요.