Claude Code for Magento Agencies — The Workflow That 3x'd My Ship Rate

Claude Code is Anthropic's terminal-resident coding agent that reads and writes files in a project, executes shell commands, and follows a per-project CLAUDE.md to ground itself in the codebase — for Magento 2.4.4 — 2.4.9 + Hyvä work it removes the most repetitive agency tasks (module scaffolding, MFTF authoring, Luma-to-Hyvä porting) and turns the developer into reviewer rather than typist.^[1] Below is the internal workflow we run at Panth Infotech — the one that took our average ship rate from one engagement per month to three.

CLAUDE.md is what makes the difference between a toy and a tool

Most failed Claude Code rollouts share one cause — no CLAUDE.md, or a one-paragraph version that says nothing useful. The agent reasons about a project it cannot see, every prompt re-explains the same context, and after three weeks the team quietly stops using it. A Magento agency runs 8 — 20 projects, each with its own version, Hyvä release, gateway mix, and deployment flow. CLAUDE.md has to encode all of that.^[3]

CLAUDE.md is not documentation. It is the conversation Claude Code would have to have with you on every prompt if the file did not exist. Write it that way.

The shape we ship on every project

The actual CLAUDE.md we drop at the root of every Magento engagement. Adjust versions and vendor namespace per project — the rest stays.

# CLAUDE.md

## Project
- Root: /srv/www/example-store/htdocs
- Magento: 2.4.9 (supported range: 2.4.4 — 2.4.9)
- PHP: 8.4 · Hyvä: 1.3.7
- Theme: Vendor/example (Hyvä; no Luma fallback)
- Vendor namespace for new modules: ExampleStore (app/code/ExampleStore)
- Stores: en_US (default), nl_NL

