Writing a good Bricklayer project-context.md: a project map for AI agents

Just enough orientation for Your AI agent to know where it is before it touches anything.

A new developer on a Magento project spends the first days asking the same questions. Hyvä or Luma? Which theme is ours and which is the vendor’s? Which module talks to the ERP? Where do I put a fix, app/code or a patch? An agent asks none of these. It just assumes.

.bricklayer/project-context.md is where You answer those questions once. It is free-form markdown, and bricklayer update appends it verbatim to every generated agent file (CLAUDE.md, .cursorrules, AGENTS.md…) under a ## Project-Specific Context heading. Empty or missing file, no section.

In practice, it is a project map.

What to cover

Five things, in compact prose and tables:

  • What the store is - brand, markets or store views, one-line summary
  • Frontend stack - Hyvä vs Luma, theme inheritance chain and where each theme lives (app/design/... or vendor/...)
  • Key custom modules - vendor vs local (app/code), what each one owns, which one to reach for
  • Integrations - ERPs, payment and shipping providers, queues, and the modules that wrap them
  • House rules - conventions that deviate from Magento defaults: async writes, scope assumptions, naming

Example, based on the one in the Bricklayer wiki:

# 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 |

## House rules

- Fixes to vendor modules go into `app/code` overrides, never into `vendor/`
- Default scope only, no website-level config
- Deep docs: `development-context category=erp-integration`

Tables work better than paragraphs here. The agent reads them as a lookup, and so do You six months later.

The last line matters. project-context.md is the map, not the territory. Keep the deep stuff in skills and point to them by category, so the agent file stays short and the details are loaded only when needed.

Keeping it current

  • Edit the file, then regenerate:
vendor/bin/bricklayer update
  • Output confirms it was applied:
  ✓ Regenerated CLAUDE.md
  Applied local overrides:
    - .bricklayer/project-context.md
  • New module, new theme, new integration? Add a row in the same PR. An outdated map is worse than none, the agent trusts it
  • Commit .bricklayer/project-context.md together with the regenerated agent file

What does not belong there:

  • anything secret - .bricklayer/ is committed by design, no credentials, API keys or sensitive data
  • generic Magento knowledge - the bundled guidelines already cover it
  • long how-tos - those are skills, see the next post

Start coding!

Source: Project-Local Overrides wiki