D4 — Prompt engineering et sorties structurées (20 %)

Un relecteur automatique signale un pattern le lundi et approuve le même pattern le jeudi. Rien n'a changé dans le code, rien n'a changé dans le prompt. Ce qui a changé, c'est que « être prudent sur les migrations risquées » n'a aucun sens fixe : chaque exécution réinvente le seuil.

Le remède que nomme le guide n'est pas un meilleur adjectif. Ce sont des critères catégoriels explicites : des conditions nommées, chacune vérifiable à la main. L'exemple du guide lui-même est la paire à mémoriser : « flag comments only when claimed behavior contradicts actual code behavior », contre « check that comments are accurate ».

# Vague — la version qui produit un verdict différent à chaque exécution
Check code comments for accuracy. Be conservative — report only
high-confidence findings.

# Critères explicites — la version qui produit deux fois le même verdict
Flag a comment ONLY IF one of these holds:
  1. It describes behaviour that contradicts what the code does.
  2. It refers to a function or variable that does not exist.
  3. A TODO or FIXME refers to a bug already fixed in the code.

DO NOT flag:
  - dated phrasing or style that does not contradict the code;
  - imprecise wording that is still consistent with the code;
  - missing comments (a separate category, reported separately).

For each finding, output: file:line, which condition matched, the quoted
comment, and the code fragment that contradicts it.

Les deux moitiés portent autant l'une que l'autre. Des critères qui disent seulement quoi signaler laissent tout le reste à l'inférence ; c'est la liste de ce qu'il faut ignorer qui empêche un relecteur de dériver vers le style mineur et les conventions locales.

Des critères de severity qui classent de la même façon

La troisième compétence du guide porte sur la severity, et elle demande deux choses : des critères explicites pour chaque niveau, et un exemple de code concret par niveau. La définition seule laisse « medium » au goût de chacun ; l'exemple travaillé le fixe.

CRITICAL — échoue à l'exécution pour les utilisateurs.
  Exemple : payment_total = order.get("total") + order["tip"]   # KeyError s'il n'y a pas de tip
HIGH — vulnérabilité de sécurité.
  Exemple : db.execute("SELECT * FROM users WHERE id = " + user_id)
MEDIUM — bug de logique sans panne immédiate.
  Exemple : for i in range(len(items) - 1):   # le dernier élément n'est jamais traité
LOW — qualité de code seulement.
  Exemple : le même bloc de six lignes dupliqué dans trois handlers.

Pourquoi une mauvaise catégorie empoisonne les bonnes

Le point de connaissance du guide sur les faux positifs est une affirmation sur les gens, pas sur les modèles : un taux élevé de faux positifs dans une catégorie érode aussi la confiance des développeurs dans les catégories justes. Une fois que le bot a crié au loup trois fois sur des conventions de nommage, son vrai signalement d'injection SQL est parcouru du même œil.

C'est ce qui rend le remède du guide contre-intuitif et digne d'être retenu : désactiver temporairement la catégorie à fort taux de faux positifs, laisser tourner les catégories précises, améliorer le prompt de celle qui est désactivée, et la réactiver une fois ses critères devenus spécifiques. Relire moins, volontairement, c'est ainsi que le reste de la sortie continue d'être lu.

Les critères explicites règlent ce qu'il faut signaler, et ils laissent une seconde défaillance intacte : les critères sont écrits, ils sont détaillés, et la sortie revient malgré tout sous une forme différente à chaque exécution, ou revient vide sur le cas que personne n'avait pensé à énumérer.

La réponse du guide est sans ambiguïté, et c'est la formule à reconnaître dans une option : les few-shot examples sont la technique la plus efficace pour une sortie cohérente et actionnable quand des instructions détaillées produisent encore des résultats inconsistants. Un exemple, c'est du one-shot prompting ; plusieurs, du multi-shot.

Deux à quatre, c'est le compte du guide lui-même, et les exemples sont ciblés : ils montrent les cas ambigus, pas les faciles. Chacun porte le raisonnement qui explique pourquoi cette action a été choisie plutôt qu'une alternative plausible, parce que c'est le raisonnement qui se transfère.

