Comment rédiger de bonnes spécifications pour les agents IA

• Les agents de codage IA ne fonctionnent pas correctement si on leur balance d’un coup des spécifications énormes ; l’essentiel est de rédiger des spécifications intelligentes
• Il est recommandé de présenter d’abord une vision de haut niveau, puis de laisser l’IA développer le plan détaillé, de relire ce plan en lecture seule dans le Plan Mode, puis de passer à l’étape d’écriture du code
• L’analyse de plus de 2 500 fichiers de configuration d’agents sur GitHub montre que des spécifications efficaces couvrent 6 domaines clés : Commands, Testing, Project Structure, Code Style, Git Workflow, Boundaries
• Pour les tâches de grande ampleur, il faut les diviser en petites tâches modulaires plutôt qu’en un unique prompt géant, et ne fournir que le contexte nécessaire à chaque tâche afin d’éviter une baisse de qualité
• Intégrer dans la spécification des limites en 3 niveaux (Always/Ask first/Never), une auto-vérification, des tests d’adéquation, puis tester, itérer et faire évoluer en continu constitue le cœur d’un workflow de développement piloté par les spécifications

---

TL;DR

• Rédiger des spécifications claires avec le bon niveau de détail (structure, style, tests, limites, etc.)
• Pour les gros travaux, il est recommandé de les découper en petites unités plutôt que de les confier sous forme d’un bloc unique
• Établir le plan d’abord en mode lecture seule, puis exécuter et améliorer en continu

Principe clé : rédiger des spécifications intelligentes

• Le simple fait de jeter des spécifications massives à un agent IA mène à l’échec, car on se heurte aux limites de la fenêtre de contexte et au budget d’attention (attention budget) du modèle
• Une « spécification intelligente » est un document qui guide clairement l’agent, reste dans une taille de contexte praticable et évolue avec le projet
• Il s’agit d’un framework de principes tirés de l’expérience d’utilisation d’agents de codage comme Claude Code et Gemini CLI

Principe 1 : donner d’abord la vue d’ensemble, puis laisser l’IA esquisser les détails

• Plutôt que d’essayer de tout concevoir de manière excessive dès le départ, il faut commencer par définir clairement une déclaration d’objectif et quelques exigences clés
• Cette spécification initiale sert de « brief produit », puis l’agent est chargé de développer à partir de là une spécification détaillée
• Les agents basés sur des LLM remplissent bien les détails lorsque les consignes de haut niveau sont claires, mais ils ont tendance à s’égarer facilement si la mission est floue
• L’essentiel est donc de graver dès le départ une mission claire pour éviter que l’agent ne parte dans tous les sens

• Utiliser Plan Mode

  • Le Plan Mode de Claude Code maintient l’agent en lecture seule et le limite à l’analyse de la base de code et à l’élaboration d’un plan détaillé
  • Après être entré dans le Plan Mode avec Shift+Tab et avoir expliqué « ce que vous voulez construire », l’agent parcourt le code existant et rédige une première ébauche de la spécification
  • À ce stade, on peut aussi lui demander d’examiner l’architecture, les bonnes pratiques, les risques de sécurité et la stratégie de test
  • Il faut rester en Plan Mode jusqu’à ce que le plan soit suffisamment affiné sans ambiguïté, puis seulement ensuite quitter le Plan Mode et passer à l’exécution

• Utiliser les spécifications comme contexte

  • La spécification validée est enregistrée dans un fichier comme SPEC.md, puis on ne redonne à l’agent que les sections nécessaires au moment du travail
  • Comme le fichier de spécification reste disponible d’une session à l’autre, il permet de recaler l’IA sur le même point de référence au redémarrage du projet
  • Cela aide à réduire les oublis qui surviennent quand l’historique de conversation s’allonge ou quand l’agent redémarre
  • Comme une équipe partage un PRD (document d’exigences produit) comme base commune, ce fichier joue le rôle de document de référence unique consulté aussi bien par les humains que par l’IA

