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
[One paragraph describing what this project does, who it's for, and its current status.]

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
  • Follow Polaris design patterns: Page > Layout > Card hierarchy
  • Use useAppBridge() for App Bridge interactions
  • Toast for success messages, Banner for persistent info/errors

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)

Webhooks​

  • Verify HMAC on all webhook endpoints
  • Respond within 1 second (offload heavy work to background jobs)
  • Implement idempotency using webhook ID tracking

Shopify-Specific Rules​

  • 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

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

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


## 範本變體

### 僅佈景主題專案

如果您在開發 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)

## 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

### 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

Claude Code 如何使用 CLAUDE.md​

理解 Claude Code 如何處理 CLAUDE.md 有助於您寫出更好的版本：

  1. 工作階段開始時讀取：Claude Code 在您的第一個提示詞之前讀取 CLAUDE.md
  2. 始終在上下文中：內容在整個工作階段中保持在上下文視窗中
  3. 層級合併：全域（~/.claude/CLAUDE.md）+ 專案根目錄 + 子目錄檔案被合併
  4. Token 成本：CLAUDE.md 消耗上下文 token，所以要簡潔。500 字的 CLAUDE.md 大約是 700 個 token——上下文視窗的一小部分
保持簡潔

太長的 CLAUDE.md 會在每次互動中浪費上下文 token。目標是 300-800 字。將詳細文件放在單獨的文件中——CLAUDE.md 應該是快速參考，而不是一本小說。每個字都應該值得它的位置。

最佳實務檢查清單​

撰寫或審查您的 CLAUDE.md 時使用此檢查清單：

  • 已指定 API 版本（最重要的一行）
  • 已列出技術堆疊（框架、語言、資料庫、UI）
  • 已記錄所有開發命令（dev、test、build、deploy）
  • 已概述檔案結構（關鍵目錄及其用途）
  • 編碼標準是明確的（不是模糊的「寫乾淨的程式碼」）
  • 已說明 Shopify 特定規則（範圍、應用程式類型、擴充）
  • 測試期望是明確的（測試什麼、如何執行測試）
  • 已記錄已知問題（防止 Claude Code 遇到同樣的問題）
  • 已列出環境變數（不含實際值）
  • 沒有敏感資料（沒有 API 金鑰、權杖或密碼）
永遠不要在 CLAUDE.md 中放置機密

CLAUDE.md 是一個會提交到版本控制的普通檔案。永遠不要包含 API 金鑰、存取權杖、資料庫密碼或任何敏感憑證。列出變數名稱（例如 SHOPIFY_API_KEY）但不列出其值。

演進您的 CLAUDE.md​

您的 CLAUDE.md 應該隨著專案演進。在以下情況更新：

  • 升級 Shopify API 版本時
  • 添加新的擴充或 webhook 時
  • 變更架構模式時
  • 發現新的浪費時間的「陷阱」時
  • 添加或變更開發命令時
  • 團隊編碼標準演進時

過時的 CLAUDE.md 比沒有 CLAUDE.md 更糟糕，因為它會給 Claude Code 自信但錯誤的上下文。保持更新、保持簡潔，並對專案的實際狀態保持誠實。

下一步​

有了 CLAUDE.md，您已準備好探索 MCP 基礎，了解 Model Context Protocol 如何進一步擴展 Claude Code 在 Shopify 開發中的能力。