<examples>
  <example>
    <request>My order is broken</request>
    <action>get_customer, puis lookup_order, puis vérifier le statut</action>
    <rationale>« Broken » peut désigner un article endommagé comme une
    livraison ratée. Les détails tranchent : les recueillir avant de router
    vers quoi que ce soit.</rationale>
  </example>
  <example>
    <request>Get me a manager</request>
    <action>escalate_to_human, immédiatement</action>
    <rationale>Le client demande explicitement une personne. Tenter d'abord
    une résolution passe outre une préférence énoncée.</rationale>
  </example>
</examples>

Les balises XML sont une habitude du cours et elles se justifient ici : les exemples sont du contenu interpolé posé à côté des instructions, et des délimiteurs descriptifs — <sample_input>, <ideal_output>, <examples> — sont ce qui empêche le modèle de lire un exemple comme une requête.

Les quatre rôles que le guide leur donne

Les deux derniers sont ceux qu'on oublie, et chacun répond à une défaillance précise.

Acceptable contre vrai problème est le levier anti-faux-positifs de 4.1 vu de l'autre côté : plutôt que d'énumérer tous les patterns bénins, en montrer un bénin et un vrai, et laisser la distinction se généraliser.

{"location": "src/auth/login.ts:42",
 "issue": "Injection SQL dans le paramètre username",
 "severity": "critical",
 "suggested_fix": "Utiliser une requête paramétrée"}

Les structures de documents variées sont le cas d'extraction du guide. Un taux rapporté par the rate is 42% (Smith, 2023) et le même taux rapporté par The rate is 42%. [1] avec une bibliographie en fin de document sont un seul fait sous deux formes, et un modèle à qui on n'a montré que la première renvoie null sur la seconde. Le guide nomme ce symptôme directement : les exemples sont ce qui traite l'extraction vide ou nulle de champs requis sur des documents dont le format varie.

Demandez du JSON en prose et vous obtenez du JSON la plupart du temps : une virgule en trop ici, un bloc de code entouré de backticks là, un champ renommé au troisième document. La réponse du guide est un mécanisme plutôt qu'une formulation, et il l'énonce sans nuance : le tool use avec des JSON Schemas est l'approche la plus fiable pour une sortie structurée garantie conforme au schéma, et il élimine les erreurs de syntaxe JSON.

Le geste est une petite inversion. Vous déclarez un outil dont l'input_schema est la forme que vous voulez en sortie, vous forcez le modèle à l'appeler, et vous lisez l'extraction dans l'input de l'appel. L'outil n'est jamais exécuté. Il n'a d'autre raison d'être que d'être un schéma que le modèle doit remplir.

{
  "tools": [{
    "name": "extract_invoice",
    "description": "Enregistre les champs extraits d'un document de facture.",
    "input_schema": {
      "type": "object",
      "properties": {
        "invoice_number": { "type": "string" },
        "issue_date":     { "type": "string", "description": "ISO 8601, YYYY-MM-DD" },
        "total":          { "type": "number" },
        "company_name":   { "type": ["string", "null"] },
        "document_kind":  { "enum": ["invoice", "credit_note", "other", "unclear"] },
        "kind_detail":    { "type": ["string", "null"] }
      },
      "required": ["invoice_number", "total", "document_kind"]
    }
  }],
  "tool_choice": { "type": "tool", "name": "extract_invoice" }
}

La réponse porte stop_reason: "tool_use" et un bloc tool_use dont l'input est votre enregistrement. Aucune prose à parser, aucune passe de réparation :

{ "type": "tool_use", "id": "toolu_01A", "name": "extract_invoice",
  "input": { "invoice_number": "INV-2024-0912", "issue_date": "2024-09-12",
             "total": 1249.90, "company_name": null,
             "document_kind": "invoice", "kind_detail": null } }

Le paramètre tool_choice

C'est le champ que D0 et D1 ont tous deux différé jusqu'ici. Il décide si l'appel d'un outil est facultatif, obligatoire, ou obligatoire et nommé.