• Rester orienté objectifs

  • Une spécification de haut niveau a intérêt à se concentrer sur le what/why plutôt qu’à décrire dès le départ toutes les méthodes d’implémentation ; le how concret peut venir plus tard
  • La structurer comme des user stories et des critères d’acceptation : « Qui est l’utilisateur ? / De quoi a-t-il besoin ? / À quoi ressemble la réussite ? »
  • Le GitHub Spec Kit insiste lui aussi sur cette logique : fournir une explication de haut niveau sur ce que l’on construit et pourquoi, puis laisser l’agent de codage produire des spécifications détaillées centrées sur l’expérience utilisateur et les critères de réussite

Principe 2 : structurer les spécifications comme un PRD professionnel (ou un SRS)

• Il est important de traiter les spécifications IA non pas comme un simple assemblage de notes, mais comme un document structuré avec des sections claires
• Une forme complète et ordonnée, comme un PRD ou un document de conception système, convient particulièrement bien à une IA qui interprète le contenu au pied de la lettre
• D’après une analyse de plus de 2 500 fichiers de configuration d’agents sur GitHub, les spécifications efficaces comportent en commun 6 domaines clés

  • 1. Commands

    • Placer les commandes exécutables au début du document
    • Ne pas se contenter du nom de l’outil, mais indiquer la commande complète avec ses flags : npm test, pytest -v, npm run build

  • 2. Testing

    • Indiquer précisément comment exécuter les tests, quel framework est utilisé, où se trouvent les fichiers de test et quel niveau de couverture est attendu

  • 3. Project Structure

    • Distinguer clairement l’emplacement du code source, des tests et de la documentation
    • Exemple : « src/ pour le code de l’application, tests/ pour les tests unitaires, docs/ pour la documentation »

  • 4. Code Style

    • Un seul snippet de code réel est bien plus efficace qu’une longue explication du style
    • Présenter aussi les conventions de nommage, les règles de formatage et des exemples de sortie souhaitée

  • 5. Git Workflow

    • Si les règles de nommage des branches, le format des messages de commit et les exigences des PR sont précisés, l’agent suivra lui aussi ce flux

  • 6. Boundaries

    • Définir clairement les zones que l’agent ne doit jamais modifier
    • Secrets, répertoires vendor, configuration de production, dossiers spécifiques, etc.
    • L’étude GitHub montre que « ne jamais commit de secrets » est la contrainte utile la plus fréquemment mentionnée

• Être précis sur la stack

  • Au lieu de rester vague avec « projet React », il est important d’écrire quelque chose de précis comme « React 18 + TypeScript + Vite + Tailwind CSS »
  • Il faut indiquer les versions et les dépendances principales : des spécifications ambiguës finissent par produire un code ambigu

• Utiliser un format cohérent

  • La clarté est le point le plus important, et beaucoup de développeurs délimitent les sections avec des titres Markdown ou des balises proches de l’XML
  • Les modèles d’IA traitent bien plus fiablement un texte bien structuré qu’une prose libre
  • Les ingénieurs d’Anthropic recommandent eux aussi une organisation en sections clairement séparées comme <background>, <instructions>, <tools>, <output_format>

• Intégrer les spécifications à la toolchain

  • Traiter les spécifications non comme une simple documentation, mais comme un « artefact exécutable » relié au versioning et au CI/CD
  • GitHub Spec Kit utilise un workflow en 4 étapes avec points de contrôle qui place les spécifications au centre du processus d’ingénierie
    • Specify : fournir une description de haut niveau de ce qui doit être construit et pourquoi, puis laisser l’agent de code générer les spécifications détaillées
    • Plan : établir un plan technique incluant la stack souhaitée, l’architecture et les contraintes
    • Tasks : découper les spécifications et le plan en unités de travail concrètes, puis les décomposer en éléments testables
    • Implement : l’agent de code traite les tâches une par une, ou en parallèle

• Persona spécialisée via agents.md

  • Dans des outils comme GitHub Copilot, il est possible de définir des personas d’agents spécialisés
  • Il est possible de séparer les rôles comme @docs-agent (documentation technique), @test-agent (QA), @security-agent (revue de code)
  • Chaque fichier agents.md sert de spécification ciblée décrivant le comportement, les commandes et les limites de ce persona

