Coding agents

A coding agent knows PHP, not Gacela. Left alone, it imports another module's classes directly, builds services with new outside the Factory, and never runs the checks that would catch either. Gacela ships a short guide that teaches it the module rules and the commands that verify them.

Point your agent at the guide Since 2.5

vendor/bin/gacela agents:install

This writes a block into the project's AGENTS.md, and creates the file if it does not exist:

<!-- gacela:start -->
## Gacela

This project is split into Gacela modules. Before changing PHP code, read `vendor/gacela-project/gacela/resources/agents/gacela.md` and follow it. Check your work with `vendor/bin/gacela doctor --only-problems`.
<!-- gacela:end -->

• A pointer, not a copy. The guide lives in the installed package. It always describes the version you run, and upgrading Gacela updates it with nothing to regenerate.
• Safe to run again. The command rewrites only the text between the markers. The rest of AGENTS.md is yours, and it stays as it was.
• Most agents read AGENTS.md. For Claude Code, add @AGENTS.md to your CLAUDE.md, or run the command and copy the block there.

What the guide covers

resources/agents/gacela.md (opens in a new tab) is about 150 lines, short enough to sit in an agent's context next to your own rules:

• the four pillars and how Gacela finds them by name;
• the rules: cross a module only through its Facade, Facades delegate, Factories build, Providers supply other modules;
• which way to get a dependency, pointing at getting dependencies;
• the commands that answer "is this right?" in one call: doctor --only-problems, debug:graph --check, list:modules --json, debug:module;
• the static analysis rules, and how to turn on the cross-module one;
• testing a module with bootstrapModule().

For anything deeper, it points at the docs in vendor/gacela-project/gacela/docs/, so the agent reads the page for the version you have installed.