MoAI-ADK : un harnais piloté par la vérification pour Claude Code, et le Factory Mode qui découpe le contexte en leader et voies

Ce que c'est

MoAI-ADK est un harnais d'orchestration d'agents en open source, publié par l'équipe modu-ai. Il est écrit en Go (Go 1.26 ou plus récent), sous licence Apache-2.0. Le badge de version du dépôt indique v3.1.3, et la section What's New annonce la v3.2 avec une fonction nommée Factory Mode.

Le projet n'entraîne pas un meilleur modèle de code. Il entoure un agent de code existant, surtout Claude Code, d'une structure externe pour que le code produit mérite la confiance. Le dépôt propose aussi une documentation en anglais, coréen, japonais et chinois, renvoie à un livre d'accompagnement intitulé Practical Agentic Coding with Claude Code, et affiche des contrôles CI, CodeQL et Codecov.

La thèse centrale : sortir trois devoirs du modèle

Le README s'ouvre sur une phrase qui résume toute la conception. Le modèle est un ouvrier stochastique qui avance jeton par jeton. D'un tour à l'autre, il ne retient pas ce qu'il a utilisé ni en quelle quantité, il ne sait pas dire si le résultat est bon, et il ignore jusqu'où la session précédente est allée. Un harnais impose ces trois choses de l'extérieur.

En termes d'ingénierie : le budget, la qualité et la progression. MoAI-ADK les confie à du code déterministe, pas au modèle. Cela diffère de l'habitude d'écrire des prompts toujours plus longs. Le harnais ne demande pas au modèle d'être sage. Il le borne et le contrôle.

Factory Mode : l'architecture

Le Factory Mode vise la fenêtre de contexte. Une session dépense une seule fenêtre. Une longue SPEC la remplit, et chaque tâche suivante porte tout ce qui précède. Le plan est fini depuis longtemps, mais il reste dans la fenêtre pendant toute la revue, et la revue reste pendant toute la rédaction finale. L'échappatoire habituelle est /clear, mais elle jette le contexte utile avec le superflu.

Le Factory Mode répartit le travail entre une session leader et plusieurs sessions voies numérotées. Le leader surveille la file et confie les cartes aux voies libres. Une carte ne change pas de session à chaque étape. Elle entre entière dans une voie, et cette voie la conduit à travers plan, run et sync dans l'ordre, au sein de sa propre session. Chaque étape est lancée comme sous-agent Agent(), et la voie elle-même se contente d'orchestrer. Rien n'est sans limite : la limite de chaque session demeure. Ce qui change, c'est l'endroit où l'historique s'accumule. L'historique d'une carte ne s'accumule que dans la voie qui la possède, donc le même budget va plus loin, et une voie vide son contexte après chaque carte avant d'en prendre une autre.

Fonctionnement

L'entrée utilise deux options. moai cc -f (forme longue --factory) ouvre le leader. moai cc -l (forme longue --lane) rejoint l'usine en cours comme voie. Aucune ne prend de valeur, et le numéro de voie est attribué automatiquement. Combiner -f et -l est une erreur. Une valeur placée après l'une ou l'autre, comme moai cc -l lane-2, est refusée avec un message d'une ligne qui indique la bonne forme. L'ancienne entrée -k du mode tableau multi-sessions est supprimée, et moai cg se termine avec un avis de migration que l'on peut prévisualiser avec moai migrate cg. La commande moai gpt n'existe pas : les modèles GPT passent par moai codex, qui n'a pas d'entrée leader et ne peut que rejoindre comme voie. Le backend se choisit par voie. moai cc -l est une voie Claude, moai glm -l une voie GLM, moai codex -l une voie Codex. La documentation conseille GLM pour la place de leader (moai glm -f), car cette place surveille une file et porte des cartes au lieu de rendre des verdicts, et un modèle bon marché attend sans coût. Si un compte commence à subir des erreurs 429, répartir les voies sur plusieurs comptes aide. Le texte précise que ce mélange n'est qu'un exemple, et qu'un seul backend pour toutes les sessions convient aussi. Pour traiter plusieurs cartes à la fois, on relance -l. Un numéro de voie n'est sauté que tant qu'une session vivante le détient. La réservation d'une voie morte ne bloque plus son numéro, mais l'attribution automatique prend toujours le plus haut numéro vivant plus un, donc elle ne comble jamais un trou au milieu. La propriété des voies est enregistrée dans ~/.moai/db/<project-key>/factory/factory.db. Quand le répertoire de base est temporaire et qu'aucun MOAI_HOME absolu n'est défini, l'enregistrement va sous <base>/.moai/db/<project-key>/factory/ dans le projet, la même exception que celle de la file d'arriéré. L'ancien .moai/state/factory/workers.json est importé une fois et conservé seulement comme preuve de retour arrière.

Une voie exécute au plus 10 sous-agents Agent() en même temps, et les lancements capables d'écrire sont isolés dans leurs propres worktrees. Le conseil est de démarrer la première voie, de vérifier qu'elle produit, puis de lancer les autres. Une carte n'est jamais répartie sur plusieurs voies. Une exécution d'usine enregistre aussi l'identité de processus de la session qui la possède. Une exécution dont le leader est mort est retirée automatiquement quand la voie suivante la rejoint, si bien que la jonction ne bloque pas sur AMBIGUOUS_FACTORY. Le cas inverse est couvert : si une voie arrive alors que l'enregistrement est absent ou retiré mais qu'un leader vivant existe, la jonction vérifie ce leader avec le pid et une empreinte de démarrage du processus.

Performances et coût : où sont les preuves ?

L'extrait du README ne donne aucun chiffre de benchmark. Il n'y a ni débit, ni comparaison de coût en jetons, ni taux de défauts avant et après.

Il offre un argument de structure : comme l'historique d'une carte reste dans sa voie, le même budget va plus loin. Le mécanisme est raisonnable, mais sans mesures publiées il faut le lire comme une hypothèse, pas comme un gain prouvé. Une équipe qui veut juger peut suivre quelques grandeurs mesurables : l'usage moyen de contexte par carte, la qualité de réutilisation de la fenêtre après vidage, le taux d'erreurs 429, et le coût de coordination entre leader et voies.

Impact pour les développeurs et les équipes

Pour un développeur seul, le Factory Mode offre un montage parallèle sans ordonnanceur maison : ouvrir plusieurs terminaux et lancer moai cc -l dans chacun. Pour une équipe, l'état se trouve dans des fichiers SQLite sous une clé de projet, ce qui aide l'audit et la reprise.

La prise en charge de plusieurs backends permet de panacher les fournisseurs selon le coût et le quota, sans parier sur un seul. Plus largement, le projet reflète un déplacement du domaine : la compétition passe du modèle lui-même à la couche de processus et de vérification qui l'entoure.

Limites et perspectives

D'abord, les voies doivent être lancées à la main, un terminal chacune, car une session ne peut pas en lancer une autre. Cela limite l'automatisation complète. Ensuite, les documents publics ne contiennent aucun benchmark chiffré. Troisièmement, les vérifications d'identité de processus et l'import unique de l'ancien état montrent que la reprise après panne porte déjà une vraie complexité, que les utilisateurs doivent comprendre.

Quatrièmement, la règle selon laquelle une carte n'est jamais découpée signifie qu'une tâche très volumineuse peut encore remplir la fenêtre d'une seule voie. Un rapport de mesures publié, davantage de backends et des politiques de découpage plus fines seraient des suites utiles. En bref, MoAI-ADK mérite d'être suivi. Avant de l'intégrer à un flux de production, mesurez-le vous-même sur un petit lot de tâches réelles.