# Cadres de décision

Chaque arbitrage A-contre-B testé par les quatre examens, consolidé en une référence unique avec le signal de scénario qui pointe vers chaque réponse.

Les examens sont des examens d'arbitrage. Cette page consolide les décisions à travers les quatre blueprints. Pour chacune : les options, les mots-signaux dans un énoncé, et le choix correct pour l'examen.

## Architecture

| Décision | Option A | Option B | Signal → choix |
| --- | --- | --- | --- |
| Workflow vs agent | **Workflow** — chemins de code prédéfinis | **Agent** — le modèle dirige ses propres étapes | Étapes connues et répétables → workflow. Ouvert, chemin dépendant des constats → agent. Par défaut le plus simple. |
| Appel unique vs chaîne | Un prompt | Chaînage de prompts avec barrières | Étapes distinctes avec sortie intermédiaire vérifiable → chaîne |
| Routage | Un prompt généraliste unique | Classifieur → prompts/modèles spécialistes | Entrées hétérogènes à traitements différents → router (routeur bon marché) |
| Parallélisation | Séquentiel | Sectionnement (parties indépendantes) / vote (même tâche ×N) | Sous-tâches indépendantes ou besoin de consensus → parallèle |
| Orchestrateur-workers | Décomposition fixe | L'orchestrateur décompose dynamiquement | Sous-tâches inconnues jusqu'à inspection → orchestrateur |
| Évaluateur-optimiseur | Passe unique | Générer → évaluer → affiner | Critères d'évaluation clairs et valeur itérative → boucle ; évaluateur dans une session séparée |
| Hébergement | **Managed Agents** — Anthropic héberge boucle + sandbox | **Agent SDK / Tool Runner** — vous hébergez | Besoin de contrôle sur runtime, réseau, localité des données → auto-héberger ; vouloir le moins d'ops → managed |
| Subagents vs workflows dynamiques | Subagents/forks | Workflows dynamiques scriptés | Quelques tâches déléguées → subagents ; dizaines–centaines → workflows dynamiques |
| Construire vs escalader (Associate) | Configurer dans claude.ai/Projects | Escalader vers Developer/Architect | Nécessite API, automatisation, intégration ou garanties de niveau système → escalader |

## Contrôle de boucle et application

| Décision | Correct | Anti-pattern |
| --- | --- | --- |
| Terminaison de boucle | Brancher sur `stop_reason` | Parser la prose pour « done » ; plafond d'itérations arbitraire comme arrêt principal |
| Règle métier critique | **Hook** programmatique (PreToolUse) / permission d'outil | Phrase dans le prompt système |
| Déclencheur d'escalade | Demande explicite → immédiat ; au-delà des capacités → résoudre-puis-escalader | Sentiment ; confiance auto-déclarée |
| Signalement d'erreur | Structuré : category, retryable, résultats partiels | Message générique ; succès vide silencieux |
| Auto-relecture | Session fraîche ou modèle différent | « êtes-vous sûr ? » dans la même session |
| Métrique de qualité | Par segment / par type de document | Agrégée uniquement |
| Nombre d'outils | 4–5 outils ciblés ; recherche d'outils + `defer_loading` au-delà de ~10 | 18 outils chargés d'emblée |

## Mécanique de l'API

