De la spec au commit
- arrow_forwardcapable de rédiger une spec exploitable par un agent (contexte, objectif, contraintes, critère de succès)
- arrow_forwardcapable de suivre le cycle complet spec→agent→diff→commit sans raccourcis
De la spec au commit
Le cycle de livraison AI-first ne commence pas avec un prompt. Il commence avec une spec. La différence entre un agent qui produit du code utilisable et un agent qui produit du bruit tient presque entièrement à la qualité de ce que vous lui donnez.
Les quatre composantes d'une spec agent-ready
Une spec utilisable par un agent contient exactement quatre choses :
- Contexte — Où se situe cette tâche dans la codebase ? Quel fichier, quel module, quelle couche d'architecture ? Quelles sont les conventions déjà en place ?
- Objectif — Qu'est-ce qui doit exister ou fonctionner différemment une fois la tâche accomplie ?
- Contraintes — Ce que l'agent ne doit pas faire. Nouvelles dépendances interdites. Pattern existant à respecter. Périmètre de fichiers limité.
- Critère de succès — Comment sait-on que c'est fini ? Un test qui passe ? Un endpoint qui répond avec le bon statut ? Un comportement observable ?
Une spec est agent-ready quand un développeur junior pourrait l'implémenter sans poser de question. Si vous devez expliquer oralement ce que vous voulez dire, la spec est incomplète.
Avant / Après : le même besoin, deux specs
Spec faible (résultat : code incohérent, dépendances inattendues) :
"Ajoute un système de cache pour les requêtes utilisateur."
Spec agent-ready :
Contexte : Le service
src/services/userService.tsappelledb.query()à chaque requête. Il n'existe pas encore de cache dans ce layer. Nous utilisonsnode-cachedanssrc/services/productService.ts(voir ce fichier pour le pattern).Objectif : Ajouter un cache en mémoire sur la méthode
getUserById(id: string)avec un TTL de 300 secondes.Contraintes : Utiliser
node-cacheuniquement (déjà installé). Ne pas modifier les types ou l'interface publique du service. Ne pas toucher aux autres méthodes.Critère de succès : Deux appels consécutifs à
getUserByIdavec le mêmeidne déclenchent qu'une seule requête DB. Un test unitaire le vérifie.
Le cycle complet
Voici le seul ordre acceptable :
- Écrire la spec (cf. les quatre composantes)
- Donner la spec à l'agent (Claude Code, Cursor, peu importe)
- Lire le diff produit ligne par ligne
- Poser des questions à l'agent sur les parties incomprises
- Committer uniquement si vous comprenez et acceptez chaque changement
Committer sans avoir lu le diff, c'est fusionner du code que vous n'avez pas écrit et que vous ne comprenez pas. Quand ce code casse en production, vous ne savez pas pourquoi. Le diff est votre dernier point de contrôle — ne le sautez jamais.
Ce que "lire le diff" signifie concrètement
Lire le diff ne signifie pas parcourir les lignes vertes en diagonale. Cela signifie :
- Comprendre pourquoi chaque fichier a été modifié
- Vérifier que les contraintes ont été respectées (aucune dépendance ajoutée ? le périmètre est respecté ?)
- Identifier les effets de bord potentiels (une fonction renommée ? une signature modifiée ?)
- Confirmer que le critère de succès est atteignable avec ce code
Si quelque chose est opaque, demandez à l'agent de l'expliquer avant de valider.
Prenez la prochaine tâche sur votre backlog. Avant de l'envoyer à un agent, rédigez-la selon les quatre composantes (contexte, objectif, contraintes, critère de succès). Comparez le résultat avec vos specs habituelles. Notez ce qui manquait.
Vérifiez votre compréhension
3 questions · répondez puis validez.