AI Coding Tools for OpenCart Extension Development: Claude Code, Cursor and Copilot Setup, Prompts and a Review Checklist

AI coding assistants are good at PHP and know a lot about OpenCart. The problem is which OpenCart. Ask for “an OpenCart module” without context and you’ll often get OpenCart 2 or 3 code: .tpl templates, $this->load->model('extension/module/...') paths, controllers without namespaces, or a vQmod file editing core code. It looks plausible and fails on OpenCart 4.

The fix is the same for every tool: give it a short, specific description of how OpenCart 4 extensions work, in the file that tool reads automatically, and review what it writes with a checklist. This guide covers both, for Claude Code, Cursor and GitHub Copilot.

Each tool’s instruction file

Tool	File it reads automatically	Notes
Claude Code	CLAUDE.md in the project root	Can also read an existing AGENTS.md; more files can be scoped with .claude/rules/
Cursor	.cursor/rules/*.mdc, or AGENTS.md	.mdc files have description, globs and alwaysApply front matter; the old .cursorrules file is deprecated
GitHub Copilot	.github/copilot-instructions.md	Also .github/instructions/*.instructions.md scoped to files, in VS Code

If your team uses more than one tool, write the instructions once in AGENTS.md and point the others at it (a one-line CLAUDE.md that says “Read AGENTS.md”, and a Cursor rule that includes it). Our earlier post on CLAUDE.md for the OpenCart developer goes deeper into Claude Code specifically.

Keep the file short. Anthropic’s documentation for Claude Code gives the reason:

Claude treats them as context, not enforced configuration. […] The more specific and concise your instructions, the more consistently Claude follows them.

Claude Code docs, How Claude remembers your project

GitHub’s guidance for Copilot instructions says the same thing in other words: short, self-contained statements work better than broad style requests. A 40-line file of concrete rules beats a 400-line essay.

A shared instruction file for OpenCart 4

This is a starting point for AGENTS.md (or CLAUDE.md). Every line prevents a mistake we’ve seen AI tools make in OpenCart 4 code:

# OpenCart 4.1 extension development

Target: OpenCart 4.1.0.x, PHP 8.1 to 8.5. Not OpenCart 2 or 3.

## Structure
- Extensions live in extension/<code>/ with admin/, catalog/, optionally system/library/, and install.json.
- Namespaces: Opencart\Admin\Controller\Extension\<CodeInCamel>\<Type> and
  Opencart\Catalog\Controller\Extension\<CodeInCamel>\<Type>. Models use ...\Model\Extension\...
- Routes use a dot before the method: extension/my_ext/module/my_ext.save
- Templates are Twig (.twig) in admin/view/template/<type>/ and catalog/view/template/<type>/.
- Package as <code>.ocmod.zip with install.json at the zip root, installed via Extensions > Installer.

## Never
- Never edit core files. Use events (registered in install(), removed in uninstall()) or OCMOD.
- Never write OpenCart 3 code: no .tpl, no extension/module/... model paths, no $this->load->model('extension/module/x').
- Never hardcode the table prefix: use DB_PREFIX.

## Security
- Cast every integer from a request: (int)$this->request->get['product_id'].
- Escape every string in SQL with $this->db->escape().
- OpenCart's Twig has autoescape OFF. Escape untrusted output with |e, or htmlspecialchars() in PHP.
- Check $this->user->hasPermission('modify', 'extension/<code>/<type>/<code>') in every admin save/delete action.
- Admin URLs need user_token. Catalog AJAX endpoints must validate input and return JSON.

## Conventions
- Settings: $this->model_setting_setting->editSetting('<type>_<code>', $post); read with $this->config->get('<type>_<code>_x').
- Language strings in admin/language/en-gb/<type>/<code>.php; never hardcode text in controllers or templates.
- Catalog view events: function x(string &$route, array &$data, string &$output): void
- Wrap event code in try/catch and log with $this->log->write(); a failing extension must never break the storefront.
- Product codes (SKU, EAN, MPN) are in the product_code table in 4.1, not columns on product.
- PHP 8.4+: pass the escape argument to fgetcsv/fputcsv. PHP 8.5: don't call curl_close().

## Before finishing
- Run php -l on every changed file.
- List the admin steps needed to test the change.

Adjust it to your projects: your extension prefix, your coding style, the OpenCart version you support.

A workflow that produces working extensions

AI tools do best with small, checkable steps, the same way a new developer would.

1. Plan first, in writing

Ask for a plan before code. In Claude Code, plan mode does this; in Cursor and Copilot, ask explicitly:

Plan an OpenCart 4.1 module extension called "free_shipping_bar" that shows
"Spend X more for free shipping" above the cart. Read AGENTS.md first.
List: files to create, events to register (trigger and method), settings,
and how it reads the free shipping threshold. Don't write code yet.

Read the plan. This is where you catch “I’ll modify catalog/controller/checkout/cart.php” (a core edit) or an OpenCart 3 path, before there are 500 lines to undo.

2. Build in slices

Then ask for one part at a time: the admin settings page first (install, settings form, save, permission check), then the storefront event, then the language files. After each slice, install the extension on a local store and click through it. A Docker setup for OpenCart makes reinstalling quick.

3. Give it real errors

When something fails, paste the exact error from System > Maintenance > Error Logs or the browser console, not a description. “Fatal error: Uncaught Error: Class \”Opencart\\Catalog\\Model\\Extension\\FreeShippingBar\\Module\\FreeShippingBar\” not found” tells the tool that the namespace or file path is wrong; “it doesn’t work” doesn’t.

4. Point it at OpenCart’s own code

The best reference for OpenCart 4 conventions is OpenCart 4 itself. Tell the tool which bundled extension to copy patterns from:

Use extension/opencart/admin/controller/module/html.php and
extension/opencart/catalog/controller/module/html.php as the pattern
for the settings page and module output.

Agentic tools like Claude Code and Cursor’s agent can open those files themselves when the OpenCart source is in the workspace.

5. Let CI check it

Linting and a PHP compatibility scan on every push catch the mechanical mistakes, whoever wrote the code. See Git, CI/CD and staging for OpenCart.

Prompts that work well

• Explain before changing: “Explain how OpenCart 4.1 calculates the cart price when a product has a discount for the customer group. Show the file and lines.” Useful before touching anything price-related.
• Upgrade old extensions: “Port this OpenCart 3 module to OpenCart 4.1. Keep the behavior. List every file you create and every OpenCart 3 API you replaced.” Then review each replacement.
• Fix deprecations: “Here is the error log after switching to PHP 8.4. Fix the deprecations in extension/my_ext only. Don’t change other folders.” Our PHP 8 guide lists the usual suspects.
• Write the test plan: “List the manual tests for this extension: storefront, admin, install and uninstall, multi-store and a second language.”

Review checklist for AI-written OpenCart code

Review AI output as you’d review a pull request from someone you just hired. These are the issues we find most often:

Check	What to look for
Version	No .tpl, no unnamespaced classes, routes with . not / before the method
Core edits	No changes outside extension/<code>/; behavior added through events or OCMOD
SQL injection	Every request value cast with (int)/(float) or passed through $this->db->escape(); no string-built ORDER BY from user input without a whitelist
XSS	Untrusted values escaped in Twig with the escape filter, or in PHP with htmlspecialchars(), because OpenCart’s Twig doesn’t auto-escape
Permissions	hasPermission('modify', ...) in every admin action that changes data
Install/uninstall	Tables, events, cron jobs and settings created in install() and removed in uninstall()
Failure isolation	Storefront events wrapped in try/catch, logging instead of crashing the page
Secrets	No API keys in code; settings or environment variables instead
Invented APIs	Every method the code calls exists in your OpenCart version (search the source)

The last row deserves emphasis: AI tools sometimes call OpenCart methods that sound right but don’t exist, or existed in another version. A quick search of the OpenCart source for each unfamiliar method name catches them.

Beyond writing code

AI tools can also operate on a store through the Model Context Protocol. Our OpenCart MCP server lets an assistant read products and orders from your store, and our free AI shop assistant extension shows how to give a model a narrow set of read-only tools inside OpenCart. Both follow the same principle as the checklist above: give the AI exactly the access the task needs, and check what it produces.

Leave a Reply Cancel reply

Your email address will not be published. Required fields are marked *

Comment *

Name *

Email *

Website

Δ