Comment rédiger des spécifications efficaces pour les agents IA — Addy Osmani

• Ce qui fait la plus grande différence dans la productivité des agents IA → un SPEC clair et structuré
• Un mauvais SPEC = ambiguïté → dérive de l’IA, échecs répétés, dépassement du contexte
• Un bon SPEC = un document vivant (SPEC.md) + des mises à jour continues

Éléments clés d’un bon SPEC

• Objectif / vision (pourquoi on le crée, à qui il s’adresse)
• Liste des fonctionnalités + priorités
• Stack technique (React 18 + TS, Node 20, etc., de manière précise)
• Commandes d’exécution (npm test, lint, build, etc.)
• Critères de test (quels tests doivent être exécutés pour considérer que c’est réussi)
• Structure du code / guide de style
• Workflow Git (règles de branche, messages de commit)
• Définition des limites (✅ toujours / ⚠️ demander / 🚫 ne jamais faire)

Modèles de prompts efficaces pour démarrer

• « Draft a detailed specification for … covering objectives, features, constraints, step-by-step plan »
• D’abord le Plan Mode → faire rédiger un brouillon du SPEC par l’IA
• Ensuite, donner des consignes découpées en petites tâches

Conseils pratiques (l’essentiel)

• Conserver SPEC.md dans un fichier séparé → n’inclure à chaque tâche que les sections pertinentes
• Modulariser + séparer les sous-tâches
• Après chaque tâche, lancer automatiquement les tests + vérifier le respect du SPEC
• Clarifier explicitement les 3 niveaux de règles de frontière (Always / Ask / Never)