Zana et les agents de codage IA : règles, inspection et contrôles intégrés

Les agents de codage IA, comme Claude Code, Codex, Copilot ou Cursor, peuvent désormais écrire une bonne partie d’une application. Le plus difficile est de leur faire écrire votre application : suivre ses règles, réutiliser ce qui existe déjà, et prouver qu’un changement fonctionne avant de le déclarer terminé.

Zana 2.7 à 2.11 apportent exactement cela. Les agents disposent d’un ensemble de fichiers simples et de commandes console pour travailler sur une application Zana comme ses développeurs. Ils lisent les règles du projet, regardent ce que contient l’application, génèrent le code avec les commandes make: et vérifient le résultat avec les mêmes contrôles qu’une personne lancerait.

Rien dans Zana n’appelle une IA ni ne dépend d’un fournisseur d’IA. Tout est du texte et du JSON : cela fonctionne avec l’agent de votre choix, et c’est tout aussi utile aux humains.

AGENTS.md : les règles, dans le fichier que chaque agent lit#

Chaque agent cherche ses instructions à un endroit différent. Zana les écrit une seule fois :

php bin/console make:agents

La commande crée trois fichiers :

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

AGENTS.md contient tout. On y trouve la démarche à suivre, les couches d’un module et ce dont chacune peut dépendre, la façon d’enregistrer les services et de lire la configuration, les règles du code web, ce qu’il ne faut pas faire, et les commandes à lancer. Il renvoie à la documentation de la version de Zana installée : l’agent n’apprend jamais à partir d’une version plus récente ou plus ancienne. CLAUDE.md l’importe et le fichier Copilot y renvoie, pour que chaque agent trouve les mêmes règles là où il les attend.

Vous ajoutez vos propres règles dans une section à la fin. Les squelettes web et API incluent aussi un test qui échoue quand AGENTS.md mentionne une autre version de Zana, et check le signale. Après une mise à jour, make:agents --force régénère le fichier.

inspect : ce que contient l’application#

Avant de modifier quoi que ce soit, un agent doit savoir ce qui existe déjà. Sinon, il ajoute un deuxième service d’e-mail, une route en double ou un module qui existe déjà sous un autre nom.

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

inspect liste l’environnement, les modules, les services, les commandes console, les routes, les migrations, les paquets et les clés de configuration. Il montre les clés de configuration avec leur type, jamais leur valeur : aucun mot de passe, aucune clé d’API ni aucun secret n’atteint l’agent par Zana.

Générer à partir d’un plan relu#

Les agents écrivent bien le code, mais la structure générée ne doit pas être improvisée. Le générateur de Zana écrit des modules, des entités, des objets-valeurs, des dépôts et des cas d’usage complets, qui suivent l’organisation du framework. Chaque commande make: peut montrer son plan avant d’écrire quoi que ce soit :

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

Le plan liste les fichiers qui seraient écrits, les lignes qui seraient enregistrées dans le module et les étapes manuelles restantes. Sans --dry-run, make:feature … --http écrit une tranche verticale complète : une commande typée et validée, son handler, une action d’API avec sa route, et deux tests, l’un pour le handler et l’autre pour l’API.

Pour un changement plus important, Zana 2.11 ajoute make:plan. L’agent propose un seul fichier, qu’une personne relit avant toute écriture :

