Claude Code Outcomes : le guide des graders

Outcomes est la fonctionnalité de contrôle qualité présentée par Anthropic à Code with Claude 2026 : vous décrivez ce qu’est un bon résultat dans une rubric, un grader séparé note chaque sortie dans sa propre fenêtre de contexte, et il renvoie l’agent corriger jusqu’à atteindre le seuil. Sur les benchmarks internes d’Anthropic, ce dispositif gagne jusqu’à 10 points de taux de réussite sur les tâches les plus dures, sans changer de modèle.

J’ai testé Outcomes sur des tâches de génération de documents et de refactorisation depuis l’annonce. Ce guide détaille comment écrire une rubric qui tient la route, comment architecturer la boucle grader vers révision, et comment combiner Outcomes avec les subagents et les Dynamic Workflows pour des agents réellement fiables en production. Outcomes est distinct des Dynamic Workflows : l’un contrôle la qualité, l’autre orchestre l’exécution.

Le problème que résout Outcomes : l’auto-évaluation biaisée

Un agent qui relit son propre travail le rationalise au lieu de l’évaluer. C’est le constat de départ d’Outcomes, et il explique pourquoi le gain ne vient pas d’un modèle plus puissant.

Quand un agent produit une sortie, il dispose d’une fenêtre de contexte pleine de son propre raisonnement et de ses étapes intermédiaires. Quand on lui demande de juger ce résultat, il a tendance à justifier ses choix plutôt qu’à les remettre en cause. C’est exactement le type de fragilité qui fait que 80 % des projets d’agents IA échouent en production : aucun mécanisme systématique pour vérifier les sorties avant livraison.

Outcomes casse ce biais par une séparation stricte. La plateforme provisionne un grader, un agent évaluateur dans une fenêtre de contexte neuve qui ne contient que deux choses : la rubric et l’artefact. Il n’a jamais vu le raisonnement de l’agent producteur. Il part d’une page blanche et attrape les défauts que l’agent d’origine s’était convaincu d’ignorer.

Le résultat se mesure. Selon Anthropic, Outcomes améliore le taux de réussite des tâches jusqu’à 10 points par rapport à une boucle de prompting standard, avec les gains les plus marqués sur les tâches les plus difficiles. En détail : +10,1 % sur la génération de fichiers PowerPoint et +8,4 % sur les documents Word. Même modèle, mêmes prompts, le levier vient uniquement de la structure ajoutée autour du travail.

Le grader évalue dans une fenêtre de contexte neuve et renvoie l’agent corriger jusqu’au seuil ou max_iterations (défaut 3, max 20).

Comment fonctionne la boucle grader vers révision

La boucle suit quatre étapes, et c’est l’architecture qui fait tout le travail.

1. Production : l’agent réalise la tâche et écrit son artefact (un fichier dans /mnt/session/outputs/ dans le bac à sable).
2. Évaluation : un grader séparé note l’artefact critère par critère contre la rubric, dans sa propre fenêtre de contexte.
3. Décision : si le résultat est en dessous du seuil, le grader renvoie une explication listant les critères en échec, et la tâche repart pour une révision.
4. Répétition : le cycle recommence jusqu’à ce que la rubric soit satisfaite ou que la limite d’itérations soit atteinte.

Le grader note chaque critère indépendamment. Sa synthèse — quels critères passent, lesquels échouent — est rendue à l’agent producteur comme feedback pour l’itération suivante. Le raisonnement interne du grader reste opaque : vous voyez qu’il travaille, pas ce qu’il pense.

Les états de fin de boucle

Chaque évaluation se termine par un événement span.outcome_evaluation_end dont le champ result indique la suite. Comprendre ces états est essentiel pour piloter vos agents en production.

Résultat	Ce qui se passe
satisfied	La rubric est satisfaite, la session passe en idle.
needs_revision	L’agent démarre un nouveau cycle d’itération.
max_iterations_reached	Plus d’évaluation ; l’agent peut faire une dernière révision avant de passer en idle.
failed	La rubric ne correspond pas fondamentalement à la tâche (description et rubric se contredisent).
interrupted	Une interruption a stoppé le cycle en cours.

