Shopify APIバージョン更新で壊れる呼び出しをClaude Codeで事前に洗い出す

Shopify APIのバージョン更新で壊れる原因は、2つあります。新バージョンで項目が削除・変更されること。そして、固定していたバージョンのアクセス期限が切れ、別のバージョンで応答されること。どちらも、リリースノートとコード中の呼び出しを突き合わせ、固定バージョンを変えたテストを回せば、本番に出る前に見つかります。この記事では、その突き合わせと検査をclaude -pとCIに任せる手順を書きます。

壊れ方は2種類ある

Shopifyは新しいAPIバージョンを3か月ごとに、四半期の初日の17時(UTC)に出します。バージョン名は2026-10のような日付形式で、安定版は最低12か月サポートされ、連続するバージョンとは9か月以上の重なりがあります。

2つ目は見落としやすい壊れ方です。アクセスできないバージョンを指定すると、Shopifyは最も古いアクセス可能な安定版で応答します。たとえば廃止済みの2024-10への要求は、最も古い安定版で処理されます。コードは何も変えていないのに、挙動だけが新しいバージョンのものになります。

このレスポンスヘッダが、暗黙の繰り上がりを検知する足がかりになります。要求したバージョンと違う値が返れば、そのアプリは使えないバージョンを指しています。

手順1: コード中の固定バージョンを集める

最初に、バージョンがどこに書かれているかを一覧にします。公式ライブラリを使っているコードでは、バージョンの指定はライブラリ側が扱います。URLを直接組み立てているコードでは、文字列として散らばっています。

grep -rnE "20[0-9]{2}-(01|04|07|10)" \
  --include='*.ts' --include='*.js' --include='*.toml' \
  --include='*.json' --include='.env*' .

出てきた行が「1か所の設定値から読んでいる」のか「各所に直書き」なのかで、後の手間が変わります。直書きが複数あるなら、先にSHOPIFY_API_VERSIONのような環境変数1つに寄せます。この整理は、Claude Codeに「バージョン文字列を環境変数1つに集約して」と頼めば済む作業です。差分を読んで、URLの組み立て箇所が漏れていないかだけ目で確かめます。

手順2: 要求したバージョンで応答されているか検査する

次に、ヘッダを見る小さなスクリプトを置きます。開発ストアに対して、軽いクエリを1回投げるだけです。

#!/usr/bin/env bash
# scripts/check-shopify-version.sh
set -euo pipefail
want="${1:?例: 2026-10}"
 
got=$(curl -s -D - -o /dev/null -X POST \
  "https://${SHOP}.myshopify.com/admin/api/${want}/graphql.json" \
  -H "X-Shopify-Access-Token: ${SHOPIFY_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ shop { name } }"}' \
  | tr -d '\r' \
  | awk -F': ' 'tolower($1)=="x-shopify-api-version"{print $2}')
 
if [ "$got" != "$want" ]; then
  echo "繰り上がり: 要求 ${want} / 応答 ${got}" >&2
  exit 1
fi
echo "OK: ${got}"

本番で使っているバージョンを引数に、定期実行しておきます。アクセス期限が切れたバージョンを指していれば、その日から失敗として表に出ます。

手順3: リリースノートとコードを突き合わせる

ここがClaude Codeの出番です。Shopifyは各バージョンのリリースノートをページ単位で公開していて、URLに.mdを付けるとMarkdownで取得できます。項目にはBreaking change:とAction required:、Update:のラベルが付いています。前の2つが、コードの修正を求める項目です。

2026-10のリリースノートには、たとえば次の項目があります。

最初の4つはフィールド名やエラーコードが名指しされているので、grepで機械的に見つかります。最後の項目は、クエリごとにメタフィールド定義がフィルタ可能かを見る必要があり、grepだけでは判定できません。

名指しの項目を人が1つずつ拾うと漏れます。そこで、リリースノートを標準入力に流し、ソースの探索だけをClaudeに任せます。claude -pは標準入力を読めるので、取得結果をそのままパイプで渡せます。

プロンプトはファイルにしておきます。

標準入力は Shopify API のリリースノートです。
Breaking change と Action required の各項目について、
名指しされているフィールド名・型名・エラーコード・引数を
./src から Grep で探してください。
このアプリが使うAPI(GraphQL Admin API、Webhookなど)の節だけを対象にしてください。
見つかった箇所だけを報告し、コードは変更しないでください。
grep で判定できない項目は、symbol に項目名を入れ、
change に「要目視」と書いてください。

実行は次のとおりです。

curl -s https://shopify.dev/changelog/release-notes/2026-10.md \
  | claude --bare -p "$(cat prompts/shopify-diff.md)" \
    --allowedTools "Read,Grep" \
    --permission-mode dontAsk \
    --output-format json \
    --json-schema '{"type":"object","properties":{"findings":{"type":"array","items":{"type":"object","properties":{"file":{"type":"string"},"line":{"type":"integer"},"symbol":{"type":"string"},"change":{"type":"string"}},"required":["file","line","symbol","change"]}}},"required":["findings"]}' \
  | jq '.structured_output.findings'

指定の意図は次のとおりです。

• --bare: 個人のhooksやMCPサーバーを読み込まず、どの環境でも同じ条件で動かします。サブスクリプションのログインは使われないため、ANTHROPIC_API_KEYを環境に設定しておきます
• --allowedTools "Read,Grep": 読むことと探すことだけを許可します。外部のページを入力にするので、シェルや書き込みの権限は渡しません
• --permission-mode dontAsk: 許可リストにないツール呼び出しを、確認待ちにせず拒否します。無人の実行で止まりません
• --json-schema: 結果がstructured_outputに入ります。条件を満たす出力が得られなかった実行ではこのフィールドが付かないので、スクリプトで使う前に有無を確かめます

