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 à 5 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 reviewer ne 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-writer est 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-writer maî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.

1. Main Claude — écrit le code de production, dans la limite de 5 fichiers PHP par lot.
2. 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.
3. reviewer — vérifie les patterns d'architecture (CQRS, Voters, DTO immuables, Repository pattern, controllers invokables…). Rend un verdict APPROVED ou BLOCKED. Tant qu'il n'est pas APPROVED, le main Claude corrige et relance.
4. test-writer — écrit les tests (PHPUnit unitaires et d'intégration, Panther E2E) sur le code validé par le reviewer.
5. 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 5 fichiers PHP

Le main Claude ne peut pas créer ou modifier plus de 5 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 reviewer plus 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/, à l'exception des fixtures (src/DataFixtures/) et des fichiers de configuration tooling (castor.php, .php-cs-fixer.dist.php, config/, importmap.php).

Ne comptent pas dans ce quota : les fichiers de tests (tests/), les fixtures (src/DataFixtures/), les fichiers YAML, Twig et de configuration, et castor.php.

Comment le compteur se remet à zéro

Le quota est tracé dans var/claude/prod-php-files.txt par le hook PostToolUse (.claude/hooks/count-prod-php.sh). Il se remet à zéro dans deux cas :

• Le reviewer approuve : à la fin de sa revue, le reviewer écrit var/claude/reviewer-verdict.txt avec la valeur APPROVED. Le hook lit ce verdict et efface le tracker.
• Le test-writer écrit dans tests/ : dès que le test-writer crée ou modifie un fichier dans tests/, le tracker est effacé et le prochain lot de 5 peut commencer.

Le hook produit un avertissement préventif à 3/5, et bloque à 5/5 en demandant de déléguer au test-writer avant toute nouvelle écriture de fichier PHP de production.

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 à 3/5 et bloque à 5/5.
stop-checklist.sh	Stop	Rappelle la checklist de clôture à chaque fin de tour : cs:fix, phpstan, lint, doctrine:schema:validate, délégations obligatoires.

Les trois hooks 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 n'est jamais bloquant ("continue": true) : il informe, il ne refuse pas.

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 un seul serveur, symfony-ai-mate, lancé via docker compose exec -T php vendor/bin/mate serve --force-keep-alive.

Le binaire mate vit donc 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, 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 :

{
  "enabledMcpjsonServers": ["symfony-ai-mate"]
}

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.