Les deux usages que le guide nomme méritent d'être mémorisés comme des scénarios, parce que c'est ainsi qu'ils sont examinés. any est la réponse quand un pipeline reçoit factures, bons de commande et bons de livraison par la même porte : vous avez un schéma pour chacun, vous ne pouvez pas dire à l'avance lequel s'applique, et ce que vous ne pouvez pas vous permettre est une réponse conversationnelle au lieu d'un appel. Un outil forcé par son nom est la réponse quand l'ordre compte : extract_metadata doit tourner en premier, et les étapes d'enrichissement viennent aux tours suivants.

Concevoir le schéma pour qu'il n'invite pas à l'invention

Un schéma est un contrat, et un contrat mal rédigé fait de la fabrication la réponse conforme.

La dernière compétence du guide sur ce task statement est facile à sauter et peu coûteux à appliquer : les règles de normalisation de format vont dans le prompt, à côté du schéma strict. Le schéma dit qu'un champ est une chaîne ; seul le prompt peut dire laquelle.

Normaliser avant de remplir le schéma :
  dates        → ISO 8601 (YYYY-MM-DD) ; résoudre « yesterday » en date absolue
  montants     → valeur numérique plus un code ISO 4217 séparé ; « five bucks » → 5, USD
  pourcentages → fraction décimale ; « half » → 0.5
  absent       → null, jamais un espace réservé, jamais une supposition

La charge utile est conforme et les valeurs sont fausses. Forcer un appel par un JSON Schema garantit la forme de l'enregistrement et rien de ce qu'il contient : total vaut 150 alors que les lignes totalisent 145 ; un nom de fournisseur se trouve dans le champ client. Rien dans le schéma ne peut le voir, parce que rien dans le schéma ne connaît l'arithmétique.

Le mécanisme est une boucle, et le guide en teste les quatre étapes :

1. Le modèle produit une extraction.
2. Votre code la valide, d'abord avec JSON Schema pour la structure, puis avec des règles métier pour le sens. Pydantic est l'outil que l'annexe nomme, et il fait les deux : types et champs requis dans le modèle, règles inter-champs dans un validateur.
3. En cas d'échec, vous envoyez une requête de suivi portant trois choses : le document d'origine, l'extraction ratée, et l'erreur de validation précise.
4. Vous suivez quelles erreurs les retries corrigent réellement.

L'étape 3 est tout le « retry with error feedback », et son adjectif en est la substance. « Il y a une erreur, réessaie » relance les mêmes dés. L'erreur doit nommer le champ et l'écart.

try:
    invoice = Invoice.model_validate(tool_use.input)   # types, puis @model_validator
    return invoice
except ValidationError as e:
    messages.append({"role": "assistant", "content": response.content})
    messages.append({"role": "user", "content": [{
        "type": "tool_result",
        "tool_use_id": tool_use.id,
        "is_error": True,
        "content": (
            "total is 150.00 but the line_items sum to 145.00. "
            "Re-read the line items and resubmit; do not adjust total to fit."
        ),
    }]})

La requête de suivi emprunte la conversation ordinaire : le message assistant qui porte le bloc tool_use retourne dans l'historique, et la réponse qui lui est faite est un bloc tool_result portant le même tool_use_id, avec is_error: true. Le document est déjà dans l'historique : le modèle voit donc les trois ingrédients du guide d'un seul coup.

Quand un retry ne peut pas marcher

C'est le jugement autour duquel ce task statement est bâti, et c'est une question sur le document source, jamais sur le nombre de tentatives.

La colonne de gauche partage une propriété : le modèle avait l'information et l'a mal mise en forme. Lui renvoyer l'erreur exacte suffit. La colonne de droite partage la propriété inverse, et un retry n'y peut produire qu'une invention plus assurée. La réponse est un champ nullable et un null, qui est la règle de conception de 4.3 revenue en décision opérationnelle.

Deux champs qui rendent le pipeline auto-diagnostique

Le guide nomme les deux, et tous deux sont des ajouts peu coûteux à un schéma.

stated_total à côté de calculated_total, plus conflict_detected. Faire extraire au modèle le chiffre que le document déclare et la somme qu'il calcule depuis les lignes, puis signaler le désaccord au lieu d'en choisir un en silence. Le conflit survit jusque dans votre code, où un humain peut arbitrer.

