Le kit de plafonds ultracode : cinq réglages, une checklist de fan-out, les mesures

TL;DR et verdict

Ultracode ne rend pas Claude Code plus intelligent. Il change ce qu'on dit au modèle et retire trois garde-fous, donc un run dépense plus et s'arrête plus tard.
La règle : ne faites du fan-out que lorsqu'une suite de tests ou un jeu de règles juge la sortie et que le travail se découpe en morceaux indépendants. Tout le reste, en classique à high.
Cinq réglages plafonnent un run : la consigne de taille des workflows sur small, un plafond de 4 agents simultanés, un seul modèle moins cher pour chaque agent de workflow, le mot-clé plutôt que le bouton, et l'auto-continue à la limite d'usage désactivé.
Les deux fichiers qui portent les plafonds sont settings.json et ultracode-caps.sh. La checklist est when-to-fan-out.md. Les paires mesurées sont dans paired-runs.csv.
La consigne de taille est un conseil, pas un plafond. Sur notre propre run, elle disait moins de 5 agents et le run en a utilisé 9.

Ce que disent les sources

Mot-clé contre bouton. Taper ultracode dans un prompt fait entrer cette seule tâche dans un workflow. Demander avec vos propres mots, comme « use a workflow », fonctionne comme le même choix s1. Le mot-clé ne fait rien dans un prompt passé avec -p, dans une entrée Agent SDK non estampillée, ni dans une tâche planifiée s1. Le bouton, c'est différent. Avec ultracode activé, Claude planifie un workflow pour chaque tâche substantielle, et une demande peut devenir plusieurs workflows à la suite s1. La documentation ajoute qu'une session avec ultracode activé atteint une limite de session ou hebdomadaire plus tôt que le même travail sans s1.

La phrase injectée. Avec ultracode activé, la référence de rédaction de workflow dit : « author and run a workflow for every substantive task by default. The goal is the most exhaustive, correct answer you can produce » et que « token cost is not a constraint. » Le même texte est cité dans une issue publique intitulée « Ultracode overrides the workflow size guideline » s8. Chaque workflow d'une séquence reçoit son propre budget d'agents, donc quatre phases de 15 agents font 60 agents alors qu'aucun workflow ne dépasse la consigne s8.

Les trois garde-fous. Ultracode désactive trois contrôles. L'avertissement Large workflow n'apparaît pas. La limite de sous-agents simultanés de la session n'est pas appliquée aux sous-agents que Claude lance avec l'outil Agent. En mode de permission auto, on ne vous demande pas d'approuver le premier lancement de workflow s1.

La consigne de taille. Small veut dire moins de 5 agents, medium moins de 10, large moins de 50. Le défaut est medium, ou small sur un forfait Pro avec la v2.1.271 ou plus récente. Claude Code l'envoie au modèle comme conseil, pas comme plafond, donc un prompt qui demande une autre échelle la remplace encore s1. Les limites strictes sont 16 agents simultanés par défaut et 1 000 agents par run. L'avertissement de gros workflow se déclenche au-dessus de 25 agents ou de 1,5 million de tokens projetés, et il ne fait qu'avertir s1.

Notre propre run. Nous avons tapé le mot-clé sur un bac à sable de deux fichiers et 16 lignes de code, avec la consigne de taille réglée sur small, et demandé une revue en lecture seule. Le run a utilisé 9 agents : 2 chercheurs et 7 vérificateurs. Chaque chercheur a lu environ 45,2k tokens. Nous n'avons pas fait de run classique du même prompt, donc nous n'avons pas de chiffre apparié à nous.

Le test apparié. Sur un forfait à 200 $, un développeur a donné la même spécification à un run classique et à un run ultracode. Les deux ont passé 136/136 vérifications cachées. Le run classique a fini en 25 min à 8 % de la limite des 5 heures. Le run ultracode a été coupé à 76 min avec 18 % consommés, et il a utilisé 12 agents en deux équipes (9 et 3), pas 1 000. Par minute, la consommation était à peu près égale : il ne s'est simplement pas arrêté s3.

