Claude Code + Shopify CLI: Real Workflow With Proven Prompts

Why this isn't another "install the CLI" tutorial

Shopify CLI tutorials are everywhere. Official docs. YouTube videos by people who opened it once and recorded the setup.

What's missing is the inside view: how to ask Claude for things without burning tokens, when human hands are still faster, which prompts work in real production. That's the difference between cutting a 2-hour task down to 20 minutes, and spending the afternoon stuck in error loops.

This article aims squarely at that.

Setup

Three commands:

# Install Shopify CLI
npm install -g @shopify/cli @shopify/theme

# Login to your store
shopify login --store my-store.myshopify.com

# Pull the current theme to your machine
shopify theme pull

That leaves you with the full theme local. In a separate terminal, inside the theme folder:

# Spin up local preview with hot reload
shopify theme dev

Open Claude Code in that same folder. From there you can work on the theme.

Context, context, context

This is 80% of the difference between Claude running efficient and Claude burning tokens.

Without prior context: you ask "add a FAQ section to the theme." Claude starts reading files at random trying to understand your setup. Reads 15 files to figure out the framework, naming conventions, which apps interact with what. Burns tokens and sometimes misinterprets.

With prior context (onboarding prompt): you paste a prompt at the start of the session that explains everything. Stack, key apps, what NOT to touch. Claude summarizes what it understood, confirms with you, and starts productive from minute one.

This is the prompt I paste at the start of every new session connected to my Shopify:

You're going to work on my Shopify store's theme. Before touching code, here's the context:

STACK
- Theme: [theme name, e.g. Dawn / Impulse / custom]
- Liquid + JS vanilla / Alpine.js / [other framework if any]
- Active languages: [es, en, etc.]