{"stated_total": 150.00, "calculated_total": 145.00,
 "conflict_detected": true, "line_items": [ … ]}

detected_pattern sur chaque signalement. Un pipeline de revue de code qui enregistre quelle construction a déclenché chaque signalement transforme les rejets en données : quand les développeurs rejettent des signalements, vous pouvez grouper les rejets par pattern et voir qu'une construction produit l'essentiel du bruit, précisément la catégorie que 4.1 vous dit de désactiver et de réécrire.

{"location": "src/auth/login.ts:42",
 "issue": "Déréférencement null possible",
 "severity": "medium",
 "detected_pattern": "pas d'optional chaining sur user.profile.email",
 "suggested_fix": "user?.profile?.email"}

La Message Batches API traite de gros volumes de requêtes Messages API de façon asynchrone. Trois propriétés décident de toutes les questions à son sujet :

La troisième ligne est celle qui décide de la compatibilité, et c'est celle que les distracteurs attaquent. « La plupart des lots finissent en moins d'une heure » est une observation sur les files d'attente ; les vingt-quatre heures bornent la durée que le traitement peut prendre. Ni l'une ni l'autre n'est une promesse sur une soumission donnée.

POST /v1/messages/batches
{ "requests": [
    { "custom_id": "invoice-10231",
      "params": { "model": "claude-sonnet-5", "max_tokens": 1024,
                  "messages": [{ "role": "user", "content": "Extract: …" }] } },
    { "custom_id": "invoice-10232",
      "params": { "model": "claude-sonnet-5", "max_tokens": 1024,
                  "messages": [{ "role": "user", "content": "Extract: …" }] } }
] }

// Les résultats reviennent sans ordre ; apparier par custom_id, jamais par position.
{ "custom_id": "invoice-10232", "result": { "type": "succeeded", "message": { … } } }
{ "custom_id": "invoice-10231", "result": { "type": "errored",  "error": { … } } }
// → ne resoumettre que invoice-10231.

custom_id n'est pas décoratif. Comme les résultats ne sont pas ordonnés, c'est le seul moyen fiable de dire quelle réponse appartient à quel document, et c'est aussi ce qui rend possible la resoumission sélective.

Quelle charge va où

Le critère tient en une question : est-ce que quelqu'un attend ? Les économies ne promeuvent jamais un workflow bloquant vers le batch.

Cadence de soumission sous SLA

Le guide vous demande d'en calculer une. L'arithmétique d'abord : avec un engagement de 30 heures et un traitement qui peut prendre jusqu'à 24 heures, une soumission peut attendre au plus 30 − 24 = 6 heures en file avant d'être envoyée.

Six heures est le plafond, pas la réponse. Un lot soumis pile à la sixième heure et traité à la limite consomme tout le budget, sans rien laisser pour un document échoué qu'il faut resoumettre. L'exemple du guide lui-même répond des fenêtres de 4 heures pour un SLA de 30 heures, le plafond moins une marge.

Remarquez quel nombre est entré dans ce calcul. La plupart des lots finissent en moins d'une heure, et cette observation n'a pas sa place dans l'arithmétique : on dimensionne sur les 24 heures que la plateforme borne, jamais sur l'heure que vous constatez d'ordinaire.

La gestion des échecs

Quatre types de résultat reviennent : succeeded, errored, canceled, expired, et seul succeeded est facturé. Une requête échouée n'affecte pas les autres.

• Identifier les échecs par leur custom_id et ne resoumettre que ceux-là. Relancer tout le lot repaie tout ce qui avait fonctionné.
• Resoumettre avec une modification, pas à l'identique, quand la cause est dans la requête : un document qui a dépassé la limite de contexte repart découpé. Une invalid_request_error signifie que le corps doit être corrigé avant d'être renvoyé ; une erreur serveur peut être retentée telle quelle.
• Affiner le prompt sur un échantillon d'abord. Faire un dry run d'une requête représentative par l'API Messages synchrone, obtenir la bonne extraction, et seulement ensuite soumettre les mille ; sinon vous découvrez un défaut de prompt après avoir payé pour chaque document du lot.