| Décision | Option A | Option B | Signal → choix |
| --- | --- | --- | --- |
| Temps réel vs Batch | Messages API | Message Batches (50 % de réduction, ≤24 h) | « Du jour au lendemain », « le coût compte, pas la latence », en masse → Batch |
| Streaming | Non-streaming | Streaming SSE | UI interactive, longues sorties, latence perçue → streamer |
| Sortie structurée | Prompt « renvoie du JSON » | `output_config.format` / outils `strict` | Sortie consommée par machine → imposée par schéma ; toujours valider + réessayer |
| Appel d'outil forcé | `tool_choice: any/tool` | `auto` + instruction / `strict` / sortie structurée | Fable 5.1 → B (A donne 400) |
| Thinking | `budget_tokens` | `{"type":"adaptive"}` | Modèles actuels → adaptive (Haiku 4.5 est l'exception) |
| Effort | `high` (défaut) | `low`/`medium` pour le mécanique ; `xhigh` pour le plus dur | Subagent faisant du travail de routine → low/medium |
| Caching | Aucun | `cache_control` sur le préfixe stable | Long préfixe répété ≥1024 tokens → cache ; le stable en premier |
| Contexte trop long | Troncature côté client | Context editing / compaction (côté serveur) | Tool results verbeux → edit ; long récit → compact ; Fable 5.1 → côté serveur uniquement |
| État persistant | Historique de conversation | Memory tool / fichiers / DB | Doit survivre à la compaction ou aux sessions → externe |
| Retry | Tout réessayer | Backoff sur 429/5xx/529 uniquement ; respectez `retry-after` | Erreurs client 4xx → corriger, ne pas réessayer |
| Modèle de repli | N'importe lequel | Modèle plus récent ou équivalent | De Fable 5.1 vers plus ancien → blocs de thinking supprimés ; prévoyez la replanification |

## Sélection de modèle

| Signal | Choix |
| --- | --- |
| Classification, routage, extraction à l'échelle, sous la seconde | Haiku 4.5 |
| Tâches générales à l'équilibre qualité/coût, chat client | Sonnet 5 |
| Coding agentique complexe, défaut en entreprise | Opus 5 |
| Raisonnement de pointe, budget secondaire, accepter les contraintes | Fable 5.1 |
| Difficulté mixte | Cascade bon marché → cher avec validateur externe |
| Latence critique | Modèle plus petit, streaming, sortie plus courte, caching, mode rapide |
| Coût critique | Modèle plus petit, caching, Batch, réduire la sortie, effort moindre |

## Prompting et contexte

| Décision | Choix | Signal |
| --- | --- | --- |
| Zero-shot vs few-shot | Few-shot | Sensible au format, ambigu, cas limites |
| CoT vs extended thinking | Thinking étendu/adaptatif | Raisonnement dur ; garder la sortie visible propre |
| Placement des documents | Documents en premier, question en dernier | Rappel en long contexte + préfixe cachable |
| Frontière données vs instruction | Balises XML | Contenu non fiable ; risque d'injection |
| Le prompt comme actif | Versionné, testé, stable pour le cache | Prompt système de production |
| Isolation du contexte | Subagent avec contexte explicite | Protéger le contexte principal ; exploration parallèle |
| Plan vs direct (Claude Code) | Mode plan | Multi-fichiers, architectural, inconnu, irréversible |
| Skill vs CLAUDE.md vs command vs subagent vs MCP | Voir tableau | Procédure → Skill ; conventions → CLAUDE.md ; ligne unique paramétrée → command ; tâche déléguée isolée → subagent ; système externe → MCP |

## Outils et MCP

| Décision | Choix | Signal |
| --- | --- | --- |
| Outil personnalisé vs serveur MCP | MCP | Réutilisé entre hosts/agents ; système externe |
| stdio vs Streamable HTTP | HTTP | Distant, multi-utilisateur, nécessite OAuth |
| Qualité de la description d'outil | Riche : quoi/quand/quand-pas/retours | Le modèle choisit le mauvais outil → corriger d'abord la description |
| Outil destructif exposé mais inutile | **Le supprimer** | Pas « le journaliser » ni « le confirmer » |
| Identité | Propagation OAuth par utilisateur | Application multi-tenant ; faille d'authz |
| Appels d'outils parallèles | Autoriser | Recherches indépendantes |

## RAG (Professional)

| Décision | Choix | Signal |
| --- | --- | --- |
| RAG vs long contexte vs fine-tuning | RAG | Corpus grand/changeant, citations nécessaires. Long contexte : petit corpus stable tient dans 1M. Fine-tuning : style/format, pas les faits |
| Chunking | Structurel/conscient du document ; parent-child | Docs structurés ; besoin de hits précis avec contexte large |
| Récupération | Hybride (dense + BM25) + reranker | Requêtes mêlant paraphrase et ID exact |
| Traitement de requête | Réécriture / multi-query / HyDE | Questions vagues ou multi-intentions |
| Confiant-mais-faux après rafraîchissement des docs | **Suspecter d'abord la récupération/l'indexation** | Index périmé, dérive de chunks |
| Eval de récupération | recall@k, MRR, faithfulness, answer relevance | Séparer la qualité de récupération de la qualité de génération |

## Évaluation

| Décision | Choix | Signal |
| --- | --- | --- |
| Grader | Exact match → rubrique → LLM-as-judge (modèle séparé, calibré) | Subjectivité croissante |
| A/B | Par paires avec significativité | Comparer prompts/modèles |
| Où | Jeu golden hors-ligne + canary en ligne | Avant et après la release |
| CI | Suite de régression conditionnant le déploiement | Changement de prompt ou de modèle |
| Vue des métriques | Par segment + agrégée | Toujours les deux |
| Cause racine | Couche d'intégration vs sortie modèle vs récupération | Vérifier les traces avant de changer les prompts |

## Gouvernance et sécurité

| Décision | Choix | Signal |
| --- | --- | --- |
| Action irréversible / réglementée / externe / PII | Barrière human-in-the-loop | « ne doit jamais », « publier », « payer », « supprimer », « diagnostic » |
| Classe de données → outil | Suivre la classification et la politique | Données restreintes → uniquement la surface d'entreprise approuvée |
| Rétention | ZDR là où requis | Réglementé ; noter l'exclusion de Fable 5.1 |
| Cadre de conformité | GDPR (données personnelles UE), HIPAA (PHI, BAA), FedRAMP High (fédéral US via Bedrock/Vertex), SOC 2 | Mots sectoriels dans l'énoncé |
| Garde-fous | En couches | Jamais mono-couche |
| Divulgation | Prévenir les utilisateurs quand l'IA est impliquée | Communications externes, décisions concernant des personnes |

## Parties prenantes et cycle de vie (Professional)

| Décision | Choix | Signal |
| --- | --- | --- |
| Découverte | Entretiens structurés → métriques de succès → contraintes | Exigences vagues |
| Communiquer les arbitrages | ADR + matrice de décision + modèle de coût + registre des risques | Sponsor non technique |
| Attentes | Alignement SLA/SLO avec des références de base mesurées | « Les dirigeants attendent 100 % de précision » |
| Cycle de vie | Découverte → conception → construction → transfert → supervision → itération avec critères de sortie | Le transfert sans runbooks est le distracteur |
| Dépréciation de modèle | Traiter comme un événement de cycle de vie planifié avec migration conditionnée par l'eval | Avis de retrait |

## Optimisation du coût et de la performance

| Décision | Choix | Signal |
| --- | --- | --- |
| Latence trop haute | Modèle plus petit → streaming → `max_tokens` plus court → caching → mode rapide | « p95 trop lent », « les utilisateurs attendent » |
| Coût trop élevé | Modèle plus petit → caching → Batch → réduire la sortie → effort moindre | « les dépenses sont trop élevées », « réduire le coût » |
| Long préfixe répété | Prompt caching, disposition stable-en-premier | « le même prompt système à chaque appel » |
| En masse, tolérant à la latence | Batch API (50 %) | « du jour au lendemain », « des millions d'éléments » |
| Flux de difficulté mixte | Cascade bon marché→cher avec validateur externe | « la plupart des tickets sont simples, certains durs » |
| Réduire les allers-retours en logique multi-outils | Appel d'outils programmatique | « nombreux appels d'outils séquentiels » |
| Réduire les tokens dans les longues exécutions d'agent | Context editing (effacer les tool results) | « le contexte grossit sans cesse », « sortie d'outil verbeuse » |
| Réglage de l'effort | `low`/`medium` mécanique, `high` défaut, `xhigh` le plus dur | « le subagent renomme des fichiers » → low |

## Fiabilité et gestion des défaillances

| Décision | Choix | Anti-pattern rejeté |
| --- | --- | --- |
| Sortie de boucle | Brancher sur `stop_reason` | Parse de prose ; plafond d'itérations comme arrêt principal |
| Sortie tronquée (`max_tokens`) | Continuer / augmenter le plafond | Traiter comme complet |
| Arrêt `refusal` | Chemin de repli explicite | Erreur générique ; réessai aveugle |
| `pause_turn` | Renvoyer pour continuer | Traiter comme un échec |
| 429/5xx/529 transitoires | Backoff + jitter + `retry-after` | Tempête de retries ; réessayer les 4xx |
| Échec d'outil | `is_error` structuré (category, retryable, partiel) | Message générique ; succès vide silencieux |
| Réessai à effet de bord | Clé d'idempotence | Double facturation au réessai |
| Repli de modèle | Plus récent ou équivalent uniquement | La migration vers le bas supprime les blocs de thinking de Fable 5.1 |
| Déclencheur d'escalade | Demande explicite / au-delà des capacités | Sentiment ; confiance auto-déclarée |

## Gestion des données et des connaissances

| Décision | Choix | Signal |
| --- | --- | --- |
| Petit corpus stable tenant dans la fenêtre | Long contexte (pas de récupération) | « manuel de 50 pages, change rarement » |
| Corpus grand / changeant, citations | RAG | « des milliers de docs », « doit citer » |
| Style/format et non faits | Fine-tuning / exemples | « correspondre à notre ton », « toujours ce format » |
| État entre sessions | Memory tool / stockage externe | « se souvenir entre chats », « survivre à la compaction » |
| Docs structurés, précis + large | Chunking parent-child | « tableaux et sections », « besoin de contexte autour des hits » |
| Requête vague / multi-intentions | Réécriture / multi-query / HyDE | « les utilisateurs posent des questions floues » |
| Requêtes mêlant ID exact + paraphrase | Hybride (dense + BM25) + reranker | « numéros de commande et langage naturel » |
| Confiant-mais-faux après rafraîchissement | Suspecter d'abord la récupération/l'indexation | « marchait avant la mise à jour du doc » |

## Profondeur du prompting

| Décision | Choix | Signal |
| --- | --- | --- |
| Sensible au format / cas limites | Few-shot avec exemples représentatifs | « la sortie varie », « format spécifique » |
| Raisonnement dur, sortie propre | Thinking adaptatif/étendu | « montre ton raisonnement mais garde la réponse propre » |
| Contenu non fiable dans le prompt | Frontières XML, traiter comme des données | « fourni par l'utilisateur », « contenu web » |
| Orienter le début de la sortie | Prefill (ou sortie structurée pour des garanties) | « commence toujours par », « JSON uniquement » |
| Sortie consommée par machine | `output_config.format` + valider/réessayer | « un système en aval la parse » |
| Protéger le contexte principal | Subagent avec contexte explicite | « exploration parallèle », « ne pas polluer le contexte » |

## Index rapide mot-signal → principe

Recherche rapide : la formulation exacte qu'emploient les rédacteurs d'items, et le principe qu'elle désigne. Quand deux formulations apparaissent dans un même énoncé, la **contrainte** (coût, latence, conformité, fiabilité) décide généralement.

| Formulation d'énoncé | Désigne |
| --- | --- |
| « le PLUS économique » | Le modèle / Batch / caching le moins cher qui satisfait encore les contraintes |
| « PREMIÈRE étape » | Le diagnostic réversible le moins cher avant de gros changements |
| « MEILLEURE approche » | La conception la plus simple satisfaisant chaque contrainte énoncée |
| « Choisir DEUX » | Deux actions indépendamment correctes ; attention à un-juste-un-plausible |
| « à l'échelle » / « des millions » | Haiku 4.5 + Batch + caching |
| « sous la seconde » / « temps réel » | Modèle plus petit, streaming, effort faible ; pas Batch |
| « du jour au lendemain » / « la latence n'importe pas » | Batch API (50 %) |
| « le même long prompt à chaque requête » | Prompt caching, préfixe-stable en premier |
| « ne doit jamais » / « en aucun cas » | Hook déterministe / permission d'outil, pas une phrase de prompt |
| « comment la boucle sait-elle qu'elle a fini » | `stop_reason: end_turn`, pas le parsing de prose |
| « quand devrait-il escalader » | Demande explicite ou au-delà des capacités ; pas le sentiment/l'auto-déclaration |
| « l'agent a continué indéfiniment » | Terminer sur `stop_reason`, pas un plafond d'itérations |
| « renvoie rien / vide » | `is_error` / not_found structuré ; anti-pattern de succès silencieux |
| « confiance » / « à quel point êtes-vous sûr » | Ne pas router sur la confiance auto-déclarée |
| « en colère » / « client frustré » | Sentiment ≠ complexité ; ne pas escalader sur le ton |
| « la précision globale est de 95 % » | Exiger des métriques par segment |
| « êtes-vous sûr ? » dans le même chat | Session fraîche / modèle différent pour la relecture |
| « 18 outils » / « trop d'outils » | 4–8 outils ; recherche d'outils + `defer_loading` |
| « forcé d'appeler un outil » + Fable 5.1 | `auto`+instruction / `strict` / sortie structurée (forcé = 400) |
| « forme JSON garantie » | `output_config.format` / `strict: true` + validation |
| « les blocs de thinking ont disparu après un repli » | Liaison de Fable 5.1 ; migrer uniquement vers le haut |
| « la fenêtre de contexte est pleine » | Context editing (tool results) ou compaction (récit) |
| « a édité un tour antérieur » + Fable 5.1 | Historique en ajout seul ; utiliser des messages system en milieu de conversation |
| « se souvenir entre sessions » | Memory tool / stockage externe |
| « doit citer les sources » | RAG + citations ; test de provenance |
| « marchait avant la mise à jour du document » | Suspecter d'abord la récupération/l'indexation |
| « IDs exacts et paraphrases » | Récupération hybride + reranker |
| « questions utilisateur vagues » | Réécriture de requête / HyDE / multi-query |
| « doc de 50 pages qui change rarement » | Long contexte, pas RAG |
| « correspondre à notre style d'écriture » | Few-shot / fine-tuning, pas RAG |
| « réutilisé entre plusieurs applications/agents » | Serveur MCP, pas un outil personnalisé |
| « serveur d'outils distant, multi-utilisateur » | Streamable HTTP + OAuth 2.1, identité par utilisateur |
| « agit comme un compte admin partagé » | Faille d'authz ; propager l'identité de l'utilisateur final |
| « outil delete/refund dont il n'a pas besoin » | Le supprimer (moindre privilège), pas journaliser/confirmer |
| « le contenu web / la sortie d'outil lui a dit de… » | Injection indirecte ; traiter comme des données, frontières |
| « règle dure dans le prompt système » | Anti-pattern du prompt-comme-application ; utiliser un hook |
| « changement multi-fichiers / architectural » (Claude Code) | Mode plan |
| « une édition unique évidente » | Mode direct |
| « procédure multi-étapes réutilisable » | Skill |
| « conventions du dépôt / commandes de build » | CLAUDE.md |
| « ligne unique paramétrée » | Slash command |
| « tâche déléguée isolée » | Subagent |
| « dizaines–centaines d'agents » | Workflows dynamiques |
| « quelques tâches déléguées » | Subagents / forks |
| « rôles nommés collaborant » | Agent teams |
| « job récurrent planifié » | Routines |
| « distribuer commandes/agents/hooks/MCP » | Plugins |
| « exécuter en CI / headless » | `claude -p --output-format json`, outils restreints |
| « noter une qualité subjective » | Rubrique → LLM-as-judge (session séparée), calibré |
| « comparer deux prompts/modèles » | A/B par paires avec significativité statistique |
| « conditionner le déploiement » | Suite de régression CI sur le jeu golden |
| « avant et après la release » | Jeu golden hors-ligne + canary en ligne |
| « action réglementée / irréversible / externe » | Barrière human-in-the-loop |
| « données personnelles UE » | GDPR ; DPIA pour le haut risque |
| « données de santé / PHI » | HIPAA + BAA |
| « fédéral US » | FedRAMP High via Bedrock/Vertex |
| « les prompts ne doivent pas être conservés » | ZDR (noter l'exclusion de Fable 5.1) |
| « sponsor non technique / dirigeants » | ADR + matrice de décision + modèle de coût + registre des risques |
| « attendre 100 % de précision » | Fixer des SLO/SLA face à des références de base mesurées |
| « transfert à l'équipe » | Runbooks, supervision, critères de sortie |
| « quel modèle devrions-nous utiliser » | Faire correspondre la matrice de capacités à la contrainte contraignante |
| « réduire les hallucinations » | Ancrage (RAG/citations), validation, pas seulement « lui dire de ne pas » |

:::tip[Signal d’examen]
Quand un énoncé empile un besoin de capacité contre une contrainte de conformité ou de coût, la contrainte l'emporte. « Nous voulons le connecteur MCP mais nous sommes ZDR-uniquement sur Fable 5.1 » est impossible tel qu'énoncé — reconnaissez le conflit plutôt que de choisir la fonctionnalité brillante.
:::