Trois paires de plus sur un forfait Pro. Agent seul contre workflow, mêmes résultats : 115k contre 972k tokens, 52k contre 936k, et 102k contre 683k. Le compteur /usage a bougé de 4 contre 12, 7 contre 12 et 4 contre 8 points, ce que l'auteur résume à environ deux fois le quota, jusqu'à trois. Le temps réel sur le script du plan Opus était de 173 s contre 178 s. Sur quatre recherches indépendantes, le parallèle était 1,6x plus rapide pour 2,3x les tokens s4.

La paire à 30x. Un agent à xhigh a pris 1 h 13 m pour environ 18 $ aux prix de l'API. Max avec ultracode a pris 9 h 14 m, avec 40 sous-agents, pour environ 554 $. Un run chacun, prix catalogue de l'API, non facturé sur un abonnement s11.

À quoi ressemble une paire. Un dépôt de test public contient une paire agent seul contre workflow sur la même tâche. L'agent seul a utilisé 181 646 tokens, le workflow 1 326 703. Le coût au prix de l'API était de 0,2678 $ contre 1,3744 $. Le temps réel était de 43 s contre 80 s, et le compteur de session a bougé de +0 contre +12 points s22. C'est une paire, donc lisez-la comme une forme et pas comme une loi. La documentation cite les sous-agents et les workflows parmi les moteurs de tokens : chaque agent qu'un workflow lance envoie ses propres requêtes en plus de celles de la conversation principale s5. L'équipe de recherche d'Anthropic a mesuré environ 4x plus de tokens pour un agent que pour un chat, et environ 15x pour un système multi-agents s20.

Où ça paie : Bun. Bun a été réécrit de Zig vers Rust avec environ 50 workflows dynamiques tournant en continu pendant 11 jours. La source faisait 535 496 lignes de Zig, et le portage est allé du départ à 100 % de la suite de tests qui passe sur toutes les plateformes en 11 jours s19. Le juge était une suite de tests existante.

Où ça paie : la chasse aux bugs. Anthropic a planté 70 bugs dans une base de code de 116k lignes. Sur 3 runs, un agent seul en a trouvé 14, 15 et 27. Un workflow en a trouvé 66 à chacun de ses 3 runs s24. Ce test a tourné sur Managed Agents, le produit API, pas sur Claude Code. Anthropic n'a donné aucun coût et conseille de commencer par une tâche circonscrite s24. Le blog de lancement dit que la plupart des tâches de code traditionnelles n'ont pas besoin d'un panel de 5 relecteurs s2.

Le run incontrôlé. Un script écrit par le modèle sur un forfait Max 20x a démarré 221 agents en 51 minutes. Après la première erreur de limite de session, 189 agents de plus ont été démarrés. Le tableau de l'auteur compte 47 465 299 tokens, cache inclus s7. Deux réserves de l'auteur : les 189 agents suivants n'avaient aucune réponse de modèle enregistrée, et le repli du script a continué à envoyer quand une fusion ne renvoyait rien. Ce run était sur la v2.1.266, avant la pause à la limite d'usage s7. Un second rapport public décrit deux workflows de 56 et 104 agents, 1 472 855 et 1 752 360 tokens, où 92 agents sur 160 ont échoué à cause de la limite de session s21. L'auteur dit qu'ultracode était signalé comme actif sans que l'utilisateur l'ait activé.

Les leviers. CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS prend une valeur de 1 à 256 et demande la v2.1.269 s10. CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL fait tourner chaque agent de workflow sur un seul modèle pendant que les autres sous-agents gardent le leur, à partir de la v2.1.296 s18. Avec autoContinueAtUsageLimit activé, un run qui atteint la limite se met en pause et reprend à la réinitialisation, jusqu'à deux attentes, et la troisième fois l'agent échoue. Désactivé, les agents concernés échouent au mur s1. Le blog de lancement dit qu'un budget dans le prompt, comme « use 10k tokens », fixe le plafond s2. La vue /workflows montre l'usage de tokens de chaque agent, et x arrête le run s1. /usage signale les comportements qui représentent 10 % ou plus de l'usage récent, et la v2.1.299 a ajouté des avertissements pour les workflows s5 s18.