Deux nombres opérationnels à retenir : un lot porte jusqu'à 100 000 requêtes ou 256 Mo, la première limite atteinte s'appliquant, et les résultats restent récupérables 29 jours. Et une courte liste de paramètres qu'un lot refuse, tous pour la même raison, puisque ce sont des réglages propres au synchrone : stream: true (les résultats reviennent sous forme de fichiers), speed, store et previous_thread_event_id, cache_hint et context_hint, et max_tokens: 0.

Demandez à la session qui vient d'écrire le code de le relire, et elle trouvera peu de chose. Non par négligence, mais à cause de ce qu'elle porte : le modèle conserve son contexte de raisonnement issu de la génération, ce qui le rend moins susceptible de questionner ses propres décisions dans la même session. Il a déjà envisagé l'alternative et l'a rejetée. La relecture confirme ; elle ne teste pas.

Le remède du guide est architectural plutôt qu'instructionnel, et la comparaison qu'il pose est le point important : une instance de revue indépendante, sans contexte de raisonnement préalable, attrape mieux les problèmes subtils qu'une instruction d'auto-relecture ou que l'extended thinking. Demander au modèle d'être critique envers lui-même, ou lui donner plus de place pour délibérer, opèrent tous deux à l'intérieur de la trace qui a produit le biais.

« Indépendante » a un sens opérationnel : une session distincte, ou un subagent, qui reçoit l'artefact et les critères et pas la conversation qui les a produits. Dans Claude Code, c'est un subagent relecteur, qui tourne dans sa propre fenêtre de contexte, restreint à des outils en lecture seule, et versionné dans le dépôt pour que l'équipe partage un seul relecteur. Le TS 3.6 de D3 met la même instance dans un pipeline ; ce qui relève d'ici, c'est pourquoi l'instance doit en être une autre.

Découper une revue trop grande pour une seule passe

Une pull request qui touche trente fichiers, relue en une seule passe, produit une sortie inconsistante : un pattern signalé dans un fichier et approuvé dans un autre, des signalements qui s'épuisent vers la fin. La cause que le guide nomme est la dilution de l'attention, et le remède est de rétrécir chaque passe plutôt que d'élargir le contexte.

# Passe 1 — local, une invocation par fichier.
for file in $(git diff --name-only main...HEAD); do
  review --scope="$file" \
         --prompt="Local issues only: bugs, security, quality in THIS file."
done

# Passe 2 — intégration, une invocation sur l'ensemble modifié.
review --scope="$(git diff --name-only main...HEAD)" \
       --prompt="Cross-file only: type mismatches across module boundaries,
                 circular dependencies, broken data flow. Ignore local issues."

Découper une tâche en passes ciblées, c'est la décomposition de tâches de D1 (TS 1.6) appliquée à la revue ; ce qui est spécifique ici, c'est la coupe, local contre inter-fichiers, parce que ce sont les deux choses qu'une passe indifférenciée fait le plus mal.

La confidence, auto-reportée

La troisième compétence est une passe de vérification où le modèle reporte une confidence à côté de chaque signalement. La valeur n'est pas le nombre lui-même mais le routage qu'il permet : les signalements à forte confidence vont directement au développeur, ceux à faible confidence vers une vérification humaine, et le seuil bouge à mesure que vous observez quelle bande vaut d'être lue.

{"file": "src/billing/refund.ts", "line": 88,
 "issue": "Le remboursement peut dépasser le montant initial si un remboursement partiel le précède",
 "confidence": 0.42,
 "detected_pattern": "pas de contrôle du cumul des remboursements avant la soustraction"}

Deux précautions gardent cela honnête. Une confidence reportée depuis l'intérieur du contexte de génération hérite de l'angle mort de ce contexte, donc la passe de vérification vaut d'être exécutée dans l'instance indépendante. Et un nombre auto-reporté est un signal de routage, pas une mesure : ce qui en fait une mesure, c'est de le comparer à des signalements dont vous connaissez déjà le verdict.