Guide d'ingénierie de spécification

Un compagnon pratique des standards d'exécution. Les standards définissent les couches et les composantes. Ce guide montre comment les utiliser.

Quand avez-vous besoin d'une spécification ?

Toute interaction IA ne nécessite pas une spécification formelle. Utilisez cet arbre de décision :

Utilisez un prompt quand :

La tâche est une étape unique avec des critères de succès évidents
Vous allez évaluer le résultat immédiatement
L'échec ne coûte rien (vous pouvez simplement relancer)

Utilisez un prompt + fichier de contexte quand :

La tâche nécessite des connaissances du domaine (terminologie, voix de marque, contraintes techniques)
Vous avez déjà fait ce type de tâche et la qualité compte
Le résultat sera utilisé par d'autres personnes

Utilisez une spécification complète quand :

La tâche comporte plusieurs étapes ou dépendances
Plusieurs personnes ou agents travailleront sur des parties de celle-ci
L'échec est coûteux (code en production, contenu destiné aux clients, actions irréversibles)
Vous avez besoin que quelqu'un d'autre vérifie le résultat sans vous poser de questions
La tâche sera répétée et doit produire des résultats cohérents

Le seuil n'est pas la complexité — c'est le coût de l'échec. Une tâche simple à enjeux élevés nécessite une spécification. Une tâche complexe sans enjeu peut commencer par un prompt.

Rédiger une spécification prend du temps. Mais la recherche montre que l'investissement est rentable : enrichir un énoncé de problème avant qu'un agent commence le travail produit une amélioration de 20 % du taux de résolution, et les agents les plus faibles en bénéficient le plus. Il est moins coûteux d'améliorer la spécification que d'améliorer l'agent.

Les quatre couches en pratique

Les standards définissent quatre couches obligatoires. Ces couches forment une progression de maturité cumulative — chaque niveau s'appuie sur le précédent. Voici à quoi ressemble chacune quand elle est bien faite.

Couche 1 — Rédaction de prompts

Le niveau de base. Vous rédigez une instruction claire.

Semble raisonnable mais comporte des lacunes :

Écris une séquence de 3 courriels d'accueil pour les utilisateurs en essai qui n'ont pas encore activé leur compte. Garde un ton amical et utile. Inclus des appels à l'action.

Mieux — assez précis pour être vérifiable :

Écris une séquence de 3 courriels de nurture pour les utilisateurs en essai qui se sont inscrits mais n'ont pas complété l'accueil dans les 7 jours. Objectif : les amener à compléter leur premier projet. Ton : utile, pas insistant. Chaque courriel doit faire moins de 100 mots avec un seul appel à l'action clair. Courriel 1 (jour 3) : mettre en valeur la façon la plus simple de commencer. Courriel 2 (jour 5) : partager un modèle qu'ils peuvent personnaliser. Courriel 3 (jour 7) : offrir un appel d'accueil de 15 minutes. Les objets doivent être conversationnels, pas promotionnels.

Le premier prompt semble complet mais laisse des questions critiques ouvertes : que signifie « activé » ? Combien de courriels ? Quelle longueur ? Vers quoi pointe l'appel à l'action ? L'agent va combler ces lacunes avec des suppositions — et les suppositions sont là où la qualité se dégrade.

La règle du ≤20 % de correction : Si vous devez régulièrement corriger plus de 20 % du résultat IA, le problème est votre prompt, pas le modèle. Investissez dans l'instruction, pas dans la révision du résultat.

Couche 2 — Ingénierie de contexte

Le contexte est tout ce que l'agent doit savoir qui n'est pas dans le prompt. Andrej Karpathy définit l'ingénierie de contexte comme « l'art et la science délicats de remplir la fenêtre de contexte avec exactement la bonne information pour la prochaine étape. »

La question clé n'est pas « qu'est-ce qui pourrait être pertinent ? » — c'est « qu'est-ce que l'agent doit voir maintenant ? » Plus de contexte n'est pas un meilleur contexte. La recherche montre que les modèles atteignent des plafonds de performance quand ils sont submergés d'information, quelle que soit la taille de la fenêtre de contexte.