• Concevoir l’Agent Experience (AX)

  • De la même manière qu’on conçoit une API pour l’expérience développeur (DX), les spécifications doivent elles aussi être pensées pour l’expérience agent (AX)
  • Un format propre et facile à parser est essentiel
    • Le schéma OpenAPI de l’API que l’agent utilisera
    • Un résumé de documentation pour la consommation par les LLM (llms.txt)
    • Des définitions de types explicites
  • Plus une spécification suit des standards comme le MCP (Model Context Protocol), plus l’agent pourra la comprendre et agir de manière fiable

• Maintenir un document vivant

  • Une spécification n’est pas un document qu’on rédige une fois pour toutes : elle doit être mise à jour en continu à mesure que des décisions sont prises avec l’IA ou que de nouveaux faits apparaissent
  • Dans les workflows pilotés par les spécifications, la spécification pilote l’implémentation, les tests et la décomposition des tâches, et l’on ne passe pas à l’étape suivante tant qu’elle n’est pas validée
  • Cette spécification n’est pas seulement un document pour l’IA : c’est aussi un outil clé qui permet aux développeurs de superviser l’ensemble du flux et de vérifier que les résultats de l’IA répondent bien aux exigences réelles

Principe 3 : diviser les tâches en prompts et contextes modulaires

• Au lieu de tout mettre dans un seul prompt gigantesque, fournissez un contexte qui permet de se concentrer sur une seule tâche à la fois
• Si l’on met les exigences, le code et les instructions de tout le projet dans un prompt unique, cela risque au contraire d’accentuer la confusion
• Au-delà du risque de dépasser les limites de tokens, la « malédiction des instructions (curse of instructions) » peut aussi provoquer une chute brutale de la capacité de concentration du modèle

• La malédiction des instructions

  • Selon les résultats de recherche, plus on empile d’instructions ou de données dans un prompt, plus la capacité à suivre précisément chaque instruction baisse de façon notable
  • Même des modèles puissants comme GPT-4 ou Claude ont du mal lorsqu’on leur demande de satisfaire simultanément de nombreuses exigences
  • Par exemple, si on fournit 10 règles détaillées sous forme de puces, ils ont tendance à respecter les premières puis à ignorer progressivement celles de la fin
  • Une meilleure stratégie consiste en une concentration itérative : se focaliser sur un seul sous-problème à la fois, puis passer au suivant une fois celui-ci terminé

• Diviser la spécification en étapes ou en composants

  • Si le document de spécification est long ou couvre un périmètre large, envisagez de le découper en plusieurs parties
  • Exemple : séparer « Backend API Spec » et « Frontend UI Spec » dans des sections distinctes
  • Lorsqu’on travaille sur le backend, il n’est pas nécessaire de fournir systématiquement la spécification frontend en même temps
  • Dans un environnement multi-agents, il est aussi possible d’affecter un agent distinct ou un sous-processus à chaque domaine
  • Le guide IA de DigitalOcean avertit également de « ne pas mélanger en une seule fois les tâches d’authentification et les modifications de schéma de base de données »

• TOC enrichie/résumé pour les spécifications de grande taille

  • Une approche consiste à demander d’abord à l’agent de produire une table des matières enrichie (TOC) qui résume l’ensemble de la spécification
  • Chaque section est condensée en quelques points clés ou mots-clés, avec une référence vers l’emplacement des détails
  • Exemple : « Security : utiliser HTTPS, protéger les clés API, implémenter la validation des entrées (voir spécification complète §4.2) »
  • En préparant ainsi un résumé hiérarchique, on peut ne conserver dans le prompt que la vue d’ensemble et ne fournir les détails qu’au moment nécessaire
  • La TOC enrichie joue le rôle d’un index et amène l’agent à se dire : « ah, il existe une section sur la sécurité », puis à demander cette partie
  • Cette approche de résumé hiérarchique aide les LLM à conserver une structure de haut niveau