Le kit de plafonds

Le bloc de réglages. Le plafond 1 est la consigne de taille, le plafond 4 est ultracode gardé à false pour que le mot-clé soit la seule entrée, et le plafond 5 est l'auto-continue désactivé. Mettez-le dans .claude/settings.json ou dans n'importe quel fichier de réglages. La clé workflowSizeGuideline fonctionne dans tout fichier de réglages à partir de la v2.1.219 s1.

settings.json

{
  "workflowSizeGuideline": "small",
  "ultracode": false,
  "autoContinueAtUsageLimit": false
}

settings.json on GitHub

Les lignes d'environnement. Plafonds 2 et 3. Remplacez le paramètre fictif par l'identifiant complet du modèle sur lequel vous voulez faire tourner vos agents de workflow.

ultracode-caps.sh

#!/usr/bin/env bash
# Source this file before you launch Claude Code: `source ultracode-caps.sh && claude`.
# These two lines are caps 2 and 3 of the five. Caps 1, 4 and 5 live in settings.json.

# Cap 2: at most 4 workflow agents run at once. The default is 16 (fewer on a machine
# with few CPUs). Accepted values are 1 to 256. Needs Claude Code v2.1.269 or later.
export CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS=4

# Cap 3: run every workflow agent on one cheaper model, while your other subagents
# keep theirs. Replace the placeholder with the full model id you want to pay for.
# Needs Claude Code v2.1.296 or later.
export CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL="<your-cheaper-model-id>"

# Optional kill switch for a shared machine: no workflows at all.
# export CLAUDE_CODE_DISABLE_WORKFLOWS=1

ultracode-caps.sh on GitHub

La checklist à passer avant de taper le mot-clé.

when-to-fan-out.md

# When to fan out: the two-condition checklist

Fan out (use the ultracode keyword in one prompt) only if both answers are yes.

1. Does a test suite or a rule set judge the output?
   - [ ] A suite that already exists and says pass or fail without anyone's opinion.
   - [ ] Or a written rule file the output is reviewed against.
2. Does the job split into independent pieces?
   - [ ] No piece waits on the result of another piece.
   - [ ] Each piece can be checked on its own.

If either answer is no, run plain at high effort. A plain run costs one bill. A
workflow costs one bill per agent.

Jobs that usually pass both tests:
- A port or migration across many files with a test suite as the judge.
- A review of a whole codebase against a rule file.
- A translation of many files with the same prompt.
- A cleanup pass over a pile of similar documents.

Jobs that usually fail one of them:
- A small feature, a bug fix, a refactor of one module.
- Anything where "good" is a matter of taste.
- A chain of steps where each one needs the previous result.

Before you start:
- [ ] Run a slice first (one folder, ten files) and read the token total.
- [ ] Put a budget in the prompt, for example "use 10k tokens".
- [ ] Open /workflows and watch per-agent tokens. Press x to stop.
- [ ] After the run, open /usage and read the share that went to workflows.

when-to-fan-out.md on GitHub

Les paires et cas mesurés issus des sources, une ligne chacun, avec l'identifiant de la source.

paired-runs.csv