Cinq critères de qualité (Vishnyakova, 2026) :

Pertinent — uniquement ce qui est nécessaire pour l'étape en cours. Les données non pertinentes dégradent activement le résultat.
Suffisant — tout ce qui est nécessaire pour prendre une décision sans deviner. Le contexte manquant est la cause architecturale principale de l'hallucination.
Isolé — chaque étape ou sous-agent ne voit que son propre contexte. Tout partager cause des échecs en cascade (voir Modes d'échec du contexte).
Économique — le minimum de tokens tout en préservant la qualité. Anthropic décrit cela comme trouver « le plus petit ensemble possible de tokens à haute valeur. »
Traçable — chaque élément de contexte doit être attribuable à une source. Quand quelque chose tourne mal, vous devez savoir quelle entrée l'a causé.

Un fichier de contexte d'équipe n'est pas un vidage de cerveau. C'est un ensemble soigneusement sélectionné de faits dont l'agent a besoin pour les tâches récurrentes. Gardez-le concis et axé sur les pièges — il se charge à chaque session, donc chaque ligne doit être universellement applicable.

# Customer Success Team Context

## Goals
- Retain existing customers (retention > acquisition)
- Reduce time-to-resolution for support tickets
- Identify expansion opportunities in existing accounts

## Constraints
- Never share customer data across accounts
- Never promise features that aren't shipped
- Escalate billing disputes over $500 to a manager
- Response time SLA: first response within 4 hours

## Terminology
- "Partner" = reseller account (not a regular customer)
- "White-label" = customer-branded version of the platform
- "Link branding" = custom domain for tracking links

## Quality standards
- Responses must address the specific question, not generic FAQ
- Include next steps in every response
- If unsure, say so — don't guess

Juste-à-temps vs en amont : Ne chargez pas tout en amont. Utilisez une stratégie hybride — chargez toujours le fichier de contexte d'équipe et la terminologie ; chargez les données spécifiques (dossiers clients, historique des tickets, documentation) à la demande. L'agent doit savoir où trouver l'information, pas tout mémoriser.

Pour un traitement approfondi de l'ingénierie de contexte, voir le guide d'Anthropic Effective Context Engineering for AI Agents.

Couche 3 — Ingénierie d'intention

L'intention répond à : « Pour quoi l'agent doit-il optimiser, et quels compromis est-il autorisé à faire ? »

Sans intention explicite, les agents optimisent la métrique la plus mesurable disponible — qui est rarement ce que vous voulez vraiment. L'étude de cas Klarna l'illustre : leur agent IA a traité les deux tiers des demandes clients et économisé 60 M$, mais le PDG a publiquement reconnu que la qualité avait souffert parce que l'agent optimisait le coût par token, pas la valeur des relations clients. Comme le dit un chercheur : « Du contexte sans intention, c'est du bruit. »

Intention pour un flux de support :

## Objective hierarchy (in order of priority)
1. Accuracy — never give incorrect information
2. Resolution — solve the customer's actual problem,
   not just answer their question
3. Tone — match the brand voice (friendly, competent)
4. Efficiency — keep responses concise

## Trade-off rules
- Accuracy vs speed → choose accuracy
- Tone vs efficiency → keep it warm, even if longer
- Uncertain about a technical answer → say so,
  don't guess

## Escalation conditions
- Customer mentions legal action → immediately
- Billing dispute over $500 → manager
- Technical issue affecting multiple customers
  → engineering
- Same question asked three times → senior support

## Decision authority
May: draft responses, look up account details,
  cite knowledge base
Must not: promise refunds, share other customers'
  data, commit to future features

Intention pour un flux d'ingénierie :

## Objective hierarchy (in order of priority)
1. Correctness — code must pass all existing tests
2. Maintainability — readable by a developer unfamiliar
   with the codebase
3. Performance — meet SLA requirements
4. Simplicity — prefer fewer lines over abstraction

## Trade-off rules
- Correctness vs speed → choose correctness
- Maintainability vs performance → favor readability
  unless the SLA is at risk
- When multiple approaches are valid → pick the one
  with less coupling to other modules

## Escalation conditions
- Change requires modifying a public API → escalate
- Performance impact exceeds 10% on critical paths
  → escalate
- Solution requires a database migration → escalate

## Decision authority
May: refactor within the scope of the task,
  add helper functions, update related tests
Must not: change public APIs, modify unrelated code,
  skip test coverage

Couche 4 — Ingénierie de spécification

Une spécification est un ensemble d'instructions complet et autonome pour une tâche non triviale. Elle inclut tout ce dont l'agent a besoin et rien de superflu.

Les sept composantes requises (des standards) :

Énoncé du problème — ce qui doit se passer et pourquoi
Portée — ce qui est inclus et explicitement ce qui ne l'est pas
Entrées — ce à quoi l'agent a accès
Contraintes — les catégories Doit / Ne doit pas / Préfère / Escalade
Critères d'acceptation — comment vérifier que le résultat est correct (à quoi ressemble « terminé », objectivement)
Conditions d'échec — ce qui constitue une tentative échouée
Tests de réussite — scénarios spécifiques que le résultat doit gérer

Les cinq composantes avec exemples

Composante 1 — Énoncés de problème autonomes

Le test : est-ce que quelqu'un sans contexte sur votre projet pourrait exécuter cette tâche en utilisant uniquement ce qui est écrit ?

Semble complet mais ne l'est pas :

Le planificateur de tâches est trop lent pour les gros lots. Corrige le système de priorité pour que les petites tâches ne restent pas bloquées derrière les grosses. Utilise BullMQ.

Autonome :

Le planificateur de tâches (src/jobs/queue.ts) traite les tâches de façon séquentielle. Les grosses tâches (50K+ éléments) bloquent les plus petites dans la file d'attente — les utilisateurs avec de petites tâches attendent plus de 30 minutes avant que le traitement commence. Le correctif doit ajouter un ordonnancement par priorité : les tâches de moins de 5K éléments obtiennent une priorité plus élevée. La configuration du limiteur de débit (100 req/s) ne doit pas changer. La fonctionnalité de priorité existante de BullMQ devrait être utilisée si possible. Si la solution nécessite de modifier le schéma des tâches, escaladez avant d'implémenter.

La première version semble actionnable mais cache des questions : quel fichier ? Que signifie « trop lent » en chiffres ? Quelles sont les contraintes ? L'agent va faire des suppositions sur tout cela — et elles pourraient être fausses.

La recherche sur les agents de code le confirme : fournir le contexte architectural, les dépendances inter-fichiers et des pistes d'exploration en amont évite aux agents de perdre des étapes dans un parcours non ciblé du dépôt.

Version marketing — semble complète mais ne l'est pas :

Crée une campagne de courriels automatisés pour les utilisateurs en essai qui n'ont pas converti. Mets l'accent sur la valeur du produit. 3 courriels, ton amical, avec des appels à l'action.

Autonome :

La conversion essai-payant est de 12 %. La référence du secteur est de 18 %. Les utilisateurs qui complètent l'accueil dans les 72 heures convertissent à 31 %. Concevez une séquence de 3 courriels déclenchée quand un utilisateur en essai n'a pas complété son premier projet au jour 3. Objectif : les amener à compléter l'accueil. Chaque courriel sous 100 mots, un appel à l'action par courriel, fonctionne en EN et FR. Aucune mention de tarification, aucune tactique d'urgence.

La première version produirait une campagne générique. La seconde donne à l'agent le contexte d'affaires (pourquoi c'est important) et les contraintes (quoi éviter) qui produisent un résultat ciblé.

Composante 2 — Critères d'acceptation

Écrivez trois phrases qui permettent à quelqu'un d'autre de vérifier le résultat sans vous poser de questions.

Semble testable mais ne l'est pas :

Le tableau de bord devrait afficher les métriques clés de façon précise et charger rapidement dans tous les navigateurs.

Réellement testable :

Le tableau de bord affiche le MRR, le taux de désabonnement et les utilisateurs actifs pour la période sélectionnée. Le MRR correspond au chiffre de l'équipe finances à 100 $ près. La page charge en moins de 2 secondes sur une connexion standard. Les graphiques s'affichent sans erreur dans Chrome et Firefox.

La première version utilise des mots qui semblent précis (« de façon précise », « rapidement », « tous les navigateurs ») mais que personne ne peut vérifier sans poser des questions de suivi. La seconde définit des chiffres spécifiques, des métriques spécifiques et des navigateurs spécifiques.

Composante 3 — Architecture des contraintes

Quatre catégories. Remplissez les quatre pour chaque tâche non triviale.

Exemple : système de réponse automatique aux tickets de support

Catégorie	Règles
Doit	S'adresser au client par son nom. Référencer son problème spécifique. Inclure une prochaine étape.
Ne doit pas	Ne jamais partager des identifiants ou des détails de systèmes internes. Ne jamais promettre un délai de résolution spécifique. Ne jamais fermer automatiquement un ticket.
Préfère	Proposer un lien vers les articles de la base de connaissances pertinents quand ils existent. Utiliser la langue du client selon les paramètres de son compte. Garder les réponses sous 200 mots.
Escalade	Le client mentionne une annulation. Le problème implique une perte de données. Le même problème est signalé 3+ fois en 24 heures. Le client est sur un plan entreprise.

Composante 4 — Décomposition

Découpez les tâches en morceaux indépendants avec des entrées et sorties claires. Cible : des sous-tâches de ≤2 heures vérifiables individuellement.

Semble décomposé mais reste couplé :

Concevoir le modèle de données et construire l'API
Construire le frontend qui utilise l'API
Écrire les tests et déployer

Réellement indépendant :

Étape	Entrée	Sortie	Vérification
1. Migration du schéma	Schéma actuel + document d'exigences	Fichier de migration + fichier de rollback	La migration s'exécute en avant et en arrière sans erreur
2. Point de terminaison API	Migration + spécification API	Gestionnaire de route avec validation	Les 5 cas de test passent, retourne les bons codes de statut
3. Formulaire frontend	Spécification API + maquette	Composant React avec validation de formulaire	Le formulaire se soumet avec succès, les erreurs de validation s'affichent correctement
4. Test d'intégration	Les trois précédents	Test de bout en bout	L'utilisateur peut compléter le flux complet en staging

La première version a des dépendances cachées (l'étape 1 regroupe deux préoccupations, l'étape 2 ne peut pas commencer tant que l'étape 1 n'est pas entièrement terminée, l'étape 3 regroupe les tests avec le déploiement). La seconde a des entrées, sorties et vérifications claires à chaque étape. Anthropic recommande ce patron orchestrateur-travailleurs pour les tâches multi-composants.

Composante 5 — Conception d'évaluation

Construisez 3 à 5 cas de test avec des résultats connus. Exécutez-les après chaque changement.

Exemple : générateur d'objets de courriel

Cas de test	Entrée	Caractéristiques attendues du résultat
1. Courriel de bienvenue	Nouvel utilisateur, inscrit aujourd'hui, nom : Marie	Contient le nom de l'utilisateur. Moins de 50 caractères. Aucun mot déclencheur de pourriel.
2. Réengagement	Utilisateur inactif depuis 30 jours	Mentionne un délai spécifique ou sa dernière activité. Crée de la curiosité. Pas culpabilisant.
3. Annonce de fonctionnalité	Nouvelle fonctionnalité d'éditeur, tous les utilisateurs	Met en valeur le bénéfice, pas le nom de la fonctionnalité. Pas de jargon technique.
4. Locale française	Même chose que le #1 mais locale utilisateur = FR	Français grammaticalement correct. Pas une traduction mot à mot.
5. Cas limite : pas de nom	L'utilisateur n'a pas de prénom au dossier	Ne dit pas « Bonjour null » ou « Bonjour ». Utilise une salutation générique.

On ne teste pas le résultat exact (l'IA est non déterministe). On teste les caractéristiques du résultat. C'est de l'évaluation, pas des tests unitaires. Anthropic recommande d'associer chaque prompt d'évaluation à des résultats vérifiables et de suivre la précision, le temps d'exécution et les taux d'erreur dans le temps.

Modes d'échec du contexte

Quand le résultat IA est mauvais, diagnostiquez quel mode d'échec du contexte l'a causé avant de réessayer. Ces quatre modes d'échec sont bien documentés dans la littérature sur l'ingénierie de contexte :

Empoisonnement

Une erreur entre dans le contexte et se propage d'un tour à l'autre. L'agent a halluciné un nom de fonction à l'étape 2, puis continue d'appeler cette fonction inexistante aux étapes 3 à 5.

Correctif : Videz le contexte entre les étapes. Ne laissez pas les sorties d'outils des premières étapes persister profondément dans la conversation. Résumez aux points de transition plutôt que de traîner l'historique brut.

Distraction

Le contexte est si long que l'agent répète des patrons de l'historique au lieu de raisonner sur l'étape en cours. La recherche a observé cette dégradation après avoir dépassé 100K tokens.

Correctif : Compressez ou résumez le contexte plus ancien. Quand la conversation s'allonge, créez une nouvelle session avec un résumé des décisions prises jusqu'ici.

Confusion

Trop d'outils ou trop de documentation dans le contexte. L'agent choisit le mauvais outil ou cite de la documentation non pertinente parce qu'il ne peut pas distinguer ce qui est pertinent.

Correctif : Réduisez ce qui est chargé. N'exposez que les outils et documents pertinents à la tâche en cours. Comme le dit Anthropic : « Si un humain ne peut pas choisir de façon définitive le bon outil, un agent ne peut pas faire mieux. »

Conflit

Des informations contradictoires dans le contexte. Le guide de style dit « soyez concis » mais le modèle dit « incluez une explication détaillée ». Une étude Microsoft/Salesforce a montré une baisse de qualité de 39 % quand des informations contradictoires étaient présentes.

Correctif : Auditez votre contexte pour les contradictions. Quand vous mettez à jour les fichiers de contexte, retirez l'ancienne consigne — n'ajoutez pas simplement la nouvelle à côté. Une seule source de vérité par sujet.

Rédiger des spécifications pour différents rôles

Spécification d'ingénierie

## Problem
The job scheduler processes tasks sequentially. Large jobs
(50K+ items) block smaller jobs in the queue. Users with
small jobs wait 30+ minutes for processing to start.

## Scope
- Modify the job queue to support priority-based scheduling
- Small jobs (< 5K items) get higher priority
- Do NOT change the processing rate limits or the
  rendering pipeline

## Inputs
- Job queue implementation: src/jobs/queue.ts
- Job model: src/models/job.ts
- Current tests: src/jobs/__tests__/queue.test.ts

## Constraints
- Must: maintain FIFO order within the same priority tier
- Must: process all jobs within the existing rate limits
- Must not: drop or reorder jobs already in progress
- Must not: require a database migration
- Prefer: use the existing BullMQ priority feature
- Escalate: if the solution requires changing the job schema

## Acceptance criteria
1. A 1K-item job queued after a 100K job starts processing
   within 5 minutes, not 30+
2. No job is starved — all jobs complete within 2x their
   expected duration
3. Existing tests pass without modification
4. New tests cover priority ordering and starvation prevention

## Failure conditions
- Any job processed with incorrect inputs
- Any job processed twice
- Queue deadlock under concurrent submissions

## Success tests
1. Queue 3 jobs: 100K, 1K, 500. Verify 1K and 500
   start before 100K completes.
2. Queue 20 small jobs and 1 large. Verify all complete.
3. Submit jobs concurrently from 3 API clients.
   Verify no duplicates or lost jobs.

Spécification marketing

## Problem
Trial-to-paid conversion is 12%. Industry benchmark is 18%.
Users who complete onboarding within 72 hours convert at 31%.
Most trial users never complete onboarding.

## Scope
Design a 3-email onboarding sequence triggered when a trial
user hasn't completed their first project by day 3. Goal:
get them to complete onboarding. This is the email content
only — the automation trigger already exists.

## Inputs
- Current welcome email (attached)
- Top 3 templates by usage (attached)
- Brand voice guide: friendly, competent, never corporate
- Product: visual editor, template library, project management

## Constraints
- Must: each email under 100 words
- Must: one clear CTA per email
- Must: work in both EN and FR
- Must not: mention pricing or plan limitations
- Must not: use urgency tactics ("your trial is expiring!")
- Prefer: show, don't tell (link to a template, not a
  feature list)
- Escalate: if the sequence needs more than 3 emails

## Acceptance criteria
1. Each email has exactly one CTA linking to a specific
   action in the product
2. Tone matches the brand voice guide
3. No email exceeds 100 words
4. Subject lines are under 50 characters
5. A non-customer can understand the value proposition
   without prior product knowledge

## Failure conditions
- Any email exceeds 100 words
- CTA links to a generic page instead of a specific action
- Urgency language appears ("limited time", "expiring",
  "last chance")
- French version is a literal translation rather than
  natural prose

## Success tests
1. Read email 1 cold. Can you identify what the product
   does and what action to take? (yes/no)
2. Read all 3 in sequence. Does the progression feel
   natural, not repetitive? (yes/no)
3. French versions read naturally, not like translations.
   (verified by native speaker)

Spécification de support

## Problem
Support response time averages 6 hours. 40% of tickets are
questions already answered in the knowledge base. Agents
spend time searching for answers that already exist.

## Scope
Build an AI-assisted draft response system. When a ticket
comes in, the system searches the knowledge base and drafts
a response for the support agent to review and send.
The agent always reviews before sending — no auto-responses.

## Inputs
- Knowledge base articles (~200 articles)
- Ticket history (last 90 days, anonymized)
- Customer account data (plan type, tenure, recent activity)
- Canned response templates (32 templates)

## Constraints
- Must: human reviews every response before sending
- Must: cite the knowledge base article used
- Must: flag when no relevant article exists
  (signal to create one)
- Must not: access customer data from other accounts
- Must not: promise resolution times
- Must not: auto-close tickets
- Prefer: match the customer's language
- Prefer: keep drafts under 200 words
- Escalate: billing disputes over $500, mentions of
  cancellation, data loss issues

## Acceptance criteria
1. Drafts are generated within 30 seconds of ticket creation
2. 70%+ of drafts require less than 20% editing
3. Cited knowledge base articles are relevant to the question
4. Agents can override or discard any draft with one click

## Failure conditions
- Response sent without human review
- Customer data from account A appears in account B's response
- Draft cites a deprecated or incorrect KB article
- System generates a draft for a ticket it should escalate

## Success tests
1. "How do I set up custom domains?" → Draft references
   the domain setup KB article with correct instructions
2. "I was charged twice" → Draft flags for escalation,
   does not attempt to resolve billing
3. Question in French → Draft is in French,
   references relevant troubleshooting steps
4. Gibberish input → System flags as unclear, does not
   generate a draft

La boucle d'amélioration de la spécification

Une spécification n'est jamais réussie du premier coup. Utilisez le modèle de responsabilité en cas d'échec :

Rédigez la spécification en utilisant les cinq composantes
Exécutez-la — laissez l'agent travailler
Évaluez le résultat par rapport à vos critères d'acceptation
Diagnostiquez les échecs par couche :

Ce qui a mal tourné	Quelle couche corriger
Le résultat est mauvais ou de faible qualité	Couche 1 — améliorez le prompt
Le résultat ignore les connaissances du domaine	Couche 2 — améliorez le contexte
Le résultat optimise la mauvaise chose	Couche 3 — clarifiez l'intention
Le résultat est incomplet ou manque des exigences	Couche 4 — resserrez la spécification

Corrigez une couche à la fois. Ne changez jamais plusieurs couches simultanément — vous ne saurez pas ce qui a fonctionné.
Mettez à jour la spécification avec ce que vous avez appris. Les meilleures spécifications sont écrites par des gens qui ont vu des agents échouer.

Cette approche itérative rejoint la recommandation d'Anthropic de « commencer au minimum avec le meilleur modèle, puis ajouter des instructions de façon itérative en se basant sur les modes d'échec observés. »

Erreurs courantes

Surspécifier. Une spécification qui décrit chaque détail d'implémentation est juste du pseudocode. Spécifiez le quoi et les contraintes, pas le comment. Laissez l'agent choisir l'approche dans vos limites.

Sous-spécifier. « Améliore ça » n'est pas une spécification. Si vous ne pouvez pas décrire « terminé », vous n'êtes pas prêt à déléguer.

Déverser du contexte. Charger tous vos documents dans le contexte « au cas où ». L'information non pertinente dégrade activement le résultat. Le principe fondamental d'Anthropic : trouver le plus petit ensemble de tokens à haute valeur, pas le plus de tokens.

Optimiser les prompts quand le problème est le contexte. Si l'agent continue de produire des résultats non pertinents, ajouter « sois plus pertinent » au prompt ne va pas aider. L'agent a besoin d'informations différentes, pas de meilleures instructions. Utilisez le modèle de responsabilité en cas d'échec pour diagnostiquer la bonne couche.

Sauter la conception d'évaluation. Sans cas de test, vous vous fiez à l'instinct pour juger la qualité du résultat. Construisez les cas de test en premier — ils vous forcent à clarifier ce que vous voulez vraiment.

Réessayer au lieu de diagnostiquer. Quand le résultat échoue, le réflexe est de régénérer. Arrêtez. Identifiez quelle couche a causé l'échec. Corrigez cette couche. Puis réessayez.

Référence rapide

Avant de déléguer, confirmez :

Je peux décrire le problème sans référencer des choses que l'agent ne connaît pas
Je peux écrire trois phrases qui vérifient le succès
J'ai listé ce qui doit arriver, ne doit pas arriver, et quand arrêter pour demander
J'ai découpé la tâche en morceaux assez petits pour être vérifiés indépendamment
J'ai des cas de test avec des caractéristiques connues

Quand le résultat échoue, diagnostiquez :

Symptôme	Cause probable	Action
Le résultat est mauvais	Prompt	Améliorez les instructions, ajoutez des exemples
Le résultat ignore votre domaine	Contexte	Ajoutez ou mettez à jour le fichier de contexte
Le résultat optimise la mauvaise chose	Intention	Définissez la hiérarchie des objectifs et les compromis
Le résultat est incomplet	Spécification	Ajoutez les exigences manquantes, resserrez la portée

Pour aller plus loin

Building Effective Agents — Le guide d'Anthropic sur les patrons d'architecture d'agents
Effective Context Engineering for AI Agents — La gestion de l'état complet des tokens à travers les boucles d'agents
Writing Tools for Agents — Principes de conception d'outils et méthodologie d'évaluation
Context Engineering for Agents — Le cadre des quatre opérations de LangChain (écrire, sélectionner, compresser, isoler)
A Survey of Context Engineering for LLMs — Revue académique établissant une taxonomie formelle
CodeScout: Contextual Problem Statement Enhancement — Recherche montrant une amélioration de 20 % grâce à de meilleures spécifications en amont

← Retour à l'accueil · Standards d'exécution · Le cadre de référence · Glossaire