CCA-F · Claude Certified Architect – Foundations

Cours

D1 · 27 %

Architecture agentique et orchestration

Le domaine 1 couvre la boucle agentique et l'orchestration multi-agents : comment une boucle sait continuer ou s'arrêter, comment un coordinateur découpe, délègue et contrôle le travail, et comment gérer les sessions. L'examen y teste surtout le bon niveau de complexité et la frontière entre ce que le modèle décide et ce que le code garantit.

La boucle agentique

Tant que stop_reason vaut tool_use, l'application exécute les outils, ajoute à l'historique la réponse assistant complète puis un message user avec un tool_result par tool_use (même tool_use_id, tous dans ce seul message, avant tout texte). end_turn marque la fin, max_tokens une sortie tronquée, et pause_turn une boucle d'outils serveur en pause, qu'on relance en renvoyant le contenu assistant tel quel. Le texte n'est jamais un signal de fin, car une réponse peut contenir texte et tool_use ; et éclater les résultats sur plusieurs messages dissuade le modèle de paralléliser. Le choix de l'étape suivante revient au modèle, qui relit les résultats : c'est ce qui distingue un agent d'un workflow codé.

Workflow ou agent

On part de la solution la plus simple et on n'ajoute de la complexité que si elle améliore le résultat. Si les sous-tâches sont connues avant l'exécution, un workflow codé (prompt chaining, parallélisation, routage) est plus prévisible et moins cher qu'un orchestrateur. Si on ne peut pas les lister (bug au chemin inconnu, recherche ouverte), un agent ou un orchestrateur découpe au fil des découvertes, avec une condition d'arrêt. De même, un plan relu avant d'éditer (plan mode) paie sur une tâche ouverte, pas sur une modification mécanique.

Hub-and-spoke

Le coordinateur décompose la demande, délègue, collecte les rapports et synthétise. Dans ce modèle, les subagents ne se parlent pas : la sortie d'un subagent revient au coordinateur, qui en recopie l'utile dans le prompt du suivant. Cette centralisation garde toute la circulation d'information visible et débogable. Revers : si le coordinateur découpe le sujet trop étroitement, il crée des trous de couverture que les subagents, chacun correct dans son périmètre, ne combleront pas.

Contexte d'un subagent

Un subagent (hors fork) démarre avec un contexte neuf : son prompt système, le prompt passé à l'outil Agent, les définitions d'outils et le CLAUDE.md du projet, mais ni l'historique ni les résultats d'outils du parent. Tout ce qu'il doit savoir (chemins, erreurs, décisions, résultats des autres subagents) va donc dans le prompt de délégation. En retour, seul son message final remonte : ses lectures intermédiaires restent hors du contexte du parent, ce qui est tout l'intérêt de l'isolation.

Rédiger une délégation

Chaque subagent a besoin d'un objectif, d'un format de sortie, d'indications sur les outils et sources à utiliser et de frontières claires. Un script pas à pas le rend fragile : il abandonne quand une requête prévue échoue et rate ce qui sort du schéma attendu. Une consigne vague (« recherche X ») produit l'excès inverse : travail dupliqué entre subagents et trous de couverture. On donne donc le but et les critères de qualité, et on laisse le subagent choisir sa méthode.

Dimensionner l'effort

Les agents jugent mal seuls l'effort qu'une requête mérite : on écrit des règles d'échelle dans le prompt du coordinateur (un fait simple : un agent et quelques appels ; une comparaison : quelques subagents ; une recherche complexe : davantage). Le coordinateur choisit à chaque requête quels subagents invoquer, plutôt que de faire passer toutes les requêtes par tout le pipeline. Un subagent coûte des tokens et du temps, car il doit reconstituer son contexte : une tâche courte que le coordinateur peut traiter avec ce qu'il sait déjà ne se délègue pas.

Parallélisme

