Le problème avec le pilotage à vue

Imaginez la scène : vous avez une idée précise d'une fonctionnalité. Vous ouvrez votre assistant IA préféré, tapez une demande rapide, et regardez avec admiration tandis qu'il réécrit joyeusement la moitié de votre codebase. Une heure plus tard, vous voilà face à une PR qui résout un problème que vous n'aviez pas vraiment visé, d'une façon qui casse des choses que vous n'aviez pas l'intention de casser.

Ça vous parle ? Vous n'êtes pas seul. Pendant que les agents IA ont évolué de simples répondeurs de questions vers de véritables éditeurs de code, beaucoup de développeurs réalisent que l'approche décontractée qui fonctionne avec un chatbot ne suffit plus quand des vrais dépôts sont en jeu.

La solution ? Pas des prompts plus détaillés. C'est un changement fondamental dans notre façon de considérer les documents qu'on envoie à ces agents.

Prompts versus specs : une différence cruciale

Le truc avec les prompts, c'est qu'ils sont faits pour démarrer. Parfaits pour des explications rapides, des scripts jetables, des conversations exploratoires. Un prompt vit dans une session de chat, peut utiliser des abréviations, et suppose souvent un contexte que seule la personne qui l'a écrit comprend.

Ça marche très bien quand on pose des questions.

Mais quand un agent IA s'apprête à modifier du code partagé, exécuter des commandes terminal, et produire des branches que des collègues vont relire ? Votre prompt décontracté devient une mission. Et les missions demandent mieux qu'un bon style — elles ont besoin du bon contexte, de limites claires, d'exemples concrets, et de critères de validation.

C'est là qu'interviennent les specs.

Une spec, ce n'est pas un prompt habillé. C'est un document structuré qui capture le problème à résoudre, quel comportement doit changer, ce qui doit rester identique, et comment savoir si le travail est réussi. Contrairement à un prompt qui disparaît dès que l'agent commence, une spec reste visible tout au long du workflow — elle guide l'agent, éclaire les reviewers, et aide les mainteneurs futurs à comprendre pourquoi les décisions ont été prises.

Ce qu'il faut dans une bonne spec pour agent IA

Pas besoin d'un pavé de 20 pages. Cinq éléments clés suffisent :

1. Contexte : Pourquoi cette tâche existe-t-elle ? Quel problème utilisateur ou quelle dette technique la motive ? Quelles contraintes dans la codebase l'agent doit-il connaître ?

2. Comportement à modifier : Quelle fonctionnalité précise doit être modifiée, ajoutée, ou supprimée ? Soyons concrets — "les utilisateurs reçoivent une notification email quand X se produit" vaut mieux que "améliorer le système de notifications".

3. Contraintes à préserver : Qu'est-ce qui ne doit绝对 PAS changer ? Quelles fonctionnalités existantes, contrats d'API, ou caractéristiques de performance doivent rester intactes ?

4. Exemples de correction : Des scénarios concrets qui montrent ce que "bon" signifie. Le format Étant donné / Quand / Alors fonctionne bien, mais quelques cas de test explicites suffisent déjà à cadrer les attentes de l'agent.

5. Critères de validation : Comment un reviewer sait-il que le travail est terminé ? Que doit-il inspecter ? Quelles questions doit-il se poser ?

Ce cadre devrait vous sembler familier si vous avez travaillé avec des scénarios BDD, des modèles de tickets avec critères d'acceptation, ou des documents de conception. Le format précis compte moins que d'avoir la bonne information dans une forme partageable et révisable.

Où ranger les specs dans votre workflow

Un des grands avantages des specs, c'est leur flexibilité. Elles n'ont pas besoin d'être des documents séparés qui vous ralentissent. Une spec peut vivre partout où ça a du sens pour votre équipe :

• Un ticket GitHub avec des critères d'acceptation explicites
• Une description de PR qui nomme le comportement modifié
• Un scénario BDD dans vos fichiers de features
• Une note de conception légère avant l'implémentation
• Des outils comme OpenSpec ou GitHub Spec Kit qui formalisent ce pattern

L'essentiel, c'est de rendre le contexte et les critères de revue visibles et persistants. Votre spec ne doit pas disparaître quand la session de chat se termine. Elle doit voyager avec le travail, donnant aux collègues quelque chose de concret à évaluer.

La couche mission : séparer l'intention de l'exécution

Voici où ça devient vraiment intéressant.

Les meilleures specs fonctionnent comme de petits contrats de comportement. Elles séparent trois questions distinctes :

1. Quel comportement doit changer ? (La exigence)
2. Quelles contraintes ou exemples définissent la correction ? (Les critères d'acceptation)
3. Quel chemin d'implémentation semble approprié actuellement ? (L'approche technique)

Ces questions sont liées, mais elles ne doivent pas se mélanger en un bloc d'instructions.

Pourquoi est-ce important pour les agents IA de codage ? Parce que quand vous mixez intention et implémentation trop tôt, l'agent peut optimiser pour la mauvaise chose. Il peut fidèlement suivre un détail d'implémentation suggéré tout en manquant le comportement dont vous aviez vraiment besoin. Ou produire du code techniquement intéressant mais qui ne résout pas le problème déclaré.

Une couche mission garde l'exigence stable tout en permettant à l'implémentation d'évoluer. Pendant que l'agent explore la codebase, découvre des complications, et affine son approche, la spec reste la référence : "Le travail satisfait-il ceci ?"

C'est particulièrement précieux pour les codebases existantes. La plupart du travail d'ingénierie n'est pas sur du vert — vous modifiez du comportement qui existe déjà. Une bonne spec dit : voici le comportement actuel, et voici ce qui doit changer. Les reviewers n'ont pas à reconstruire mentalement votre intention à partir des détails d'implémentation.

Passer le cap

Si vous avez l'habitude de traiter les agents IA comme des moteurs de recherche surboostés, tout ça peut sembler overkill. Mais considérez l'alternative : des modifications incontrôlées du code partagé, des PR dures à relire, et un travail qui ne correspond pas vraiment à ce que vous aviez imaginé.

Le passage à une collaboration IA guidée par des specs, ce n'est pas de la bureaucratie. C'est donner aux humains comme aux machines la clarté dont ils ont besoin pour travailler efficacement ensemble.

Commencez petit. La prochaine fois que vous vous apprêtez à lâcher un agent IA dans un dépôt, prenez cinq minutes pour noter le contexte, le changement de comportement, et les critères de succès. Mettez ça quelque part de visible — même si c'est juste dans la description de la PR.

Votre futur vous (et vos collègues) vous remercieront.

En résumé : Les agents IA de codage sont des collaborateurs puissants. Traitez-les comme tels. Donnez-leur un briefing correct, et vous obtiendrez un travail qui mérite d'être relu.