Claude CodeでShopifyテーマ開発を進める — theme checkで誤りを直させる手順

Claude CodeでShopifyテーマ(Liquid)を編集するなら、検証コマンドは shopify theme check が軸になります。Theme Checkは、テーマのコードをLiquidとテーマのベストプラクティスに照らして解析するリンターです。Claudeは書いた直後にこの出力を読み、構文ミスや未定義の変数を自分で直せます。

Liquidはコンパイルが無いので、書き間違いに気づくのはプレビューを開いたときか、ストアに反映したあとになりがちです。ここを「編集のたびにtheme checkを通す」形に変えるのが本記事の中心です。CLAUDE.mdに書く内容、PostToolUse hookでの自動実行、本番テーマを守る権限設計までを順に扱います。

theme checkは何を見つけてくれるのか

Theme Checkのチェックは、Liquidファイル向けとJSONファイル向けに分かれています。重要度(severity)は error / warning / info の3段階で、既定ではerrorが1件でもあると終了コード1で失敗します。Claudeに直させたい種類のミスは、ほぼこの一覧に載っています。

重要度は、チェック一覧のページに載っている値です。MissingTemplate や DeprecatedFilter のように、--auto-correct による自動修正に対応するチェックもあります。

ここで読み取れるのは、Theme Checkが「見た目」ではなく「参照の整合性」に強いという点です。スニペット名の打ち間違い、消したはずのアセットへの参照、翻訳キーの抜けといった、プレビューで初めて気づく類のミスを機械的に拾います。Claudeが編集した直後の確認に向くのは、この種の誤りです。

公式の例で見る、Claudeが直す対象

公式のチェック解説にある失敗例を、そのまま抜き出すと次の形です。

{{ x | some_unknown_filter }}
{% render 'snippet-that-does-not-exist' %}

1行目は UnknownFilter、2行目は MissingTemplate の対象です。Theme Checkはファイルと行を添えて報告するので、Claudeはメッセージを読み、フィルターを実在のものに替えるか、スニペットのファイル名を直せます。人間が間に立つ必要はありません。

最初に整える環境と設定ファイル

Theme Checkの実行にはShopify CLIが要ります。コマンド解説のページでは、@shopify/cli と @shopify/theme のパッケージを入れること(macOSはHomebrew、WindowsとLinuxはグローバルインストール)が要件として挙がっています。

新規にテーマを作るなら、shopify theme init が出発点です。Gitリポジトリを指定しなければ、ShopifyのSkeletonテーマが指定名のフォルダにコピーされます。

shopify theme init my-theme
cd my-theme
shopify theme check --init

--init は .theme-check.yml を生成するフラグで、設定ファイルはテーマのルートに置きます。最小の設定は次のとおりです。

# .theme-check.yml
extends:
  - theme-check:recommended
 
ignore:
  - 'node_modules/**'

extends には theme-check:all / theme-check:recommended / theme-check:theme-app-extension が使えます。設定の指定を一時的に変えたいときは、-C で別の設定ファイルを渡せます。.theme-check.yml よりもこちらが優先されます。

CLAUDE.mdに書く内容

Claude Codeは、CLAUDE.mdをセッションの開始時に読みます。公式の目安は1ファイル200行未満で、長いほど遵守率が下がると説明されています。テーマ開発では、次の4点に絞ると足ります。

# Shopify テーマ開発
 
## 検証(編集のたびに実行)
- `shopify theme check --fail-level error` が終了コード0になるまで直す
- 出力のチェック名(UnknownFilter など)を見て原因を特定する
- 警告(warning)は報告するが、勝手に抑制コメントで消さない
 
## 構成
- templates/ sections/ snippets/ blocks/ assets/ locales/ config/ の標準構成を保つ
- 再利用する部品は snippets/ に置き、{% render %} で呼ぶ
- ハードコードしたURLは使わず routes オブジェクトを使う
 