KEY APPS THAT TOUCH THE THEME
- [App 1 — what it does in the theme]
- [App 2 — what it does]
- [App 3 — what it does]
(These apps inject their own snippets. Don't touch them without asking me.)

PROJECT CONVENTIONS
- Components: snippets/ for reusables, sections/ for schema-driven.
- Naming: [your convention, e.g. kebab-case]
- My custom code lives in: [folder or prefix]

WHAT YOU DON'T TOUCH WITHOUT ASKING
- /checkout.liquid and anything related to checkout
- Payment configs (payment-method snippets)
- Tracking scripts (GA4, Meta Pixel, TikTok Pixel)
- Any snippet starting with "app-"

WORKFLOW
- I test changes locally with "shopify theme dev" before pushing.
- NEVER run "shopify theme push" unless I explicitly ask for it.
- If a task is ambiguous, ask before assuming.

Confirm you understood and summarize in 3-5 lines what you know about the project before starting.

Why it works: it gives Claude three things it can't infer on its own.

1. Which apps inject code (Klaviyo, reviews app, COD form, etc.) — info that lives in Shopify admin, not in the files.
2. What you can't break — the checkout, tracking pixels, app snippets. Without this, Claude feels free to "clean up" critical files.
3. Your workflow — local first, manual push. Without this, it offers to push directly and can break your live store.

I paste this at the start of every new session. Thirty seconds of setup that saves hours of debugging later.

How I iterate day to day

Two terminals open. One running shopify theme dev for the local preview. The other for Claude Code inside the theme folder.

When I ask for a change:

1. Claude reads, analyzes, proposes. Ideally without touching files yet.
2. I approve or adjust the proposal.
3. Claude edits.
4. I refresh the local preview and check visually.
5. If it looks good, move on. If not, another round.
6. When I finish the day's batch, I do the push manually: shopify theme push --unpublished (to a staging theme first) and review there before publishing.

Claude doesn't run git push or shopify theme push automatically. That friction is the only protection against production incidents.

The 7 prompts I use most

You paste these into a Claude Code session (with the Onboarding already loaded), replace the bracketed placeholders, and they're ready.

Prompt 2: Full theme audit

Useful when inheriting a theme or before big changes. Returns an inventory of the current state without touching anything.

Run an audit of the theme focused on:

1. PERFORMANCE
   - Blocking scripts (missing defer/async)
   - Non-optimized images or missing lazy-loading
   - Unused or duplicate CSS
   - Web fonts loaded unnecessarily

2. TECHNICAL SEO
   - Meta tags present and correct
   - Structured data (Product, Organization, BreadcrumbList)
   - Canonicals
   - hreflang if multi-language

3. ACCESSIBILITY
   - Color contrast (AA minimum)
   - Labels on form inputs
   - Keyboard navigation
   - Alt text on images

4. MOBILE
   - Correct viewport
   - Tap targets at least 44px
   - Layout shift (CLS)

RETURN:
- Issues found, grouped by priority (critical/high/medium/low)
- For each: file and line, what's happening, estimated impact, proposed fix
- DO NOT modify anything yet. Just the report.

Prompt 3: Optimize product page for conversion

The one I use most. PDP defines conversion.

I'll share the main product page file (sections/main-product.liquid or equivalent).

ANALYZE AND PROPOSE CONVERSION IMPROVEMENTS:

1. Visual hierarchy of info
   - Price: location and prominence
   - Variants (size, color): clear or ambiguous UI
   - Main CTA: above the fold? competing CTAs?

2. Social proof
   - Reviews visible without scroll?
   - Trust badges present?

3. Urgency / scarcity (without manipulating)
   - Stock visible when low?
   - Estimated shipping time visible?

4. Variant clarity
   - Visual stock indicator per variant
   - Sensible default selection

5. Info that reduces returns
   - Size chart
   - Inline FAQ
   - Material / care instructions

FOR EACH SUGGESTION:
- Show the exact code change
- Explain why (based on best practice or data)
- Warn if it breaks existing logic (variants, tracking, etc.)

Don't apply anything. First the analysis with proposals. I decide which to apply.

Prompt 4: Create a custom section from scratch

For when you need something the theme doesn't have. Important: ask for schema first, code after.

I need a custom section called [name-in-kebab-case]. Functionality:

[Describe in clear language what it does, e.g.:
"Shows 3 USPs (icon + title + text) in horizontal grid on desktop,
vertical stack on mobile. Each USP configurable separately from theme editor."]

REQUIREMENTS:
- Configurable from theme editor (settings + blocks)
- Mobile-first responsive
- Accessible (semantic HTML, aria where appropriate)
- No external libraries if avoidable
- Compatible with OS 2.0

BEFORE WRITING CODE:
1. Show me the proposed schema (settings and blocks).
2. Confirm it'll work on any OS 2.0 theme.
3. Tell me if the feature needs additional assets (CSS, JS).

After my OK on the schema, generate the full file.

Prompt 5: Checkout or flow debugging

When something breaks in production and you don't know what. Critical: don't touch code until cause is confirmed.

I'm seeing this problem:

SYMPTOM: [exact description of what's happening]
STEPS TO REPRODUCE: [if you have them; if not, say "intermittent"]
SINCE WHEN: [how long it's been happening]
RECENT CHANGES: [app updates, theme push, etc.]

BEFORE PROPOSING A FIX:

1. Make hypotheses about possible causes, ordered by likelihood.
2. For each hypothesis, tell me how to verify it:
   - Which logs to check
   - Which files to inspect
   - Which request to inspect in DevTools Network
   - Which Shopify admin config to check

3. DO NOT modify anything until we confirm the cause.

If you suspect the problem comes from a third-party app:
- Tell me how to isolate it (disable the app, see if it persists)
- Show me which scripts that app injects that could be related
- DON'T touch the app's code, only our theme

Prompt 6: Migrate from one app to another

For when you replace one app with another (typical: switching reviews app, COD form, etc.). Risk is leaving zombie code from the old app.

We have [App A] installed doing [function].
We're going to migrate to [App B] because [reason].

I NEED:

1. INVENTORY of all theme logic that touches [App A]:
   - Snippets that include its code
   - Sections that depend on its API
   - Scripts listening to its events
   - CSS styling its elements

2. MAPPING of what to adapt for [App B]:
   - Different API (what changes in the calls)
   - Different events (names, payloads)
   - Tracking hooks if any

3. MIGRATION PLAN in steps:
   - Each step with its rollback point
   - What to test after each step
   - How to run both apps in parallel during transition (if possible)

4. CLEANUP CHECKLIST when done:
   - Which snippets to remove
   - Which assets to clean
   - Which settings to uninstall

Don't start migrating until I approve the plan.

Prompt 7: Performance audit with real metrics

When "the store feels slow" and you need real data, not impressions.

I need to understand why the store feels slow on mobile (low Lighthouse mobile score, or real user complaints).

FIRST ASK ME FOR THE DATA YOU NEED:
- PageSpeed Insights URL of home, a PDP, the cart
- Lighthouse local report (I'll paste it)
- Network tab capture filtered by type
- List of installed apps that inject scripts

AFTER ANALYSIS:

1. Identify the TOP 5 blockers with their metric:
   - Blocking script: execution time, kb
   - Heavy image: file, weight, dimensions
   - Third-party tag: domain, weight, priority

2. Prioritize by impact / fix-effort ratio.

3. For the top 3, show me:
   - The exact change to make (with code if it's theme)
   - The expected LCP/CLS/FID delta
   - If it requires app intervention (can't be touched from theme)

DON'T touch code yet. First the report.

Prompt 8: Multi-language without breaking existing translations

For when you add a new language to the theme. Watch out for hardcoded strings.

The store sells in [current countries]. I need to add [new language] to the theme.

TASK:

1. SCAN all .liquid theme files looking for hardcoded strings not using the "t" filter system (e.g., "Add to cart" hardcoded instead of using the t filter syntax).

2. LIST the strings found, grouped by file. For each:
   - File and line
   - Exact string
   - Suggested key for the locales JSON (e.g., "product.add_to_cart")

3. MOVE the strings to the locales JSON (locales/es.default.json, locales/en.json, etc.)
   - Keep existing translations intact
   - For new strings, leave the original in es and empty in other locales

4. REPLACE the hardcoded strings in .liquid with the "t" filter syntax.

Don't translate. I load translations later in each locale.json.

Confirm how many strings you found BEFORE moving them, so I approve the scope.

When NOT to use Claude

Honest take: it's not the tool for everything. Cases where human hands are faster or safer:

• You know the exact change and it's a single line. Change a CSS color. Edit a piece of copy. Faster to edit directly than ask.
• Context required is huge and unique. If you have to explain 20 minutes of context for a small change, do it yourself.
• Something that touches sensitive Shopify admin configs. Payments, taxes, shipping zones. That lives in admin, not theme. Claude doesn't have access. Do it yourself.
• Debugging that requires seeing real production behavior with your logged-in session. Claude can't see your admin. You can pass logs or screenshots, but sometimes you're faster directly.
• Changes that require business intent only you have. "What price should we set on this product?" — not Claude's job.

Three habits that changed my speed

If you only take three things from this article:

1. Onboarding session always. Prompt 1 at the start. No exceptions. The thirty seconds invested pay off the first five times Claude doesn't get confused with apps it didn't know about.

2. Push is on you. shopify theme push runs manually against a staging theme first. Friction is the only protection against production incidents.

3. One session per domain. Don't mix PDP tweaks, checkout debugging, and Klaviyo integration in the same session. Each needs its own context. Separate sessions keep context clean and token consumption under control.

Verdict

Frequently asked questions

How much does Claude Code cost for Shopify?

Claude Code requires a Pro plan ($20/month) or API. For operator use on a Shopify, Pro plan is more than enough. Compared to a freelance dev cost ($30-80/hour), it pays for itself with the first task that saves you an hour.

Does it replace a senior dev?

No, complements. For operational tasks (PDP optimization, custom sections, routine debug, multi-language) time savings are significant. For complex architecture, stack decisions, or customizations affecting checkout/payments, senior dev is still needed.

Does it work with custom themes or only Dawn?

Works with any OS 2.0 theme. The more standard (Dawn, Impulse, Prestige) the easier because Claude knows the conventions. With unusual custom themes, Prompt 1 Onboarding compensates: you explain the specific conventions and it adapts.

Do I need to know Liquid for this?

Helps a lot. You don't have to be an expert, but understanding the difference between snippet, section, template, knowing the theme editor, and reading basic Liquid makes the difference between asking vague things and losing time, or asking precise things that move fast. If you're starting from scratch, dedicate 2-3 days to official Liquid documentation before intensive use.

What about Shopify Plus?

Same workflow, with a warning: Plus has customizable checkout.liquid (not available in Basic/Advanced). That expands a lot of what's possible with Claude — and also the risk. Prompt 1 restrictions need to be stricter on Plus, not looser.