Workflow des agents Claude¶
Cette page explique pourquoi Kirexo délègue certaines tâches à des sous-agents Claude spécialisés, et comment fonctionne le mécanisme de délégation. Pour l'inventaire des règles, voir CLAUDE.md à la racine.
Elle est destinée à un développeur qui rejoint le projet, constate que Claude refuse d'écrire des tests ou s'arrête à 13 fichiers PHP, et cherche à comprendre la logique en place.
Pourquoi déléguer ?¶
Un seul agent chargé d'écrire le code, de le valider architecturalement, d'en écrire les tests et d'en rédiger la documentation accumule un biais d'auto-confirmation : il valide ses propres choix sans regard extérieur et produit une couverture de tests qui tend à confirmer ce qu'il vient d'écrire plutôt qu'à le mettre en défaut.
La délégation à des sous-agents spécialisés brise ce circuit :
- Le
reviewerne voit que le code déjà stabilisé et n'est pas l'auteur de ce qu'il examine. Son prompt est optimisé pour détecter les violations de patterns (CQRS, Voters, DTO immuables, Repository pattern…), pas pour produire du code. - Le
test-writerest spécialisé PHPUnit et Panther. Il écrit des tests à partir du code validé par le reviewer — il n'est jamais l'auteur du code de production qu'il teste. - Le
doc-writermaîtrise Diátaxis et les conventions de rédaction du projet. Il intervient uniquement si l'interface ou un concept utilisateur a changé — jamais par défaut, jamais de manière préventive.
Mélanger ces périmètres dans une même délégation dégraderait la qualité des trois.
La chaîne de délégation¶
L'ordre est fixe et non négociable.
- Main Claude — écrit le code de production, dans la limite de 13 fichiers PHP par lot.
- Main Claude — vérifie dans l'ordre :
castor cs:fix→castor phpstan→castor lint→castor doctrine:schema:validate. Des cibles utilitaires (castor cache:clear,castor fixtures:load) peuvent être appelées à tout moment sans impacter ce cycle. reviewer— vérifie les patterns d'architecture (CQRS, Voters, DTO immuables, Repository pattern, controllers invokables…). Rend un verdictAPPROVEDouBLOCKED. Tant qu'il n'est pasAPPROVED, le main Claude corrige et relance.test-writer— écrit les tests (PHPUnit unitaires et d'intégration, Panther E2E) sur le code validé par le reviewer.doc-writer— met à jour la documentation si l'interface ou un concept utilisateur a changé.
Un agent = un périmètre. Ne jamais les mélanger dans une même délégation.
Le quota de 13 fichiers PHP¶
Le main Claude ne peut pas créer ou modifier plus de 13 fichiers PHP de production entre deux délégations au test-writer. Ce plafond sert à :
- Garder les lots de code petits, ce qui rend la revue architecturale du
reviewerplus facile et plus fiable. - Forcer un cycle test rapide — pas de dette de couverture accumulée sur plusieurs dizaines de fichiers.
- Éviter que la pile de « tests à écrire » devienne ingérable en fin de session.
Sont considérés comme fichiers PHP de production : tout fichier .php dans src/, public/ ou bin/ (y compris bin/console, sans extension), à l'exception des fixtures (src/DataFixtures/) et des fichiers de configuration tooling (castor.php et les sous-fichiers castor/*.php, .php-cs-fixer.dist.php, config/, importmap.php, tests/bootstrap.php).
Ne comptent pas dans ce quota : les fichiers de tests (tests/), les fixtures (src/DataFixtures/), les fichiers YAML, Twig et de configuration, ni le task runner Castor.
Comment le compteur se remet à zéro¶
Le quota est tracé dans var/claude/.session/<worktree>/prod-php-files.txt par le hook PostToolUse (.claude/hooks/count-prod-php.sh). Il se remet à zéro dans deux cas :
- Le
reviewerapprouve : à la fin de sa revue, le reviewer écritreviewer-verdict.txtdans ce même dossier, avec la valeurAPPROVED. Le hook lit ce verdict et efface le tracker. - Le
test-writerécrit danstests/: dès que le test-writer crée ou modifie un fichier danstests/, le tracker est effacé et le prochain lot de 13 peut commencer.
Le hook produit un avertissement préventif à 11/13, et bloque à 13/13 en demandant de déléguer au test-writer avant toute nouvelle écriture de fichier PHP de production.
Le <worktree> dans ce chemin n'est pas décoratif. var/claude est commun au dépôt principal et à tous les worktrees : sans ce cloisonnement, un quota atteint dans un worktree bloquerait la session ouverte dans un autre, et deux agents en parallèle s'écraseraient leur verdict de revue. Le détail de la résolution est en référence — Le dossier d'état de session —, le raisonnement dans Pourquoi l'agent pousse lui-même, et ce qui le retient.
Les hooks en bref¶
| Hook | Déclencheur | Rôle |
|---|---|---|
guard-delegation.sh |
PreToolUse Write/Edit |
Empêche le main Claude de créer des fichiers dans tests/ ou docs/, et limite chaque agent à son périmètre. |
count-prod-php.sh |
PostToolUse Write/Edit |
Compte les fichiers PHP de production écrits par le main Claude ; informe à 11/13 et bloque à 13/13. |
stop-checklist.sh |
Stop |
Rappelle à chaque fin de tour ce qui reste à jouer de la checklist de clôture — l'agrégat castor all côté conteneur, castor host:check côté hôte (énumération exacte en référence) — et les délégations obligatoires. Sonde aussi la vitalité des services quand la session tourne dans le conteneur. |
Trois autres complètent le dispositif sans porter la délégation : guard-rm.sh (PreToolUse) encadre les suppressions, track-checklist.sh (PostToolUse) note au fil de l'eau ce qui a déjà été joué de la checklist, et session-dashboard.sh (SessionStart) affiche l'état de l'environnement et porte le gate de confinement — le seul hook capable d'empêcher une session de travailler (cf. Modèle de menace et contrat de confinement). L'inventaire complet est en référence : Hooks Claude Code.
Les hooks de délégation lisent le contexte d'appel via jq (qui est un prérequis du projet). guard-delegation.sh agit en PreToolUse — il bloque l'écriture avant qu'elle n'ait lieu. count-prod-php.sh agit en PostToolUse — il comptabilise après écriture effective. stop-checklist.sh, lui, n'est bloquant que dans un cas : l'application est tombée et la session a modifié du code qui la fait tourner — une régression à la fois imputable à la session et corrigeable depuis le conteneur. Tout le reste informe sans refuser, y compris une panne du conteneur docs, que l'agent ne peut pas relancer faute de socket Docker. Le détail est dans Hooks Claude Code — stop-checklist.sh.
Le serveur MCP symfony-ai-mate¶
Pour donner à Claude Code l'accès aux capacités MCP exposées par Symfony AI - Mate, le projet versionne un fichier .mcp.json à la racine. Ce fichier déclare deux serveurs MCP : symfony-ai-mate, pour les capacités Mate, et playwright, pour le pilotage de navigateur (voir Config MCP Playwright).
Le serveur symfony-ai-mate n'est pas lancé par une commande écrite en dur dans .mcp.json, mais par un wrapper versionné, infra/mcp/mate-mcp.sh. La raison tient à l'isolation : la même déclaration MCP doit fonctionner depuis l'hôte et depuis le conteneur, or ces deux contextes n'ont pas le même geste. Depuis l'hôte, il faut passer par docker compose exec -T php vendor/bin/mate serve --force-keep-alive ; depuis le conteneur, cette commande ne peut pas fonctionner — le socket Docker n'y est pas monté, c'est l'invariant C2 du contrat de confinement — et le binaire est appelé directement. Le wrapper choisit sur KIREXO_INSIDE_CONTAINER, la même convention que castor.php.
Le binaire mate vit dans les deux cas dans le conteneur php, jamais sur la machine hôte — cohérent avec le principe « rien d'installé en local, tout dans les conteneurs ». Conséquence directe : la stack Docker doit être démarrée (castor docker:up) avant de lancer Claude Code depuis l'hôte, sinon le serveur MCP ne pourra pas démarrer.
Le serveur n'est activé que si .claude/settings.local.json (non versionné, propre à chaque développeur) le déclare explicitement :
Sans cette entrée, Claude Code lit le .mcp.json mais n'instancie aucun serveur — le projet reste utilisable sans MCP pour qui ne le souhaite pas.
castor wt:up réécrit bien ce fichier, mais seulement pour y aligner les deux clés liées au mode de permission de la session : tout le reste est préservé, cette entrée comprise (cf. le tableau de réconciliation de wt:up).
Vidéo de démo obligatoire sur impact visuel¶
Un lot qui modifie un rendu (.twig) produit un changement visuel qu'un diff de code ne restitue pas et qu'une capture statique documente mal : un attribut de classe déplacé, un composant qui se réagence, une transition, un état vide qui s'affiche différemment. Le reviewer humain ne peut pas déduire du seul diff ce que l'utilisateur va voir à l'écran.
D'où la règle : dès qu'un lot touche un .twig, une courte vidéo est produite via /demo-video et attachée au work-item du lot. Elle donne au reviewer une preuve visuelle immédiate du rendu réellement obtenu, sans qu'il ait à dérouler lui-même le parcours.
La règle joue à deux échelles, et il faut les distinguer parce que leur automatisation n'est pas la même :
- par lot, le gate est mécanique :
detect-twig.sh(.claude/skills/implementer-lot/bin/detect-twig.sh) liste les.twigajoutés, modifiés ou renommés depuis la branche parente, et le skill refuse de clore le lot tant que la vidéo n'est pas attachée ; - en fin de cycle, la couverture est plus large que ce que ce gate sait détecter : une vidéo « grand tour » est due dès qu'un lot du cycle a touché une surface visuelle — un
.twig, mais aussi une feuille de style ou un fichier d'assets/(contrôleur Stimulus, importmap). Un changement purement CSS ne fait rougir aucun gate ; c'est l'implémenteur qui le repère.
Le scénario filmé, lui, reste écrit par l'implémenteur à chaque échelle : seul lui sait quel parcours illustre sa modification, et cette part de jugement ne s'automatise pas.
Pour le geste concret (prérequis, invocation, upload), voir la how-to Enregistrer une vidéo de démo. Pour la config du serveur de pilotage, voir la reference Config MCP Playwright.