DotMDComment relire une spec écrite par une IA :une checklist avant que l’agent ne construise.
Un agent IA écrit en une minute une spec assurée et propre. C’est le danger : elle se lit bien même quand elle est fausse. Cette checklist montre quoi chercher avant de dire à l’agent de commencer à construire.
macOS 14 ou ultérieur. La lecture est gratuite ; l’édition et les relectures se paient en une fois.
Réponse rapide
Relisez une spec écrite par une IA comme vous relisez une pull request : vérifiez qu’elle résout le bon problème, puis cherchez ce qui manque. Parcourez le périmètre et le hors périmètre, les cas limites, les données et migrations, les tests et le retour arrière, et laissez un commentaire sur chaque passage à changer avant que l’agent n’écrive du code.
- [ ] Scope matches what I asked for
- [ ] Non-goals are listed
- [ ] Edge cases and errors are covered
- [ ] Data and migrations are explicit
- [ ] Tests prove each requirement
- [ ] There is a rollback·
Pourquoi les specs IA demandent un autre type de revue
Une personne qui rédige une spec laisse en général des trous là où elle n’est pas sûre. Un modèle écrit un texte fluide pour tout, y compris pour les parties qu’il a devinées. Les signes habituels d’une spec faible, formulations floues et trous évidents, sont donc absents, et les problèmes se cachent dans des phrases assurées. Relisez en cherchant ce qu’un bon auteur aurait demandé.
La checklist
-
Périmètre : résout-elle ce que vous avez demandé ?
Comparez le premier paragraphe avec votre demande. Cherchez un autre problème résolu et des fonctionnalités que personne n’a demandées.
-
Hors périmètre : que ne fera-t-elle pas ?
Une spec sans hors périmètre n’a pas de bord. Ajoutez les extras dont vous ne voulez pas.
-
Hypothèses : qu’a-t-elle deviné ?
Cherchez « probablement », « vraisemblablement » et tout ce qui est affirmé comme un fait sur du code ou des données qu’elle n’a peut-être pas lus. Demandez-lui de citer les fichiers.
-
Cas limites : que se passe-t-il quand ça tourne mal ?
Entrée vide, entrée très grande, pas d’autorisation, pas de réseau, deux utilisateurs en même temps, la même action deux fois.
-
Données : qu’est-ce qui est stocké, modifié ou supprimé ?
Les champs, les formats, qui peut les lire, et ce qui arrive aux enregistrements existants.
-
Migrations : comment les anciennes données migrent-elles ?
Un changement de schéma demande un ordre d’étapes, un plan en cas d’échec à mi-chemin et un moyen de l’exécuter deux fois sans risque.
-
Interfaces : qu’est-ce qui est touché d’autre ?
API, écrans, tâches planifiées, code d’autres équipes. Tout ce que la spec change sans le lister est une surprise plus tard.
-
Sécurité et confidentialité : qui peut faire quoi ?
Nouvelles autorisations, nouvelles données qui quittent le système, secrets dans les journaux.
-
Tests : comment saurez-vous que ça marche ?
Chaque exigence doit correspondre à une vérification. Si une exigence ne peut pas être testée, réécrivez-la.
-
Déploiement et retour arrière : comment l’annuler ?
Un drapeau, un déploiement progressif, un chemin de retour. « On corrigera en avançant » n’est pas un plan.
-
Questions ouvertes : qui les tranche ?
Une spec honnête liste ce qu’elle ne sait pas. S’il n’y en a aucune, méfiez-vous.
Un commentaire qui fonctionne
Un retour vague donne une réécriture vague. Un bon commentaire de revue désigne un passage, dit ce qui ne va pas et ce que vous voulez à la place :
> The export runs when the user taps Export.
Missing: what happens with a 2 GB file? Add a limit (R4) and an
error message, and say whether the export can be cancelled.Gardez les commentaires séparés du texte de la spec pour que le fichier reste propre, et groupez-les : lisez toute la spec une fois, puis commentez, pour que l’agent réécrive une fois plutôt que dix.
La boucle de revue
-
Lisez-la d’abord de bout en bout
Avant de commenter, assurez-vous d’avoir compris tout le plan.
-
Commentez les passages exacts
Un problème par commentaire.
-
Laissez l’agent réviser
Il corrige chaque commentaire et produit une nouvelle version.
-
Vérifiez ce qui a changé, pas tout le document
Lisez les différences. Une correction peut casser ce qui allait bien.
-
N’approuvez que quand la checklist est propre
Laissez-le alors construire, selon les exigences numérotées.
La même checklist marche quand un agent relit la spec d’un autre. Demandez au relecteur de répondre à chaque point par une citation de la spec.
Le faire dans DotMD
Tout cela se fait sur la page. Dans DotMD, vous sélectionnez le passage et écrivez un commentaire dessus ; les commentaires sont conservés dans DotMD, pas dans le fichier. L’agent les corrige et renvoie le document, et relire les changements montre l’ancien texte en rouge et le nouveau en vert pour que vous les acceptiez un par un. La mise en place est décrite dans relire des specs IA. La lecture est gratuite ; voir les tarifs pour les revues.
Erreurs courantes
- Relire le style, pas le fond. Une spec soignée peut quand même être fausse.
- Approuver parce qu’elle est longue. La longueur n’est pas la couverture.
- Sauter le hors périmètre et le retour arrière, les deux sections que les modèles laissent le plus souvent minces.
- Corriger le code au lieu de la spec. Si le plan est faux, corrigez-le d’abord.
- Pas de second regard. Une fois l’agent passé, vérifiez le diff.
Questions sur la relecture de specs écrites par une IA
Comment relire une spec écrite par une IA ?
Vérifiez qu’elle résout le bon problème, puis cherchez ce qui manque : hors périmètre, cas limites, données et migrations, tests et retour arrière. Commentez chaque passage et faites réviser l’agent avant qu’il n’écrive du code.
Que doit contenir une checklist de revue de spec ?
Le périmètre, le hors périmètre, les hypothèses, les cas limites, les données, les migrations, les interfaces, la sécurité, les tests, le déploiement et le retour arrière, et les questions ouvertes.
Un agent IA peut-il relire la spec d’un autre agent ?
Oui. Donnez la checklist au relecteur et demandez-lui de répondre à chaque point par une citation de la spec. C’est toujours vous qui décidez de ce que vous acceptez.
Pourquoi ne pas simplement lire le code ?
À ce stade, les décisions sont prises et coûteuses à changer. Une hypothèse fausse se corrige au moindre coût dans la spec.