CCDV-F · Claude Certified Developer – Foundations

Cours

APP · 33.1 %

Applications et intégration

Ce domaine couvre l'intégration de la Messages API dans une application : format des échanges, lecture de stop_reason, erreurs, limites de débit et traitements en lot. Il teste aussi les choix d'exploitation : identifiants de modèle, plateformes tierces et discipline de changement.

Une API sans état

La Messages API ne garde rien entre deux appels : l'application renvoie tout l'historique à chaque tour, d'où un coût d'entrée qui croît avec la conversation. Elle n'ajoute aucun system prompt, contrairement à claude.ai ou à Claude Code : le comportement dépend uniquement de ce qui est envoyé. Dans l'Agent SDK, sans option systemPrompt, seul un prompt minimal s'applique, et le preset claude_code redonne le comportement du CLI.

Renvoyer les résultats d'outils

Tous les tool_result d'un tour partent dans un seul message user, juste après le message de l'assistant et avant tout texte. Il n'existe pas de rôle tool : tout passe par user et assistant. Ajouter du texte après chaque résultat apprend à Claude à clore son tour, ce qui produit des réponses vides avec end_turn.

Lire `stop_reason` avant le contenu

max_tokens signale une sortie tronquée : un tool_use incomplet se relance avec un plafond plus haut. pause_turn signale qu'un server tool a atteint sa limite d'itérations : on renvoie la réponse telle quelle pour que Claude reprenne. refusal arrive en HTTP 200, donc seul stop_reason le distingue d'un succès.

Streaming : où arrivent les signaux

En streaming, stop_reason vaut null dans message_start et n'arrive que dans message_delta. Une erreur survenue après le 200 arrive comme un événement error dans le flux, puisque le statut HTTP est déjà parti. Le streaming améliore la latence perçue et protège les longues requêtes des coupures de connexion inactive, sans réduire le coût.

Erreurs, retries et idempotence

Le SDK relance déjà deux fois les erreurs transitoires (connexion, 408, 409, 429, 5xx) : une boucle maison par-dessus multiplie les appels. Le code se branche sur le statut et error.type, jamais sur le texte du message, car de nouveaux types peuvent apparaître sans nouvelle version d'API ; le request-id se journalise pour le support. Un retry n'est sûr que sur une opération idempotente : une clé d'idempotence évite qu'un outil à effet de bord s'exécute deux fois.

Limites de débit et concurrence

Les limites suivent un token bucket : la capacité se recharge en continu, et une rafale peut déclencher un 429 sous le quota par minute. Les lectures de cache ne comptent pas dans l'ITPM, et max_tokens n'entre pas dans l'OTPM. Pour un gros volume avec échéance, un pool de concurrence borné qui respecte retry-after donne un débit régulier, et un handler async utilise AsyncAnthropic pour ne pas bloquer la boucle d'événements.

Message Batches API

Le batch coûte 50 % du prix standard en échange d'un délai non garanti : la plupart des batches finissent en moins d'une heure, mais seule l'expiration à 24 heures fait foi. Les résultats arrivent dans un ordre quelconque et se rapprochent par custom_id. La validation de params est asynchrone : une requête invalide revient errored, non facturée, sans bloquer les autres.

Ce que refusent les modèles récents

Depuis Claude 4.6, un prefill du dernier tour assistant renvoie une 400 : on passe par les structured outputs ou le system prompt. Les blocs thinking et redacted_thinking se renvoient exactement tels que reçus, car l'API vérifie leur intégrité. Plusieurs modèles récents (Opus 5.5, Sonnet 5.5, Fable 5.2) refusent tool_choice any ou tool : on utilise auto avec le strict tool use, et la boucle de l'application impose l'ordre des étapes.

Identifiants de modèle et cycle de vie

Depuis la génération 4.6, l'ID sans date (claude-sonnet-4-6) est un snapshot figé ; avant, l'alias court suivait le dernier snapshot daté. Épingler fixe les poids, pas la disponibilité : chaque ID a sa date de retrait, annoncée au moins 60 jours avant pour les modèles publics, après quoi les requêtes échouent. On migre donc tôt, evals à l'appui, et l'export d'usage de la Console montre les clés qui appellent encore l'ancien modèle.

Plateformes tierces et contraintes fermes