Pour lancer des tâches indépendantes en même temps, le modèle émet plusieurs appels d'outil (dont l'outil Agent) dans une même réponse ; un appel par tour impose l'enchaînement séquentiel. Avec l'API Messages, c'est votre code qui exécute ce lot en parallèle puis renvoie tous les résultats ensemble. Paralléliser depuis le coordinateur ramène la latence à celle de la tâche la plus lente tout en gardant chaque délégation visible, ce que perdent une file externe ou une hiérarchie de subagents imbriqués.

AgentDefinition et outil Agent

Dans une AgentDefinition, description indique au coordinateur quand déléguer, prompt porte l'expertise du subagent, et tools est la vraie restriction : omis, le subagent hérite de tous les outils disponibles. Un prompt qui dit « ne modifie rien » reste une consigne ; seule la liste d'outils (ou disallowedTools) l'impose. Le coordinateur délègue en appelant l'outil Agent (nommé Task dans les anciennes versions) : s'il ne dispose pas de cet outil, il peut annoncer une délégation sans jamais l'exécuter.

Boucle de raffinement

Une première synthèse n'est pas la finale. Le coordinateur, ou un agent relecteur, évalue la couverture ; l'agent qui constate un manque le signale explicitement, puis le coordinateur relance des recherches ciblées et refait la synthèse. Une règle d'arrêt (plus de trou, ou nombre maximal de tours) borne le coût. Documenter le manque dans le rapport ou élargir les requêtes au départ ne comble pas les trous découverts en cours de route.

Garanties en code

Un prompt, des exemples ou une consigne en majuscules réduisent les erreurs sans les supprimer : le modèle peut toujours décider autrement. Une règle sans exception (ordre d'outils, seuil de montant, conformité) se code dans un hook, dans l'outil lui-même ou dans l'orchestration, sur des données que le modèle ne fournit pas ; un paramètre que le modèle remplit n'est pas un contrôle. Pour garantir une issue quelle que soit la fin de la boucle, le code vérifie après le run le subtype du ResultMessage (success, error_max_turns...) et déclenche lui-même l'action de repli.

Hooks PreToolUse et PostToolUse

PreToolUse s'exécute avant l'outil : il lit tool_input et peut refuser l'appel (deny) ou modifier l'entrée ; c'est là qu'on bloque, en refusant aussi quand la vérification elle-même échoue (fail closed). PostToolUse s'exécute après : il peut enrichir ou remplacer ce que Claude voit, mais l'effet de l'outil (paiement, écriture, requête) a déjà eu lieu. Le matcher ne filtre que sur le nom d'outil (mcp__serveur__.* pour tout un serveur MCP) ; les conditions sur les arguments se testent dans le callback.

Sessions : continuer, reprendre, forker

continue reprend la session la plus récente du dossier, ce qui suffit pour une seule conversation à la fois ; resume cible un ID (ou un nom dans Claude Code), indispensable dès qu'il y a plusieurs utilisateurs ou sessions. Un fork copie l'historique dans une nouvelle session pour explorer une alternative sans toucher l'original ; il copie la conversation, pas les fichiers. En reprenant une session, on signale à Claude ce qui a changé hors de sa vue (fichiers modifiés, renommages) ; si l'essentiel a changé, mieux vaut une nouvelle session avec un résumé des conclusions.

D2 · 18 %

Conception d'outils et MCP

Un agent choisit et utilise ses outils d'après ce qu'on lui en dit : nom, description, schéma, forme des résultats et des erreurs. Ce domaine couvre la conception de ces contrats, la gestion des erreurs, tool_choice, l'intégration MCP et les outils intégrés de Claude Code.

Descriptions : le levier principal

Le modèle choisit un outil et remplit ses paramètres d'après le nom, la description et le schéma ; la doc fait des descriptions le premier facteur de performance. Une bonne description dit ce que fait l'outil, quand l'utiliser et quand ne pas l'utiliser, ses entrées, sa sortie, ses limites et sa frontière avec les outils voisins. Chaque paramètre précise son sens, son format et d'où vient sa valeur (« issu d'un find_reservation, jamais deviné ») : un paramètre inventé, ou un outil MCP délaissé au profit de Bash, se corrige d'abord là. L'ordre du tableau d'outils ne compte pas pour la sélection ; un ordre stable aide en revanche le cache de prompt.

