Tu as vu passer le mot ultrathink dans un tutoriel, un thread ou un fichier de config, et tu te demandes s'il faut l'écrire dans chaque prompt. La réponse tient en une ligne : non. Depuis Claude Code 2.1.311, ce mot-clé fait tourner le tour concerné à l'effort xhigh, et ça a un prix en quota. Cet article te dit ce qu'il déclenche, quand il vaut son coût et comment fixer l'effort de tes sous-agents. Si tu pars de zéro sur Claude, commence par le guide complet pour apprendre Claude.
En bref :
- Écrit n'importe où dans un prompt,
ultrathinkdemande un raisonnement plus profond sur ce seul tour, sans changer le niveau d'effort de la session. - Depuis la version 2.1.311 (26 octobre 2026), dans le terminal interactif, il fait tourner le tour à l'effort
xhighsur Opus 5.5, Sonnet 5.5, Haiku 5.5 et Fable 5.1. - Les niveaux d'effort vont de
lowàmax; plus on monte, plus la réflexion consomme de tokens, donc de quota ou de coût API. - La version 2.1.316 (31 octobre 2026) ajoute
CLAUDE_CODE_SUBAGENT_EFFORTpour fixer l'effort des sous-agents au lieu de leur faire hériter celui de la session. - Réserve l'effort élevé aux étapes où une erreur de raisonnement coûte cher, et fais travailler les tâches mécaniques à un niveau bas ou moyen.
Que fait ultrathink dans Claude Code aujourd'hui ?
Le mot ultrathink, placé n'importe où dans ton prompt, demande à Claude Code un raisonnement plus profond sur ce seul tour. Depuis la version 2.1.311, dans le terminal interactif, ce tour tourne à l'effort xhigh sur Opus 5.5, Sonnet 5.5, Haiku 5.5 et Fable 5.1 via l'API d'Anthropic. La session, elle, garde son niveau habituel.
Quelques détails de comportement tirés du changelog et de la doc officielle. Le mot s'affiche en arc-en-ciel dans la zone de saisie, mais seulement quand il peut vraiment relever l'effort : entre guillemets ou dans un chemin de fichier, il reste du texte ordinaire. Si tu le tapes pendant que Claude travaille déjà, il relève le reste du tour en cours. Et les variantes du type « think hard » ou « think more » ne sont pas reconnues comme des mots-clés : ce sont des phrases comme les autres.
La version 2.1.316 va plus loin : l'extension VS Code applique la même règle (tour à xhigh, arc-en-ciel dans la zone de saisie), et une variable d'environnement, CLAUDE_CODE_DISABLE_ULTRATHINK, permet de désactiver le mot-clé. Utile pour une équipe qui veut garder la main sur la consommation. Ces deux variables nouvelles figurent dans le changelog de la 2.1.316 mais, au 31 octobre 2026, pas encore dans les pages de référence : je m'appuie donc sur le changelog.
Qu'est-ce que les niveaux d'effort de Claude Code, et où se situe xhigh ?
L'effort règle la quantité de réflexion que le modèle investit avant de répondre. Selon la doc officielle, l'échelle compte cinq niveaux : low, medium, high, xhigh et max. xhigh se place donc au-dessus de high, juste sous max.
| Niveau | Usage conseillé | Coût relatif en réflexion |
|---|---|---|
| low | Modifications mécaniques, questions factuelles courtes | Le plus bas |
| medium | Travail courant, défaut d'Opus 5.5, Sonnet 5.5 et Haiku 5.5 | Modéré |
| high | Débogage standard, défaut des autres modèles | Élevé |
| xhigh | Architecture, bug difficile, revue de sécurité | Très élevé |
| max | Cas extrêmes, session courante uniquement | Le plus élevé |
Le niveau xhigh est disponible sur Fable 5.1, Fable 5, Opus 5.5, Sonnet 5.5, Haiku 5.5, Opus 5, Sonnet 5, Opus 4.8 et Opus 4.7. Opus 4.6 et Sonnet 4.6 n'ont pas ce palier. Aucun chiffre officiel ne donne le surcoût exact de xhigh : le principe est simple, plus d'effort signifie plus de tokens de réflexion, donc plus de consommation d'usage ou de coût API. Ne retiens aucun pourcentage que tu croiserais sans source.
Pour voir et changer le niveau actif, la commande /effort ouvre un curseur, et /effort high (par exemple) fixe directement le niveau. Attention à max : il ne vaut que pour la session courante, sauf si tu le fixes via la variable CLAUDE_CODE_EFFORT_LEVEL. Pour mettre en place l'outil lui-même, installer et prendre en main Claude Code te prendra un quart d'heure.
Quand faut-il écrire ultrathink, et quand vaut-il mieux s'en passer ?
Écris ultrathink quand une erreur de raisonnement coûte cher : décision d'architecture, bug qu'on ne reproduit pas, refactor sur plusieurs fichiers, revue de sécurité. Évite-le pour tout ce qui est mécanique, où réfléchir plus longtemps ne change pas le résultat et ne fait que consommer ton quota.
Trois cas concrets, avec le prompt à copier.
Planifier le schéma d'une base Supabase. Une mauvaise modélisation se paie ensuite à chaque fonctionnalité ajoutée :
ultrathink. Je construis une app de réservation de créneaux pour des coachs.
Propose le schéma Supabase (tables, relations, contraintes) avant d'écrire
le moindre code. Liste les compromis que tu fais et les cas limites
(annulation, fuseau horaire, double réservation).Diagnostiquer un bug de déploiement Vercel. Le site tourne en local et casse en production, le genre de bug où il faut croiser variables d'environnement, build et runtime :
ultrathink. Le build passe en local mais la page /dashboard renvoie une
erreur 500 sur Vercel. Lis les logs fournis ci-dessous, formule trois
hypothèses classées par probabilité, puis vérifie-les une par une dans le
code avant de proposer un correctif.Restructurer une app Next.js. Déplacer la logique métier hors des composants touche beaucoup de fichiers à la fois, et l'ordre des modifications compte :
ultrathink. Sépare la logique d'accès aux données des composants de
l'app Next.js. Établis d'abord le plan de migration fichier par fichier,
signale ce qui risque de casser, et attends ma validation avant de
modifier quoi que ce soit.À l'inverse, renommer des variables, corriger une faute dans un texte ou reformater un fichier ne demandent aucun raisonnement poussé : ultrathink y est du gaspillage pur. Sur l'impact précis en durée et en quota, je n'ai pas de mesure interne à te donner, et Anthropic n'en publie pas non plus : mesure toi-même en comparant ta consommation avant et après sur une tâche répétée. Pour passer de ces prompts à un produit complet, regarde comment créer une application avec Claude Code sans être développeur.
Comment régler l'effort d'un sous-agent dans Claude Code ?
Un sous-agent se définit dans un fichier Markdown placé dans .claude/agents/, avec un en-tête YAML. Depuis la version 2.1.316, tu peux aussi fixer l'effort de tous tes sous-agents d'un coup avec la variable CLAUDE_CODE_SUBAGENT_EFFORT, utilisée quand rien d'autre ne désigne un niveau, au lieu d'hériter de la session.
Voici la définition d'un agent de revue, à copier telle quelle :
---
name: reviewer
description: Relit les modifications avant commit et signale les risques
model: inherit
---
Tu relis le code modifié. Cherche les erreurs de logique, les cas limites
non gérés et les problèmes de sécurité. Réponds par une liste courte,
classée par gravité.La commande /agents permet de créer et modifier ces agents depuis Claude Code sans toucher au fichier à la main. Ce que le changelog ne détaille pas, c'est un champ d'effort dans l'en-tête YAML : je ne t'en donne donc pas, et je te conseille de vérifier dans la doc officielle des sous-agents avant d'en écrire un. Ce qui est documenté, ce sont les variables d'environnement.
Pour l'héritage, la règle de la doc model-config est la suivante : CLAUDE_CODE_SUBAGENT_EFFORT règle l'effort des sous-agents quand rien d'autre n'en désigne un, et CLAUDE_CODE_EFFORT_LEVEL, s'il est défini, prime sur l'effort déclaré dans un sous-agent. Concrètement :
export CLAUDE_CODE_SUBAGENT_EFFORT=medium
claudeAvec ce réglage, tes sous-agents tournent à medium même si ta session principale monte en xhigh. Sans lui, ils suivent le comportement par défaut décrit dans la doc, ce qui peut les faire travailler plus haut que nécessaire.
Quel effort choisir pour quel type de sous-agent ?
Garde l'effort élevé pour les agents qui planifient ou relisent (architecte, reviewer, auditeur de sécurité), et un effort bas à moyen pour les agents d'exécution rapide : formatage, recherche de fichiers, génération de tests simples. L'effort d'un agent doit refléter le coût d'une erreur de sa part, pas son importance apparente.
Voici une configuration type pour une petite application :
| Agent | Rôle | Effort conseillé | Pourquoi |
|---|---|---|---|
| architect | Planifie les changements avant toute modification | high à xhigh | Une erreur de plan se répercute sur tout le reste |
| reviewer | Relit le diff avant commit | high | Repérer une faille coûte moins cher que la corriger après |
| worker | Applique les modifications, formate, renomme | low à medium | La tâche est mécanique, réfléchir plus ne change rien |
Le raisonnement sur le coût tient en une phrase : un orchestrateur qui monte en effort pour décider, puis délègue à des exécutants économes, consomme moins qu'une session entière réglée en xhigh avec les mêmes sous-agents. Tu paies la réflexion là où elle apporte quelque chose.
Une nuance importante : Anthropic a publié le 22 octobre 2026 un guide qui recommande d'utiliser moins de sous-agents qu'on ne le fait d'habitude, et de s'appuyer sur un agent unique avec des skills. Les sous-agents restent pertinents pour les tâches parallèles ou quand un contexte chargé fait chuter la qualité. Le détail est dans notre article sur l'agent unique ou les sous-agents : avant d'optimiser l'effort de trois agents, vérifie que tu en as vraiment besoin de trois.
Ultrathink, effort global ou effort par sous-agent : lequel utiliser ?
Utilise ultrathink pour un coup de boost ponctuel sur un prompt, le réglage /effort pour toute une session de travail difficile, et l'effort par sous-agent pour une configuration durable. Les trois ne s'excluent pas, mais chacun a sa portée et son risque de surconsommation.
| Méthode | Portée | Durée | Cas d'usage | Risque de surconsommation |
|---|---|---|---|---|
| ultrathink | Le tour en cours | Un seul tour | Une décision précise ou un bug bloquant | Faible, tu contrôles chaque usage |
| /effort (session) | Tous les échanges | Jusqu'à changement | Une longue séance sur un problème complexe | Élevé si tu oublies de redescendre |
| Effort des sous-agents | Chaque agent concerné | Durable, versionné | Équipe d'agents partagés dans le repo | Faible une fois réglé, prévisible |
Pour un solo qui construit son premier produit, le plus simple est de rester à l'effort par défaut et d'écrire ultrathink à la main sur les trois ou quatre moments où ça compte. Pour une équipe qui partage des agents dans son dépôt, c'est l'inverse : fixe l'effort de chaque agent une fois, et la consommation devient prévisible, sans dépendre des habitudes de chacun. Une équipe peut aussi couper le mot-clé avec CLAUDE_CODE_DISABLE_ULTRATHINK pour éviter les dérives.
Comment éviter de brûler son quota avec un effort trop élevé ?
Surveille ta consommation, monte en effort seulement sur l'étape qui bloque, puis redescends. Le plus gros piège est d'oublier un réglage de session en xhigh ou max et de laisser Claude réfléchir à fond sur des tâches triviales pendant des heures.
Trois réflexes simples :
- Démarre à un niveau modéré. Le défaut d'Opus 5.5, Sonnet 5.5 et Haiku 5.5 est
medium, et c'est un bon point de départ pour le travail courant. - Escalade par prompt, pas globalement. Écrire
ultrathinksur l'étape difficile revient moins cher que de passer toute la session enxhigh. - Cantonne
xhighà la planification et à la revue. Pour les agents d'exécution, fixeCLAUDE_CODE_SUBAGENT_EFFORTà un niveau bas ou moyen.
Côté limites, elles dépendent de ton abonnement ou de ton usage API, et elles évoluent régulièrement : consulte la page de ton plan plutôt que de t'appuyer sur un chiffre vu en passant. Une bonne lecture pour cadrer ça est notre point sur le contexte 1M et la limite de 5 heures de Claude Code.
Questions fréquentes
Faut-il toujours écrire ultrathink dans mes prompts Claude Code ?
Non. Ce mot-clé déclenche une réflexion plus longue et plus coûteuse en quota, utile pour une décision d'architecture ou un bug difficile, inutile pour une modification mécanique. Utilise-le sur l'étape où une erreur de raisonnement coûterait cher, pas par défaut.
Quelle différence entre ultrathink et changer le niveau d'effort de toute la session ?
Ultrathink agit sur le tour où tu l'écris, comme un boost ponctuel, sans toucher au niveau de la session. Le réglage /effort s'applique à tous les échanges jusqu'à ce que tu le changes. Pour un travail suivi sur un problème complexe, le réglage de session évite de répéter le mot-clé, au prix d'une consommation plus élevée.
Où se configure l'effort d'un sous-agent ?
Les sous-agents se définissent dans un fichier Markdown de .claude/agents/, et la commande /agents permet de les créer et modifier. Pour l'effort, la variable CLAUDE_CODE_SUBAGENT_EFFORT (version 2.1.316) fixe le niveau quand rien d'autre n'en désigne un. Vérifie dans la doc officielle si un champ d'effort existe dans l'en-tête YAML avant d'en utiliser un.
Un sous-agent hérite-t-il de l'effort de la session principale ?
Sans réglage propre, il suit le comportement par défaut décrit dans la documentation de Claude Code, ce qui peut le faire tourner à un niveau plus élevé que nécessaire. Si CLAUDE_CODE_EFFORT_LEVEL est défini, il prime sur l'effort déclaré dans un sous-agent. Fixer l'effort explicitement rend la consommation prévisible.
Peut-on utiliser xhigh sans abonnement Max ?
Cela dépend de ton plan et du modèle sélectionné. Consulte la page des abonnements et la documentation Anthropic pour les conditions à jour : les limites et les accès par plan changent régulièrement, et aucune source vérifiée ne donne ici de réponse par palier.
Passer à la pratique
Teste ça sur ton propre projet cette semaine : repère le moment où Claude se trompe sur un raisonnement, écris ultrathink à cet endroit précis, et compare avec un tour sans le mot-clé. Ensuite, fixe l'effort de tes sous-agents. Si tu veux monter un workflow d'agents complet, avec une application déployée à la clé, c'est exactement ce que couvre Construire votre produit IA en 5 semaines.