Skip to main content

5분 만에 Shopify를 위한 Claude Code 시작하기

· One min read
Shopify Dev MasterClass Team
Shopify Dev MasterClass Team
Core Contributors

Claude Code에 대해 들어봤지만 Shopify 개발 워크플로에 어떻게 맞는지 확실하지 않다면, 이 가이드를 통해 정확히 5분 만에 시작할 수 있습니다. 마지막에는 Claude Code가 설치되고, Shopify 작업을 위해 구성되며, 첫 번째 AI 지원 스토어 작업을 실행하게 됩니다.

사전 요건​

시작하기 전에 다음을 준비하세요:

  • 머신에 설치된 Node.js 18+
  • Shopify 파트너 계정 (partners.shopify.com에서 무료 생성)
  • 샘플 제품이 있는 개발 스토어
  • 적절한 스코프가 있는 Shopify Admin API 액세스 토큰

1단계: Claude Code 설치​

Claude Code를 머신에 설치하는 것은 단일 명령으로 가능합니다:

npm install -g @anthropic-ai/claude-code

설치 확인:

claude --version

터미널에 버전 번호가 출력되어야 합니다. 권한 오류가 발생하면 npm 프리픽스를 구성하거나 sudo를 사용해야 할 수 있습니다(npm 권한을 수정하는 것을 권장합니다).

2단계: Shopify 프로젝트 초기화​

Shopify 프로젝트 디렉토리로 이동하거나 새로 생성합니다:

mkdir my-shopify-app && cd my-shopify-app
npm init -y
npm install @shopify/shopify-api @shopify/shopify-app-remix

이제 프로젝트 안에서 Claude Code를 실행합니다:

claude

Claude가 프로젝트 구조를 분석하고 컨텍스트를 자동으로 이해합니다. 바로 Shopify 관련 질문을 시작할 수 있습니다.

3단계: Shopify 접근을 위한 MCP 구성​

Shopify 개발을 위한 Claude Code의 진정한 힘은 MCP(Model Context Protocol)를 통해 스토어에 연결하는 것에서 나옵니다. 프로젝트 루트에 .mcp.json 파일을 생성합니다:

{
  "mcpServers": {
    "shopify-dev-store": {
      "command": "npx",
      "args": [
        "-y",
        "@anthropic-ai/shopify-mcp-server",
        "--store", "your-store.myshopify.com",
        "--token", "${SHOPIFY_ACCESS_TOKEN}"
      ],
      "env": {
        "SHOPIFY_ACCESS_TOKEN": ""
      }
    }
  }
}

액세스 토큰을 환경 변수로 설정합니다:

export SHOPIFY_ACCESS_TOKEN="shpat_xxxxxxxxxxxxxxxxxxxxx"

이제 Claude Code를 시작하면 MCP 서버를 통해 Shopify 스토어 데이터에 직접 접근할 수 있습니다.

4단계: 첫 번째 AI 지원 명령​

Claude Code가 스토어에 연결되면 다음과 같은 유용한 시작 명령을 시도해 보세요:

스토어 데이터 탐색​

> 스토어의 모든 제품을 변형(variants)과 가격과 함께 나열해줘

Claude가 MCP 연결을 사용하여 스토어의 Admin API를 쿼리하고 구조화된 제품 데이터를 터미널에 직접 반환합니다.

Shopify 코드 생성​

> Slack 알림을 보내는 orders/create 웹훅 핸들러를 만들어줘

Claude가 웹훅 검증, 페이로드 파싱, Slack API 호출을 처리하는 프로덕션 수준의 코드를 생성합니다 — 모두 Shopify 모범 사례를 따릅니다.

API 문제 디버깅​

> Storefront API를 쿼리할 때 429 오류가 발생합니다. 적절한 속도 제한을 구현하도록 도와주세요.

Claude는 Shopify의 속도 제한 모델(REST의 리키 버킷 알고리즘, GraphQL의 쿼리 비용)을 이해하고 적절한 재시도 로직을 생성합니다.

Shopify 개발에 가장 유용한 명령​

매일 사용하는 Claude Code 명령 패턴입니다:

명령 패턴기능
> 메타필드와 함께 제품을 가져오는 GraphQL 쿼리를 보여줘올바른 Storefront 또는 Admin API 쿼리 생성
> 수량 할인을 위한 Shopify Function을 만들어줘Rust 또는 JavaScript로 완전한 Shopify Function 스캐폴딩
> 이 REST API 호출을 GraphQL로 변환해줘더 이상 사용되지 않는 REST 패턴을 현대적 GraphQL로 마이그레이션
> 이 Liquid 템플릿의 성능 문제를 검토해줘테마 코드를 분석하고 최적화를 제안
> 이 Shopify 앱을 위한 CI 파이프라인을 설정해줘GitHub Actions 또는 유사한 CI 구성 생성

일반적인 주의사항과 회피 방법​

주의사항 1: API 버전 불일치​

Claude가 앱에 구성된 것과 다른 API 버전을 대상으로 코드를 생성할 수 있습니다. 항상 프롬프트에서 버전을 지정하세요:

> 2026-01 Admin API 버전을 사용하여 제품 쿼리를 생성해줘

또는 더 나은 방법으로, shopify.app.toml에 올바른 버전이 있는지 확인하면 Claude가 컨텍스트에서 자동으로 인식합니다.

주의사항 2: 스코프 혼동​

Claude가 MCP를 통해 특정 스토어 데이터에 접근할 수 없다면 스코프 문제일 가능성이 높습니다. 액세스 토큰에 필요한 스코프가 포함되어 있는지 확인하세요:

# 개발에 일반적인 스코프
read_products, write_products
read_orders, write_orders
read_customers
read_inventory, write_inventory

주의사항 3: 토큰 보안​

하드코딩된 토큰이 포함된 .mcp.json을 절대 커밋하지 마세요. 위에 표시된 것처럼 항상 환경 변수를 사용하고 .mcp.json을 .gitignore에 추가하세요:

echo ".mcp.json" >> .gitignore

주의사항 4: GraphQL 쿼리 복잡성​

Shopify의 GraphQL API에는 쿼리 비용 제한이 있습니다. Claude가 깊게 중첩된 쿼리를 생성하면 최적화를 요청하세요:

> 이 쿼리가 비용 제한을 초과합니다. 페이지네이션을 사용하고 중첩을 줄이도록 리팩터링해줘.

다음 단계​

Shopify 개발을 위한 Claude Code 설정이 완료되었으니, 워크플로를 가속할 준비가 되었습니다. 향후 게시물에서 다룰 내용은 다음과 같습니다:

  • Claude Code를 페어 프로그래머로 활용한 처음부터 완전한 Shopify 앱 구축
  • 멀티 스토어 관리를 위한 고급 MCP 구성
  • Claude Code를 사용하여 Liquid에서 Hydrogen으로 테마 마이그레이션

Claude Code와 Shopify 개발의 조합은 진정으로 변혁적입니다. Shopify API 전체를 이해하는 AI 어시스턴트의 속도를 경험하면, 문서만으로 개발하는 것이 고통스럽게 느리게 느껴질 것입니다.

한번 시도해 보시고, 어떠셨는지 알려주세요.