Claude Code vous offre deux paramètres qui semblent tous deux "améliorer la réponse" : le modèle et le niveau d'effort. Mais quel est leur réel impact sur le résultat ? Et comment savoir s'il faut opter pour un modèle différent ou simplement modifier le niveau d'effort ?
Il est facile de supposer que choisir un modèle plus grand comme Fable donne un résultat plus intelligent que Sonnet, et qu'un niveau d'effort plus élevé signifie simplement que Claude réfléchit plus longtemps avant de répondre.
La première hypothèse est vraie. Nos plus grands modèles sont plus performants, selon les benchmarks standard de l'industrie.
Mais l'effort signifie bien plus qu'un "temps de réflexion". L'effort contrôle la quantité de travail que Claude effectue globalement sur votre demande. Cela inclut le temps de réflexion, mais aussi :
- le nombre de fichiers qu'il lit ;
- le niveau de vérification qu'il effectue ;
- et jusqu'où il avance dans une tâche en plusieurs étapes avant de vous faire un point.
Avec un effort plus élevé, Claude effectue davantage de ces actions (lire des fichiers, exécuter des tests, revérifier) avant de revenir vers vous. Avec un effort plus faible, il préfère vous demander plus de contexte plutôt que de dépenser des tokens pour trouver une solution par lui-même.
Comment fonctionne la sélection du modèle
Pour comprendre ce que le paramètre de modèle contrôle réellement, il est utile de commencer par le tout début, à partir du moment où vous appuyez sur Entrée.
Claude Code assemble votre message avec le prompt système, les définitions d'outils, votre CLAUDE.md, l'historique de la conversation et tous les fichiers en contexte. Le tout est envoyé comme une seule requête à l'API.
Tout ce que Claude Code possède est regroupé dans une seule requête API. Sur le serveur, le texte est tokenisé avant même d'atteindre le modèle.
Le modèle ne voit jamais rien de tout cela en texte brut, cependant. La première chose qui se produit sur le serveur est la tokenisation : le texte est divisé en morceaux, et chaque morceau est associé à un entier provenant d'un vocabulaire fixe avec lequel le modèle a été entraîné. const pourrait correspondre à 1978, await pourrait correspondre à 4293. À partir de là, votre prompt est un tableau d'entiers.
Le tokeniseur divise votre texte en morceaux et associe chaque morceau à un entier dans un vocabulaire fixe. Chaque bloc de la rangée supérieure devient son ID de token (rangée inférieure) ; les ID affichés sont illustratifs.
Le travail du modèle est de prendre ce tableau et de prédire quel token vient ensuite. Il le fait en calculant une probabilité pour chaque token de son vocabulaire et en choisissant parmi les meilleurs. Après "const x = await", un modèle bien entraîné attribue une probabilité élevée à "fetch" (très probable) et quasi nulle à "banana" (pas probable du tout).
La prédiction du modèle est une probabilité pour chaque token de son vocabulaire. L'écart entre la meilleure estimation et une estimation non pertinente est énorme.
Ce qui transforme vos tokens d'entrée en ces probabilités, ce sont les poids (également appelés paramètres) : des milliards de nombres organisés en grandes matrices. Pour prédire un token, le modèle fait passer votre entrée à travers ces matrices (une longue chaîne de multiplications matricielles) et lit les probabilités à la fin. Les poids sont l'endroit où réside tout ce que le modèle "sait" .
Les poids de chaque modèle sont définis lors de l'entraînement, et au moment où vous envoyez des requêtes, ils sont en lecture seule. Rien dans votre prompt, votre CLAUDE.md ou votre contexte ne les modifie. Si vous avez déjà rencontré le mot inférence, c'est tout ce que cela signifie : utiliser le modèle après la fin de l'entraînement, avec les poids fixes.
Votre prompt entre, les probabilités sortent. Les poids au milieu ne changent pas.
Tout ce que Claude sait sur TypeScript, les frameworks populaires ou toute autre connaissance générale en programmation a été encodé dans ces poids lors de l'entraînement.
Votre prompt et votre contexte peuvent toujours orienter la prédiction. Mettre votre vrai code devant Claude est une forme d'orientation, et cela fonctionne très bien. Cependant, cela n'ajoute rien aux poids eux-mêmes.
Si une bibliothèque n'existait pas lorsque le modèle a été entraîné, elle n'est pas dans les poids. Vous pouvez mettre la documentation en contexte et Claude l'utilisera, mais c'est de l'orientation, pas de l'apprentissage. La réponse de Claude n'est influencée que pour cette seule requête, mais le modèle sous-jacent n'a rien retenu.
Lorsque Claude appelle avec confiance une API qui n'existe pas (une hallucination), ce sont les poids qui produisent une séquence de tokens qui semble plausible d'après les schémas d'entraînement, et non un échec de recherche.
Alors, que fait réellement le changement de modèle ? Il échange l'ensemble de poids figés qui traite votre requête.
Le modèle ne génère pas une réponse entière d'un coup. Il prédit un token, l'ajoute à la séquence, et exécute à nouveau tout le calcul pour obtenir le suivant. Une réponse de 200 tokens correspond à 200 passages séparés à travers les poids. Cette boucle est à l'origine de la majeure partie de votre temps d'attente (et de votre coût de sortie).
La séquence s'allonge d'exactement un token par étape. Le modèle relit l'intégralité du tableau à chaque fois pour prédire la suite.
Le paramètre de modèle détermine quels poids traitent votre requête, et il détermine également le coût de chaque token de sortie.
Ce qu'il ne détermine pas, c'est le nombre de tokens qui seront générés. Ce nombre peut varier considérablement pour le même prompt, en fonction de la quantité de travail que Claude décide d'effectuer.
C'est exactement ce que contrôle l'effort.
Comment fonctionne l'effort
Pendant que Claude Code travaille sur une tâche, les tokens qu'il génèrent se répartissent en quelques catégories :
- Réflexion : le raisonnement que vous voyez en streaming avant et entre les actions.
- Appels d'outils : blocs structurés nommant un outil comme Read ou Edit et ses arguments, que Claude Code analyse ensuite et exécute.
- Texte pour vous : le plan, les mises à jour de progression, le résumé à la fin.
Ce sont tous des tokens de sortie ordinaires provenant de la même boucle, facturés au même tarif. Les tokens de réflexion, par exemple, sont générés exactement comme les autres tokens de sortie et restent en contexte pour le reste de ce tour.
Au moment où Claude passe à l'écriture de code, son raisonnement antérieur fait partie de l'entrée, tout comme un fichier qu'il a lu.
Toute la sortie de Claude est constituée de tokens. La réflexion, les appels d'outils et le texte pour vous sont tous générés à partir de la même boucle.
Alors, comment l'effort change-t-il tout cela ? Le niveau d'effort est envoyé au modèle dans le cadre de la requête, en même temps que votre prompt. Le modèle a été entraîné à comprendre comment se comporter à chaque niveau d'effort, et ce comportement appris est intégré dans les poids figés.
Lorsque votre requête arrive, l'effort n'est qu'une entrée supplémentaire à laquelle le modèle répond, de la même manière qu'il répond au texte de votre prompt. Il définit le degré de minutie, et de certitude, dont Claude a besoin avant de considérer la tâche comme terminée. Cela est pris en compte à chaque tour, et une confiance plus élevée nécessite plus de tokens pour être atteinte.
Même prompt, deux niveaux d'effort. Le chemin à effort élevé génère environ 7 fois plus de tokens pour atteindre une réponse de confiance plus élevée.
À des niveaux d'effort plus élevés, Claude commence souvent par créer un plan, et le niveau d'effort influence la profondeur et l'ampleur de ce plan. Mais le plan n'est pas figé. Au fur et à mesure que Claude reçoit les résultats de ses actions, il met à jour son image de ses progrès et de sa certitude quant au résultat accumulé.
Lorsque l'étape 1 d'un plan de débogage à trois hypothèses trouve le bug, "enquêter sur les hypothèses 2 et 3" peut ne plus être nécessaire. Claude le dira généralement explicitement (par exemple, "la première vérification a trouvé le problème, donc les vérifications restantes ne sont pas nécessaires") et passera à la suite. Vous voyez cela se produire dans Claude Code lorsque les listes de tâches sont révisées en cours d'exécution.
Un effort plus élevé rend Claude plus susceptible de revérifier, comme vérifier la réponse qu'il a trouvée, ou encore examiner les hypothèses qu'il aurait pu sauter. Cependant, il ne va généralement pas gonfler artificiellement l'utilisation sur une tâche simple simplement parce que le niveau d'effort est augmenté. La "suranalyse" est quelque chose que notre équipe surveille spécifiquement pendant l'entraînement du modèle, car elle dégrade l'efficacité.
Choisir un niveau d'effort
Pour la plupart des tâches, utilisez le niveau d'effort par défaut du modèle. Le niveau par défaut est celui où Claude adapte sa consommation de tokens à ce que la plupart des gens voudraient dépenser pour une tâche.
Considérez l'effort comme un override manuel sur la difficulté et la durée du travail de Claude. Utilisez-le délibérément lorsque vous avez une forte préférence pour la minutie ou la rapidité en fonction de votre domaine ou du type de travail que vous effectuez, et traitez-le comme une préférence générale, et non comme une décision tâche par tâche.
Une note pratique suite au lancement d'Opus 4.8 : dans nos tests, le réglage d'effort par défaut sur Opus 4.8 produit de meilleurs résultats pour à peu près le même nombre de tokens que le réglage d'effort par défaut sur Opus 4.7 pour la même tâche.
Que modifier lorsque Claude se trompe
Lorsque Claude se trompe, votre premier réflexe ne devrait pas être de modifier un paramètre. Il devrait être d'examiner le contexte que vous lui avez donné. Votre prompt est-il trop vague ? Claude est-il connecté aux bons outils ? A-t-il les bonnes compétences ?
Si vous augmentez l'effort sur une tâche qui ne devrait pas en avoir besoin, la correction se trouve généralement en amont : dans votre contexte, votre CLAUDE.md, ou la façon dont la tâche est définie.
Mais disons que vous avez donné un contexte clair et que Claude se trompe toujours. La question à vous poser est : n'a-t-il pas assez essayé, ou n'en savait-il pas assez ?
Modèle : le problème était trop difficile
Choisissez un modèle plus grand lorsque le problème est vraiment difficile, comme des bugs subtils, des domaines inconnus, des décisions d'architecture. Un modèle plus grand est ce qu'il vous faut lorsque le modèle plus petit est confiant et erroné peu importe le contexte que vous lui donnez.
Les modèles plus grands sont également meilleurs pour gérer l'ambiguïté. Sur les modèles plus petits, des instructions spécifiques qui dirigent l'exécution sont une meilleure recette pour le succès.
Choisissez un modèle plus petit lorsque le travail est routinier : des modifications que vous pouvez décrire précisément, des changements mécaniques, des questions sur du code déjà en contexte. Il n'y a aucune raison de payer pour une capacité dont la tâche n'a pas besoin.
Si Claude avait tout le contexte pertinent, a clairement essayé, et s'est quand même trompé ; c'est un signal pour choisir un modèle plus grand. Et si vous êtes sur le modèle plus grand et que le travail est routinier depuis un certain temps, descendre augmentera la vitesse et réduira généralement le coût sans impact sur la qualité du résultat.
Effort : Claude n'a pas assez essayé
Choisissez un niveau d'effort plus élevé si Claude a mal fait les choses en n'essayant pas assez : sauter un fichier, ne pas exécuter les tests, ou ne pas revérifier son travail. C'est particulièrement pertinent si vous aviez sélectionné un niveau d'effort inférieur à la valeur par défaut du modèle.
Le spécialiste, l'expert et le généraliste
Une façon que j'aime pour penser aux deux paramètres est que Fable est un spécialiste qui peut gérer des problèmes que presque personne d'autre ne peut résoudre, Opus est l'expert, et Sonnet est un très bon généraliste. Le niveau d'effort décide du temps que chacun d'eux consacre à votre tâche.
Opus à faible effort, c'est comme obtenir cinq minutes avec un expert qui a une expérience approfondie de problèmes similaires aux vôtres. Il apporte des connaissances qui ne se trouvent nulle part dans votre codebase ; des schémas qu'il a déjà vus, des pièges qu'il sait vérifier, le genre d'expérience que l'on n'acquiert qu'en ayant résolu beaucoup de problèmes similaires. Mais cinq minutes signifient une lecture rapide de votre code, pas un passage minutieux dans chaque fichier.
Sonnet à effort élevé, c'est le généraliste qui a tout l'après-midi. Il est excellent en codage, et il va tout lire, exécuter des choses, revérifier son travail, et finir par comprendre votre code spécifique en profondeur.
Fable est le spécialiste que vous appelez lorsque tout le monde est bloqué. Même à faible effort, il repérera la chose que personne d'autre ne verrait. Cette reconnaissance est aussi ce pour quoi vous payez le plus, donc il vaut la peine de le réserver pour les tâches qui en ont besoin.
Aucun de ces modèles n'est universellement "meilleur". Le paramètre de modèle correspond à peu près à la capacité ; le paramètre d'effort correspond à peu près à la minutie. La plupart des tâches réelles ont besoin d'un peu des deux.
Effort, modèle et consommation de tokens
Alors, comment la sélection du modèle, l'effort et la consommation de tokens interagissent-ils ? Cela dépend de la tâche.
Sur un travail routinier au même niveau d'effort, les modèles plus grands et plus petits réussissent généralement. Le modèle plus grand consomme plus de tokens avec des étapes de vérification supplémentaires, à un prix par token plus élevé. C'est pourquoi descendre au modèle plus petit pour les phases routinières permet de réaliser de réelles économies sans perte de qualité.
Les courbes sont données à titre d'illustration uniquement, montrées pour une seule tâche suffisamment simple pour être accomplie rapidement par les deux modèles. Elles ne représentent pas des données de benchmark réelles.
Sur un travail plus difficile et en plusieurs étapes, l'équation s'inverse. Le modèle plus petit doit peiner jusqu'à la limite de ses capacités, brûlant des itérations, tandis que le modèle plus grand atteint le même niveau de qualité en moins d'étapes.
Vous payez plus par token pour le modèle plus grand, mais sur des tâches qui mettent réellement à rude épreuve le modèle plus petit, le coût total par tâche peut s'avérer inférieur. Et plus important encore : le modèle plus grand peut accomplir des tâches que le modèle plus petit ne peut pas, même aux réglages d'effort les plus élevés.
C'est particulièrement prononcé avec Fable. Sur un travail long et en plusieurs étapes, il prend la plus grande avance. Dans nos tests, il a terminé des travaux qu'Opus et Sonnet ne peuvent pas atteindre, quel que soit le niveau d'effort. Il coûte également le plus par token, ce qui est l'autre raison de le réserver pour le travail qui en a vraiment besoin.
Les courbes sont données à titre d'illustration uniquement, montrées pour une seule tâche suffisamment difficile pour mettre les deux modèles à l'épreuve. Elles ne représentent pas des données de benchmark réelles.
Le point clé dans les graphiques ci-dessus : l'effort détermine jusqu'où Claude est prêt à aller le long de la courbe. Cela ne signifie pas que Claude aura besoin d'aller aussi loin pour terminer la tâche.
Enfin, l'effort façonne la consommation de tokens, mais il ne la limite pas. La seule limite stricte dans le système est max_tokens, qui tronque une réponse en plein milieu lorsqu'elle est atteinte, mais c'est un outil grossier et surtout pertinent pour les développeurs d'API. Des contrôles plus souples comme les budgets de tâche ou le fait de demander à Claude d'être bref dans votre prompt sont plus utiles. Ce sont des indications que le modèle est entraîné à suivre (il cherchera à conclure à l'approche de la limite) plutôt qu'un mur dans lequel il se heurte.
L'effort modifie la quantité de travail que Claude effectue. Le modèle modifie ce que Claude sait.
Lorsque vous n'êtes pas satisfait d'un résultat, vérifiez le contexte avant de toucher à l'un ou l'autre paramètre : donnez à Claude un prompt clair, les bons outils et compétences, et un moyen de vérifier son propre travail.
Si Claude se trompe encore, demandez-vous : n'en savait-il pas assez, ou n'a-t-il pas essayé assez fort ? Ne pas en savoir assez est un problème de modèle, ne pas essayer assez fort est un problème d'effort.
Cet article a été rédigé par @lydiahallie, membre du personnel technique de l'équipe Claude Code.