Sur Google Cloud (Google managed) ou Bedrock, la forme des messages reste la même, mais l'authentification, les endpoints, les ID de modèle et les fonctionnalités changent : pas de Files API ni de sources URL sur Google managed, par exemple. Les exigences de résidence éliminent des options avant toute comparaison de coût. Sur l'API Claude, inference_geo accepte global ou us, alors que Google Cloud (Google managed) propose un endpoint multi-région eu.

Documents PDF

Chaque page d'un PDF est convertie en image et son texte est extrait : les deux sont facturés, soit environ 1 500 à 3 000 tokens de texte plus au plus 1 568 tokens d'image par page. Le coût dépend donc du nombre de pages, pas du poids du fichier. Placer le PDF avant la question améliore les résultats.

Versionner prompts et changements

Prompts, ID de modèle, schémas et jeux d'evals vivent dans le contrôle de version, passent en revue et se promeuvent sur un score d'eval : un incident peut alors nommer la version fautive et revenir en arrière. La doc pose les critères de succès et les tests empiriques comme préalables à tout travail de prompt. Un changement de structure et un changement de comportement se livrent séparément, avec des tests qui fixent d'abord le comportement à préserver.

OPT · 16.8 %

Choix du modèle et optimisation

Ce domaine teste les leviers de coût et de latence : prompt caching, thinking et effort, fast mode, batch et choix du modèle. Les questions visent surtout les mécanismes silencieux, ceux qui dégradent la facture ou le débit sans lever d'erreur.

Ordre du préfixe et invalidation

Le cache couvre le préfixe dans l'ordre tools, system, messages, jusqu'au bloc marqué cache_control. Un changement à un niveau invalide ce niveau et tous les suivants : modifier les outils vide tout le cache, alors que changer tool_choice ou ajouter une image n'affecte que les messages. Le passage en fast mode, l'effort et la configuration du thinking peuvent aussi invalider le cache.

Le breakpoint sur le dernier bloc stable

Une lecture exige un préfixe identique à 100 %, et l'écriture ne se fait qu'au breakpoint. Un horodatage ou un contexte propre à la requête placé avant le breakpoint change le hash à chaque appel : on paie une écriture à chaque fois sans jamais lire. Le contenu stable vient d'abord, la partie variable après le breakpoint.

Choisir le TTL selon la cadence

Une écriture coûte 1,25 fois le prix d'entrée avec le TTL de 5 minutes et 2 fois avec celui d'une heure ; une lecture coûte 0,1 fois (moins sur certains modèles récents). Le TTL de 5 minutes se renouvelle gratuitement à chaque lecture, il convient donc si les requêtes arrivent plus souvent que toutes les 5 minutes. Entre 5 minutes et 1 heure d'écart, le TTL d'une heure évite de payer une écriture à chaque appel.

Lire `usage` correctement

input_tokens ne compte que les tokens situés après le dernier breakpoint. Le total d'entrée vaut cache_read_input_tokens + cache_creation_input_tokens + input_tokens. Un suivi fondé sur input_tokens seul sous-estime massivement le volume dès que le cache fonctionne.

Requêtes parallèles et préchauffage

Une entrée de cache n'existe qu'une fois la première réponse commencée : 50 requêtes lancées ensemble paient chacune une écriture. On envoie une première requête et on attend son début, ou on préchauffe avec max_tokens: 0, qui écrit le cache sans générer de sortie. Dans un batch, les lectures de cache restent en best effort, mais les remises batch et cache se cumulent.

Thinking adaptatif et effort

À partir de Claude 4.7, thinking en mode enabled avec budget_tokens renvoie une 400 : on passe au mode adaptive et on règle output_config.effort. L'effort est une indication souple, alors que max_tokens reste le plafond strict de la sortie, thinking compris. Changer d'effort entre deux requêtes peut invalider le cache : on fixe une configuration par conversation.

Le coût caché du thinking

Tous les tokens de thinking générés sont facturés en sortie, qu'ils soient affichés, résumés ou omis. display: "omitted" réduit le délai avant le premier token de texte, pas la facture. Le nombre de tokens facturés ne correspond donc pas à ce qui est visible dans la réponse.

Vitesse : fast mode, effort, streaming

Le fast mode fait générer le même modèle jusqu'à 2,5 fois plus vite, à prix majoré, sur quelques modèles (Opus 5.5, Fable 5.2) et hors Batch API. L'effort échange de la capacité contre de la vitesse et du coût, au sein d'un même modèle. Le streaming ne change ni le coût ni la durée totale : il réduit le délai avant le premier token affiché.

