As AI coding assistants become part of everyday development, one challenge quickly becomes obvious: they only know what you tell them. Without project-specific guidance, even the best AI models may generate code that doesn’t match your framework conventions, architecture, or coding standards.
For OpenCart developers, this is where a CLAUDE.md file becomes incredibly valuable.
What Is CLAUDE.md?
CLAUDE.md is a project-level instruction file used by Claude Code to understand how it should work within your repository. Think of it as onboarding documentation for your AI pair programmer.
Instead of explaining your project’s conventions every time you ask for help, you define them once in CLAUDE.md. Claude then uses those instructions to generate code that aligns with your existing codebase.
The result is more consistent code, fewer corrections, and a development workflow that feels much more like collaborating with an experienced teammate.
Why OpenCart Projects Benefit
OpenCart has its own architecture, conventions, and extension mechanisms that differ significantly from generic PHP applications. A general-purpose AI assistant may not automatically know that:
- Business logic belongs in models.
- Controllers should remain lightweight.
- User-facing text belongs in language files.
- Twig templates should contain presentation logic only.
- Database queries should use the OpenCart database abstraction layer.
DB_PREFIXshould always be respected.- Events or OCMOD are preferred over modifying core files.
- Admin URLs require security tokens.
- Permissions must be validated before performing administrative actions.
Encoding these expectations in CLAUDE.md helps ensure the AI follows established OpenCart practices from the beginning.
What Should Be Included?
A well-written CLAUDE.md should describe how the project is organized and how new code should be written.
Typical sections include:
- Project overview
- Supported OpenCart versions
- Directory structure
- Coding standards
- MVC guidelines
- Database conventions
- Language file usage
- Security practices
- Extension development
- OCMOD and Event preferences
- Testing checklist
- Deployment expectations
Rather than documenting every implementation detail, focus on the rules that guide consistent development decisions.
Example Instructions
For an OpenCart project, your CLAUDE.md might include instructions such as:
- Load models using OpenCart’s loader.
- Never hardcode database table prefixes.
- Store UI text in language files.
- Use Twig for presentation only.
- Validate permissions in every admin controller.
- Prefer Events or OCMOD over core modifications.
- Cast numeric IDs before using them in SQL queries.
- Reuse existing models whenever possible.
These simple guidelines dramatically improve the quality of AI-generated code.
Keeping Your Architecture Consistent
One of the biggest advantages of CLAUDE.md is architectural consistency.
Without project guidance, an AI assistant might:
- Place business logic inside controllers.
- Duplicate existing models.
- Hardcode configuration values.
- Introduce a new JavaScript framework into a jQuery-based application.
- Edit OpenCart core files unnecessarily.
A good CLAUDE.md establishes clear boundaries and encourages solutions that fit naturally within your application.
# CLAUDE.md
## Project Overview
This is an OpenCart eCommerce application.
Primary objectives:
- Maintain compatibility with the existing OpenCart version.
- Follow OpenCart MVC architecture.
- Prefer OCMOD/Event system over core modifications.
- Keep backward compatibility whenever possible.
- Minimize breaking database changes.
---
# Tech Stack
- PHP 8.x (follow project requirement)
- OpenCart
- MySQL / MariaDB
- Twig Templates
- JavaScript (Vanilla + existing libraries)
- Bootstrap (existing version)
- jQuery (existing version)
---
# Directory Structure
Typical directories:
```
admin/
catalog/
system/
extension/
image/
storage/
```
Important MVC locations:
```
admin/controller/
admin/model/
admin/view/
catalog/controller/
catalog/model/
catalog/view/
```
Language files:
```
admin/language/
catalog/language/
```
Twig templates:
```
*.twig
```
---
# Coding Standards
## PHP
- Follow PSR-12 where practical.
- Use strict comparisons.
- Use descriptive variable names.
- Keep controller actions small.
- Business logic belongs in models.
- Avoid duplicated SQL.
- Prefer OpenCart database abstraction.
Example:
```php
$query = $this->db->query(
"SELECT * FROM `" . DB_PREFIX . "product` WHERE product_id = '" . (int)$product_id . "'"
);
```
Always cast IDs to integers.
Never concatenate raw user input into SQL.
---
## Controllers
Controllers should:
- Validate permissions
- Validate input
- Call models
- Prepare `$data`
- Load language
- Render view
Avoid business logic inside controllers.
---
## Models
Models should:
- Handle SQL
- Handle reusable business logic
- Return structured arrays
- Never echo output
---
## Views
Views should:
- Contain presentation only
- Avoid business logic
- Use Twig syntax
- Escape output when appropriate
---
# OpenCart Conventions
Always load dependencies using OpenCart loaders.
Example:
```php
$this->load->language('extension/module/example');
$this->load->model('catalog/product');
$this->load->model('setting/setting');
```
Avoid direct includes.
---
# Language Files
Never hardcode UI strings.
Always use:
```php
$_['text_success']
$_['entry_name']
$_['error_permission']
```
Controller:
```php
$data['heading_title'] = $this->language->get('heading_title');
```
---
# Configuration
Use configuration values:
```php
$this->config->get('config_name');
```
Avoid hardcoded configuration.
---
# URL Generation
Generate admin URLs using:
```php
$this->url->link(...)
```
Always include:
- user_token (OpenCart 3)
- route
Do not hardcode admin URLs.
---
# Security
Always:
- Validate permissions
```php
$this->user->hasPermission(...)
```
- Validate CSRF tokens where applicable.
- Escape output.
- Sanitize filenames.
- Cast numeric IDs.
- Validate uploaded files.
- Prevent directory traversal.
- Prevent SQL injection.
- Prevent XSS.
Never trust:
- GET
- POST
- COOKIE
- FILES
---
# Database
Prefer existing tables.
Before creating a new table, verify one does not already exist.
Use:
```php
DB_PREFIX
```
Never hardcode prefixes.
Example:
```php
"SELECT * FROM `" . DB_PREFIX . "customer`"
```
---
# Events
Prefer Events over core edits.
If extending functionality:
1. Events
2. OCMOD
3. Core modification (last resort)
---
# OCMOD
If modifying OpenCart behavior:
Prefer generating an OCMOD XML instead of editing core files.
Only edit core when explicitly requested.
---
# Extension Development
Structure:
```
extension/example/
admin/
catalog/
system/
```
Include:
- controller
- model
- language
- view
Keep admin and catalog separated.
---
# Settings
Persist module settings using:
```php
model_setting_setting
```
Do not write configuration directly to the database.
---
# Error Handling
Return meaningful errors.
Avoid:
```php
die();
exit();
print_r();
var_dump();
```
Use:
- logs
- exceptions
- OpenCart error handling
---
# Logging
Use:
```php
$this->log->write(...)
```
Do not leave debug statements in production.
---
# JavaScript
Prefer existing OpenCart patterns.
Avoid introducing new frameworks.
Use vanilla JS where possible.
If existing code uses jQuery, remain consistent.
---
# CSS
Reuse existing Bootstrap classes.
Avoid large custom CSS unless necessary.
---
# Performance
Prefer:
- single SQL query
- indexed lookups
- pagination
- lazy loading where applicable
Avoid:
- N+1 queries
- unnecessary loops
- repeated model loading
---
# Cache
Respect OpenCart cache.
Use:
```php
$this->cache
```
when appropriate.
Clear caches only when necessary.
---
# File Uploads
Validate:
- extension
- MIME type
- file size
Never trust filenames.
Generate safe filenames.
---
# API
When adding API endpoints:
- validate authentication
- validate permissions
- return JSON
- use proper HTTP status codes where supported
---
# Admin UI
Follow existing OpenCart UI.
Use:
- breadcrumbs
- success messages
- warning messages
- pagination
- tokenized URLs
Maintain consistency with the admin theme.
---
# Forms
Always validate:
- required fields
- permissions
- data types
Populate validation errors via:
```php
$error['field']
```
---
# Installation
Installation scripts should:
- create tables only if absent
- add indexes if missing
- avoid destructive changes
- support repeated execution safely
Uninstall should clean up only extension-owned data.
---
# Backward Compatibility
Do not remove:
- existing events
- hooks
- language keys
- config values
- database columns
without explicit approval.
---
# Version Compatibility
Before using new APIs, verify compatibility with the target OpenCart version.
Avoid features unavailable in supported versions.
---
# Testing Checklist
Before submitting changes:
- PHP syntax passes
- Admin pages load
- Catalog pages load
- No warnings/notices
- No fatal errors
- Language strings resolve
- URLs generate correctly
- Permissions verified
- SQL queries work
- Module installs
- Module uninstalls
- Cache cleared if needed
---
# When Making Changes
Claude should:
1. Search for existing implementations before creating new ones.
2. Preserve OpenCart coding style.
3. Minimize file modifications.
4. Explain architectural changes.
5. Avoid unnecessary refactoring.
6. Keep patches focused.
7. Maintain backward compatibility.
8. Update language files when UI changes.
9. Update both admin and catalog sides when required.
10. Prefer Events/OCMOD over core edits.
---
# Avoid
- Editing OpenCart core without request
- Hardcoded SQL prefixes
- Hardcoded URLs
- Inline HTML in controllers
- Business logic in Twig
- Business logic in controllers
- Duplicate code
- Unvalidated input
- Direct SQL with raw input
- Debug output in production
---
# Preferred Workflow
When implementing a feature:
1. Understand the OpenCart version.
2. Identify existing patterns.
3. Reuse existing models where possible.
4. Create language entries.
5. Implement model.
6. Implement controller.
7. Implement Twig template.
8. Validate permissions.
9. Test admin.
10. Test storefront.
11. Check logs for warnings/errors.
Always aim for maintainable, OpenCart-native solutions that integrate cleanly with the existing architecture.Better Code Reviews
When everyone on a team uses the same project instructions, AI-generated code becomes much more predictable.
Reviewers spend less time pointing out style violations or architectural inconsistencies and more time evaluating business logic and functionality.
This leads to:
- Smaller pull requests
- Faster reviews
- Fewer revisions
- More maintainable code
Faster Onboarding
New developers often need time to learn an existing OpenCart project’s conventions. A comprehensive CLAUDE.md serves as both AI guidance and lightweight documentation for human contributors.
Instead of relying solely on tribal knowledge, the project’s expectations are documented in one place.
This benefits both developers and AI assistants.
Easier Extension Development
OpenCart extension developers often need to maintain compatibility across multiple stores and versions.
A CLAUDE.md can specify important rules such as:
- Preserve backward compatibility.
- Avoid destructive database migrations.
- Separate admin and catalog functionality.
- Register events instead of editing core files.
- Store settings using OpenCart’s configuration models.
- Clean up only extension-owned data during uninstall.
These practices help produce extensions that are easier to maintain and more compatible with future OpenCart releases.
Living Documentation
Your project evolves over time, and your AI instructions should evolve with it.
Whenever you adopt a new coding standard, architectural pattern, or deployment workflow, update your CLAUDE.md. The AI immediately benefits from the new guidance without requiring repeated explanations.
Treat it as living documentation that grows alongside your application.
Final Thoughts
AI coding assistants are most effective when they understand the context of the project they’re working on. For OpenCart developers, a thoughtfully crafted CLAUDE.md provides that context by documenting architecture, coding standards, and development expectations.
Whether you’re building custom modules, maintaining client stores, or developing marketplace extensions, investing a little time in a comprehensive CLAUDE.md can lead to more consistent code, fewer mistakes, and a smoother development experience.
As AI becomes a standard part of modern software development, project-specific guidance is no longer a nice-to-have—it’s an important part of maintaining quality and consistency across your codebase.
