Spec-first : écrire la spec avec l'agent
Avant de laisser l'agent coder, fais-le réfléchir. L'approche spec-first transforme une demande vague en contrat écrit — PRD, critères d'acceptation, tests dérivés — que l'agent peut suivre avec précision et que tu peux auditer.
Pourquoi écrire une spec avant de coder ?
L’erreur la plus courante avec un agent de développement : lui donner une instruction et le laisser coder immédiatement. Le résultat compile, peut-être même les tests passent, mais ça ne correspond pas à ce qu’on voulait. Le problème n’est pas l’agent — c’est l’absence de contrat écrit entre toi et lui.
Le coût de l’ambiguïté
Quand tu dis « ajoute un système de notifications », l’agent doit interpréter : notifications par email ? Push ? In-app ? Temps réel ? Batch ? Chaque interprétation produit un code différent. Sans spec, l’agent choisit à ta place — et souvent mal.
Point clé : La spec est un investissement qui se rembourse dès la première session : tu valides la direction sur du texte (quelques secondes) au lieu de la valider sur du code (plusieurs minutes de relecture).
L’approche spec-first
Spec-first signifie : écrire (ou co-écrire avec l’agent) une spécification textuelle avant de produire la moindre ligne de code. La séquence naturelle est PRD → spec → tests → code.
Qu’est-ce qu’une bonne spec agentique ?
Une spec pour un agent n’est pas un cahier des charges de 50 pages. C’est un document court qui contient :
- L’objectif : ce que le système doit faire une fois la feature livrée (1 à 3 phrases).
- Les critères d’acceptation : les conditions vérifiables qui confirment que c’est terminé.
- Les contraintes : ce qu’il ne faut pas faire (ne pas casser l’API existante, ne pas modifier tel module).
- Les exemples : entrée → sortie attendue, cas nominaux et cas limites.
Point clé : Une spec d’une demi-page vaut mieux qu’un prompt de trois lignes. Elle réduit l’espace d’interprétation de l’agent et rend le résultat auditable.
Co-rédiger la spec avec l’agent
La rédaction de la spec elle-même peut être déléguée partiellement à l’agent. Le workflow :
- Tu formules la demande informelle (« je veux un système de notifications pour les commandes en retard »).
- L’agent propose une spec structurée (objectif, critères, contraintes, exemples).
- Tu relis, corriges, précises les zones floues.
- La spec finalisée devient le brief pour la phase d’implémentation.
Attention : Ne pas confondre co-rédaction et approbation aveugle. L’agent peut structurer une spec, mais c’est toi qui valides que les critères d’acceptation sont les bons. Une spec « approuvée sans lecture » est aussi dangereuse qu’un plan approuvé sans lecture.
La spec comme mémoire et oracle
Mémoire inter-sessions
Un agent perd son contexte entre deux sessions. La spec écrite résout ce problème : lors d’un --resume, d’une nouvelle session, ou d’un brief à un sub-agent, la spec joue le rôle de mémoire fiable du « pourquoi » et du « quoi ».
Oracle pour les tests
Les critères d’acceptation de la spec se transforment directement en assertions de test. La séquence naturelle :
- Spec → test (le test vérifie chaque critère d’acceptation).
- Test → code (l’agent implémente jusqu’à ce que les tests passent).
- Le test est l’oracle exécutable de la spec.
Point clé : En TDD agentique, la spec alimente les tests, et les tests pilotent l’agent. La boucle red-green-refactor devient : spec → red → green → refactor.
Spec-first vs. prompt direct
| Critère | Prompt direct | Spec-first |
|---|---|---|
| Temps de préparation | Quelques secondes | 5 à 15 minutes |
| Risque de drift | Élevé (interprétation libre) | Faible (contrat écrit) |
| Réutilisabilité | Nulle (perdu en fin de session) | Forte (fichier persistant) |
| Auditabilité | Difficile (il faut relire le code) | Facile (spec = référence) |
| Coût de correction | Élevé (repartir de zéro) | Faible (ajuster la spec, relancer) |
Attention : Le prompt direct reste valide pour les tâches triviales (correction d’un bug isolé, ajout d’un champ, documentation). La spec-first se justifie dès que la tâche touche plusieurs fichiers ou qu’un malentendu coûterait plus cher que 10 minutes de rédaction.
Pièges de l’approche spec-first
La spec-fleuve
Une spec de 5 pages est contre-productive. L’agent la lira, mais toi tu ne la reliras plus. Et une spec non relue est une spec non validée. Règle : si la spec dépasse une page, c’est que la tâche doit être découpée.
La spec figée
La spec est un point de départ, pas un contrat gravé dans le marbre. Si l’agent découvre une contrainte technique imprévue, la spec doit évoluer. Traiter la spec comme immuable crée des frictions inutiles.
La spec sans tests
Une spec dont les critères d’acceptation ne sont jamais transformés en tests reste une déclaration d’intention. Sans tests, la boucle de vérification est ouverte — l’agent ne peut pas confirmer automatiquement qu’il respecte la spec.
Remonte relire la fiche memo ci-dessus en pretant attention aux points rates, puis clique sur « Recommencer » pour retenter.