• Exploiter des sous-agents ou des « skills »

  • À l’image des sous-agents (ou « skills ») décrits par Anthropic, il est possible d’utiliser plusieurs agents aux rôles séparés
  • Chaque sous-agent est configuré pour un domaine d’expertise précis et ne reçoit que la partie de la spécification correspondant à ce domaine
  • Exemple : le sous-agent Database Designer ne connaît que la section du modèle de données, tandis que le sous-agent API Coder ne voit que la spécification des endpoints API
  • Cela permet à chaque agent d’avoir un contexte plus réduit et un rôle plus net, ce qui rend possibles une meilleure précision et un travail en parallèle
  • Claude Code prend en charge la définition de sous-agents disposant de leur propre prompt système et de leurs propres outils

• Des agents parallèles pour le débit

  • Faire tourner plusieurs agents simultanément s’impose comme la prochaine étape de la productivité des développeurs
  • Au lieu d’attendre qu’un agent ait terminé, on affecte des agents en parallèle à des tâches qui ne se chevauchent pas
  • Simon Willison appelle cela « accepter les agents de code parallèles » et indique que c’est étonnamment efficace, mais mentalement assez épuisant
  • L’essentiel est de bien découper le périmètre des tâches pour que les agents ne perturbent pas le travail les uns des autres
  • Des frameworks d’orchestration comme LangGraph ou OpenAI Swarm peuvent aider à cette coordination,
  • et si l’on utilise une base de données vectorielle comme Chroma comme mémoire partagée, il devient possible d’accéder à un contexte commun sans re-prompter inutilement

• Agent unique vs multi-agents : quand les utiliser

  Aspect	Agent unique	Agents parallèles / multi-agents
  Avantages	Configuration simple, faible overhead, débogage et suivi du flux faciles	Débit élevé, meilleure gestion des interdépendances complexes et spécialisation par domaine
  Inconvénients	Surcharge de contexte sur les grands projets, ralentissement des itérations, point de défaillance unique	Coût de coordination accru, risques de conflit, besoin d’une mémoire partagée
  Cas adaptés	Modules isolés, projets petits à moyens, prototypage initial	Grandes bases de code, séparation codage/test/revue, développement de fonctionnalités indépendantes
  Conseils	Utiliser des résumés de spécification, actualiser le contexte par tâche, réinitialiser souvent les sessions	Se limiter à 2 ou 3 agents au départ, partager les outils via MCP, clarifier les frontières

• Faire en sorte que chaque prompt se concentre sur une seule tâche/section

  • Même sans environnement multi-agents complexe, on peut imposer suffisamment de modularité de façon manuelle
  • Exemple : après avoir rédigé la spécification, à l’étape « Step 1: implémentation du schéma de base de données », ne fournir que la section Database de la spécification
  • Recomposez le contexte chaque fois que la tâche principale change, afin de réduire les distractions dues à des informations obsolètes ou non pertinentes
  • Certains guides recommandent de démarrer une nouvelle session lors d’un changement de fonctionnalité majeure afin de nettoyer le contexte

• Utiliser des instructions inline et des TODO dans le code

  • Une autre méthode consiste à écrire dans le code ce qu’il faut faire au moyen de commentaires // TODO, puis à laisser l’agent les traiter un par un
  • Chaque TODO joue le rôle d’une mini-spécification pour une petite tâche
  • Au final, l’IA se retrouve à se concentrer sur un périmètre très étroit du type : « implémente uniquement cette fonction conformément à cet extrait de spécification »

Principe 4 : intégrer l’auto-vérification, les contraintes et l’expertise humaine