リリースノートはAPIごとの節に分かれています。2026-10では、GraphQL Admin API、Customer Account API、Events & webhooks、Functions、Storefront APIなどです。使っていないAPIの節を読ませない指示を、プロンプトに入れておきます。

出力はfile・line・symbol・changeの配列になるので、そのままチケットの一覧にできます。要目視と書かれた項目は、手順4のテストで受け持ちます。Claudeが「該当なし」と返した項目は、grep -rn priceRule srcのように名指しの語を自分でも検索して、結果が一致するか確かめます。0件という答えほど、取りこぼしの有無が見えにくいためです。

リリースノートの挙動変更は、grepでは出ません。たとえば、未発送の注文の配送先をorderUpdateで変えると、税が新しい宛先で再計算されます。呼び出しの文字列は変わらないので突き合わせでは見つからず、金額を前提にしたテストの期待値に現れます。

呼び出しコードの洗い出しをclaude -pに任せる考え方は、Sunsetヘッダで旧APIを廃止予告する手順の「呼び出し側のコードをgrepして対応表を作る」節と同じ型です。権限まわりの詳細はclaude -pオプションの解説にまとめています。

手順4: 固定バージョンを変えたテストをCIで回す

最後に、テストを2つのバージョンで走らせます。現行の固定バージョンと、次の四半期のリリース候補です。リリース候補は、安定版と同じ日に公開されます。後方互換のない変更を含みうるため、本番には向きませんが、先に壊れる箇所を見つける用途には合います。

jobs:
  shopify-compat:
    runs-on: ubuntu-latest
    continue-on-error: ${{ matrix.allow-failure }}
    strategy:
      matrix:
        include:
          - version: "2026-10"
            allow-failure: false
          - version: "2027-01"   # リリース候補の例
            allow-failure: true
    env:
      SHOPIFY_API_VERSION: ${{ matrix.version }}
    steps:
      - uses: actions/checkout@v4
      - run: scripts/check-shopify-version.sh "$SHOPIFY_API_VERSION"
      - run: npm test

候補側は失敗を許容します。目的は合格させることではなく、落ちたテストの名前を先に読むことです。落ちた箇所がリリースノートのどの項目に当たるかは、手順3の一覧と照らして分類できます。

アプリのコードがバージョンを環境変数から読む形になっていれば、このジョブは設定の差し替えだけで動きます。手順1の整理が前提になるのはこのためです。

更新を四半期ごとの定例にする

バージョンには、リリース日とアクセス期限が決まっています。期限はリリースの約12か月半後で、日付は表のとおりです。

Shopifyは、毎四半期に最新の安定版へ上げることと、リクエストで必ずバージョンを指定することを勧めています。非推奨の扱いも、この間隔に合わせて考えます。ある項目が2026-10で非推奨になれば、2027-01以降のリリースで削除されることがあります。削除される版を待たず、非推奨が告知された時点で手順3を回しておけば、移行の時間を稼げます。

CLAUDE.mdに更新の手順を書いておくと、四半期ごとにプロンプトを書き直さずに済みます。

## Shopify APIバージョン更新
- バージョン文字列は SHOPIFY_API_VERSION だけで読む。直書きしない
- 更新時は prompts/shopify-diff.md と scripts/check-shopify-version.sh を使う
- リリースノートに根拠のない項目は、影響ありと断定しない
- 本番の設定とデプロイには触れない

--bareを付けた実行はCLAUDE.mdを読み込まないので、CIから呼ぶときは、必要な指示をプロンプトファイルのほうに入れておきます。

検出が届かない領域

ここまでの手順は、バージョンを持つAPIが対象です。次の3点は別に見ます。

• バージョンを持たないAPIは、いつでも変わりえます。LiquidやOAuthのエンドポイント、Web Pixels APIなどが該当します。テーマ側の確認はClaude CodeでShopifyテーマ開発を進めるが扱っています
• Webhookのペイロードも、APIの応答と同じようにバージョンで決まります。選択中のバージョンにアクセスできなくなると繰り上がり、ヘッダX-Shopify-Api-Versionが使われたバージョンを示します
• 非推奨の呼び出しは、アクセストークンを発行したアプリに結び付けられます。サポート担当のPostmanやInsomniaのコレクションに同じトークンを入れると、そのアプリに対する警告として届きます

非推奨の警告は、Dev Dashboardのアラートや、GraphiQL Explorerの警告にも出ます。コードの外側の信号として、通知先の連絡先を最新にしておくと取りこぼしが減ります。期限を過ぎても未サポートのリソースを使い続けると、アプリはShopify App Storeから掲載を外されます。

廃止の予告から移行までの手順を決めておく考え方は、別のサービスでも同じです。KubernetesではClaude CodeとplutoでKubernetesの非推奨APIを移行する手順が、検出を専用ツールに固定してClaudeには修正だけを渡す分担を書いています。実行環境側の期限はGitHub ActionsのNode 20非推奨に備え、Claude Codeでworkflowを更新するに例があります。

まとめ

四半期ごとの更新で効くのは、コードの外から壊れ方を見張る仕組みです。バージョン文字列を1か所に集め、応答ヘッダで繰り上がりを検査し、リリースノートの名指し項目はClaudeにソースを探させます。grepで見つからない挙動変更は、リリース候補で回すテストの失敗として拾います。更新当日に初めて失敗に気づく事態は、これで避けられます。