Zana for AI coding agents: rules, inspection and checks built in

AI coding agents such as Claude Code, Codex, Copilot and Cursor can now write a good part of an application. The hard part is making them write your application: following its rules, reusing what already exists, and proving that a change works before calling it done.

Zana 2.7 to 2.11 add exactly that. Agents get a set of plain files and console commands that let them work on a Zana application the way its developers do. They read the project's rules, look at what the application contains, generate code with the make: commands, and verify the result with the same checks a person would run.

Nothing in Zana calls an AI or depends on an AI provider. It is all text and JSON, so it works with whichever agent you use, and it is just as useful to people.

AGENTS.md: the rules, in the file every agent reads#

Every agent looks for instructions in a different place. Zana writes them once:

php bin/console make:agents

This creates three files:

AGENTS.md
CLAUDE.md
.github/copilot-instructions.md

AGENTS.md holds everything. It covers the workflow to follow, the layers of a module and what each may depend on, how to register services and read configuration, the rules for web code, what not to do, and the commands to run. It links to the documentation of the installed Zana version, so the agent never learns from a newer or older release. CLAUDE.md imports it, and the Copilot file points to it, so each agent finds the same rules where it expects them.

You add your own rules in a section at the end. The website and API skeletons also ship a test that fails when AGENTS.md names another Zana version, and check warns about it. After an upgrade, make:agents --force refreshes the file.

inspect: what the application contains#

Before an agent changes anything, it should know what is already there. Otherwise it adds a second email service, a duplicate route or a module that already exists under another name.

php bin/console inspect --format=json
php bin/console inspect routes

inspect lists the environment, modules, services, console commands, routes, migrations, packages and configuration keys. It shows configuration keys with their types, never their values, so no password, API key or secret reaches the agent through Zana.

Generate with a plan you can review#

Agents are good at writing code, but generated structure should not be improvised. Zana's maker writes modules, entities, value objects, repositories and complete use cases that follow the framework's layout. Every make: command can show its plan before writing anything:

php bin/console make:feature Library AddBook --field=title:string --field=author:string --http --dry-run --format=json

The plan lists the files it would write, the lines it would register in the module and the manual steps left. Without --dry-run, make:feature … --http writes a full vertical slice: a typed and validated command, its handler, an API action with its route, and two tests, one for the handler and one for the HTTP endpoint.

For a larger change, Zana 2.11 adds make:plan. The agent proposes one file and a person reviews it before anything is written:

{
    "schema": "zana.plan/1",
    "module": "Library",
    "entities": ["Book"],
    "value_objects": ["BookTitle"],
    "repositories": ["Book"],
    "features": [
        {"name": "AddBook", "http": true, "fields": ["title:string", "author:string"]},
        {"name": "ListBooks", "query": true, "http": true}
    ]
}

php bin/console make:plan library.plan.json --dry-run
php bin/console make:plan library.plan.json

make:plan runs the same make: commands in a temporary copy first. Nothing is written unless every step succeeds.

The generated code is the structure. The business rules, such as what makes a valid title or who may add a book, are still written by hand, by the agent or by you, in the Domain and Application layers.

check: is the change right?#

This is the piece that makes the rest trustworthy. An agent can say "done" with total confidence. check makes it prove it:

php bin/console check --format=json

It verifies that the container builds, the deployment checks pass, and singletons are sound. It also checks that the architecture rules hold across modules/, every route reaches a registered handler, every middleware can be created, and no migration is pending. Packages and applications can add their own checks.

Each problem is a finding, with an id, a severity, a message, the file when there is one, and a hint on how to fix it. Here an agent added a route and forgot to register its controller:

zana.check/1: error [exit 1]
error routing.handler: GET /shelves: its handler ShelfController is not registered in the container.
  hint: Register it in its module's register(): $services->transient(\ShelfController::class);
warning shop.opening_hours: The opening hours are not set.
  hint: Set shop.opening_hours in config/shop.php.

The agent reads the hint, makes the fix and runs check again. The loop is short and the answer is unambiguous. A non-zero exit code means the work is not finished.

The JSON formats are versioned (zana.inspect/1, zana.check/1, zana.make/1, zana.plan/1). Fields are only ever added within a version, so scripts and agents that read them keep working.

One workflow for agents and people#

AGENTS.md asks the agent to work in the order a careful developer follows:

1. Understand the request and restate it.
2. Inspect the application.
3. Reuse an existing feature, contract or service before adding one.
4. Plan which module and layer the change belongs to, with --dry-run.
5. Generate the structure with the make: commands.
6. Write the business logic.
7. Check, and fix every error.
8. Test with composer test.
9. Summarise the files changed, the decisions made and the commands run.

Nothing in it is specific to one agent. A developer without an agent follows the same steps, and a reviewer knows what to expect in every summary.

Documentation agents can trust#

Agents learn a framework from its documentation, so wrong documentation produces wrong code with full confidence. Every code sample in Zana's documentation is a runnable file, tested against its documented output. The walkthrough in the AI guide builds a small library API, and its test suite rebuilds that application from the commands on the page.

For agents, the documentation also publishes llms.txt, an index of every page of the version with a line on each. The full text of every page is attached to each documentation release as llms-full.txt.

An AI-ready checklist#

Zana 2.11 defines what an application maintained by agents should meet. It is not a certification, and each line names what verifies it:

• AGENTS.md exists and names the installed version, and CLAUDE.md and the Copilot instructions point to it;
• check passes without an error, and the architecture rules apply to modules/;
• tests run without a .env file, and module tests run with the others;
• CI runs both the tests and check;
• commands and queries are validated whatever sends them;
• features are generated with a reviewed plan, then written by hand.

Both skeletons meet the checklist out of the box:

composer create-project mj-zana/skeleton-web my-site
composer create-project mj-zana/skeleton-api my-api

The API skeleton includes user accounts with bearer tokens, problem JSON errors and validation, so make:feature … --http works from the very first command.

What it does not do#

check and the tests catch wiring and architecture mistakes. They do not catch a wrong business rule. If the agent misunderstands how a discount is calculated, the code can pass every check and still be wrong. Zana's documentation is explicit: review what an agent writes as you would review a colleague's work. The tooling removes the mechanical mistakes, so review can focus on the part only people can judge.

Getting started#

In an existing Zana application, upgrade to 2.11, install mj-zana/maker and run php bin/console make:agents. In a new one, start from a skeleton, where it is already done. The guide to working with AI coding agents covers the details, including the full walkthrough.

If you want help setting up AI-assisted development on your own projects, or a team that builds this way, let’s talk.