• Traiter la spécification non pas comme une simple liste de tâches pour l’agent, mais comme un guide de pilotage de la qualité, en y intégrant activement sa propre expertise
• Une bonne spécification anticipe les endroits où l’IA risque de se tromper et y met en place des garde-fous
• Y inclure la connaissance métier, les cas limites et diverses « précautions » pour éviter que l’IA n’opère dans le vide, sans contexte
• Il est plus facile de comprendre la spécification si on la considère comme le coach et l’arbitre de l’IA : elle oriente vers la bonne approche et freine immédiatement les mauvais comportements
• D’après l’analyse de plus de 2 500 fichiers d’agents sur GitHub, les spécifications les plus efficaces n’utilisent pas une simple liste d’interdictions, mais un système de garde à trois niveaux
  • Elles indiquent clairement quand l’agent peut continuer tel quel, quand il doit s’arrêter pour demander, et quand il doit interrompre complètement

  • ✅ Always do (toujours faire)

    • Les tâches à exécuter sans poser de question
    • Ex. : « toujours exécuter les tests avant un commit », « toujours respecter les conventions de nommage du guide de style », « toujours journaliser les erreurs dans le service de monitoring »

  • ⚠️ Ask first (demander d’abord)

    • Les tâches qui nécessitent une approbation humaine
    • Ex. : « demander avant de modifier le schéma de la base de données », « demander avant d’ajouter une nouvelle dépendance », « demander avant de modifier la configuration CI/CD »
    • Même si ces actions sont techniquement possibles, on filtre ici les changements qui demandent un jugement humain en raison de leur impact potentiellement large

  • 🚫 Never do (ne jamais faire)

    • Les zones d’arrêt net et explicite
    • Ex. : « ne jamais commit de secrets ni de clés API », « ne jamais modifier node_modules/ ou vendor/ », « ne jamais supprimer des tests qui échouent sans approbation explicite »
    • L’étude montre aussi que « ne jamais commit de secrets » est la contrainte utile qui revient le plus souvent

• Encourager l’auto-vérification

  • Inciter l’agent à vérifier lui-même ses résultats au regard de la spécification
  • Si les outils l’autorisent, intégrer au workflow l’exécution directe de tests unitaires ou du linting après la génération de code
  • On peut aussi donner une consigne de revérification au niveau du prompt
    • Ex. : « après l’implémentation, compare le résultat à la spécification, vérifie que toutes les exigences sont satisfaites et liste celles qui ne le sont pas »
  • Cela pousse le LLM à confronter sa propre sortie à la spécification, ce qui réduit les oublis

• LLM-as-a-Judge pour les vérifications subjectives

  • Pour les critères difficiles à automatiser, comme le style de code, la lisibilité ou le respect des patterns d’architecture, utiliser l’approche LLM-as-a-Judge
  • Un second agent (ou un prompt séparé) examine la sortie du premier agent au regard des critères de qualité de la spécification
  • Ex. : « vérifie si ce code respecte notre guide de style et signale les violations »
  • L’agent jouant le rôle d’arbitre renvoie un feedback, qui peut ensuite être pris en compte ou servir de déclencheur pour une correction

• Tests de conformité

  • Willison recommande de construire une suite de conformité (conformance suite)
  • Il s’agit de tests indépendants du langage, souvent basés sur YAML, qui servent de contrat que toute implémentation doit impérativement respecter
  • Dans le cas d’une API, la suite de conformité définit les entrées et sorties attendues, et le code produit par l’agent doit toutes les satisfaire
  • Dans la section Success de la spécification, on peut expliciter un critère du type : « tous les cas de conformance/api-tests.yaml doivent obligatoirement passer »

• Utiliser les tests dans la spécification

  • Si possible, inclure directement dans la spécification et dans le flux de prompts un plan de test ou les tests eux-mêmes
  • Comme en TDD, les cas de test rendent les exigences plus explicites
    • Ex. : dans Success Criteria, indiquer que « cette entrée d’exemple doit obligatoirement produire cette sortie »
  • Willison décrit une suite de tests robuste comme donnant pratiquement un super-pouvoir à l’agent
  • Parce qu’elle permet de vérifier immédiatement en cas d’échec, puis d’itérer
  • Dans une architecture à sous-agents, on peut aussi prévoir un agent de test dédié, qui reçoit les critères de la spécification et valide en continu les sorties de code