## Memory anchors
- Live deploy flow: DEPLOYMENT.md (read before any "apply on live" task)
- Module recipe: PRODUCT.md (sections 5b + 5c are load-bearing)
- SEO integration checklist: SEO_INTEGRATION.md
- MFTF patterns: tests/acceptance/README.md
- mage2kishan SEO modules: composer-installed; never edit vendor/mage2kishan/*

## Conventions
- Never edit vendor/ — extend via plugins, observers, di.xml, theme overrides
- declare(strict_types=1) on all new PHP files
- DataPatchInterface/SchemaPatchInterface only; no InstallData/InstallSchema
- Email templates: no nested {{depend}} or adjacent }}{{depend
- chmod a+r on pub/media uploads (CloudPanel umask 0007)

## May run unattended
- bin/magento setup:di:compile · cache:flush · static-content:deploy -f
- composer dump-autoload -o
- vendor/bin/phpcs --standard=Magento2
- vendor/bin/phpstan analyse -l 6 app/code

## Must ask first
- bin/magento setup:upgrade · composer require/update
- rm / find -delete / DROP TABLE
- Any SSH against the live host

## Out of context
- app/etc/env.php · var/log/* · pub/media/customer/*
- .git/objects · vendor/ · generated/ · var/cache/

That file is 35 lines and it changes how every prompt lands. Claude Code holds it in the system prompt for the life of the session and stops asking what Magento version the project runs.^[3]

Sub-agent recipe 1 — build-module

Most-used recipe. A client asks for "a module that adds a delivery date field to checkout and shows it on the order grid" — the output is a module shell that compiles cleanly, ready for business logic. Lives at .claude/agents/build-module.md.

---
name: build-module
description: Scaffold a Magento 2 module shell from a one-line feature description. Produces module.xml, registration.php, composer.json, initial di.xml.
tools: Read, Write, Edit, Bash
---

Scaffold a Magento 2.4.4 — 2.4.9 + Hyvä module under app/code/{Vendor}/{ModuleName}/:

1. registration.php — ComponentRegistrar::MODULE
2. etc/module.xml — sequence deps on Magento_Catalog/Sales/Checkout if relevant
3. composer.json — type magento2-module, require magento/framework ^103.0, PSR-4 autoload
4. etc/di.xml — empty  shell
5. README.md — one paragraph

Rules:
- Vendor namespace from CLAUDE.md (do not invent)
- All PHP files: declare(strict_types=1);
- Run module:enable, then phpcs --standard=Magento2 and fix violations
- Ask before running setup:upgrade
- No business logic — shell only; the next prompt fills it in

The trigger is one line: /build-module DeliveryDate — adds a delivery date field to Hyvä checkout and shows it on the admin order grid. Claude Code reads the recipe, pulls the vendor namespace from CLAUDE.md, scaffolds five files, runs phpcs, and reports back. End-to-end on a warm project: 10 minutes, versus 60 — 90 minutes by hand.

Sub-agent recipe 2 — write-mftf

MFTF is the test layer most agencies skip because the XML format is verbose and the docs are sparse. Claude Code closes that gap — it knows the schema, the action set, and converts a feature description into a working test.

---
name: write-mftf
description: Generate an MFTF acceptance test from a feature description. Produces Test/Section/Page/ActionGroup XML files.
tools: Read, Write, Edit, Bash
---

Write an MFTF acceptance test for Magento 2.4.4 — 2.4.9.

Produce under tests/acceptance/Tests/{Vendor}/{Module}/:

1. Test/{Feature}Test.xml — annotations: stories, title, description, severity (default AVERAGE), group
2. Section/{Feature}Section.xml — descriptive selectors, no positional xpath
3. Page/{Feature}Page.xml — URL references
4. ActionGroup/{Feature}ActionGroup.xml — only if a flow is used 2+ times

Rules:
- Reuse OOTB sections (CheckoutPaymentSection, AdminOrderFormSection) for core areas
- Selector priority: data-qa > id > descriptive class
- Test data lives under Data/, never inline
- Every test has  (create entities) and  (delete)
- Run vendor/bin/mftf generate:tests {Vendor}_{Module} to verify compile

Trigger: /write-mftf DeliveryDate — customer picks a delivery date in checkout, completes payment, sees the date on the order success page. Claude writes the four XML files, runs generate:tests, and reports compile errors. The 38-test backlog that sat on every project's Jira board drains over a single sprint.

Sub-agent recipe 3 — hyva-compat

The Luma-to-Hyvä compatibility port is the most lucrative recurring agency work — and the most repetitive. Manual ports take 8 — 14 hours per extension. The hyva-compat recipe collapses most of that.

---
name: hyva-compat
description: Port a Luma Magento 2 extension to Hyvä — phtml overrides, Alpine.js components from Knockout originals.
tools: Read, Write, Edit, Bash, Grep
---

Port a Luma extension to Hyvä 1.3.x. Given a path under vendor/ or app/code/:

1. Walk view/frontend/
2. Find phtml using x-magento-init / data-mage-init (need Hyvä replacements)
3. Find requirejs-config.js shims (Hyvä drops requirejs)
4. Find Knockout .html templates (become Alpine.js)

Emit under app/design/frontend/{Vendor}/{Theme}/{Vendor}_{ExtModule}/:
- phtml overrides with Alpine x-data/x-show/x-on instead of Knockout bindings
- web/js/{feature}.js if the Knockout component had logic worth keeping
- view.xml stub if the extension declared image dimensions

Rules:
- Never modify vendor/ directly
- Alpine components stay under 60 lines (split otherwise)
- Keep template paths identical so layout XML still resolves
- Run setup:di:compile after
- Report Knockout bindings that did not port cleanly

Trigger: /hyva-compat vendor/yotpo/magento2-reviews. Claude walks the directory, identifies 7 — 12 Knockout templates, emits Alpine equivalents, and flags the 2 — 3 components needing human review. Average port time: 4 hours against a 14-hour baseline.

The MCP stack — DataForSEO, Anthropic, custom Magento MCP

Model Context Protocol (MCP) is the standard that lets Claude Code talk to external tools without bespoke integration code.^[2] The three servers below are what a Magento agency actually needs.

DataForSEO MCP — SERP analysis without leaving the editor

Half of agency blog and landing-page work depends on "what does Google show for this keyword today?". DataForSEO MCP exposes live SERP, keyword volume, backlink, and Lighthouse endpoints to Claude Code, so the answer arrives without alt-tabbing to a dashboard.

# ~/.config/claude-code/mcp.json fragment
{
  "mcpServers": {
    "dataforseo": {
      "command": "npx",
      "args": ["-y", "dataforseo-mcp-server"],
      "env": {
        "DATAFORSEO_LOGIN": "",
        "DATAFORSEO_PASSWORD": ""
      }
    }
  }
}

Credentials never live in CLAUDE.md — they sit in the local MCP config at ~/.config/, outside any project tree and outside any context Claude reads. The agent calls DataForSEO when a prompt asks "top 10 SERP results for hyva theme development" and feeds the answer into the content brief.

Anthropic MCP — content drafts from inside the agent loop

Gives Claude Code a second Claude instance for long-form generation that should not happen in the main conversation (a 2,000-word blog draft, an email body, API docs). Main agent stays focused on code; secondary handles prose.

Custom Magento MCP — local product, order, and customer queries

The one we wrote in-house. Exposes read-only tools against the local Magento database: get_product_by_sku, get_order_by_increment_id, get_customer_by_email, list_recent_orders. Claude Code calls it when a debugging prompt needs context — "why does order 100000234 show paid but no invoice" — without running SQL by hand.

<?php
// app/code/Panth/McpServer/Tool/GetProductBySku.php
namespace Panth\McpServer\Tool;

use Magento\Catalog\Api\ProductRepositoryInterface;
use Panth\McpServer\Api\ToolInterface;

class GetProductBySku implements ToolInterface
{
    public function __construct(
        private readonly ProductRepositoryInterface $productRepository
    ) {}

    public function getName(): string { return 'get_product_by_sku'; }

    public function getSchema(): array
    {
        return [
            'type' => 'object',
            'properties' => ['sku' => ['type' => 'string']],
            'required' => ['sku'],
        ];
    }

    public function execute(array $input): array
    {
        $p = $this->productRepository->get($input['sku']);
        return [
            'sku' => $p->getSku(),
            'name' => $p->getName(),
            'price' => (float) $p->getPrice(),
            'status' => (int) $p->getStatus(),
            'qty' => (int) $p->getExtensionAttributes()?->getStockItem()?->getQty(),
        ];
    }
}

Registers via di.xml, lists its tools through the MCP protocol, and Claude Code consumes them like any other tool. Read-only by design. Two engineer-days to build the first version; hundreds of hours saved since.

The security boundary — what NEVER goes in CLAUDE.md

The most common mistake on every Claude Code rollout I have audited is leaking secrets into the context file. The agent reads CLAUDE.md at session start, sends it to the model as the system prompt, and can surface its contents in commit messages, draft docs, and slash-command output. Treat CLAUDE.md as if it were public.

Live hostnames and admin URLs are reconnaissance gold for credential-stuffing. Keep them in NOTES.local.md — .gitignore'd and excluded from context via .claudeignore.

The before/after metrics

Median across 12 Magento engagements between January and May 2026, from project tracker timers. "Manual" is a senior developer without Claude Code; "Claude Code" is the same developer with the setup above.

The total impact across a typical engagement: three weeks of solo dev time compressed into five working days. That is the 3x ship rate in the title — the line item in our kishansavaliya.com project tracker that lets us take three clients per month instead of one.

What Claude Code does not help with

• Production debugging under time pressure — when checkout is broken on live and the client is on the phone, an agent loop adds latency. Read the stack trace and ssh in.
• Performance tuning that depends on profiler output — Claude can read a Blackfire trace but cannot connect to one.
• Subjective design judgement — visual review stays human.

Rollout sequence for a small Magento agency

Six weeks, one step per week. Skipping steps is the most common failure mode.

1. Week 1 — install Claude Code, write CLAUDE.md for one active project, use it for code review and refactoring only.
2. Week 2 — add the build-module recipe. Scaffold one real module. Adjust the recipe until output matches your conventions.
3. Week 3 — add write-mftf and hyva-compat. Run them in parallel with manual writes for two weeks and grade the diffs.
4. Week 4 — install the DataForSEO MCP and the custom Magento MCP. Replace one research step per day with an MCP call.
5. Week 5 — roll out to the second and third developer. Each writes their own CLAUDE.md — no copy-paste.
6. Week 6 — audit every project's CLAUDE.md for leaks. Add a pre-commit hook that scans for API key patterns.

Related reading

• How to integrate ChatGPT with Magento 2 — 4 real patterns
• Alpine.js patterns for Hyvä developers
• Future of Magento with AI and Claude Code
• Magento 2 development service
• Hyvä theme development service