Repository navigation
developer guide
A practical guide for Magento developers working with AI agents powered by Bricklayer. This is about how you should work — what to ask, how to structure your requests, and how to avoid burning through tokens on wasted cycles.
Bricklayer gives your AI agent live access to your Magento installation — it can read your database schema, inspect DI configuration, check plugin chains, query products, diagnose errors, and generate code that fits your actual setup. The agent doesn't have to guess or rely on generic Magento knowledge alone.
But the agent only uses these capabilities well if you guide it. A vague prompt produces vague results. A precise prompt backed by Bricklayer produces code that works on first try.
The single most impactful habit: always ask the agent to investigate your codebase before generating anything.
Without this, the agent writes code based on generic Magento patterns. With it, the agent writes code that accounts for your existing plugins, preferences, DI overrides, custom EAV attributes, and database customizations.
Bad:
"Create a plugin that modifies the product save process."
The agent writes a generic plugin. It might conflict with three other plugins you already have on the same method.
Good:
"I need to modify the product save process. Check what plugins already exist on
Magento\Catalog\Api\ProductRepositoryInterfaceand what DI configuration is set for it, then create a plugin that adds a custom validation step."
The agent now calls check-class (which combines plugin-list, di-configuration, and preference-list in one call), sees the full interceptor chain, and writes a plugin with the correct sort order that doesn't conflict.
Other examples:
"Before writing the data patch, check the current schema for the
catalog_product_entitytable and show me what custom EAV attributes exist for products."
"Look at how order processing currently works — check the event observers on
sales_order_place_afterand the plugins onOrderManagementInterface— then suggest where my custom logic should hook in."
Token cost scales with ambiguity. The more the agent has to guess, explore, and iterate, the more tokens it burns.
Expensive (vague):
"Help me set up a custom module for managing warranties."
The agent doesn't know scope, so it asks clarifying questions or over-builds a full CRUD system you didn't need.
Cheap (specific):
"Create a module
Vendor_Warrantythat adds awarranty_periodEAV attribute to products (integer, in months) and displays it on the product detail page. We use Hyvä theme. Check our current product EAV attributes first."
One focused cycle. The agent checks existing attributes, loads Hyvä context, generates exactly what's needed.
Things worth specifying upfront:
- The module vendor and name
- Which theme you're using (Luma, Hyvä, or custom)
- Whether it's frontend, admin, or API work
- If you need it to work with specific existing modules or customizations
- Your PHP/Magento version if it matters for the task
Bricklayer's biggest value isn't code generation — it's live introspection. Before you can fix a problem or extend functionality, you need to understand what's there. Train yourself to ask investigation questions:
"What plugins are active on
Magento\Checkout\Model\Session?"
"Show me the DI configuration for
Magento\Sales\Api\OrderRepositoryInterface— I want to see if anyone has a preference or proxy set up."
"Check the database schema for tables matching
warranty— I want to see if someone already created these."
"How many products do we have with status disabled? Don't fetch them, just give me the count."
"Look at the recent exception log and tell me what's going wrong."
These are cheap calls that give you a clear picture before you spend tokens on code generation.
Magento stores have thousands of products, hundreds of categories, and complex order histories. Pulling full datasets through the agent wastes massive amounts of tokens. Tell the agent to be selective:
Ask for counts first:
"How many orders are in
processingstatus? Just the count, don't list them."
The agent uses count_only=true — one small response instead of a huge list.
Request specific fields:
"List the last 20 orders, but only show me order number, status, total, and date."
The agent uses the fields parameter to return only what you asked for.
Use minimal verbosity for overviews:
"Give me a quick overview of all installed modules — just names and whether they're enabled."
Then drill into specific ones:
"Now show me the full details for
Vendor_CustomModule."
The pattern is: overview → filter → detail. Don't start at detail level.
When your question involves logic, calculations, or combining data from multiple sources, tell the agent to use code-runner instead of chaining multiple tool calls. Each tool call has overhead. A single code-runner call that does five lookups in PHP is cheaper and faster than five separate tool calls.
"Use code-runner to find all products that are assigned to category 42 but have qty=0. Show me their SKUs and names."
"Run a code-runner script to check if all payment methods have valid configuration — loop through active methods and verify their required fields are set."
"Use code-runner to compare the product count per category in the default store vs. the German store."
This is especially valuable for one-off investigations you'd otherwise do with multiple manual queries.
Bricklayer has 38 development context categories covering everything from Hyvä checkout to message queues. Each one adds tokens when loaded. Don't load them preemptively — load them just before the agent needs to write code in that domain.
Don't do this:
"Load all Hyvä contexts and checkout contexts, then help me fix a small CSS issue on the product page."
Do this:
"I need to fix a styling issue on the Hyvä product page. Load the Hyvä theme context and show me how component styling works."
If you're just investigating or asking questions, you often don't need context loaded at all. Context is for when the agent is about to write code.
When something breaks, don't paste the full stack trace into the chat and ask "what's wrong?" Bricklayer can read your logs directly and cross-reference them with your DI configuration, plugin chains, and system status.
Expensive (copy-pasting logs):
"Here's my error: [300 lines of stack trace]. What's wrong?"
Those 300 lines cost tokens and the agent still needs to look up your configuration.
Cheap (let Bricklayer read the logs):
"Something's broken — diagnose the latest error. Also check if any indexers are invalid or caches are disabled."
The agent calls diagnose-error (which parses the log, checks DI, reviews system status, and suggests fixes) and system-status — using structured data instead of raw text.
For specific errors:
"I'm getting an error when saving products in the admin. Diagnose the latest error, then check what plugins exist on the product save process."
For larger tasks, break your request into clear phases. This prevents the agent from going down the wrong path and having to redo work (which is the most expensive kind of token waste).
Instead of one giant prompt:
"Build me a complete warranty management system with admin grid, REST API, product attribute, and frontend display using Hyvä."
Break it into phases:
Phase 1: "Check if any warranty-related tables, attributes, or modules already exist in our installation."
Phase 2: "Based on what you found, create the base module with the database schema and EAV attribute. Load the module and EAV development contexts first."
Phase 3: "Now add the admin grid. Load the adminhtml and UI component contexts."
Phase 4: "Add the REST API endpoint. Load the REST API context."
Phase 5: "Add the Hyvä frontend display. Load the Hyvä theme context."
Each phase builds on confirmed results from the previous one. If Phase 1 reveals an existing warranty table, the entire plan adjusts — saving you from generating code that conflicts.
You don't need to explain basic Magento concepts to the agent. Bricklayer's guidelines system already covers coding standards, architecture patterns, XML schema conventions, and DI patterns. Adding these instructions yourself just burns tokens.
Unnecessary:
"Create a plugin. Remember to use
strict_types, follow PSR-12, use the correct XML schema declarations, register the module withregistration.php, and make sure thedi.xmluses the proper format..."
Sufficient:
"Create a before-plugin on
Magento\Catalog\Model\Product::getNamein moduleVendor_CustomCatalogthat prepends '[SALE]' for products with special price."
The agent already knows the coding standards. Focus your prompt on the business logic, not the boilerplate rules.
Long conversations accumulate context and cost more per message as the conversation grows. For best results:
- One task per conversation. Don't mix "fix this bug" with "also build me a new module" in the same session.
- Start new conversations for new topics. The agent will reconnect to Bricklayer fresh each time.
- If a conversation goes sideways, start over. A clean start with a better prompt is cheaper than 10 rounds of correction in a bloated context.
-
After
setup:upgradeordi:compile, tell the agent to reinitialize. Bricklayer detects this automatically in most cases, but if you notice stale results, say "reinitialize the Magento connection."
Copy and adapt these for common scenarios:
Investigating before coding:
"Before writing any code, check [specific classes/tables/attributes]. Then [create/modify] [what you need]."
Debugging:
"Diagnose the latest exception. Also check indexer and cache status."
Focused code generation:
"Create [specific component] in module
Vendor_Module. We use [Hyvä/Luma]. Load [relevant] context first. Check for conflicts with existing [plugins/preferences/observers]."
Data questions (token-efficient):
"How many [entities] match [condition]? Just the count." "List [entities] with [condition], only show [field1, field2, field3]."
Multi-step task kickoff:
"I need to build [feature]. Before we start, check what already exists: [specific things to look for]. Then we'll plan the implementation."
| Don't | Why | Instead |
|---|---|---|
| Paste full stack traces into chat | Wastes tokens; agent can read logs directly | Ask it to diagnose the latest error |
| Ask for "all products" or "all orders" | Massive token cost, often unnecessary | Ask for counts first, then filtered subsets |
| Load every development context upfront | Each context adds tokens to every subsequent message | Load only what's needed, right before coding |
| Give one giant prompt for complex features | High risk of wrong direction, expensive to correct | Break into investigation → planning → implementation phases |
| Explain Magento conventions in your prompt | Bricklayer already provides these to the agent | Focus on business logic and your specific requirements |
| Keep reusing a long conversation for unrelated tasks | Context grows, costs increase, relevance decreases | Start fresh conversations for new topics |
| Assume the agent knows your customizations | It doesn't until it checks | Always ask it to investigate your setup first |
Getting Started
Architecture
Tools Reference
- Overview (84 Tools)
- Introspection
- Catalog
- Orders
- Customers
- Database
- Logs & Diagnostics
- GraphQL
- Development
Configuration
Guidelines & Skills
Code Generation
Diagnostics
Security