• Intégrer la connaissance métier

  • La spécification doit contenir des insights concrets que seuls des développeurs expérimentés ou des personnes connaissant le contexte possèdent
  • Ex. : lors de la création d’un agent e-commerce, préciser explicitement que products et categories sont dans une relation many-to-many
    • Il ne faut pas supposer que l’IA le déduira d’elle-même
  • Si une bibliothèque donnée est délicate à utiliser, préciser aussi les pièges fréquents et les points d’attention
  • C’est une manière d’insuffler son mentorat dans la spécification
    • Ex. : « lors de l’utilisation de la bibliothèque X, la version Y présente un problème de fuite mémoire, il faut donc appliquer le contournement Z »

• Minimalisme pour les tâches simples

  • Une spécification rigoureuse est importante, mais une part de l’expertise consiste aussi à savoir quand il faut rester simple
  • Pour des tâches relativement simples et isolées, une spécification trop lourde peut au contraire accroître la confusion
  • Ex. : pour une tâche comme « centrer un div sur la page »
    • une consigne du type « garder une solution concise, sans ajouter de markup ni de styles inutiles » peut suffire
  • À l’inverse, une tâche complexe comme « implémenter un flux OAuth avec renouvellement de token et gestion des erreurs » nécessite une spécification détaillée
  • La règle empirique consiste à ajuster la densité de la spécification à la complexité de la tâche

• Garder l’humain comme filtre qualité final

  • La spécification délègue de l’autorité à l’agent, mais la responsabilité finale de la qualité reste au développeur
  • Même si l’agent satisfait techniquement la spécification, si le résultat ne semble pas juste ou ne colle pas au contexte, il faut faire confiance à son jugement
  • Si nécessaire, retravailler la spécification ou retoucher directement le résultat fait naturellement partie du processus
  • Willison compare le travail avec des agents IA à « une forme de management très étrange » et à quelque chose qui « ressemble de façon inconfortable à la gestion d’un stagiaire humain »
  • En fin de compte, fournir des consignes claires (la spécification), suffisamment de contexte et un feedback exploitable reste toujours du ressort de l’humain

Principe 5 : tester, itérer, faire évoluer les spécifications (en utilisant les bons outils)

• Considérez la rédaction des spécifications et la construction d’un agent non pas comme une tâche à faire en une seule fois, mais comme une boucle itérative
  • Un flux consistant à tester rapidement, recueillir des retours, affiner les spécifications et automatiser les vérifications avec des outils
• Les spécifications initiales ne sont pas la version finale, mais le point de départ d’un cycle

• Tests continus

  • N’attendez pas que toute l’implémentation soit terminée : effectuez des tests ou de simples vérifications manuelles à chaque jalon important ou au niveau des fonctions
  • Si un échec est détecté, ne continuez pas tel quel ; modifiez d’abord les spécifications ou le prompt
  • Les tests automatisés sont particulièrement efficaces et, s’il en existe, l’agent peut exécuter lui-même des commandes comme npm test
  • Utilisez directement les résultats d’échec des tests comme entrée du prompt suivant
    • Exemple : « La sortie ne respecte pas les spécifications sur X, Y et Z ; corrige-la »
  • La boucle agentique code → test → correction → répétition est une approche très puissante

• Itération sur les spécifications elles-mêmes

  • Si l’agent a mal compris ou qu’une exigence manquante est révélée, ne masquez pas le problème : corrigez d’abord le document de spécifications
  • Resynchronisez ensuite explicitement l’agent avec les spécifications modifiées
    • Exemple : « J’ai mis à jour les spécifications comme suit. Ajuste le plan ou refactorise le code pour refléter ce changement »
  • Conservez toujours les spécifications comme source unique de vérité
  • Si possible, gardez un historique des versions via des messages de commit ou des notes pour pouvoir suivre ce qui a changé et pourquoi

