Vibe coding, specs, skills, agents : structurer son usage de l'IA

Vibe coding, specs, skills, agents : structurer son usage de l'IA

On ne va pas se mentir : le vibe coding, c'est grisant. Ouvrir Claude Code, rédiger un prompt du type « génère-moi un dashboard Next.js pour monitorer la santé d'un cluster », et en quelques secondes on a un code qui tourne. Ça fait son petit effet.

Sauf que quand on regarde de plus près, la réalité rattrape vite l'enthousiasme. L'authentification ? Absente. La librairie de data fetching ? Celle que vous aviez explicitement dépréciée le mois dernier. Le format des réponses API ? Inventé de toutes pièces. Le vibe était bon, mais le delivery est complètement à côté.

Nos consultants techniques interviennent au quotidien sur des architectures headless, des pipelines CI/CD et du conseil en choix technologiques. Et ce que nous observons chez nos clients, c'est que la plupart des équipes de développement sont bloquées entre deux extrêmes : soit elles improvisent à 100 % et espèrent que cela tienne, soit elles écrivent des specs monolithiques de 80 pages que l'IA finit par ignorer. Les deux approches sont des impasses.

Il y a une troisième voie, et elle repose sur quatre briques complémentaires.

Le gap d'encodage/décodage : pourquoi le vibe coding seul ne scale pas ?

Ce que l'on peut appeler le gap d'encodage et de décodage, c'est l'écart entre ce que l'on a en tête quand on prompte un agent IA et ce que l'agent produit réellement. Quand cet écart est faible, c'est magique, le code ressemble à ce qu'on aurait écrit nous-même. Quand il est large, on passe plus de temps à corriger l'output qu'à coder from scratch.

Le problème du vibe coding pur, c'est que cet écart est structurellement large. On donne une intention floue et l'agent comble les blancs avec ses propres hypothèses. Celles-ci étant basées sur ses propres données d'entraînement, pas sur votre projet, votre infra ou encore vos contraintes métier.

Sur un MVP ou prototype, cela peut passer. Sur un projet client avec des contraintes de sécurité, une stack imposée et un existant à respecter, c'est un risque qu'on ne peut pas se permettre.

Les quatre piliers : vibes, specs, skills, agents

Voici le type de framework que nous sommes amenés à utiliser dans nos missions de conseil technique.

1. Vibes : l'exploration

Le vibe coding garde tout son sens en phase d'exploration. On peut tester une idée, comparer deux approches d'architecture, prototyper un composant en 10 minutes et j'en passe ...

Concrètement, c'est le mode « interacting » : on discute avec l'agent, on itère, puis on affine. Cela s'apparente à du brainstorming assisté et non pas à de la production.

Une astuce : utiliser le plan mode de Claude Code dans cette phase. Demander à l'agent de scorer la qualité de son brief avant de passer en exécution. Un truc du genre :

« Sur une échelle de 0 à 10, à quel point un agent autonome pourrait-il implémenter cette feature à partir de ce brief seul ? Qu'est-ce qu'il manque ? »

Ça crée une boucle de coaching qui vous aidera à clarifier l'intention avant de lâcher l'agent en mode autonome.

2. Specs : le contrat

C'est là que ça devient sérieux. La spécification, c'est le contrat entre vous et l'agent. Elle formalise le what (quoi construire, pourquoi) et le how (comment le construire dans un contexte précis).

Et la clé, c'est de ne pas mélanger les deux dans un seul document. Si vous rédigez le what et le how dans un même prompt, l'agent perd son focus.

Nous recommandons une approche modulaire, avec des fichiers Markdown dans un dossier specs/ :

• what-vision.md : les objectifs métier, les user stories, les critères de succès.
• how-security.md : authentification, gestion des secrets, OIDC.
• how-observability.md : OpenTelemetry, stratégie de logging, APM.
• how-standards.md : conventions de code, architecture cible, patterns imposés.
• how-testing.md : couverture cible, stratégies de mocking, tests de bout en bout.

L'avantage de cette modularité, c'est de charger uniquement le contexte pertinent à chaque task dédiée.

3. Skills : le savoir-faire packagé

C'est le pilier le plus récent, et sans doute le plus sous-estimé. Si la spec dit quoi faire, la skill dit comment le faire concrètement.

Une skill, c'est un dossier contenant un fichier SKILL.md avec du frontmatter YAML et des instructions Markdown. Il s'agit des normes officielles définies par agentskills.io.

Exemple concret : vous avez besoin que votre agent sache déployer sur un cluster Kubernetes via kubectl ou oc ? Vous empaquetez cela dans une skill :

.claude/skills/deploy-k8s/
├── SKILL.md
├── deploy-template.yaml
└── validate-route.sh

Le SKILL.md décrit la procédure étape par étape :

• vérifier l'authentification ;
• sélectionner le namespace ;
• appliquer le template ;
• valider le deployment.

L'agent lit la skill et l'applique, ce qui lui permet de ne pas réinventer la roue à chaque fois. C'est exactement la logique que nous défendons auprès de nos clients : encoder le savoir-faire de l'équipe dans des assets réutilisables. Les skills, c'est de l'onboarding automatique pour les agents, et accessoirement pour les nouveaux développeurs qui rejoignent le projet.