source_id,run,measure,baseline,workflow_or_fanout,note
s22,rebuild-your-claude-md pair (rep 2),tokens,181646,1326703,"all four usage fields summed, 14 agent transcripts on the workflow side"
s22,rebuild-your-claude-md pair (rep 2),API cost in USD,0.2678,1.3744,single agent vs workflow
s22,rebuild-your-claude-md pair (rep 2),wall time in seconds,43,80,single agent vs workflow
s22,rebuild-your-claude-md pair (rep 2),session meter points,+0,+12,"/usage before to after: 17% to 17% vs 19% to 31%"
s24,70 planted bugs in 116k lines,bugs found,"14, 15 and 27 (3 runs)","66 in each of 3 runs","Managed Agents, not Claude Code; no cost given"
s19,Bun port from Zig to Rust,test suite passing,,100%,"about 50 dynamic workflows, 11 days, 535,496 lines of Zig"
s6,fixed worker and gate files,tokens for workflow execution and monitoring,100%,about 20%,"self-reported, no plan stated; runs 5 to 6 hours down to 20 to 40 minutes"
s7,runaway run on Max 20x,agents started,,221,"51 minutes; 189 started after the first session-limit error; 47,465,299 tokens including cache"
s21,ultracode reported on without the user enabling it,agents started,,"56 and 104","1,472,855 and 1,752,360 tokens; 92 of 160 agents failed with the session limit"
s20,multi-agent research system,tokens vs a chat,about 4x for an agent,about 15x for multi-agent,Anthropic's own data
s3,same spec on a $200 plan,hidden checks passed,136/136,136/136,"both runs perfect"
s3,same spec on a $200 plan,time and 5-hour limit used,"25 min, 8%","76 min (cut off), 18%","12 agents in two teams (9 and 3)"
s4,Opus plan script,tokens,115k,972k,"Pro plan; /usage 4 vs 12 points; 173 s vs 178 s"
s4,compact script,tokens,52k,936k,"Pro plan; /usage 7 vs 12 points"
s4,Claude.md script,tokens,102k,683k,"Pro plan; /usage 4 vs 8 points"
s4,four independent research jobs,time and tokens,"102 s, about 33k","about 64 s, 76k","parallel 1.6x faster for 2.3x tokens"
s11,Cybercity,time and API cost,"1 h 13 m, about $18 (1 agent)","9 h 14 m, about $554 (40 subagents)","xhigh vs max with ultracode; one run each; API list prices"

paired-runs.csv on GitHub

Deux notes sur le kit. La clé ultracode n'a d'importance que si vous démarriez sinon vos sessions avec le bouton activé, et la garder à false fait de chaque fan-out une décision que vous prenez dans un seul prompt. Désactiver complètement les workflows retire le mot-clé et le bouton : mettez "disableWorkflows": true dans ~/.claude/settings.json s1.

À faire lundi

Copiez settings.json dans les réglages de votre projet et vérifiez que /config affiche la consigne de taille sur small.
Chargez ultracode-caps.sh dans le shell d'où vous lancez Claude Code, avec un vrai identifiant de modèle à la place du paramètre fictif.
Vérifiez que le bouton ultracode est éteint dans /effort, et utilisez le mot-clé dans un seul prompt quand vous voulez un fan-out.
Avant tout fan-out, répondez aux deux questions de when-to-fan-out.md. Si une réponse est non, lancez en classique à high.
Lancez d'abord une tranche et lisez le total de tokens dans /workflows avant d'élargir le travail.
Ajoutez un budget au prompt, par exemple « use 10k tokens ».
Gardez /workflows ouvert au premier run et appuyez sur x si le nombre d'agents monte plus haut que prévu.
Après le run, ouvrez /usage et notez la part qui est allée aux workflows.

Aller plus loin

Fixez le worker et le gate au lieu de laisser le modèle les écrire. Un post Hacker News rapporte avoir ramené la dépense de tokens pour l'exécution et la surveillance des workflows à environ 20 % de ce qu'elle était, avec des workflows qui prenaient 5 à 6 heures et prennent maintenant 20 à 40 minutes. C'est déclaré par l'auteur et sans forfait précisé s6. La méthode a deux parties. Un fichier d'agent workflow-worker reçoit un morceau du plan et des permissions restreintes pour écrire et lancer des tests de sa propre partie uniquement. Un fichier d'agent workflow-gate prend les résultats des agents parallèles, et les vérifications en série passent dans un Makefile avec deux cibles : make workflow-serial-gate vérifie l'arbre git et lance les tests de ce qui a changé, et make workflow-final-gate lance des tests propres sur tout s6. La vérification de gate qui prenait 10 minutes pour des plans complexes prend maintenant une seconde, selon le même post. Les 20 % couvrent l'exécution et la surveillance, pas la création du plan ni l'implémentation. Pour essayer, écrivez les deux fichiers d'agent une fois, gardez-les dans le dépôt, et pointez votre prompt de workflow vers eux.