Tester un système non déterministe

Même à température 0, un LLM ne garantit pas des sorties identiques, et les modèles récents refusent de toute façon une temperature différente de la valeur par défaut. Les tests vérifient donc des propriétés : schéma valide, champ présent, critère noté selon une grille. Le prompt caching ne met jamais les réponses en cache.

Choisir un modèle sur ses propres evals

Deux points de départ sont valides : le plus petit modèle, avec montée en gamme seulement en cas d'écart, ou le plus capable, puis optimisation vers le bas. Pour un gros volume de tâches simples comme la classification, coût et latence dominent et un petit modèle suffit souvent. Dans tous les cas, la décision repose sur un jeu d'evals propre au cas d'usage, et régler l'effort est souvent un meilleur levier que changer de modèle.

AGT · 14.7 %

Agents et workflows

Anthropic distingue les workflows, où le code décide de l'étape suivante, des agents, où le modèle en décide. La plupart des questions vérifient que l'architecture choisie est la plus simple qui fonctionne, et que les points de contrôle reposent sur du code ou des données structurées.

Commencer par la solution la plus simple

Anthropic recommande de n'ajouter de la complexité que si elle améliore un résultat mesuré. Souvent, un appel unique bien construit, avec récupération ou exemples dans le prompt, suffit. Une base de connaissances de moins de 200 000 tokens (environ 500 pages) peut aller entière dans le prompt, et le prompt caching rend cette approche rapide et peu coûteuse.

Les patrons de workflow

Prompt chaining : des étapes fixes, avec une vérification programmatique (une porte) entre elles. Routing : classer l'entrée puis l'envoyer vers un traitement spécialisé. Parallélisation : des sous-tâches définies d'avance dans le code (sectioning) ou la même tâche répétée (voting). Orchestrator-workers : un LLM décompose la tâche selon l'entrée, utile quand les sous-tâches sont imprévisibles, comme le nombre de fichiers à modifier.

Frameworks : comprendre ce qu'ils génèrent

Les frameworks accélèrent le démarrage mais ajoutent des couches qui masquent les prompts et les réponses réels, ce qui complique le débogage. Anthropic conseille de commencer par l'API directe, puisque la plupart des patrons tiennent en quelques lignes. Avec un framework, il faut comprendre le code sous-jacent : les hypothèses fausses sur son fonctionnement sont une source d'erreur fréquente.

Une boucle pilotée par `stop_reason`

Une boucle d'agent écrite à la main lit stop_reason à chaque réponse : tool_use, exécuter les outils et renvoyer tous les résultats dans un seul message user ; pause_turn, renvoyer le contenu tel quel pour continuer ; end_turn, s'arrêter. Les tool_use d'un même tour ne sont pas ordonnés, et chacun attend son tool_result. Un plafond d'itérations et un budget servent de filet de sécurité, et la présence de texte ne signale jamais la fin.

Les règles absolues vont dans un hook

Une instruction, dans le prompt ou dans CLAUDE.md, reste soumise au jugement du modèle : Claude la lit comme du contexte, et rien ne garantit qu'il la suive. Un hook exécute du code à un point fixe du cycle de vie, à chaque fois : PostToolUse pour formater chaque fichier modifié, PreToolUse pour bloquer un appel. Quand une question dit « toujours », « jamais » ou « sans exception », chercher le mécanisme déterministe.

Sous-agents : un contexte isolé

Un sous-agent démarre avec son propre contexte : il ne voit ni l'historique de la conversation principale ni les fichiers déjà lus, et ne reçoit que le prompt de délégation. Ses appels d'outils restent chez lui, seul son message final remonte. Cet isolement protège le contexte principal (lire 40 fichiers, ne rapporter que la synthèse), à condition que le prompt de délégation contienne toutes les contraintes utiles. Seule exception : un fork, qui copie la conversation en cours.

Des relais structurés entre agents