Découper ou consolider

Deux erreurs opposées dégradent la sélection. Un outil fourre-tout piloté par une instruction libre, ou des opérations aux paramètres requis différents réunies dans un seul outil, n'ont pas de contrat clair : on sépare en outils dédiés, chacun avec ses seuls paramètres et une sortie définie. À l'inverse, deux outils qui répondent au même besoin forcent un choix sans critère : on les fusionne, avec un paramètre action ou un flag. La doc penche vers la consolidation des opérations liées ; la séparation se justifie quand les contrats diffèrent vraiment.

Concevoir l'outil pour l'agent

Un outil n'a pas à calquer l'API : il peut enchaîner plusieurs appels en interne. S'il accepte l'identifiant que l'agent possède déjà, l'appel intermédiaire et son point de panne disparaissent. On regroupe les étapes mécaniques (rechercher puis récupérer les résumés), mais on garde séparée l'étape qui demande du jugement, que le modèle doit faire en voyant tous les candidats. Les valeurs reprises par une étape suivante se renvoient en champs structurés (en MCP, structuredContent et outputSchema) : lecture fiable, sans garantie sur la justesse des données sources.

Combien d'outils par agent

Plus un agent a d'outils, plus son choix devient incertain, surtout quand ils se recouvrent. Le repère de l'examen : 4 à 5 outils par rôle, plus au besoin un outil transverse étroit (un verify_fact pour les vérifications simples) plutôt que tout l'arsenal d'un autre agent. La doc de la recherche d'outils la recommande dès 10 outils, ou quand la précision de sélection baisse à mesure qu'on en ajoute. Dans Claude Code, le champ tools d'un sous-agent restreint sa liste.

Erreur de protocole ou d'exécution

MCP sépare deux canaux. Erreur de protocole (JSON-RPC) : outil inconnu, requête qui ne respecte pas le schéma de CallToolRequest, erreur serveur ; le modèle peut rarement la corriger. Erreur d'exécution, renvoyée dans le résultat avec isError: true : échec d'API, validation d'entrée, règle métier ; le client doit la montrer au modèle pour qu'il se corrige. Attention : la spec 2025-06-18 classait les arguments invalides côté protocole, la spec 2025-11-25 les a basculés côté exécution.

Des erreurs exploitables

Un « failed » générique laisse l'agent deviner : il retente en boucle ou abandonne. La doc demande de dire ce qui a échoué et quoi essayer ensuite (« Rate limit exceeded. Retry after 60 seconds »). Pour choisir entre retenter, corriger l'entrée et escalader, l'agent a besoin d'une catégorie (transitoire, validation, permission, métier), d'un indicateur de nouvel essai possible et d'une cause lisible, réutilisable telle quelle avec le client. Une exception levée dans le handler fait perdre tout cela.

Zéro résultat et timeouts

Une recherche sans résultat a réussi : elle se renvoie en succès structuré (liste vide, compteur à zéro), sinon l'agent croit à une panne et retente. is_error reste pour les cas où l'outil n'a pas pu répondre. Un timeout sur une action à effet de bord (paiement, envoi) laisse le statut inconnu : le message doit le dire, déconseiller de retenter et indiquer comment vérifier. Retenter n'est sûr que pour un appel idempotent, ce que MCP signale avec l'annotation idempotentHint.

tool_choice

auto (défaut quand des outils sont fournis) laisse Claude décider, sans garantie d'appel ; any impose un outil au choix ; tool impose celui-là ; none interdit les outils. Avec any ou tool, la réponse commence par le tool_use : aucun texte avant, même demandé ; pour une explication, ajouter un champ dédié dans le schéma, ou passer en auto avec une consigne. Les modèles les plus récents (Opus 5.5, Sonnet 5.5, Fable 5.2 et d'autres) refusent any et tool avec une erreur 400 : la doc conseille alors auto avec strict tool use, ou les structured outputs.