Lisez le rapport du run incontrôlé avant de faire confiance à un script généré. L'issue montre un tableau par phase et le schéma unique derrière les 189 agents en trop : quand un agent de fusion ne renvoie rien, le script se rabat sur la liste brute et continue s7. Demandez au modèle des scripts qui s'arrêtent sur un agent en échec. Gardez l'auto-continue désactivé sur tout run que vous ne surveillez pas.

Sachez pourquoi la consigne perd. L'issue 92631 montre le texte de la consigne à côté de la phrase d'ultracode, et pourquoi la seconde gagne quand elles divergent s8. Si vous voulez un plafond strict, la variable de concurrence limite le nombre d'agents qui tournent en même temps, et le budget dans le prompt limite ce qu'ils dépensent.

Utilisez le fil de lancement pour les gros travaux. Le rejet le plus tranchant du premier jour est dans le fil de lancement, avec des commentaires comme « an exciting new way to burn up as many tokens as possible » et « Quantity of output is not the issue right now. Quality is. » s9. Les gains que les gens y rapportent ont la même forme : revue face à un fichier de règles, traduction d'une base de code, nettoyage de pages scannées.

Managed Agents est un autre produit. Le test des 70 bugs utilisait les workflows dynamiques de Managed Agents, qui sont réservés à l'API. Si vous construisez sur l'API, commencez par une tâche circonscrite, comme Anthropic le conseille s24. Les réglages de Claude Code ne s'y appliquent pas.

Ce à quoi il ne faut pas se fier. Les anecdotes de quota sans forfait ni chiffre sont de seconde main. Un commentateur rapporte que 6 agents ont mangé un quota de 4 heures, et un autre rapporte un portage de presque 2 milliards de tokens qui a coûté 20 $ sur un modèle bon marché d'un autre fournisseur via son propre clone s23 s9. Aucun des deux n'est une mesure de Claude Code sur un forfait. Un chiffre n'a sa place dans vos notes que s'il vient avec le forfait, le modèle, la version et la tâche.

FAQ

Le mot-clé coûte-t-il autant que le bouton ? Non. Le mot-clé exécute une tâche comme workflow. Le bouton planifie un workflow pour chaque tâche substantielle, donc une demande peut en devenir plusieurs s1. Les deux dépensent en plus de votre conversation, parce que chaque agent envoie ses propres requêtes s5.

Régler la consigne de taille sur small limite-t-il un run à 4 agents ? Non. C'est un conseil envoyé au modèle, et un prompt ou la phrase d'ultracode peut le remplacer s1 s8. Sur notre run, elle disait moins de 5 et le run en a utilisé 9. Les limites strictes sont la variable de concurrence et votre propre arrêt.

Que se passe-t-il quand un run atteint ma limite d'usage ? Avec autoContinueAtUsageLimit activé, une session claude.ai interactive met le run en pause et continue à la réinitialisation, jusqu'à deux attentes, à partir de la v2.1.271. Les versions antérieures font échouer les agents concernés s1. Désactivé, les agents échouent à la limite et le run s'arrête là.

Pourquoi un modèle moins cher pour les agents de workflow ? L'essentiel d'un workflow est de la vérification, et chaque agent envoie ses propres requêtes. CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL met tous les agents de workflow sur un seul modèle et laisse vos autres sous-agents tranquilles s18. Vérifiez le résultat sur une tranche avant de vous y fier.

Puis-je encore utiliser ultracode ? Oui, pour les travaux qui passent les deux questions de la checklist. Le portage de Bun avait une suite de tests complète comme juge s19. Pour une petite fonctionnalité ou un correctif, un run classique à high reste le défaut.