Le champ iteration est un compteur indexé à zéro : 0 est la première évaluation, 1 la ré-évaluation après la première révision, et ainsi de suite. Vous suivez la progression sur le flux d’événements via span.outcome_evaluation_start, span.outcome_evaluation_ongoing et span.outcome_evaluation_end, ou en interrogeant GET /v1/sessions/:id et en lisant outcome_evaluations[].result.

Borner la boucle avec max_iterations

Le paramètre max_iterations est votre garde-fou contre les boucles coûteuses. Il est optionnel, sa valeur par défaut est 3 et son maximum 20.

Une rubric mal écrite — trop ambiguë ou contradictoire — peut faire renvoyer needs_revision indéfiniment sans jamais converger. Je recommande de garder une limite basse, entre 3 et 5, surtout en phase de mise au point. Chaque itération relance l’agent et le grader, donc consomme des tokens des deux côtés. Vous pourrez relever la limite une fois la rubric stabilisée.

Un critère fort se coche ou se décoche sans débat ; un critère vague produit une évaluation bruitée.

Écrire une rubric efficace : la règle des critères d’acceptation

Une bonne rubric ressemble à des critères d’acceptation, pas à un prompt. C’est la distinction la plus importante de ce guide, et celle que la plupart des équipes ratent au premier essai.

Une rubric est un document Markdown qui décrit le scoring critère par critère. Le grader évalue chaque critère indépendamment, donc un critère vague produit une évaluation bruitée. La règle : chaque ligne doit être observable et vérifiable sans interprétation.

Critère faible	Critère fort
« Les données ont l’air bonnes »	« Le CSV contient une colonne prix avec des valeurs numériques »
« Bien écrit »	« L’introduction énonce le résultat principal dans la première phrase »
« Ton professionnel »	« Aucune voix passive dans le résumé exécutif »
« Analyse complète »	« Une analyse de sensibilité sur le WACC et le taux de croissance terminal est incluse »

Trois principes structurent une rubric solide :

• Spécificité plutôt que vague : un critère doit pouvoir être coché ou décoché sans débat.
• Critères négatifs quand c’est plus simple : interdire un défaut précis se grade souvent mieux qu’exiger une qualité abstraite.
• Séparer les obligatoires des optionnels : distinguez les must-have (un tableau de données requis) des nice-to-have (un ton conversationnel).

Voici à quoi ressemble un fragment de rubric concret, structuré en sections avec des critères gradables :

# Rubric — Modèle DCF

## Projections de revenus
- Utilise les revenus historiques des 5 derniers exercices
- Projette les revenus sur au moins 5 ans
- Les hypothèses de croissance sont explicitées et raisonnables

## Qualité de sortie
- Tous les chiffres dans un seul fichier .xlsx avec des feuilles libellées
- Les hypothèses clés sont sur une feuille « Hypothèses » séparée
- Une analyse de sensibilité est incluse

L’astuce du bon exemple

Si vous n’avez pas de rubric sous la main, ne partez pas de zéro. Donnez à Claude un artefact que vous savez excellent et demandez-lui d’analyser ce qui le rend bon, puis transformez cette analyse en rubric. Cette approche intermédiaire produit souvent de meilleurs critères que l’écriture à froid.

Dernier réflexe avant la production : testez votre rubric manuellement. Faites grader un exemple connu-bon et un exemple connu-mauvais, puis comparez le verdict du grader au vôtre. Si le grader valide un mauvais artefact, votre rubric est trop laxiste.

Définir un outcome : le mécanisme technique

Définir un outcome tient en un événement. Après avoir créé une session, vous envoyez un événement user.define_outcome ; l’agent commence à travailler dès réception, sans message utilisateur supplémentaire.

client.beta.sessions.events.send(
    session_id=session.id,
    events=[
        {
            "type": "user.define_outcome",
            "description": "Construire un modèle DCF pour Costco en .xlsx",
            "rubric": {"type": "text", "content": RUBRIC},
            # ou : {"type": "file", "file_id": rubric.id}
            "max_iterations": 5,  # optionnel ; défaut 3, max 20
        }
    ],
)

La rubric se passe de deux façons : en texte inline via {"type": "text", "content": "..."}, ou par référence à un fichier uploadé via l’API Files avec {"type": "file", "file_id": "..."}. La seconde option permet de réutiliser la même rubric sur plusieurs sessions.

Côté en-têtes, toute requête à l’API Managed Agents exige le header bêta managed-agents-2026-04-01. Les SDK officiels l’ajoutent automatiquement. Si vous uploadez une rubric via l’API Files, il faut combiner ce header avec files-api-2025-04-14.