• Gestion du contexte et utilisation d’outils de mémoire

  • Un écosystème d’outils destiné à aider les agents IA à gérer leur contexte et leurs connaissances est en pleine croissance
  • En utilisant le modèle RAG (Retrieval-Augmented Generation), l’agent peut récupérer instantanément seulement les informations nécessaires depuis une base de connaissances telle qu’une base de données vectorielle
  • Si les spécifications sont très volumineuses, vous pouvez intégrer les sections sous forme d’embeddings afin que l’agent recherche uniquement les parties les plus pertinentes au lieu de recevoir l’ensemble
  • Les frameworks basés sur MCP (Model Context Protocol) fournissent automatiquement le contexte adapté à la tâche en cours
  • Des outils comme Context7(context7.com) chargent automatiquement les extraits pertinents depuis la documentation selon le travail en cours

• Parallélisation prudente

  • Certains développeurs accélèrent le travail en exécutant en parallèle plusieurs instances d’agents sur des tâches différentes
  • Exemple : un agent génère le code tandis qu’un autre rédige les tests en même temps
  • Si vous choisissez cette approche, les tâches doivent être réellement indépendantes ou clairement séparées afin d’éviter les conflits
  • Exemple : imposez que deux agents ne modifient pas le même fichier simultanément
  • Pour réduire la charge de gestion, il est réaliste de commencer avec 2 à 3 agents maximum

• Contrôle de version et gel des spécifications

  • Suivez attentivement le travail de l’agent avec un outil de contrôle de version comme Git
  • Plus vous utilisez l’IA, plus l’importance de bonnes habitudes de gestion de versions augmente
  • Commitez aussi le fichier de spécifications lui-même dans le dépôt pour conserver l’historique des modifications
  • L’agent peut également lire git diff ou blame et comprendre le contexte des changements
    • En pratique, les LLM sont assez doués pour interpréter les diff
  • En gardant les spécifications dans le dépôt, les développeurs comme l’IA peuvent suivre ensemble l’évolution du projet
  • Willison dit du modèle qu’il est « férocement compétent avec Git »

• Prendre en compte les coûts et la vitesse

  • Les tâches qui utilisent de grands modèles et un contexte long peuvent être lentes et coûteuses
  • Séparez stratégiquement le choix des modèles
    • Un modèle rapide et bon marché pour les premiers brouillons ou les tâches répétitives
    • Le modèle le plus performant (et le plus coûteux) pour la sortie finale ou les raisonnements complexes
  • Exemple : confiez GPT-4 ou Claude à la planification et aux étapes clés, et déléguez les extensions simples ou le refactoring à un modèle local ou à un petit modèle d’API
  • Un agent d’exécution de tests ou un agent de lint peut très bien se contenter d’un modèle relativement petit
  • La taille du contexte doit aussi être gérée
    • Inutile d’envoyer 20k tokens à une tâche pour laquelle 5k suffisent
    • L’efficacité peut diminuer à mesure que le nombre de tokens augmente

• Tout surveiller et tout consigner

  • Dans les workflows d’agents complexes, les journaux d’actions et de sorties de l’agent sont indispensables
  • Les logs permettent de vérifier si l’agent s’est écarté de l’intention ou si une erreur s’est produite
  • De nombreux frameworks fournissent des traces ou permettent d’afficher le raisonnement étape par étape
  • L’examen des logs permet de voir où les spécifications ou les instructions ont été mal interprétées

• Apprendre et s’améliorer

  • Considérez chaque projet comme une opportunité d’apprentissage pour améliorer votre capacité à rédiger des spécifications
  • Vous pouvez observer si certaines formulations déstabilisent régulièrement l’IA, ou quelles structures de spécifications sont mieux respectées
  • Réinjectez activement ces enseignements dans les spécifications suivantes
  • Le domaine des agents IA évolue rapidement, et de nouveaux outils comme de nouvelles bonnes pratiques apparaissent sans cesse

Éviter les erreurs fréquentes

• L’analyse de plus de 2 500 fichiers d’agents sur GitHub montre que la principale cause d’échec est le caractère trop flou des spécifications et des instructions

• Prompts vagues

  • Des demandes comme « Fais quelque chose de cool » ou « Fais en sorte que ça marche mieux » ne donnent à l’agent aucun véritable critère de jugement
  • Il faut préciser aussi concrètement que possible les entrées, les sorties et les contraintes
  • Une attribution de rôle générique comme « Vous êtes un assistant de codage utile » est presque sans effet
  • À l’inverse, une consigne comme « Vous êtes un ingénieur test chargé d’écrire des tests de composants React, vous suivez cet exemple et vous ne modifiez jamais le code source » fonctionne bien mieux, car elle définit à la fois le rôle, le périmètre et les contraintes

