Ce que 10 ans de code m'ont appris sur les specs pour agents IA

Après 10 ans à implémenter des specs — bonnes et mauvaises — je reconnais une mauvaise spec IA en quelques lignes. Voici les patterns que je vois revenir, et ce qu’on peut faire à la place.

Le problème fondamental

Une spec classique part d’un comportement attendu et l’exprime comme une règle : “Le système doit faire X quand Y”. Ça fonctionne pour du code déterministe.

Un LLM, c’est probabiliste. Il ne fait pas X, il génère une réponse qui ressemble à X dans la plupart des cas. Ce glissement de paradigme change tout dans la façon d’écrire des specs.

Erreur n°1 : spécifier le comportement sans spécifier les cas limites

J’ai vu des dizaines de specs du type :

“L’agent doit analyser les emails entrants et créer une tâche dans le CRM si l’email contient une demande client.”

En apparence, c’est clair. En pratique, ça ignore des dizaines de questions :

• Qu’est-ce qu’une “demande client” ? Un email qui dit “ça ne marche pas” c’est une demande ?
• Un email de spam qui mentionne un produit, c’est une demande ?
• Un email de votre propre équipe qui parle d’un client, c’est une demande ?

Ce que je fais à la place : je demande systématiquement 10 exemples d’inputs avec le comportement attendu pour chacun. Ça force à préciser les cas limites avant de commencer à coder.

Erreur n°2 : confondre “l’IA comprend” et “l’IA fait”

Une spec écrite comme si le LLM était un humain intelligent qui comprend l’intention derrière les mots :

“L’agent doit répondre de manière professionnelle et empathique.”

Professionnel comment ? Empathique dans quel contexte ? Pour quel type de clients ?

Un LLM sans contrainte précise va inventer sa propre définition de “professionnel” — qui peut très bien ne pas correspondre à la vôtre.

Ce que je fais à la place : je traduis chaque adjectif flou en critères observables. “Professionnel” devient : “Utilise le vouvoiement. Ne commence pas par ‘Bonjour !’. Évite les formules comme ‘Pas de souci’. Termine par une proposition d’action concrète.”

Erreur n°3 : ignorer le format de sortie

La moitié des bugs d’intégration d’agents que j’ai vus viennent d’un JSON mal formé ou d’une structure de réponse imprévue.

Si votre agent doit retourner des données structurées, la spec doit inclure :

{
  "action": "create_task" | "ignore" | "escalate",
  "priority": "low" | "medium" | "high",
  "summary": "string (max 100 chars)",
  "confidence": 0.0 à 1.0
}

Et le prompt système doit explicitement demander ce format — avec un exemple, pas juste une description.

Erreur n°4 : ne pas spécifier le comportement en cas d’incertitude

Que fait l’agent quand il ne sait pas ? C’est souvent la question la plus importante, et la plus oubliée.

Un LLM sans instruction va halluciner une réponse plutôt que d’admettre son incertitude. Il faut lui dire explicitement quand et comment se déclarer incertain :

“Si tu n’es pas sûr à plus de 80% de ta classification, retourne {"action": "escalate", "reason": "incertitude"} plutôt que de prendre une décision.”

Ce que ça change en pratique

Une bonne spec pour un agent IA, ça ressemble à ça :

• Des exemples concrets (inputs + outputs attendus), pas juste une description
• Un schéma de sortie précis avec tous les champs et leurs types
• Des règles de gestion des cas limites explicites
• Un comportement défini pour les situations d’incertitude
• Des métriques d’évaluation : comment savoir si l’agent fonctionne bien ?

C’est plus long à écrire qu’une spec classique. Mais c’est infiniment moins long que de debugger un agent qui hallucine en prod.