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
これにより、認証、セッション処理、App Bridgeが既に設定された適切な基盤がClaude Codeに提供されます。
アプリエクステンションのスキャフォールディング
アプリエクステンション（テーマエクステンション、チェックアウトUIエクステンション、管理UIエクステンション）には特定のファイル構造要件があります。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ファーストであり、正しいクエリの作成は最も一般的なタスクの1つです。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
エンドツーエンドテーマテスト
> 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
Brief project description and purpose.
## Tech Stack
Framework, language, database, UI library.
## Shopify Configuration
API version, app type, scopes, extensions.
## Commands
Dev server, build, test, deploy commands.
## File Structure
Key directories and their purposes.
## Coding Standards
Language-specific conventions and Shopify rules.
## Testing Requirements
Test framework, coverage expectations, what to test.
## Common Patterns
Recurring patterns specific to your project.
## Known Issues
Active bugs or workarounds Claude should know about.
CLAUDE.mdには必ずShopify APIバージョンを含めてください。これがないと、Claude Codeが異なるバージョンをデフォルトにし、廃止されたフィールドや存在しないフィールドを参照するコードを生成する可能性があります。API Version: 2025-01のような1行で、何時間ものデバッグを防げます。
ワークフローチートシート
| タスク | プロンプトパターン |
|---|---|
| 新しいセクション | 「Xというliquidセクションを作成して...」 |
| GraphQLクエリ | 「X を Y で取得するGraphQLクエリを書いて...」 |
| Webhookハンドラー | 「Xのwebhookハンドラーを作成して...」 |
| バグ修正 | 「このエラーが...で発生します。[エラーを貼り付け]。修正して。」 |
| テストスイート | 「Y, Zのシナリオをカバーする X のテストを書いて」 |
| リファクタリング | 「Xを[パターン/標準]に従うようにリファクタリングして」 |
| コードレビュー | 「[特定の懸念点]についてXをレビューして」 |
| マイグレーション | 「Xを[古い]から[新しい]に移行して」 |
これらのパターンが機能するのは、Claude Codeがコードベース全体にアクセスできるためです。関連するファイルを読み、コンテキストを理解し、プロジェクトの残りの部分と一貫した変更を行います。
次のステップ
コアワークフローを理解したら、プロンプトエンジニアリングに進んで、Claude CodeでのShopify開発を強化するすぐに使えるプロンプトテンプレートを学びましょう。