Un agent ne peut exploiter que ce qu'il reçoit. Exiger de chaque sous-agent des enregistrements structurés (chemin, symbole, lignes, extrait), un rapport d'échec explicite (section, type d'erreur, résultats partiels, relance possible) et la provenance de chaque affirmation (client, outil, inférence, statut de vérification). Une dépendance entre étapes se contrôle dans le code, sur un champ structuré, jamais sur un mot comme « done ». Un résultat vide marqué comme réussi rend l'erreur invisible en aval.

Agent SDK : réglages chargés et fin de boucle

L'option settingSources décide de ce que le SDK charge depuis le disque : "project" pour le CLAUDE.md, les skills, les hooks et les permissions du projet, "user" pour ~/.claude. Omise, elle vaut ["user", "project", "local"] ; fixée explicitement, elle doit lister chaque source nécessaire. En fin de boucle, le ResultMessage porte un subtype : le texte result n'existe que sur success, alors que coût, usage et session_id sont présents sur tous les sous-types. max_turns et max_budget_usd bornent une exécution qui, sinon, tourne jusqu'à ce que Claude s'arrête.

Managed Agents ou Agent SDK

Avec Managed Agents, Anthropic héberge la boucle, le sandbox et l'exécution des outils ; les sessions sont stateful et stockées côté serveur, ce qui convient aux tâches longues et asynchrones. Ce stockage a un prix : pas d'éligibilité HIPAA, et le ZDR seulement en variante auto-hébergée. L'Agent SDK tourne dans le processus de l'application, qui lance un sous-processus claude par session et gère hébergement, persistance et montée en charge. Une exigence de rétention peut trancher avant tout autre critère.

PRM · 11 %

Prompt et contexte

Ce domaine couvre la structure d'un prompt (exemples, ordre, balises) et la garantie de forme qu'apportent les structured outputs. Il teste aussi la gestion du contexte dans la durée : context editing, compaction et emplacement des règles qui doivent survivre.

Des exemples variés et balisés

Claude reproduit les régularités de surface de ses exemples : cinq exemples semblables installent un biais. Les exemples doivent être pertinents, variés (cas limites compris) et encadrés par <example> pour rester distincts des instructions ; la doc en recommande 3 à 5. Pour une extraction, des exemples où la valeur vient de sections différentes montrent au modèle où chercher.

Ce que garantissent les structured outputs

Le décodage contraint garantit un JSON valide, les champs obligatoires et les types. Il ne garantit ni la justesse des valeurs, ni leur cohérence, ni l'existence d'un identifiant : la validation applicative reste indispensable. Les contraintes minimum, maximum, minLength et maxLength ne sont pas prises en charge (les helpers du SDK les retirent et valident après coup), et la casse des valeurs enum n'est pas garantie.

Les deux exceptions au schéma

Un stop_reason à refusal (HTTP 200, tokens facturés) ou à max_tokens (JSON tronqué) peut donner une sortie hors schéma. Le code lit stop_reason avant de parser : max_tokens se relance avec un plafond plus haut, refusal suit un chemin dédié. Un try/except autour du parsing masquerait la cause.

Compatibilités des sorties JSON

output_config.format est incompatible avec les citations et avec le prefill : l'API renvoie une 400. Il fonctionne avec le batch, le streaming, le comptage de tokens et le strict tool use. Changer de schéma invalide le cache du fil ; pour obtenir une citation par valeur extraite, la doc propose une réponse ligne par ligne, parsée par le code.

Compaction : un résumé qui remplace

La compaction remplace l'historique ancien par un résumé, à partir de 150 000 tokens par défaut (minimum 50 000) ; la doc la présente comme la stratégie principale pour les longues conversations. Des instructions personnalisées remplacent entièrement le prompt de résumé par défaut : elles doivent nommer tout ce qui doit survivre (tâche, fichiers, décisions). Le coût de cette étape se lit dans usage.iterations.

Gonflement ou dérive : deux symptômes

Le gonflement du contexte (coût, latence, débordement) se traite en élaguant ou en compactant. La dérive, une règle perdue loin dans l'historique, se traite par l'emplacement de la règle : system prompt, CLAUDE.md ou mémoire, relus à chaque requête. Une fenêtre plus grande ne règle aucun des deux, car la capacité de rappel baisse quand le contexte grossit (context rot).

TLS · 10.6 %

Outils et MCP

Les outils donnent des capacités à Claude, et leur qualité dépend surtout de leurs descriptions et de la façon dont les erreurs lui reviennent. MCP standardise l'exposition des outils, ressources et prompts, avec des règles qui changent selon le transport et la surface utilisée.

La description d'abord

La doc présente la description comme le facteur le plus important de la performance d'un outil : ce qu'il fait, quand l'utiliser et quand l'éviter, le sens de chaque paramètre, ses limites. Viser au moins 3 à 4 phrases par outil. Quand Claude confond deux outils, réécrire les descriptions passe avant tout ajout d'architecture (classifieur, tool_choice forcé, fusion).

Renvoyer les erreurs au modèle

Un outil en échec répond par un tool_result avec is_error: true et un message instructif (la cause, et quoi tenter ensuite), pour que Claude s'adapte ; il peut alors rappeler l'outil, d'où un plafond de relances dans la boucle. Une recherche sans résultat est un succès : la marquer en erreur provoque des relances inutiles. Un tool_result vide reste valide, et strict: true sur la définition empêche en amont les appels non conformes au schéma.

Forcer un outil : `tool_choice`

tool_choice accepte auto (par défaut), any, tool et none. Forcer avec any ou tool échoue en thinking manuel et sur certains modèles récents (dont Opus 5.5, Sonnet 5.5 et Fable 5.2) : la doc recommande alors auto avec le strict tool use, ou les structured outputs. Là où il est accepté, un appel forcé commence directement par l'outil, sans texte ni thinking avant. disable_parallel_tool_use: true, placé dans tool_choice, limite chaque réponse à un appel.

Tool search pour les grands catalogues

Au-delà de 30 à 50 outils, la précision de sélection baisse, et les définitions consomment des dizaines de milliers de tokens avant le premier message. Le tool search tool, avec defer_loading: true sur les outils rares, ne charge que ceux que Claude trouve par la recherche ; toutes les définitions restent envoyées dans la requête. Garder chargés les 3 à 5 outils les plus utilisés. Claude Code et l'Agent SDK diffèrent les outils MCP par défaut.

Primitives MCP : qui décide

Les outils sont contrôlés par le modèle, qui les découvre et les appelle. Les ressources sont pilotées par l'application hôte, qui choisit ce qu'elle joint au contexte. Les prompts sont contrôlés par l'utilisateur, qui les déclenche, par exemple comme slash commands. Des données en lecture seule jointes par l'application relèvent donc des ressources.

Serveur MCP : erreurs et transports

MCP sépare deux erreurs : celles de protocole (outil inconnu, requête malformée) passent par l'erreur JSON-RPC, celles d'exécution (API en échec, donnée invalide, règle métier) reviennent dans le résultat avec isError: true, pour que le modèle réagisse. En stdio, le client lance le serveur comme sous-processus et lit les messages JSON-RPC sur stdout : les logs vont sur stderr, sinon le flux est corrompu. L'autre transport standard est Streamable HTTP ; depuis la révision 2026-07-28, le protocole est sans état et l'en-tête Mcp-Session-Id a disparu.

Outil, Skill, MCP ou hook

Une capacité manquante (lire ou agir dans un système) appelle un outil ; un savoir-faire appliqué de façon irrégulière appelle une Skill, qui se charge à la demande et ne donne accès à aucun système. Un second consommateur ou un système détenu par une autre équipe oriente vers un serveur MCP partagé ; pour un seul consommateur, un outil sur mesure suffit. Une exécution garantie relève d'un hook, et les procédures longues sortent de CLAUDE.md pour devenir des skills.

Ce que l'API impose

Le connecteur MCP de la Messages API (mcp_servers) ne gère que les appels d'outils, sans ressources ni prompts, et exige un serveur exposé publiquement en HTTP : un serveur stdio local passe par un client MCP que l'application exécute. Les Skills de l'API tournent dans un conteneur sans réseau et sans installation de paquets, alors que dans Claude Code elles ont le réseau de la machine. Les server tools s'exécutent chez Anthropic et n'atteignent pas un réseau privé. Les Skills personnalisées ne se synchronisent pas entre surfaces.

Le périmètre d'un outil fait barrière

Le modèle ne peut pas faire ce que ses outils ne permettent pas. Un outil générique comme fetch_url ouvre tout, alors qu'un outil qui n'accepte que des identifiants d'un catalogue approuvé rend l'écart impossible. Cette barrière est plus fiable qu'une consigne dans le prompt ou qu'un filtrage en aval, qui laisse le contenu non approuvé influencer l'analyse avant d'être retiré.

SEC · 8.1 %

Sécurité et sûreté

Une instruction dans le prompt oriente le comportement, mais seul le code garantit une limite. Ce domaine teste où placer chaque contrôle : hooks, permissions, sandbox, autorisation côté backend, gestion des secrets.

Le contrôle critique vit dans le code

Quand une erreur a des conséquences financières, de sécurité ou de conformité, le contrôle doit être programmatique : une garde dans l'outil, un hook qui refuse l'appel, une approbation humaine. Anthropic le rappelle pour les paiements : un bloc de system prompt guide Claude sans rien imposer, donc une personne approuve chaque appel à un outil qui déplace de l'argent. Le moindre privilège complète le dispositif : l'outil ne doit pas pouvoir faire ce qui est interdit.

Codes de sortie des hooks

Code 0 : succès. Code 2 : blocage, et stderr est transmis à Claude comme motif. Tout autre code, y compris 1, est une erreur non bloquante : l'action continue, comme lorsqu'un hook plante ou dépasse son délai, sauf avec onFailure: "block". Seul PreToolUse peut empêcher un appel (code 2 ou permissionDecision: "deny") ; PostToolUse arrive trop tard, et sur Stop le code 2 empêche Claude de s'arrêter (vérifier stop_hook_active pour éviter une boucle sans fin).

Permissions : le deny l'emporte

Les règles de permission sont appliquées par le client, alors que CLAUDE.md n'est que du contexte. Un deny posé à n'importe quel niveau bloque, quels que soient les allow ailleurs, et un allow renvoyé par un hook PreToolUse ne lève ni deny ni ask. À l'inverse, un hook qui bloque l'emporte sur une règle allow. Les règles deny et ask d'un projet s'appliquent tout de suite, ses règles allow attendent que le dossier soit approuvé.

Les limites des règles, et le sandbox

Les règles Read et Edit couvrent les outils de fichiers de Claude, les commandes Bash qu'il reconnaît (cat, head...) et les redirections. Un script Python ou Node qui ouvre lui-même un fichier y échappe. Le sandbox impose les restrictions de fichiers et de réseau au niveau du système d'exploitation, pour les commandes shell et leurs processus enfants : les deux couches se complètent.

Injection de prompt : des défenses en couches

Le risque naît de la combinaison d'un contenu non fiable, d'un accès à des données privées et d'un moyen d'envoyer vers l'extérieur. Aucune mesure isolée ne suffit : placer le contenu tiers dans des tool_result et le traiter comme des données, énoncer cette règle dans le system prompt, appliquer le moindre privilège, faire approuver les actions sensibles, filtrer entrées et sorties. Baisser la température ou ajouter « n'obéis jamais aux injections » ne protège de rien.

Clés API et secrets

La clé reste côté serveur, dans un gestionnaire de secrets ou une variable d'environnement : envoyée au navigateur, elle devient publique, et un fichier versionné (CLAUDE.md, .claude/settings.json) la garde dans l'historique git. Une clé divulguée se révoque et se remplace, même après suppression du commit. Des clés distinctes par environnement (workspaces dev, staging, prod) limitent l'impact d'une fuite. Un 401 « CORS requests are not allowed » signale un appel fait depuis un navigateur.

Autoriser chaque appel, minimiser les données

L'authentification dit qui est l'utilisateur ; l'autorisation, appliquée dans le code à chaque appel, décide à quoi il accède. Un outil qui appelle le backend avec une clé de service admin contourne ce contrôle : il doit agir dans le périmètre de l'utilisateur, avec des identifiants au moindre privilège. Côté données, n'envoyer au modèle que les champs dont la tâche a besoin et masquer les données personnelles avant la requête : ce qui n'est pas envoyé ne peut pas fuiter.

CI et dépôts non fiables

Le dialogue de confiance n'existe qu'en session interactive. Sans --bare, claude -p exécute les hooks des settings du projet et connecte les serveurs de .mcp.json, même dans un dossier jamais approuvé : une PR externe peut livrer un hook qui s'exécute sur le runner. --bare ignore les hooks, skills, serveurs MCP et CLAUDE.md du dépôt, et la configuration nécessaire passe par --settings, --mcp-config ou --agents.

CC · 3.1 %

Claude Code

Les questions Claude Code portent sur la configuration : quels fichiers se chargent, lequel l'emporte, et comment lancer Claude Code depuis un script. La règle de fond : la portée d'un fichier suit sa diffusion (machine, équipe, utilisateur, organisation).

Chargement des `CLAUDE.md`

Au lancement, Claude Code charge chaque CLAUDE.md des dossiers parents du répertoire de travail, concaténés de la racine vers le dossier courant ; ceux des sous-dossiers se chargent quand Claude lit, écrit ou modifie un fichier du sous-dossier. Les fichiers s'additionnent : face à deux instructions contradictoires, Claude peut en choisir une arbitrairement. Après /compact, le CLAUDE.md racine est relu depuis le disque, alors qu'une consigne donnée seulement dans la conversation dépend du résumé. Viser moins de 200 lignes par fichier.

Précédence et portée des settings

De la plus forte à la plus faible : managed, ligne de commande (--settings), local (.claude/settings.local.json), projet (.claude/settings.json), utilisateur (~/.claude/settings.json). Les listes comme permissions.allow fusionnent au lieu de se remplacer. Le fichier local est personnel et reste hors de git, le fichier projet se commite pour l'équipe, et une règle que personne ne doit contourner passe par les managed settings.

Claude Code dans un script : `-p`

-p (ou --print) exécute Claude Code sans interface interactive ; --allowedTools pré-approuve des outils et --output-format json produit une sortie lisible par un script. Avec --json-schema, la sortie conforme arrive dans structured_output, absent si Claude décline : le vérifier avant usage. Pour reprendre une conversation précise, capturer session_id et passer --resume, car --continue prend la plus récente. --bare est le mode recommandé pour les appels scriptés.

Skills : quel homonyme s'exécute

Pour deux Skills de même nom, l'ordre est entreprise, puis personnel (~/.claude/skills/), puis projet : la version personnelle l'emporte sur celle du projet, à l'inverse des settings. Une Skill l'emporte sur un fichier .claude/commands/ de même nom. Les Skills de plugin, préfixées en /plugin:skill, n'entrent jamais en conflit.

Portées MCP

Un serveur MCP dont l'équipe dépend va dans .mcp.json à la racine du projet, versionné : quiconque clone obtient la même configuration. Les portées local (par défaut, limitée au projet) et utilisateur (tous les projets) restent privées et sont stockées dans ~/.claude.json ; la doc recommande local pour les serveurs expérimentaux. Copier des commandes claude mcp add depuis un README crée des écarts entre machines.

DBG · 2.6 %

Évaluation, tests et débogage

Déboguer un système à base de LLM commence par localiser le défaut : modèle, prompt, outil ou données. Ce domaine teste la lecture des traces, la classification des erreurs et des évaluations qui ne cachent pas les segments en échec.

Lire la trace dans l'ordre

Pour chaque mauvaise réponse, vérifier dans l'ordre : le modèle a-t-il appelé le bon outil, avec les bons arguments, et reçu les bonnes données ? Des arguments faux désignent la description de l'outil ou le prompt ; des données fausses dans le tool_result désignent l'intégration, et modifier le prompt n'y changerait rien. Journaliser le request-id de chaque appel : le support Anthropic le demande.

Classer l'erreur avant de choisir la reprise

Erreur transitoire (timeout, 429, 5xx) : relancer avec backoff. Erreur de validation : renvoyer is_error avec un message clair pour que Claude corrige. Refus métier ou de permission : escalader. Une recherche sans résultat n'est pas une erreur, et la marquer comme telle provoque des relances inutiles.

Segmenter les évaluations

Une moyenne masque les segments en échec : 97 % au global peut cacher 40 % sur un type de document rare. Les évaluations doivent refléter la distribution réelle et ses cas limites, et se lire par catégorie d'entrée et par champ. La confiance qu'exprime le modèle n'est pas calibrée : avant de réduire la revue humaine, échantillonner au hasard par sujet et type de source, puis n'automatiser que les segments qui tiennent le seuil.

Couvrir un long document

Une seule passe sur un long document répartit l'attention de façon inégale, et la répéter reproduit les mêmes angles morts. Mieux vaut une passe par section, qui assure la couverture locale, puis une passe dédiée à la cohérence entre sections. C'est le sectioning de la parallélisation, enchaîné de façon à pouvoir inspecter chaque étape.

Surveiller `stop_reason`

Un refus (refusal) et une troncature (max_tokens) arrivent en HTTP 200 : un tableau de bord fondé sur les erreurs HTTP reste plat pendant que les réponses utilisables chutent. Suivre la distribution de stop_reason en plus du coût, de la latence et des erreurs de transport, dès le premier jour.