MCP dans Claude Code : scopes et secrets

Pour un besoin standard (tickets, erreurs de production), on branche d'abord un serveur MCP existant ; un serveur maison se justifie pour un workflow propre à l'équipe. Trois scopes : local (défaut, pour soi, ce projet), project (.mcp.json versionné, partagé avec l'équipe), user (pour soi, tous les projets) ; les deux scopes personnels sont stockés dans ~/.claude.json. Un .mcp.json partagé ne contient aucun secret : on écrit ${VAR} et chacun exporte sa variable ; un ${VAR:-défaut} qui contient un vrai jeton revient à le committer.

Plusieurs serveurs et recherche d'outils

L'hôte ouvre une connexion par serveur configuré et réunit leurs outils, préfixés par serveur (mcp__serveur__outil) : une même demande peut enchaîner des outils de plusieurs serveurs. Par défaut, Claude Code active la recherche d'outils : seuls les noms des outils et les instructions des serveurs sont en contexte au démarrage, la description et le schéma arrivent à la demande ; ENABLE_TOOL_SEARCH=false charge tout d'emblée. Ajouter des serveurs coûte donc peu de contexte, mais un outil différé n'est trouvé que si sa description place les mots-clés au début.

Tools, resources, prompts

MCP offre trois primitives, chacune pilotée par un acteur différent. Les tools sont des actions que le modèle décide d'appeler. Les resources sont des données passives en lecture seule fournies par l'application (schémas, documentation, catalogues) : quand un agent multiplie les appels juste pour savoir « ce qui existe », ce sont elles qu'il faut exposer ; dans Claude Code, on les joint avec une @-mention. Les prompts sont des modèles lancés par l'utilisateur, exposés comme commandes dans Claude Code.

Outils intégrés de Claude Code

Grep cherche dans le contenu des fichiers, Glob par nom ou chemin, Bash exécute. Pour lister les appelants d'une fonction réexportée sous d'autres noms, on relève d'abord tous les alias, puis on cherche chacun. Edit remplace une chaîne exacte qui doit être unique ; sans ancre unique possible, Read puis Write du fichier complet. Sur macOS, Linux et WSL, Claude Code retire Glob et Grep par défaut et passe par grep et find dans Bash, avec la même logique.

D3 · 20 %

Claude Code : configuration et workflows

Ce domaine porte sur la configuration de Claude Code (CLAUDE.md, rules, skills, hooks, permissions, MCP) et sur les workflows, en local comme en CI. Le fil rouge : choisir le bon mécanisme selon qu'il faut guider Claude, le contraindre ou lui fournir du contexte au bon moment.

Hiérarchie de CLAUDE.md

Quatre niveaux : managed (organisation), user ~/.claude/CLAUDE.md (toi, partout), project ./CLAUDE.md commité (l'équipe), local CLAUDE.local.md gitignoré (toi, ce projet). Ils s'additionnent au lieu de se remplacer : en cas de contradiction, Claude peut suivre l'une ou l'autre consigne, d'où l'intérêt de les garder cohérents. Les fichiers des dossiers parents se chargent au lancement, ceux des sous-dossiers à la demande. Si une consigne semble ignorée, vérifie d'abord ce qui est chargé : /context all (section Memory files), et /memory pour lister et ouvrir les fichiers.

Guidance ou garantie

CLAUDE.md, rules, skills et prompt sont lus par le modèle : il les suit presque toujours, sans garantie, et l'emphase (IMPORTANT, majuscules) n'y change rien. Les règles deny et les hooks de type command sont appliqués par le harnais, quoi que décide Claude ; un hook prompt ou agent fait juger un autre modèle et reste probabiliste. Répartition : interdire -> deny (dans les managed settings, que rien ne surcharge, si c'est une exigence d'organisation), toujours faire -> hook (PostToolUse sur Edit|Write pour formater), préférer -> CLAUDE.md, car une préférence a des exceptions que Claude sait juger. Garde l'ensemble imposé petit : chaque hook ou règle se déclenche parfois à tort et doit être maintenu.

Cibler les instructions : rules et imports

Un fichier .claude/rules/*.md avec paths: (globs) ne se charge que quand Claude lit ou modifie un fichier correspondant : idéal pour une convention par type de fichier, même dispersé (**/*.test.tsx). * couvre un seul niveau, ** toute profondeur : terraform/**/* et non terraform/*. Un @import organise un CLAUDE.md sans réduire le contexte, car le fichier importé se charge avec lui ; il sert à importer sélectivement quand seuls les propriétaires d'un paquet savent ce qui s'y applique. Le CLAUDE.md par dossier convient quand chaque équipe gère ses propres conventions.

Skills et commandes

Un skill dans .claude/skills/<nom>/SKILL.md (ou une commande dans .claude/commands/, l'ancien format) est commité et partagé avec l'équipe ; dans ~/.claude/, il reste personnel. Seuls le nom et la description se chargent d'office, le contenu complet arrive à l'invocation : une procédure longue et ponctuelle (release, checklist de revue) coûte donc bien moins qu'une section de CLAUDE.md. Avec disable-model-invocation: true, Claude ne peut pas le lancer seul et rien ne se charge avant /nom : le bon réglage pour un workflow à effets de bord.

Frontmatter d'un skill

context: fork exécute le skill dans un subagent : seul le résultat revient, et une investigation verbeuse ne remplit pas la conversation. allowed-tools pré-approuve des outils pendant le tour d'invocation sans rien restreindre ; pour retirer des outils, c'est disallowed-tools, et le piège classique consiste à lire allowed-tools comme une liste blanche. user-invocable: false cache le skill du menu /, disable-model-invocation: true empêche Claude de le lancer seul, et argument-hint n'est qu'un affichage dans l'autocomplétion.

MCP : scopes et primitives

Le scope décide qui reçoit le serveur : project écrit dans .mcp.json à la racine, commité pour toute l'équipe ; local (par défaut) et user écrivent dans ~/.claude.json, pour toi seul, dans ce projet (local) ou dans tous tes projets (user). Mettre un serveur expérimental en project l'impose donc à toute l'équipe. À l'usage, Claude appelle les tools, les resources se référencent avec @ et sont jointes au message, et les prompts deviennent des commandes (/mcp__serveur__prompt, arguments à la suite).

Plan mode ou exécution directe

En plan mode, Claude lit, explore et propose un plan sans rien modifier avant ton accord. Il se justifie quand partir dans la mauvaise direction coûte cher : grande échelle, plusieurs approches valables, décision d'architecture, migration sur des dizaines de fichiers. Sur un changement local et clair, ou un bug qu'une stack trace localise déjà, il n'ajoute que de l'attente : exécution directe, même dans un module que tu découvres. Sur une longue session qui touche plusieurs paquets, le plan écrit dans un fichier survit aux compactions.

Itérer efficacement

Claude converge vite quand il dispose d'un check qui répond pass/fail : écris d'abord les tests (ou des paires entrée/sortie), fais-les lancer, puis partage l'échec réel plutôt qu'une description. Si un fichier exemplaire existe déjà, donne-le avec @ au lieu de le décrire. Dans un domaine mal connu, demande à Claude de t'interviewer jusqu'à pouvoir écrire une SPEC. Des problèmes qui interagissent se donnent dans un seul message ; des problèmes indépendants, un par un.

Claude Code en CI

claude -p traite le prompt et quitte ; sans lui, le job attend une saisie, et -p n'accorde aucune permission (--allowedTools pré-approuve, --permission-mode dontAsk refuse le reste). --append-system-prompt ajoute des consignes au prompt par défaut, alors que --system-prompt le remplace et fait perdre la guidance sur les outils ; --output-format json donne un résultat à parser. --bare saute la découverte automatique (hooks, skills, MCP, CLAUDE.md) pour démarrer vite, à condition de passer explicitement ce qui compte. --max-turns et --max-budget-usd bornent chaque invocation depuis Claude Code lui-même ; le budget se compare à une estimation, donc garde de la marge.

Revue de code automatisée

Un relecteur qui n'a pas vu le code s'écrire juge mieux : lance la revue dans une session ou un subagent neuf, et aux re-runs, fournis les findings précédents pour éviter les doublons. Quand le contexte utile est inconnu d'avance (appelants dans d'autres fichiers), donne des outils de lecture et de recherche avec un plafond plutôt qu'un prompt statique. Les conventions du projet vont dans CLAUDE.md, lu à chaque exécution ; pour le Code Review managé, les règles propres à la revue (plafond de nits, chemins ignorés, sévérité, preuves exigées) vont dans REVIEW.md à la racine, sur la branche par défaut protégée.

D4 · 20 %

Prompt et sortie structurée

Ce domaine porte sur la fiabilité des sorties : un format garanti par l'API, des valeurs justes grâce à des consignes et des exemples précis, et des contrôles en code là où le modèle ne garantit rien. Il couvre aussi la revue automatisée (critères, indépendance, passes séparées) et l'API Batch, choisie selon la latence acceptable.

Sortie structurée imposée par l'API

Pour un JSON conforme à chaque appel, le schéma doit être imposé par l'API : sorties structurées (output_config.format) ou outil strict: true dont l'input_schema est l'enregistrement voulu, lu dans tool_use.input. Le décodage contraint garantit un JSON valide, les types et les champs requis. Des consignes de format, une regex sur du texte ou un prefill (refusé avec une erreur 400 depuis les modèles 4.6) restent des demandes, sans garantie.

Ce que le schéma ne garantit pas

strict garantit la syntaxe, pas la sémantique : des totaux qui ne tombent pas juste ou un champ rempli au mauvais endroit passent la validation. La cohérence se vérifie en code (total calculé contre total déclaré), et un écart se signale au lieu d'être corrigé de force. Le schéma peut aussi céder sur un refus ou une troncature : on teste stop_reason avant de parser, et une sortie qui dépasse max_tokens se règle en découpant l'entrée, pas en dégradant le contenu.

Un schéma fidèle à la source

Un champ requis pousse le modèle à inventer quand l'information manque : un champ possiblement absent est nullable, avec la consigne explicite de renvoyer null. Une catégorie ouverte dans la réalité devient un enum avec other et un champ de détail (voire unclear), sinon le modèle force la valeur la plus proche. Quand la source contient plusieurs valeurs vraies, le schéma les capture toutes, avec leur condition et leur provenance.

Consignes précises et normalisation

Le modèle lit déjà la source : lui donner le format canonique attendu (ISO 8601, codes pays) et les règles de conversion, dans le prompt ou les descriptions de champs, produit des valeurs homogènes dès l'extraction. Un post-traitement devrait au contraire couvrir des variantes sans fin. Test simple : un collègue sans contexte suivrait-il la consigne sans hésiter ?

Exemples (few-shot)

Les exemples sont le levier le plus fiable pour stabiliser format et jugement : découpage d'éléments composés, valeurs vagues gardées telles quelles, informations dispersées dans des mises en page variées. La doc recommande 3 à 5 exemples pertinents, variés (cas limites compris) et balisés <example>. Des exemples annotés, qui montrent le raisonnement, généralisent à des cas qu'aucune liste de règles n'aurait prévus.

tool_choice

auto (par défaut) laisse Claude décider, any impose un outil quelconque, tool impose un outil nommé, none interdit les outils. Pour garantir une étape obligatoire, on force l'outil au premier tour puis on repasse en auto ; le forcer à chaque tour bloque les autres outils. Opus 5.5, Sonnet 5.5, Fable 5.1 et 5.2 et Mythos 5.1 et 5.2 refusent any et tool : sur ces modèles, on combine auto, une consigne claire et strict: true.

Critères de revue et filtrage en aval

Des findings exacts mais rejetés signalent une définition floue du problème : une liste concrète « à signaler / à ignorer » fixe le seuil, là où « sois prudent » le laisse deviner. Une consigne comme « ignore ce dont tu doutes » fait taire des bugs que le modèle a pourtant trouvés. Mieux vaut tout signaler avec sévérité et confiance, puis filtrer en code ou dans une passe de vérification.

Revue indépendante et passes séparées

La session qui a écrit le code garde son raisonnement et tend à le confirmer : une revue indépendante tourne dans un contexte neuf (/code-review, deuxième session). Sur un gros changement, un seul prompt dilue l'attention : une passe par fichier, puis une passe d'intégration pour les flux entre fichiers. Si deux catégories de problèmes se concurrencent dans un même prompt, chacune reçoit sa passe et ses exemples, puis on consolide.

API Batch : quand l'utiliser

Le Batch coûte 50 % de moins sur l'entrée et la sortie, mais le traitement peut prendre jusqu'à 24 h (souvent moins d'une heure, sans garantie). Il convient au travail différé (rapport de nuit, revue non bloquante), jamais à une étape bloquante ou urgente. Chaque requête est un appel unique : une boucle d'outils client exige un nouvel appel par étape, donc l'agent reste en synchrone. Les remises du cache de prompt se cumulent avec celle du Batch.

API Batch : résultats, échecs et cadence

Les résultats arrivent dans n'importe quel ordre : on les joint par custom_id. En cas d'échec, on soumet un nouveau batch avec les seuls custom_id concernés, en corrigeant d'abord les invalid_request_error (requête trop longue à découper, par exemple) ; erreurs serveur et expirations se relancent telles quelles. Pour tenir un délai, l'intervalle entre deux soumissions plus 24 h doit rester sous le SLA.

Demande ambiguë

Une série de questions avant d'agir fait décrocher l'utilisateur. Quand le contexte permet une lecture plausible, le modèle avance sur cette hypothèse, la dit et propose d'ajuster ; il ne pose une question que si deux lectures mènent à des résultats vraiment différents. Des choix silencieux, à l'inverse, produisent des erreurs que personne ne voit.

D5 · 15 %

Contexte et fiabilité

Ce domaine couvre ce qui garde un agent fiable dans la durée : ce qu'on met dans le contexte, ce qu'on en retire et comment on le transmet d'un agent à l'autre. Il couvre aussi les moments où un humain reprend la main : escalade, confirmation d'une action et revue des extractions.

API sans état et budget de contexte

L'API Messages ne garde rien entre deux requêtes standard : chaque appel renvoie l'historique utile, sinon le modèle « oublie ». Tout ce que contient la requête compte dans la fenêtre : system prompt, messages, résultats d'outils, définitions d'outils et sortie. Un document qui tient seul peut donc dépasser une fois ces éléments ajoutés ; l'API de comptage de tokens le vérifie avant l'envoi.

Faits exacts hors du résumé

Un résumé garde le fil de la conversation mais perd des détails : un montant, un statut, une promesse faite au client. Les faits exacts (IDs, montants, dates, statuts) vont dans un bloc structuré, un enregistrement par sujet, tenu hors de l'historique résumé et réinjecté à chaque prompt. Ils survivent ainsi à la compaction, qui peut effacer un détail dont l'importance n'apparaît que plus tard.

Résultats d'outils volumineux

Un outil qui renvoie 40 champs remplit le contexte de données que l'agent n'utilisera pas, et la précision baisse quand le contexte grossit. On ne garde que les champs utiles, en code : dans l'outil lui-même, ou dans un hook PostToolUse qui remplace la sortie (updatedToolOutput) avant que le modèle la voie. Faire résumer par le modèle est moins sûr : il lit quand même tout et peut altérer une valeur.

Contexte long : la structure avant la taille

Dans un long prompt, les informations placées au milieu sont plus souvent manquées (« lost in the middle »), et une fenêtre plus grande n'y change rien : la précision baisse quand le nombre de tokens augmente. On place les documents longs en haut et la question à la fin, on balise chaque source (<document>, <source>), on met un résumé des points clés en tête, ou on découpe en passes focalisées avant de synthétiser.

Conversations longues et sessions reprises

La bonne stratégie se lit dans les données : si l'ancien contexte sert rarement et se redit facilement, une fenêtre glissante simple suffit, sans résumé ni base vectorielle. Quand une session reprend avec des résultats d'outils périmés, ils continuent d'influencer les réponses, même avec une consigne de préférer les plus récents. On repart alors d'une nouvelle session, avec un résumé structuré de la précédente et des appels d'outils frais.

Explorer un codebase sans saturer le contexte

Tout lire sature le contexte. On part d'un point d'entrée (un Grep, la classe de base), on lit, puis on suit appels et imports : chaque lecture indique la suivante. Quand le contexte se dégrade (réponses génériques, oublis), on délègue le verbeux à des subagents comme Explore, qui renvoient des résumés, et on note les faits établis dans un fichier relu après une compaction. /compact résume avec perte ; /clear repart de zéro et sert entre deux tâches sans rapport.

Quand escalader

Trois déclencheurs fiables : le client demande un humain (on transfère tout de suite, sans enquêter d'abord), la politique est muette ou ambiguë sur le cas, ou l'agent ne progresse plus. Le sentiment négatif, la complexité apparente et la confiance auto-déclarée ne sont pas des déclencheurs : un client frustré dont le problème se règle maintenant a besoin de la solution, avec l'humain proposé s'il le préfère. Pour corriger une escalade mal calibrée, on commence par des critères explicites et des exemples dans le prompt, avant toute infrastructure.

Lever l'ambiguïté et confirmer une action

Si une recherche renvoie plusieurs clients, choisir le plus récent ou fusionner les comptes risque d'agir sur la mauvaise personne : on demande un identifiant de plus. Avant une action visible par d'autres, la confirmation doit montrer ce qui va réellement se passer (destinataire, montant, date, contenu). Une invite « Confirmer ? » sans détails est approuvée par réflexe et ne protège de rien.

Handoff vers un humain

L'humain qui reprend le dossier ne voit pas la conversation : ce qu'on lui transmet doit se suffire. Un résumé structuré (ID vérifié, cause racine, montants, règle applicable, ce qui a été fait, action recommandée et sa raison) lui évite de refaire l'enquête. Un transcript brut ou une simple référence lui laissent tout le travail.

Erreurs et reprise en multi-agent

Un échec doit remonter avec son contexte : type d'erreur, ce qui a été tenté, résultats partiels, alternatives. Un timeout n'est pas un résultat vide : le masquer en succès fait croire qu'il n'y avait rien à trouver, et tout arrêter gaspille le reste du travail. Face au client, on fait ce qui reste possible, on dit ce qui a échoué et on propose la suite. Pour reprendre après un crash, chaque agent persiste des sorties structurées et le coordinateur tient un manifeste de ce qui est fait.

Revue humaine des extractions

Une précision globale cache souvent un type de document ou un champ faible : on mesure par type × champ avant d'automatiser. Un score de confiance du modèle n'est pas une probabilité tant qu'il n'est pas calibré sur un jeu labellisé ; le seuil validé s'applique en code et revient comme une décision (needs_review + raisons). Après l'automatisation, un échantillonnage aléatoire stratifié des extractions acceptées mesure le taux d'erreur et révèle les dérives.

Provenance et chiffres divergents

Chaque affirmation voyage avec sa source dans des champs séparés (affirmation, source, extrait, date) : fondue dans du texte résumé, l'attribution se perd à la première synthèse. Deux chiffres différents ne sont pas forcément une contradiction : des dates différentes montrent une tendance, des méthodes différentes expliquent un écart. La synthèse garde les deux valeurs attribuées, sépare l'établi du contesté et choisit le format selon le contenu (tableau pour des chiffres, prose pour un récit).