02 — Concepts : développer avec un agent IA sans perdre le fil — Bac à sable — développer avec un agent IA

@diagram:lesson-contract
duration :: 10 min lecture
deliverable :: Un fichier SPEC.md complété pour le projet fil rouge (gourde inox 750 ml)
outcome :: Comprendre quand déléguer à l'agent et quand reprendre la main, avec une spec stable comme point d'ancrage

Définition utile

Développer avec un agent, c’est simple : tu décris ce que tu veux, l’IA écrit le code. Ça marche bien pour explorer une piste, sortir une première version, corriger une erreur ou comprendre une base que tu ne connais pas.

Le problème arrive plus tard. La délégation casse quand :

ton besoin change toutes les dix minutes ;
tu ne sais plus quels fichiers ont bougé ;
l’agent ajoute des dépendances sans te demander ;
personne ne vérifie ce que ça fait vraiment ;
ton prompt finit par remplacer la doc.

D’où la règle qui structure tout ce module : vibe pour explorer, spec pour stabiliser.

Les 4 niveaux de dialogue avec l’IA

Tu ne parles pas à un agent de la même façon selon où tu en es. Voici quatre manières de cadrer une demande, de la plus ouverte à la plus serrée.

1. Demander une explication

C’est ton réflexe quand tu débarques sur un outil ou un code inconnu.

Explique-moi l'arborescence de ce projet comme si je devais le modifier demain.

2. Demander un plan

À sortir avant de laisser quoi que ce soit s’écrire.

Propose un plan en 5 étapes pour créer ce prototype. Ne code pas encore.

3. Demander une modification ciblée

Quand tu sais exactement ce que tu touches et jusqu’où.

Ajoute un bouton "Copier" au résultat généré. Ne modifie pas la structure globale.

4. Demander une itération vérifiée

Le bon réflexe juste après un bug ou un test qui casse.

Voici l'erreur terminale et le fichier concerné. Corrige la cause probable, puis relance la commande de validation.

Le passage du dialogue libre à la spec stable

Une spec, ce n’est pas un dossier administratif que personne ne relira. C’est une consigne posée une fois, que l’agent peut rouvrir à chaque session pour rester aligné.

Le seuil pratique : crée un fichier SPEC.md dès que ton prototype dépasse trois fichiers. Chaque section y joue un rôle. Le diagramme suivant détaille cette anatomie, section par section.

@diagram:spec-anatomy

Exemple minimal :

# SPEC — Générateur de fiches produit

## Objectif
Créer une application web locale qui génère un brouillon de fiche produit en français.

## Utilisateur
Petite boutique ou freelance e-commerce.

## Entrées
- nom du produit
- public cible
- bénéfice 1
- bénéfice 2
- bénéfice 3

## Sortie
- titre court
- description de 2 phrases
- 5 bullet points

## Contraintes
- pas de login
- pas de paiement
- pas de base externe
- lancement local documenté

## Validation
- `npm run dev` démarre l'app
- le formulaire affiche le résultat
- le résultat est copiable

Une fois ce fichier en place, tu cadres l’agent dessus :

Lis SPEC.md. Implémente uniquement ce qui est demandé. Si une décision manque, propose 2 options avant de modifier le code.

Exemple concret : le SPEC.md du projet fil rouge

On reprend le générateur de fiches produit et on l’étoffe. Voici la version complète, avec le cas de test de la gourde inox 750 ml qu’on va trimballer dans tout le parcours.

# SPEC — Générateur de fiches produit gourde inox

## Objectif
Application web locale qui génère un brouillon de fiche produit en français
à partir d'informations produit saisies dans un formulaire.

## Périmètre V1
Interface uniquement front-end, sans backend ni base de données.
La génération produit un texte structuré depuis les champs du formulaire.

## Stack V1
- HTML + CSS + JavaScript vanilla (ou Vite + React si on veut un projet plus structuré)
- Pas de serveur, pas de base de données, pas d'authentification

## User stories

### US-01 — Saisir les informations produit
En tant que responsable boutique, je veux saisir le nom, le public cible
et trois bénéfices produit dans un formulaire simple.

### US-02 — Générer une fiche produit
En tant que responsable boutique, je veux cliquer sur "Générer"
et obtenir un titre, une description courte et 5 bullet points en français.

### US-03 — Copier le résultat
En tant que responsable boutique, je veux copier le résultat en un clic
pour le coller dans mon outil de gestion.

## Critères d'acceptation

- Le formulaire contient : nom produit, public cible, bénéfice 1, bénéfice 2, bénéfice 3.
- Cliquer sur "Générer" produit : un titre (< 10 mots), une description (2 phrases), 5 bullet points.
- Le résultat est en français quelle que soit la langue de saisie.
- Un bouton "Copier" place le résultat dans le presse-papiers.
- L'application démarre avec `npm run dev` ou en ouvrant `index.html` directement.

## Hors périmètre V1
- Appel à une API IA externe
- Sauvegarde sur serveur
- Authentification
- Design avancé

## Cas de test de référence
Produit : Gourde inox 750 ml
Public cible : randonneurs occasionnels
Bénéfice 1 : garde l'eau fraîche
Bénéfice 2 : solide dans un sac
Bénéfice 3 : facile à nettoyer

Sortie attendue (exemple) :
- Titre : Gourde inox 750 ml pour randonneurs occasionnels
- Description : Une solution robuste pensée pour les sorties en plein air, pratique et durable.
- Bullets : garde l'eau fraîche · résiste aux chocs · se rince facilement · compacte dans un sac · sans BPA

Garde ce fichier sous la main : c’est la référence que tu redonnes à l’agent à chaque session, et c’est ce qui tient les dérives à distance.

Ce que l’IA doit faire, et ce que tu gardes

Décision	Toi	Agent
Choisir le problème	✅	❌
Proposer une stack	✅ validation	✅ suggestion
Écrire le code	contrôle	✅
Ajouter des dépendances	✅ autorisation	suggestion
Lancer les tests	vérifie	✅ exécute
Décider que c’est terminé	✅	❌

L’agent va vite. Ton rôle se résume à une chose : retirer les ambiguïtés avant qu’il s’engouffre dedans.

Exercice pratique

Reprends le brief écrit au module 1 et passe-le à ton IA :

Transforme mon brief en SPEC.md court.
Garde uniquement : objectif, utilisateur, entrées, sorties, contraintes, critères de validation.
Ne propose pas de fonctionnalités nouvelles.

Relis ensuite la sortie ligne par ligne et coupe tout ce qui sent la V2.

Check-list de validation

@diagram:checklist
item-1 :: Tu sais expliquer la différence entre prompt improvisé et spec stable.
item-2 :: Tu as un fichier SPEC.md ou un brouillon équivalent.
item-3 :: Les contraintes sont écrites.
item-4 :: Les critères de validation sont mesurables.
item-5 :: Tu as interdit les fonctionnalités hors V1.

Pièges fréquents

Laisser l’agent élargir le produit. Il glisse souvent une auth, un dashboard, des analytics ou une base de données parce que ça fait plus « vraie app ». Dis non.
Écrire une spec trop longue. Une spec V1 guide l’action du jour, elle ne documente pas toute la boîte.
Changer de stack à chaque réponse. Prends une stack simple et tiens-la jusqu’à la validation.
Accepter un code sans commande de lancement. Si tu ne peux pas le lancer, ce n’est pas un prototype.

Suite conseillée

Enchaîne sur le module 3 : tu y prépares l’environnement local avant de confier à un agent la modification de tes fichiers.