Working with coding agents

MelaCMS is designed so a coding agent can build most of a site and be right about it. It gives the agent three things: instructions, a guide, and a way to check its work.

Instructions in AGENTS.md and CLAUDE.md

mela:install writes a MelaCMS section into the site's AGENTS.md and CLAUDE.md, between <mela-cms-guidelines> tags. Every agent that reads those files learns:

• what lives in the core and what lives in the site, and that vendor/ is never edited,
• how to read the languages, the settings and the media,
• how pages are served and how a template gets its own fields,
• what a new kind of content needs, from the migration to the test,
• the commands to format, test and update,
• how releases and deploys work.

Only the tagged section belongs to MelaCMS. Write your own notes about the project outside the tags: mela:update rewrites the section to match the installed core and leaves the rest of the file alone.

The site's CI runs php artisan mela:update --check. It fails while the section does not match the installed core, so an agent never works from the instructions of an older version.

The entity guide

A site's own content, such as services, posts, projects or team members, is called an entity. Building one touches many files: a migration, a model, an admin screen, a controller, routes, views, the sitemap and a test.

The core ships a guide for it, docs/entity.md, which the instructions tell the agent to read at vendor/melasistema/mela-cms/docs/entity.md first. It has:

• the decisions to take before writing code,
• a table from "what the entity has" to the columns, traits and form fields it needs,
• every file of a complete worked example,
• the variants, and what not to do.

The guide is read from vendor/, so it always matches the installed core. Its code blocks are run by the core's test suite, so it cannot drift from how the core behaves.

See Your own content for the short version.

Checking the work

A fresh MelaCMS site has what an agent needs to prove a change:

Check	Command
Tests, on SQLite	php artisan test
Formatting	vendor/bin/pint, and vendor/bin/pint --test in CI
The agent instructions	php artisan mela:update --check

The core roles exist in every test that migrates its database, so a feature test can log in as an editor and use the admin screens.

A typical session

1. Ask the agent for a feature: "Add a team page with a photo, a role and a short bio for each person, in English and Italian."
2. The agent reads the MelaCMS section, then the entity guide, and builds the slice.
3. It runs Pint and the tests.
4. You review the diff, try it locally at /admin, and commit with a conventional message, such as feat: add the team page.
5. The commit reaches the server with the next release.

Prompting tips

• Name the content and its fields, and say which ones are translated.
• Say whether it has its own address on the site, or only appears inside a page.
• Point the agent to a page template when the content only belongs to one page: a template field may be enough, with no entity.
• Ask for the test. The instructions require one, but saying it costs nothing.