## 禁止
- `shopify theme push` は実行しない(公開は人間が行う)
- config/settings_data.json と templates/*.json を手で整形しない

書き方の要点は、検証コマンドを1つに決めて「終了コード0」を完了条件にすることです。Claudeは「直した」で止まらず、通るまでやり直します。

config/settings_data.json などに触れない旨を入れているのは、テーマエディターが書き換えるファイルだからです。アーキテクチャの解説ページでは、templates/*.json、セクショングループ、config/settings_data.json、locales/*.json は、コメントや末尾カンマが保持されない種類のファイルとされています。コマンドで整形し直すと、エディター側の変更と衝突しやすくなります。

「抑制コメントで消さない」の1行も効きます。Theme Checkには {% # theme-check-disable UnusedAssign %} のような無効化コメントがあり、Claudeは通すために使いたくなるからです。警告は報告させて、抑制するかどうかは人間が決める分担にします。

theme checkの出力でLiquidを直させる反復

実際の作業は、次の流れで回ります。

3の切り分けでは、チェック名がそのまま手がかりになります。UndefinedObject は、変数を assign か capture で宣言するか、スニペットなら {% doc %} タグの @param で文書化する必要がある、と解説されています。

# 人が読む形(既定)
shopify theme check --fail-level error --no-color
 
# JSON形式で受け取る
shopify theme check --fail-level error --output json

--output は出力形式を選ぶフラグで、json と text(既定)が使えます。長いテーマで件数が多いとき、JSONなら jq で error だけを抜き出して読ませる運用もできます。

自動修正は差分を見てから採用する

-a(--auto-correct)を付けると、直せる違反は自動で修正されます。チェック一覧で自動修正に対応しているのは DeprecatedFilter、MissingTemplate、MatchingTranslations です。

shopify theme check -a
git diff

MissingTemplate のように「存在しない参照先」を扱うチェックは、修正の結果としてファイルが増えることがあり得ます。自動修正のあとは git diff で何が変わったかを見るところまでを、CLAUDE.mdの手順に含めておくと安全です。

PostToolUse hookで編集のたびに自動実行する

CLAUDE.mdの指示は、守られない回もあります。確実に毎回走らせたいなら、hooksで検証を固定します。PostToolUse hookは、ツール呼び出しが成功した直後に動きます。終了コード2で終わると、標準エラーの内容がClaudeにフィードバックとして渡る仕組みです。

次のスクリプトは、.liquid と .json の編集後だけtheme checkを実行します。

#!/bin/bash
# .claude/hooks/theme-check.sh
INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
 
case "$FILE" in
  *.liquid|*.json) ;;
  *) exit 0 ;;
esac
 
OUT=$(shopify theme check --fail-level error --no-color \
  --path "$CLAUDE_PROJECT_DIR" 2>&1)
if [ $? -ne 0 ]; then
  echo "$OUT" >&2
  exit 2
fi
exit 0

.claude/settings.json には、Edit|Write を対象にして登録します。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/theme-check.sh"
          }
        ]
      }
    ]
  }
}

スクリプトは chmod +x .claude/hooks/theme-check.sh で実行権限を付けておきます。matcherの書き方や、編集ごとにLintを自動修正する他言語の型は、PostToolUse hookのLint自動修正に早見表があります。

作業の最後に「全体で合格しているか」を確かめたいなら、Stop hookに同じコマンドを置く手もあります。その場合は、フックがすでに継続中かを示す stop_hook_active を確認して、合格しない状態でループし続けないようにします。型検証コマンドを同じ形で組み込んだ例は、Claude CodeでNuxtアプリを開発するにあります。

権限設計 — checkは許可、公開系は確認を挟む

theme checkはテーマのファイルを読むだけなので、許可リストに入れて承認の手間を省けます。一方で、ストアに作用するコマンドは扱いを分けます。

{
  "permissions": {
    "allow": [
      "Bash(shopify theme check *)"
    ],
    "ask": [
      "Bash(shopify theme push *)",
      "Bash(shopify theme dev *)"
    ]
  }
}

shopify theme push は、手元のテーマファイルをShopifyへアップロードし、指定すればリモート側のテーマを上書きします。--live はライブテーマを対象にするフラグで、非対話の環境でライブテーマへ押し上げるには --allow-live も必要です。上書きの操作なので、人間の承認を挟む対象に向いています。

shopify theme dev も、ローカルのテーマを開発テーマとしてストアにアップロードします。すでに開発テーマがあれば、ローカルのテーマで置き換えます。開発テーマは shopify auth logout を実行すると削除される点も、仕様として書かれています。

権限ルールの書き方(ワイルドカードの位置やdenyの優先順位)は、Cloudflare Workersのwrangler権限設計の記事とも共通する考え方です。ストアに反映するコマンドは ask に置いて、人間の承認を通す形にしておくと、Claudeが勢いで本番に押し上げる事故を避けられます。

つまずきやすい点

構文エラーのファイルでは無効化コメントが効かない

無効化コメントは、Theme Checkがファイルをパースしたあとに読まれます。構文エラーでパースが止まったファイルでは、コメントが無視されます。そのため、構文エラー(LiquidHTMLSyntaxError)は抑制コメントでは消えません。直すしかないので、Claudeに「コメントで逃げない」と指示する意味が、ここでも出てきます。

公式ページ同士で記述が食い違う箇所がある

--fail-level に指定できる値は、コマンドのページでは error / suggestion / style と書かれています。一方、設定のページでは重要度が error / warning / info です。また、UndefinedObject はチェック一覧ではErrorですが、チェック個別のページの設定例は severity: warning です。

手元のテーマで何が有効かは、shopify theme check --print で有効な設定を出力して確かめられます。--list を付ければ、有効なチェックの一覧も見られます。CLAUDE.mdで --fail-level error を指定するなら、まず手元でこの値が通るかを試しておくと安心です。

UndefinedObjectはスニペットでは条件つき

UndefinedObject は、LiquidDocを含まないスニペットファイルではスキップされます。スニペットの引数を {% doc %} の @param で宣言しておくと、チェックの対象になります。Claudeに新しいスニペットを作らせるときは、@param の記述もセットで頼むと、後から未定義変数を拾えるようになります。

theme devは標準のフォルダ構成が前提

shopify theme dev は、標準的なテーマのフォルダ構成に合致するディレクトリでしか実行できません。src から生成したコードを dist に出力するような構成では、Theme Checkのほうも root 設定で dist を指す必要があります。構成を変えた場合は、CLAUDE.mdの「構成」の節も合わせて直します。

まとめ

ShopifyテーマのLiquidは、書いた直後に検証する手段を持たせると、Claude Codeが自分で誤りを直せるようになります。要点は3つです。shopify theme check --fail-level error を完了条件にしてCLAUDE.mdへ書くこと。PostToolUse hookで編集のたびに実行し、エラーをClaudeへ返すこと。push と dev は ask に置き、本番テーマへの反映だけは人間の承認を挟むことです。

ストア運営の側でClaudeに任せる作業は、ClaudeにShopifyのEC運営を任せる実践パターンにまとめています。