• Contexte excessif sans résumé

  • Déverser tel quel un document de 50 pages dans le prompt en espérant que le modèle le comprenne seul échoue dans la plupart des cas
  • Il faut utiliser un résumé hiérarchique ou du RAG pour ne faire apparaître que les éléments directement pertinents pour la tâche en cours
  • Augmenter la longueur du contexte ne compense pas un manque de qualité du contexte

• Sauter la revue humaine

  • Principe personnel de Willison : « Je ne committe pas de code que je serais incapable d’expliquer à quelqu’un d’autre »
  • Ce n’est pas parce qu’un agent a produit quelque chose qui passe les tests que ce code est automatiquement correct, sûr et maintenable
  • En particulier, les chemins de code critiques doivent toujours être relus par un humain
  • Le code généré par IA peut sembler solide en apparence, mais s’effondrer sur des cas limites non testés ; la métaphore du « château de cartes » est donc très juste

• Confondre vibe coding et ingénierie de production

  • Le prototypage rapide avec l’IA, ce qu’on appelle le « vibe coding », convient aux phases d’exploration ou aux projets ponctuels
  • Déployer tel quel ce résultat en production, sans spécifications rigoureuses, tests ni revue, risque fortement de poser problème
  • Il faut clairement distinguer le « vibe coding » de l’« ingénierie assistée par IA » ; cette dernière exige la discipline et les procédures décrites dans ce guide
  • Il est important d’avoir conscience du mode dans lequel on est en train de travailler

• Ignorer le « trio fatal »

  • Les trois propriétés qui, selon Willison, rendent les agents IA dangereux
    • Vitesse : ils produisent des résultats plus vite qu’un humain ne peut les relire
    • Non-déterminisme : à entrée identique, la sortie peut varier d’une exécution à l’autre
    • Coût : cela pousse à prendre des raccourcis au lieu de valider correctement
  • Les spécifications et le processus de revue doivent être conçus en prenant en compte ces trois éléments
  • Il faut en particulier contrôler consciemment que la vitesse ne dépasse pas la capacité de vérification

• Oublier les 6 domaines essentiels

  • Si les spécifications ne couvrent pas Commands, Testing, Project Structure, Code Style, Git Workflow et Boundaries, l’agent risque facilement de passer à côté d’informations importantes nécessaires au travail
  • Avant de les transmettre à l’agent, il est prudent de refaire une vérification avec une checklist des 6 domaines

Conclusion

• La rédaction de spécifications efficaces pour les agents de codage IA exige à la fois des principes solides d’ingénierie logicielle et une approche ajustée aux caractéristiques des LLM
• Tout commence par une définition claire de l’objectif, puis par une répartition des rôles où l’IA développe le plan et les détails à partir de cette base
• Une spécification ne doit pas être traitée comme une simple note, mais comme un véritable document de conception, incluant 6 domaines clés et considéré comme un artefact exécutable relié à la toolchain
• Au lieu de tout fournir d’un seul coup, il faut découper et transmettre par unités de travail afin de préserver la concentration de l’agent
  (un TOC résumé, des sous-agents et une orchestration parallèle sont des moyens concrets pour gérer des spécifications de grande ampleur)
• Grâce à une frontière en 3 niveaux (Always / Ask first / Never), à l’auto-vérification et à des tests d’adéquation, on peut bloquer à l’avance les pièges dans lesquels l’IA tombe facilement
• L’essentiel est de traiter la spécification et l’implémentation non comme des résultats figés, mais comme un processus itératif, en les affinant continuellement ensemble via les tests et le feedback
• En suivant ces lignes directrices, il est possible de réduire sensiblement le risque qu’un agent IA perde sa direction dans un contexte volumineux ou dérive vers des réponses incohérentes