用 代理人 建構Shopify 商店
2026.05 EDITION VOL. 01 / SHOPIFY EST. READ 18 MIN
Shopify 在 2025–2026 年的 三次關鍵發布 。
Shopify 在 2025–2026 年連續推出三項變動,將 AI 代理人整合納入核心開發與銷售流程。
2025 年 12 月,Winter '26 Edition 發布。 Shopify 把官方 Dev MCP Server 內建到平台,讓 AI 代理人第一次能用 結構化 的方式存取 GraphQL Admin API、Storefront API 與 Liquid 文件。這場改版含 150 + 項 AI 功能,Shopify 自己稱為「The Renaissance」。
2026 年 3 月 24 日,Agentic Storefronts 全面啟用。 美國境內合資格商家被預設打開: 5.6 M 間商店 同時在 ChatGPT、Microsoft Copilot、Google AI Mode、Gemini App 裡 變得可購買 。麥肯錫預估 2030 年全球代理人商務將達到 5 兆美元規模。
2026 年 4 月 9 日,Shopify AI Toolkit 開源(MIT License)。 一鍵把 Dev MCP、Admin GraphQL、Liquid 驗證、UI Extensions 校驗等 16 項 Agent Skills 裝進 Claude Code、Codex、Cursor、Gemini CLI、VS Code。
對開發者的實際影響有三點:第一, 不需要記憶 GraphQL 欄位 ,代理人在寫程式前會先用 Dev MCP 驗證 schema。第二, 不需要切換視窗 ,代理人在終端機裡即可改主題、跑 mutation、推上線。第三,Shopify 工程副總 Farhan Thawar 指出: 「2026 年沒搞懂怎麼駕馭代理人的人就會被甩開。」
工具棧的四個 核心元件 與分工。
Claude Code 與 Codex 不是替代關係,關鍵問題是: 哪一段工作要交給哪個元件? 以下四個元件在完整工作流中各有角色。
CODING HARNESS
Claude Code
Anthropic 出品、終端機原生 (terminal-native) 的代理人 CLI。讀整個 repo、跑 shell、做 git 操作。1M token context 能裝得下整套 Dawn theme,適合改 Liquid、寫 Hydrogen、做大型重構。
npm i -g @anthropic-ai/claude-code
CODING HARNESS
OpenAI Codex CLI
OpenAI 的對應品,讀 AGENTS.md 而非 CLAUDE.md,設定走 TOML(~/.codex/config.toml)。Subagent、Hook、Skill 都有,且支援把自己當成 MCP server 給別的代理人呼叫。
~/.codex/config.toml
DEV MCP · 開發者用
Shopify Dev MCP
本機跑、不需 auth。提供文件搜尋、GraphQL Admin/Storefront schema 即時校驗、Liquid 範本驗證。所有 寫程式 的代理人請務必接上。
npx -y @shopify/dev-mcp@latest
STOREFRONT MCP · 消費者用
Storefront MCP
每間商店自動擁有 /api/mcp 端點,讓 ChatGPT、Claude.ai、Perplexity 的 購物代理人 能搜商品、加購物車、走結帳。不是你要呼叫的,是 你要被呼叫的 。
https://{shop}.myshopify.com/api/mcp
ADMIN · 跑商店用
Admin GraphQL · 透過 CLI
用 shopify store auth + shopify store execute(3.93.0 起),代理人能直接讀寫商品、訂單、metafield。 --allow-mutations 預設關閉,寫操作要明確開啟。
shopify store auth --scopes ...
ADMIN · 社群維護
shopify-mcp (社群)
GeLi2001 等社群成員維護的 Admin MCP,直接接 Shopify Admin GraphQL。比 Shopify 官方更直接,但維護不保證,適合熟練後玩自動化。
github.com/GeLi2001/shopify-mcp
三條 MCP 路線,各自解決不同問題
MCP 類型
給誰用
解決什麼問題
Dev MCP
開發者 / Claude Code / Codex / Cursor
寫程式前查文件、驗證 GraphQL 與 Liquid、避免幻覺出不存在的欄位。
Storefront MCP
外部 AI 購物代理人(ChatGPT、Claude、Perplexity)
讓你的商品在「對話式購物」漏斗裡可被找到、加購、結帳。
Admin MCP / Store Execute
店主 / 營運 / 開發者(批次操作)
用自然語言改商品、metafield、價格規則,批次處理上百個 SKU。
從乾淨機器到第一個 prompt 。
先決條件: Node.js 18+ 、終端機 (Terminal / iTerm2 / Warp)、一個 Shopify Partner 帳號。沒 Partner 帳號?去 partners.shopify.com 免費註冊,順便開一個 Dev Store( 永遠不要在正式店做第一次練習 )。
A路線 A — Claude Code(推薦初學者)
~/projects · zsh
$ npm install -g @anthropic-ai/claude-code
$ claude
✓ Signed in as you@example.com (Max subscription)
claude> /plugin marketplace add Shopify/shopify-ai-toolkit
claude> /plugin install shopify-plugin@shopify-ai-toolkit
✓ 7 tools available · auto-update enabled
$ claude mcp add --transport stdio shopify-dev-mcp \
-- npx -y @shopify/dev-mcp@latest
claude> /mcp
✓ shopify-dev-mcp · connectedB路線 B — OpenAI Codex CLI
~/.codex · zsh
$ npm install -g @openai/codex
$ codex login
$ codex
codex> /plugins
$ cat >> ~/.codex/config.toml << 'EOF'
[mcp_servers.shopify-dev]
command = "npx"
args = ["-y", "@shopify/dev-mcp@latest"]
EOF
$ codex mcp list
shopify-dev · stdio · readyC共用 — 把 Shopify CLI 也裝上
~/projects/my-store · zsh
$ npm install -g @shopify/cli@latest
$ shopify store auth --store your-store.myshopify.com \
--scopes read_products,read_orders,read_customers,read_inventory
$ shopify store execute \
--store your-store.myshopify.com \
--query 'query { shop { name email currencyCode } }'
{ "shop": { "name": "Your Store", ... } }
$ shopify store execute --allow-mutations \
--query 'mutation { productCreate(input: { title: "Test" }) { product { id } } }'CLAUDE.md 控制代理人的行為邊界。
CLAUDE.md(Claude Code 讀取)、AGENTS.md(Codex、Cursor、Gemini CLI 共用標準)放在專案根目錄。
這份檔案是代理人的專案說明書、守則與風格指南。若未正確設定,代理人可能發明不存在的 Liquid filter、將 metafield 寫入 client-side JS,或 commit settings_data.json 覆蓋線上客製化內容。
一份能上戰場的 CLAUDE.md 骨架
CLAUDE.md
## Stack
- Shopify Online Store 2.0 theme (Dawn-based)
- Shopify CLI 3.x · Node 20
- Theme check enforced, zero errors required
## Rules — non-negotiable
1. Never push to a live theme. Use development themes.
2. Never commit config/settings_data.json.
3. Before marking ANY task complete, run
shopify theme check and confirm 0 errors.
4. Prefer {% render %} over {% include %}.
5. Themes only READ metafields — never write.
6. Always check existence:
{% if product.metafields.custom.x != blank %}
## Conventions
- Branch names: feature/, fix/, chore/ prefixes
- One logical change per commit, imperative mood
- Translation keys via locales/, no hard-coded strings
## When in doubt
- ASK clarifying questions BEFORE editing.
- Validate every GraphQL query via shopify-dev-mcp first.
- If 16KB metafield limit hit, flag it — don't truncate.
## House style
- Brand voice: warm, expert, no hype.
- Currency: NTD primary, USD secondary.社群有開源版本可直接套用。Karim Tarek 在 GitHub 維護一份 Shopify Theme CLAUDE.md,涵蓋前端最佳實踐,drop 到專案根目錄即可使用。
30 天建站 逐日 prompt 腳本 。
以下不是工程進度表,而是 給初次做電商的人的逐日對話範本 ,可直接貼給代理人執行。
D1SETUP
環境就緒、註冊 Dev Store
安裝 Node、Claude Code 或 Codex、Shopify CLI。註冊 Partner 帳號,開一間 development store。將 CLAUDE.md 放入專案根目錄。 第一個 prompt 不要寫程式, 請代理人讀整個 repo 並回報對專案的理解。將不正確的部分補進 CLAUDE.md。
D2–4FOUNDATION
用 Dawn 為基礎、定義商品結構
「 請從 Shopify CLI 用 dawn 為 base 初始化一個 theme,把它的目錄結構解釋給我聽,然後幫我做三件事:1) 改 logo 與 favicon 的 placeholder; 2) 設定品牌色 CSS variable; 3) 把 hero section 的 placeholder 內容換成符合 {你的品牌敘述} 的文案。每一步請先說會改哪些檔案再動手。 」
D5–8CATALOG
用代理人批次匯入商品
準備一份 CSV(欄位:title, description, price, sku, vendor, tags, variant_options, images_urls)。叫代理人:「 用 Admin GraphQL productCreate mutation 把這份 CSV 匯入 dev store。每筆寫 SEO-optimized description。商品標題要自然語言化(給 AI 購物代理人吃),不要走品牌系列命名。匯入完用 shopify store execute 查回來,告訴我有幾筆失敗。 」
D9–12METAFIELDS
結構化資料 · 給人類也給 AI
定義 product.specifications(JSON metafield)、product.care_instructions(rich text)、product.materials(list)。叫代理人把這些 metafield 從 admin 建好、批次 populate、再在 product page section 渲染出來。 這一步是 AI 購物代理人能找到你商品的關鍵。
D13–16SECTIONS
把首頁、商品頁、集合頁全部模組化
每一個 section 是一個 Liquid 檔加一份 schema。叫代理人:「 把 hero 改成可以接 image_picker、richtext、url 三種 setting 的 reusable section。然後在 templates/index.json 加入這個 section 並讓我可以在 theme editor 拖拉。改完跑 shopify theme check,把所有錯誤跟警告一併修掉。 」
D17–20CHECKOUT
付款、運費、稅金、條款
這段大部分在 admin UI 設定,代理人協助確認 checklist。請代理人:「 用 shopify store execute 把以下事項都檢查一遍並列出尚未設定的:payment gateway 啟用、shipping zones、tax registration、refund policy、privacy policy、cookie banner、abandoned cart email。每一項給我具體要去哪裡開啟。 」
D21–24PERFORMANCE
速度、SEO、a11y 全面體檢
建立一個叫 theme-performance-auditor 的 subagent(放在 .claude/agents/),指定它能跑 Lighthouse、讀輸出、提出具體 Liquid 改動,並再跑一次驗證進步幅度。pair with shopify theme check --performance。
D25–28AGENT-READY
對 AI 購物代理人開門
編輯 robots.txt,確認 GPTBot、ClaudeBot、PerplexityBot 都被允許爬取。送商品到 Shopify Catalog。在 Search Console、Bing Webmaster 註冊 sitemap。 每一間商店都自動擁有 /api/mcp ,你不用做什麼,但要驗證它回得正常。
D29–30LAUNCH
上線、開廣告、開始量測
shopify theme push --unpublished 預覽。把 GA4、GTM、Klaviyo 接好(都可用 MCP 或代理人寫腳本完成)。發布。 之後每週固定請代理人跑一份 30 分鐘的健檢: 低庫存商品、缺 alt text 圖片、未回應評論、購物車放棄序列觸發率。
可直接使用的 四份 prompt 範本 。
有效 prompt 的三個要素: (1) 先計畫、後執行 ; (2) 給驗證手段,不只給目標 ; (3) 明訂 stopping condition 。以下四份範本對應不同開發階段,可直接套用。
範本 1 — 從零 scaffold 商店
[ROLE] 你是 Shopify 主題開發資深工程師,熟悉 Online Store 2.0、Liquid、theme app extensions、Shopify CLI 3.x。
[CONTEXT] 我有一間賣 {台灣手沖咖啡器具} 的 dev store({store.myshopify.com}),預計上架 {40} 個 SKU,客單價約 {NT$1,500–4,000}。目標市場:{台灣 + 日本},語系:{zh-TW 主要、ja 次要}。
[TASK] 替我從 Dawn 為 base 初始化一個 theme,並完成以下:
1. 設定 brand color tokens(CSS var)為 {#1A1A1A, #C77B3E, #F4F1EA}
2. 設定 typography(display: {Fraunces},body: {Noto Sans TC})
3. 客製 hero section:支援 image / video / no media 三種模式
4. 客製 product card:顯示金額、評星、metafield {custom.origin} 與 {custom.brewing_method}
5. 建立 zh-TW 與 ja locale 檔,所有 hard-coded 字串都搬進 translation key
[CONSTRAINTS]
- 每改一個檔案前先說「我即將改哪幾個檔、為什麼」
- 所有 Liquid 用 shopify-dev-mcp 驗證過再寫
- {% render %} 優先,禁用 {% include %}
- 完工前跑 shopify theme check,0 errors 才回報完成
[STOP CONDITION]
- 全部跑通 + theme check 0 errors + 在 dev store 可預覽
- 給我一份 README 描述每個自訂 section 的 setting
[BEGIN] 先 plan 再 execute,plan 階段請等我說 "go" 才動手。範本 2 — 批次匯入 CSV(含 AI 寫描述)
[ROLE] 你是 Shopify 商品資料工程師。
[CONTEXT] CSV 檔在 {./data/products-2026Q3.csv},欄位:{sku, title_zh, title_en, price, vendor, tags, weight_g, variant_color, image_urls}。共 {40} 筆。
[TASK]
1. 用 shopify-dev-mcp 驗證 productCreate / productVariantsBulkCreate 的最新 schema
2. 對每筆商品產生:
- 自然語言化 product title(給 AI 購物代理人吃,不要用品牌系列名)
- 80–120 字 SEO description(含 1 個 primary keyword + 2 個 long-tail)
- 4 個 metafield: custom.origin / custom.brewing_method / custom.material / custom.gift_ready (boolean)
3. 用 Admin GraphQL bulk operation 一次寫入
4. 失敗筆數獨立輸出到 {./logs/failed-{timestamp}.json}
[GUARDRAILS]
- GraphQL rate cost 上限 1000/min,自動 throttle
- 寫描述前先讀 CLAUDE.md 裡的「品牌語氣」段落
- 如果同 SKU 已存在,印出比對結果讓我選 skip 或 update,不要直接覆蓋
[VERIFICATION]
- 跑完後 query 回來確認筆數
- 抽 3 筆完整印出來給我審
[BEGIN] 先 plan、列出會用到的 mutation 與 estimated cost,等我說 "go"。範本 3 — 把抽象需求轉成 spec(訪談式)
[GOAL] 我想做一個「{訂閱式咖啡豆配送}」功能,但我不知道用 metafields、theme app extension、checkout extension、還是 Shopify Subscription App 比較好。
[TASK]
請用 AskUserQuestion 工具訪談我,把這些挖出來:
- 技術實作偏好(我能接受的複雜度)
- UX/UI(顧客買的時候會看到什麼)
- Edge cases(換貨、暫停、跳過一期)
- 我沒想到的取捨
不要問顯而易見的問題,挑硬的問。
訪談結束後,寫一份完整 spec 到 {./SPEC-subscription.md}。
[ENDING] spec 完成後 → 不要動手實作。
告訴我:「請開新 session,把 SPEC 當 input 來執行。」範本 4 — 安全的 mutation(代理人最容易出包的地方)
[ROLE] 你是執行 Shopify Admin mutation 的 careful operator。
[TASK] 把所有標籤含 {summer-2026} 的商品,
variant 售價 ≥ NT$1,500 的部分,變動價格為原價 85%。
[NON-NEGOTIABLE]
1. 先 dry-run:列出 affected products 與 affected variants
2. 計算每筆 old_price → new_price,輸出成 CSV 給我審
3. 等我打字確認 "EXECUTE" 才真的跑 mutation
4. 跑的時候用 productVariantsBulkUpdate(不是逐筆),分批 batch
5. 跑完後輸出:成功筆數、失敗筆數、失敗原因
6. 失敗的部分產生 rollback 指令(原價 list)
7. 全程用 --allow-mutations,完事後請我手動關掉
[STOP IF]
- dry-run 顯示 affected variants > {500}
- 任何 variant 的 new_price 算出來 < {50}(可能是資料錯)社群實戰整理的 常見操作錯誤 與對策。
以下內容來自 r/ClaudeAI、r/Shopify、r/ChatGPTCoding 開發者的實際回報,以及 Talk Shop、Charle、Flagship 等代理商的 post-mortem,官方文件未收錄。
FIELD NOTE · 01
關於環境
把代理人關在開發店裡跑 10 次以上,再讓它碰正式店
「scope 是給整類資源的,不是某幾筆」 授權
write_products的瞬間,代理人可以改店裡 每一個 商品。Talk Shop 社群統計:十次中有一次代理人會誤解你的指令邊界。把 mutation 設成需要逐次確認 Claude Code 預設 allow per command 而非 session-wide approval。永遠不要把
--dangerously-bypass-approvals-and-sandbox(yolo mode)用在正式店。正式部署前一定 commit 每次 non-trivial 的 prompt 之前 git commit 一次。Claude Code 不會自動 commit,壞掉的時候要
git reset --hard才有救。
FIELD NOTE · 02
關於 prompt
「先計畫,再執行」的操作方式
Shift + Tab 進 planning mode Claude Code 內建模式切換鍵。在 plan mode 下代理人只輸出計畫,不執行任何操作。確認計畫後再退出執行。r/ClaudeAI 開發者回報此操作顯著減少錯誤。
每個複雜任務都先 /init
/init命令會讓 Claude Code 掃整個專案、寫一份 CLAUDE.md 草稿。即使你已經有 CLAUDE.md,在大重構前讓它重做一次能補上你漏掉的脈絡。用截圖傳 UI 給代理人 Mac 上是
Control + V(不是 Cmd + V)貼圖到 Claude Code。「分析這頁 UI 並建議改進」會比文字描述精準十倍。長對話會 context rot 當代理人開始重複自己、忽略 CLAUDE.md 規則或產出品質下滑時,用
/clear重開,將現況記錄進 status.md 後再開下一個 session。
FIELD NOTE · 03
關於 subagent
四個值回票價的 subagent
liquid-reviewer 讀 Liquid 檔、跑 theme check、抓 Shopify house style 違規。每個 PR 都該過它。
metafield-wizard 專做 metafield definition、metaobject reference、product page 渲染。知道
list.product_reference跟list.single_line_text_field該何時用。theme-performance-auditor 跑 Lighthouse、讀輸出、提具體 Liquid 改動。之後再跑一次驗證進步。
app-extension-builder 限定能寫 theme app extensions、checkout UI extensions、Shopify Functions。對 extension target 分類熟到滾瓜爛熟。
每個 subagent 是 .claude/agents/{name}.md,YAML frontmatter 寫好 scope / tools / personality。 commit 進 repo 給整個團隊用。
FIELD NOTE · 04
關於 Codex 特有的招數
Codex CLI 的進階功能
把 Codex 自己當 MCP server
codex mcp serve讓 Claude Code 能呼叫 Codex。兩個不同模型互相審查同一段程式,可降低錯誤率。多 agent 協作要明確 ON
features.multi_agent = true才會啟用 spawn_agent、send_input、resume_agent。預設是開的,但低於 stable 之前手動確認一次。Project root marker monorepo 用
project_root_markers = [".git", "pnpm-workspace.yaml"]讓 Codex 知道從哪一層讀 AGENTS.md。/review 在送 PR 前執行 Codex 內建 review preset,讀取 diff 並輸出 prioritized findings,可在 PR 前發現程式問題。
FIELD NOTE · 05
關於資料 · 給 AI 購物代理人開門
讓 AI 購物代理人能找到並索引你的商品
商品標題要自然語言化 「Organic Cotton Sleep Mask, Blackout, Adjustable Strap」會贏「The Luna Collection · Midnight」。AI 代理人是用語意搜的,不是品牌敘事。
欄位填滿勝過稀疏 Google Product Category、availability、完整 variant data、metafield → 都要填。AI 代理人 ranking 看完整度。
robots.txt 要放 ClaudeBot / GPTBot / PerplexityBot 不允許 = 你不存在於 AI 漏斗。Shopify 預設允許,但很多 agency 客戶因為早期 SEO 工程師擋掉了,沒人想過要解開。
Hydrogen 升到 2026.1.4+ 此版本起內建 Storefront MCP,Oxygen 部署自動成為 agent endpoint。未升級的商店不會出現在支援 MCP 的 AI 購物漏斗中。
FIELD NOTE · 06
關於團隊與審查
讓代理人產出能被審查
每個 PR 都 commit CLAUDE.md / AGENTS.md 的變動 專案的「品牌聖經」是組織資產,版本化它。
Hooks 在執行前後做防呆 Codex 與 Claude Code 都支援 hook。
PreToolUse攔截危險 bash 指令,PostToolUse自動跑 theme check。Anthropic 官方 best practices 有完整範例。「Comprehension Debt」是真的 Hydrogen 團隊 Farhan Thawar 的警告:代理人寫得快,但兩三層下沒人懂的程式碼,半年後變維護地獄。每次大重構都留 30 分鐘給人類審。
八項 常見錯誤 與對應的正確做法。
上線後的 三條延伸路線 。
商店上線後,依目標可向三個方向延伸: 規模化 、 功能深化 或 產品化 。
→路線 1 · Hydrogen Headless
當 Liquid theme 撐不住你想做的互動深度時,用 Hydrogen(Remix-based 的 Shopify 框架)+ Oxygen 部署。Claude Code 的 Hydrogen subagent 能直接寫 routes、queries、components,且 Shopify Storefront MCP 從 2026.1.4 起 內建 到 Hydrogen。
→路線 2 · Custom App + Functions
要做 dynamic pricing、特殊 discount logic、checkout 客製,走 Shopify Functions(Wasm)+ Custom App。Claude Code 用 shopify app create scaffold,寫 Polaris React UI,跑 prisma migrate,全程不離終端機。TinyTwo 的 ReviewMate 案例(從零用 Claude Code 寫一個 production review app)是最佳參考。
→路線 3 · 多店舖編排
當你有 5 + 間商店要管時,把 Composio Tool Router 或社群 admin MCP 接進 Claude Code。一個自然語言指令打到 Claude → 並行操作多店:「 把所有店裡標籤含 holiday-2026 的商品庫存歸零並下架。 」
用 代理人 建構Shopify 商店
學習重點不在 Liquid 語法,在於 如何定義問題、選擇代理人、驗收輸出 。
— Agentic-Dev Field Manual · 2026 Edition
© 2026 · AGENTIC-DEV FIELD MANUAL · VOL.01
SOURCES: SHOPIFY DEV DOCS · TALK SHOP · ASK PHILL · CHARLE · CLAUDEFAST · FLAGSHIP · REDDIT R/CLAUDEAI · R/SHOPIFY
LAST UPDATED 2026.05.14