{
    "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 lance les mêmes commandes make:, d’abord dans une copie temporaire. Rien n’est écrit si une seule étape échoue.

Le code généré, c’est la structure. Les règles métier, comme ce qui rend un titre valide ou qui peut ajouter un livre, restent écrites à la main, par l’agent ou par vous, dans les couches Domain et Application.

check : le changement est-il correct ?#

C’est la pièce qui rend le reste fiable. Un agent peut dire « terminé » avec une assurance totale. check l’oblige à le prouver :

php bin/console check --format=json

La commande vérifie que le conteneur se construit, que les contrôles de déploiement passent et que les singletons sont sains. Elle vérifie aussi que les règles d’architecture sont respectées dans modules/, que chaque route mène à un handler enregistré, que chaque middleware peut être créé et qu’aucune migration n’est en attente. Les paquets et les applications peuvent ajouter leurs propres contrôles.

Chaque problème est un constat : un identifiant, une gravité, un message, le fichier s’il y en a un, et une piste de correction. Ici, un agent a ajouté une route en oubliant d’enregistrer son contrôleur :

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.

L’agent lit la piste, corrige et relance check. La boucle est courte et la réponse sans ambiguïté : un code de sortie différent de zéro veut dire que le travail n’est pas fini.

Les formats JSON sont versionnés (zana.inspect/1, zana.check/1, zana.make/1, zana.plan/1). Au sein d’une version, des champs peuvent seulement être ajoutés : les scripts et les agents qui les lisent continuent de fonctionner.

Une seule démarche pour les agents et les humains#

AGENTS.md demande à l’agent de travailler dans l’ordre que suit un développeur soigneux :

1. Comprendre la demande et la reformuler.
2. Inspecter l’application.
3. Réutiliser une fonctionnalité, un contrat ou un service existant avant d’en ajouter un.
4. Planifier le module et la couche concernés, avec --dry-run.
5. Générer la structure avec les commandes make:.
6. Écrire la logique métier.
7. Vérifier avec check, et corriger chaque erreur.
8. Tester avec composer test.
9. Résumer les fichiers modifiés, les décisions prises et les commandes lancées.

Rien de tout cela n’est propre à un agent. Un développeur sans agent suit les mêmes étapes, et un relecteur sait ce qu’il trouvera dans chaque résumé.

Une documentation fiable pour les agents#

Les agents apprennent un framework dans sa documentation : une documentation fausse produit du code faux, avec une totale assurance. Chaque exemple de code de la documentation de Zana est un fichier exécutable, testé contre le résultat annoncé. Le guide IA construit pas à pas une petite API de bibliothèque, et sa suite de tests reconstruit cette application à partir des commandes de la page.

Pour les agents, la documentation publie aussi llms.txt, un index de toutes les pages de la version avec une ligne pour chacune. Le texte complet de chaque page est joint à chaque version de la documentation sous le nom llms-full.txt.

Une liste de contrôle « prête pour l’IA »#

Zana 2.11 définit ce qu’une application maintenue par des agents doit respecter. Ce n’est pas une certification, et chaque ligne indique ce qui la vérifie :

• AGENTS.md existe et mentionne la version installée, et CLAUDE.md et les instructions Copilot y renvoient ;
• check passe sans erreur, et les règles d’architecture s’appliquent à modules/ ;
• les tests tournent sans fichier .env, et les tests des modules tournent avec les autres ;
• l’intégration continue lance les tests et check ;
• les commandes et les requêtes sont validées, quelle que soit leur origine ;
• les fonctionnalités sont générées à partir d’un plan relu, puis écrites à la main.

Les deux squelettes respectent cette liste dès leur création :

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

Le squelette d’API inclut des comptes utilisateurs avec jetons d’accès, des erreurs au format problem JSON et la validation : make:feature … --http fonctionne dès la première commande.

Ce que ces outils ne font pas#

check et les tests attrapent les erreurs de câblage et d’architecture. Ils n’attrapent pas une règle métier fausse. Si l’agent comprend mal le calcul d’une remise, le code peut passer tous les contrôles et rester faux. La documentation de Zana est claire : relisez ce qu’écrit un agent comme vous reliriez le travail d’un collègue. Les outils éliminent les erreurs mécaniques, pour que la relecture se concentre sur ce que seuls les humains peuvent juger.

Pour commencer#

Dans une application Zana existante, passez à la version 2.11, installez mj-zana/maker et lancez php bin/console make:agents. Dans une nouvelle application, partez d’un squelette, où c’est déjà fait. Le guide sur le travail avec les agents de codage IA (en anglais) donne tous les détails, y compris l’exemple complet.

Si vous voulez de l’aide pour mettre en place le développement assisté par l’IA sur vos projets, ou une équipe qui travaille ainsi, parlons-en.