4. Agents : les moteurs d'exécution

L'agent, c'est le runtime qui consomme les specs et skills pour produire du code. Mais tous les agents ne se valent pas, et il est crucial de choisir le bon outil pour le bon job.

En pratique, on peut distinguer trois types :

Les agents interactifs / chat (Cursor Agent, Claude Code ), qui sont parfaits pour le brainstorming et l'itération rapide. Attention : ils ne chargent pas automatiquement vos specs, il faut les pointer explicitement vers les fichiers.

Les agents IDE-intégrés (Cursor Agent, Claude Code en mode agent, Kiro), qui accèdent au filesystem, lisent les fichiers du projet, exécutent des commandes dans le terminal. C'est le sweet spot pour l'implémentation de features et le refactoring.

Les agents autonomes (AutoGPT, Claude Code en mode non-interactif, agents custom), en leur attribuant des specs solides, ils exécutent sans intervention. C'est le mode le plus efficace pour les migrations à grande échelle ou les tasks répétitives.

Un workflow type : Commencer en mode interactif pour explorer et affiner la spec, puis passer en agent IDE pour l'implémentation, et réserver l'autonome pour les chantiers de mass refactoring ou de migration.

La co-évolution des specs : chaque bug rend le système plus intelligent

Un élément qui fait vraiment la différence en pratique, c'est ce que l'on pourrait appeler la co-évolution des specs. L'idée est simple, chaque erreur de l'agent alimente un fichier LessonsLearned.md, et chaque leçon tirée déclenche une mise à jour de la spec how-xxx.md concernée.

Exemple :

Votre agent génère un endpoint sans vérifier le claim aud du JWT ?

Vous documentez le correctif dans LessonsLearned.md, vous mettez à jour how-security.md avec la contrainte.

-> La prochaine fois que l'agent travaille sur de l'auth, il ne refera pas la même erreur.

C'est un cercle vertueux : vos spécifications s'améliorent au fil du temps, la qualité des outputs augmente et le gap d'encodage/décodage se réduit progressivement. Sur un projet long comme ceux que nous accompagnons (e-commerce BtoB, plateformes multi-sites), c'est un game changer.

En pratique : quel pilier pour quel besoin ?

Un petit récapitulatif pour savoir quand activer quoi :

Situation	Pilier principal	Mode	Résultat attendu
Explorer une nouvelle librairie	Vibe coding	Interagir	Compréhension rapide et vérification
Définir les limites de l'API	Specs (quoi ?)	Instruction	Blueprint fonctionnel
Appliquer les modèles d'authentification	Specs (comment ?)	Instruction	Garde-fous réutilisables
Automatiser un déploiement récurrent	Skills	Agent autonome	Exécution fiable et reproductible
Affiner une spécification existante	Coaching par l'IA	Interagir	Encodage
Passer la génération de code à l'échelle	Agents	Instruction	Code précis à haut volume

Pourquoi cela vaut-il l'investissement ?

On peut objecter que cela fait beaucoup de mise en place pour coder avec de l'IA. Il est vrai que le vibe coding pur est plus rapide sur une demi-heure. Mais après, ce sont les corrections permanentes, les régressions et les hypothèses fausses qui s'accumulent.

Le payoff du système à quatre piliers se mesure sur trois axes :

Productivité : Moins de temps à corriger l'IA, plus de temps pour la review et l'architecture. Dans le cadre de nos projets, nous estimons qu'une spécification bien écrite divise de moitié le temps de review des PRs générées par un agent.

Qualité : Le code devient traçable. Si un bug survient, on sait si c'est la spec qui était incomplète ou si c'est l'agent qui a mal exécuté. Cette traçabilité est impossible en mode vibe only.

Scaling : Un développeur seul peut vibe coder. Mais une équipe ne scale pas sur des vibes. En empaquetant les specs et les skills comme des team assets, tout le monde opère au niveau du meilleur architecte de l'équipe.

Par où commencer ?

Si tout cela vous parle, voici comment démarrer sans tout changer d'un coup :

1. Prenez votre prompt le plus fréquent et transformez-le en spécification modulaire (un fichier what et un fichier how).

2. Identifiez une tâche répétitive (déploiement, migration, setup de projet) et packagez-la en skill.

3. Testez la boucle de coaching : demandez à l'agent de scorer votre spécification avant de l'exécuter.

4. Itérez : alimentez votre LessonsLearned.md à chaque correction.

Le jour où votre agent vous livre du code qui ressemble exactement à ce que vous auriez écrit vous-même, vous saurez que le gap est comblé.

---

Vous voulez structurer l'usage de l'IA dans votre équipe ? Nous encodons le savoir-faire d'une équipe en spécifications et en assets réutilisables.

Parlons de votre projet →

---

Article publié par l'équipe de l'Agence Wex, qui conçoit et construit des produits digitaux : recherche utilisateur, UX et UI design, développement front et headless, accessibilité et maintenance applicative.