Minimal working Bricklayer project-local overrides

Just enough setup to teach Your AI agent the conventions of Your Magento project, not just Magento in general.

Magento Bricklayer ships with a bundled library of guidelines and skills: plugins, EAV, GraphQL, Hyvä, checkout, payment and so on. That covers Magento. It does not cover Your project. Every real store has things the bundled library can not know about: a custom ERP integration, a vendor module with a local override next to it, CSP rules, payment quirks, house style.

Without that knowledge the agent does what agents do, it guesses. Or You explain the same ERP flow in every new session.

The fix is the .bricklayer/ directory in Your Magento root. Any file You put there is picked up automatically by bricklayer update, development-context and search-docs. Nothing to register in .bricklayer.json, the path is the contract. No forking the package either.

Directory layout

Every entry is optional. There is no manifest and no required file, Bricklayer scans for whatever exists and ignores the rest. bricklayer init creates the empty .bricklayer/ directory, subdirectories You create Yourself on first use.

Most projects need only two things, a project map and a few skills:

{magento_root}/
└── .bricklayer/
    ├── project-context.md
    └── skills/
        ├── erp-integration/
        │   └── SKILL.md
        └── company-conventions/
            └── SKILL.md

The full set, for when You need everything:

File What it does
project-context.md Appended to every generated agent file under ## Project-Specific Context
decision-matrix.md Extra rows for the “Before Modifying Magento Code” table in agent files
guidelines/{category}/{name}.md Overrides or adds a guideline
skills/{name}/SKILL.md Overrides or adds a skill

Guidelines and skills mirror the package’s own config/guidelines/ and config/skills/, so the rule is simple:

  • Override - local path matches a bundled one (e.g. .bricklayer/skills/plugin/SKILL.md ↔ config/skills/plugin/SKILL.md), Your file replaces the bundled one everywhere it would be loaded
  • Addition - no bundled counterpart (e.g. .bricklayer/skills/erp-integration/SKILL.md), it becomes new content: a new section in the agent file for guidelines, a new callable category for skills

Creating the files

Let’s assume we have a store with a Luma-based theme and an ERP integration split between a vendor module and a local one.

  • Create the directories:
mkdir -p .bricklayer/skills/erp-integration
  • Add the project map:
    • .bricklayer/project-context.md

Think of it as orientation for a new developer: what the store is, frontend stack, key custom modules, integrations, house rules. Compact prose and tables:

# Project Context — acme-store

Magento 2 storefront for **Acme** (DE + AT). Luma-based custom theme stack.

## Frontend

| Theme | Parent | Location |
|---|---|---|
| `Acme/storefront` | `Vendor/base` | `app/design/frontend/Acme/storefront` |

## Key modules

| Module | Location | Role |
|---|---|---|
| `Vendor_ErpSync` | vendor | Pulls order status from ERP via cron |
| `Acme_ErpStock` | `app/code/Acme/ErpStock` | Local stock pull, reuses Vendor's client |
  • Add a skill for the custom code:
    • .bricklayer/skills/erp-integration/SKILL.md

This is the main reason to use .bricklayer/. The directory name is the category the agent types, so keep it short and kebab-case (erp-integration, not Our ERP Integration). Frontmatter is optional, only name and description are read, other keys are ignored:

---
name: ERP integration
description: Two-module stack — Vendor_ErpSync pulls order status from the ERP via cron; Acme_ErpStock adds a local stock pull reusing the vendor client. Default-scope only. Load before touching either module.
---

# ERP integration

...which modules, where they live, how the data flows, what to load before touching them...

Write a real description. Its words become search keywords, that is how the agent finds the skill via search-docs before it even knows the category exists. Keep it on a single line, only the first line after description: is parsed.

  • Optionally, add rows to the “Before Modifying” table:
    • .bricklayer/decision-matrix.md

Rows only, header and separator lines are ignored:

| Modifying ERP sync logic | `code-runner` to inspect `Vendor\Erp\Model\SyncQueue` | `development-context category=erp-integration` |
| Changing checkout steps | `plugin-list className=Magento\Checkout\Model\Type\Onepage` | `development-context category=checkout` |
  • Optionally, override a bundled guideline by mirroring its path, e.g. .bricklayer/guidelines/patterns/plugin.md. Only do this when You are actually changing something, unmodified copies are just maintenance burden.

Regenerate and use

Run:

vendor/bin/bricklayer update

It regenerates the agent files and tells You exactly what was applied:

  ✓ Regenerated CLAUDE.md
  Applied local overrides:
    - .bricklayer/project-context.md
    - .bricklayer/skills/erp-integration/SKILL.md
  Indexed 1 local file(s) into docs index

From now on Your agent sees the project content in three places:

  • Agent file (CLAUDE.md, .cursorrules…) - project-context.md under ## Project-Specific Context, new skills under a Project-specific group in the categories table, decision-matrix.md rows in the “Before Modifying” table
  • development-context category=erp-integration - returns Your SKILL.md, frontmatter stripped
  • search-docs query=... - local entries prefixed with [Project] and marked source: local

That [Project] tag matters. The agent can tell Your project conventions apart from bundled Magento knowledge. Where You override a bundled file, the bundled version is not served at all, so there is no conflicting advice to choose from.

Why bother

  • Write it once - the ERP flow, the theme chain, the house rules live in a file, not in Your head and not in every prompt
  • Same context for the whole team - .bricklayer/ is committed to the project repo by design, every developer and every agent works from the same conventions
  • Works across agents - one source, bricklayer update compiles it into CLAUDE.md, .cursorrules, AGENTS.md or whatever You selected
  • Loaded on demand - skills are pulled via development-context only when the task needs them, the agent file does not grow into a novel
  • Discoverable - a good description lets the agent find the skill through search-docs without You pointing at it
  • No fork - package updates keep coming, Your overrides stay where they are
  • Reviewable - it is plain markdown in git, conventions get code-reviewed and versioned like code

Few things that do not belong there:

  • anything secret - no credentials, API keys or sensitive data, it is committed
  • generic Magento knowledge - if it belongs in the bundled library, contribute it upstream
  • unmodified copies of bundled files

Your final structure should look like this:

{magento_root}/
├── .bricklayer/
│   ├── project-context.md
│   ├── decision-matrix.md        # optional
│   └── skills/
│       └── erp-integration/
│           └── SKILL.md
├── .bricklayer.json
├── .mcp.json
└── CLAUDE.md                     # regenerated by bricklayer update
  • If You are working in git flow, commit .bricklayer/ together with the regenerated agent file
  • Changed something in .bricklayer/? Run vendor/bin/bricklayer update again

Start coding!

Source: Project-Local Overrides wiki · GitHub