Une fois la session en idle, vous récupérez les livrables via l’API Files en filtrant sur l’identifiant de session — l’agent écrit ses fichiers dans /mnt/session/outputs/. Notez qu’un seul outcome est actif à la fois, mais vous pouvez enchaîner plusieurs outcomes en séquence : il suffit d’envoyer un nouvel événement user.define_outcome après la fin du précédent, la session conservant l’historique.

Subagents, Dynamic Workflows et Outcomes répondent à trois questions distinctes ; les empiler donne des agents rapides et fiables.

Combiner Outcomes avec subagents et Dynamic Workflows

Outcomes, subagents et Dynamic Workflows répondent à trois questions différentes. Les empiler donne des agents à la fois rapides et fiables.

Brique	Question à laquelle elle répond	Niveau
Subagents	Qui fait quoi, avec quelle spécialisation ?	Délégation
Dynamic Workflows	Comment exécuter vite et en parallèle ?	Orchestration
Outcomes	Comment garantir que le résultat est correct ?	Contrôle qualité

Outcomes vit au niveau de la session et de l’artefact final, pas au niveau de chaque sous-agent. Vous pouvez donc déléguer la production à plusieurs subagents spécialisés, puis définir un outcome qui juge le livrable consolidé. Le grader évalue le résultat, peu importe comment il a été produit.

La combinaison la plus puissante associe les trois. Un Dynamic Workflow répartit une tâche lourde sur des dizaines de sous-agents en parallèle pour produire un artefact ; l’outcome et son grader valident ensuite que cet artefact respecte la rubric avant livraison. L’orchestration apporte la vitesse, la rubric apporte le filet de sécurité.

Pour structurer la spécialisation de vos subagents en amont, le système d’extension de Claude Code via les skills reste le point d’entrée : un skill encode les conventions, l’outcome vérifie qu’elles sont respectées dans le livrable final.

Trois cas d’usage concrets

Outcomes brille sur les tâches où la qualité est subjective ou riche en détails — exactement celles où un agent seul dérape.

Refactorisation de code

Définissez une rubric qui encode vos critères de refactorisation : « aucune fonction de plus de 40 lignes », « la couverture de tests existante reste verte », « aucune dépendance circulaire introduite ». Le grader vérifie chaque critère sur le code produit. L’agent ne livre que lorsque la refactorisation respecte vos règles, pas seulement quand elle compile.

Génération de contenu éditorial

C’est l’usage qu’illustre Anthropic avec Spiral, l’agent éditorial d’Every. Chaque brouillon est noté contre une rubric reprenant les principes éditoriaux d’Every et la voix de l’utilisateur. La qualité d’écriture étant la valeur centrale de Spiral, l’outcome sert à l’imposer avant relecture humaine, et à éviter la prose business générique.

Production de données et de documents

Sur la génération de fichiers structurés — tableurs, modèles financiers, exports CSV — la rubric vérifie la présence et la conformité de chaque élément attendu. C’est précisément le terrain où Anthropic mesure ses meilleurs gains : +10,1 % sur PowerPoint et +8,4 % sur Word, parce que ces livrables comportent de nombreux critères objectifs faciles à grader.

Mon avis : un changement d’architecture, pas un gadget

Outcomes mérite l’attention parce qu’il déplace le levier de qualité du modèle vers l’architecture. Gagner 10 points de réussite sans changer de modèle, c’est le signal que la plupart des équipes laissent de la qualité sur la table — non parce que leur modèle est faible, mais parce qu’elles n’ont aucun moyen systématique de vérifier les sorties avant livraison.

La vraie difficulté n’est pas technique, elle est rédactionnelle : écrire une rubric en critères d’acceptation observables demande de la rigueur. Une rubric vague donne une fausse impression de gouvernance et des évaluations bruitées. Investissez le temps là, testez sur des exemples connus-bons et connus-mauvais, bornez max_iterations à 3-5 au départ.

Mon verdict : si vous construisez des agents destinés à la production, Outcomes est le mécanisme de contrôle qualité qui manquait. Combiné aux subagents pour la spécialisation et aux Dynamic Workflows pour l’orchestration, il transforme un agent qui « a l’air de marcher » en agent dont vous pouvez mesurer la fiabilité.