Spécifier avant de déléguer

En chantier Cette section est en cours d'écriture : ce guide est lisible mais pas encore finalisé, son contenu peut évoluer.

Les Fondamentaux l’ont posé : un prompt est une spécification, et tout ce qu’elle ne dit pas sera comblé par la moyenne du corpus.

Avec un agent, la règle change d’échelle. Vous ne demandez plus une réponse à relire, vous déléguez une tâche à une boucle qui agit. Une ambiguïté ne produit plus une mauvaise réponse : elle produit une exécution complète, cohérente et convaincue du malentendu.

La qualité de la sortie ne dépasse jamais la qualité de la demande. Spécifier est la compétence ; prompter n’en est que la surface. Ce guide montre comment transformer une intention en demande qu’un agent peut exécuter sans la déformer.

Une ambiguïté qui s’exécute

En chat, une demande floue coûtait une réponse à jeter. La boucle agentique change l’arithmétique : chaque blanc de votre demande est comblé par la continuation la plus probable, et chaque blanc comblé devient le socle de l’itération suivante. L’agent n’exécute pas votre intention, il exécute son interprétation. Puis il bâtit dessus, appel d’outil après appel d’outil, avec une cohérence parfaite. Au bout : un diff de huit cents lignes, plausible, soigné, et à côté.

L’asymétrie des coûts en découle. Dix minutes passées à fermer une spécification se voient ; elles ressemblent à du sur-place quand l’agent pourrait « déjà être en train ». L’alternative, elle, ne se voit qu’après : relire un grand diff convaincant pour y traquer le malentendu, ou le jeter. Le travail de spécification n’a pas disparu avec la délégation. Il s’est déplacé avant l’exécution, au seul endroit où l’erreur coûte zéro ligne de code.

Et le blanc le plus coûteux n’est pas dans le contenu de la tâche : c’est la condition de fin. Le guide 01 l’a établi, la boucle converge vers ce que vos outils vérifient. Une demande sans critère de fin vérifiable laisse l’agent décider lui-même quand c’est terminé. Et un modèle optimise la vraisemblance, y compris celle d’un rapport de succès.

L’anatomie d’une demande exécutable

Les Fondamentaux ont donné la grammaire (objectif, contraintes, périmètre) ; la délégation y ajoute ses exigences propres.

L’objectif, en comportement observable. « Améliore la gestion d’erreurs » est une intention. « Toute réponse 5xx de l’API amont doit être réessayée deux fois puis journalisée avec son corps » est une spécification qu’une boucle peut atteindre et que vous pouvez vérifier.
Le périmètre, fermé en négatif. Les agents débordent par défaut : l’enthousiasme statistique du corpus penche vers « refactorer au passage ». Ce qui ne doit pas bouger se dit explicitement : pas de nouvelle dépendance, pas de changement de schéma, uniquement ce module.
Les critères d’acceptation, comme conditions de sortie de la boucle. Chaque critère que l’agent peut exécuter lui-même (« npm run build passe », « ce test, écrit d’abord, passe au vert ») transforme la délégation en boucle qui converge sans vous. Chaque critère que vous seul pouvez juger marque l’endroit où la session devra s’arrêter et vous attendre. Distinguer les deux dès la demande, c’est dessiner les points de rendez-vous de la session.

La spécification a aussi une frontière : elle dit ce qui doit changer ; le dossier de contexte dit ce qui est vrai et interdit en tout temps. Si vous recopiez vos conventions dans chaque demande, ce n’est pas de la rigueur. C’est un bug du dossier, à corriger là-bas, une fois pour toutes les sessions.

Calibrer l’effort de spécification

Tout ne mérite pas une spécification écrite. L’exiger partout produit de la bureaucratie, puis de la triche. Mon critère de calibrage, c’est le coût du malentendu, produit de trois facteurs : la taille du diff attendu, sa réversibilité, et l’écart entre ce que vous voulez et ce que ferait la moyenne du corpus.

Une tâche petite, réversible et conventionnelle se délègue en une phrase : l’agent comblera les blancs avec la moyenne, et la moyenne vous convient. Dès que la tâche touche ce qui fait la singularité de votre projet (vos déviations délibérées, vos invariants), chaque écart à la moyenne doit être écrit, faute de quoi il sera « corrigé ». Et une tâche structurante ou difficile à défaire mérite l’arsenal complet : spécification écrite, puis plan validé avant exécution.

Le calibrage rend aussi un verdict utile dans l’autre sens. Si vous n’arrivez pas à écrire le critère d’acceptation, le problème n’est pas votre formulation : c’est que la tâche n’est pas claire pour vous non plus. Ne déléguez pas un flou. Découpez jusqu’à la première sous-tâche dont la fin se décrit, et commencez là.

Le plan : exécuter le malentendu à blanc

Pour les tâches structurantes, intercalez un artefact entre l’intention et le code : le plan. La plupart des harnais offrent un mode dédié (agent en lecture seule, qui explore et propose sans rien toucher), mais la pratique ne dépend pas de la fonctionnalité : « propose un plan, n’écris rien pour l’instant » l’obtient partout. Le plan est le détecteur de malentendu le moins cher qui existe. L’interprétation de l’agent devient visible avant d’être exécutée.

Un plan se relit comme une revue de conception, pas comme de la prose. Quels fichiers, dans quel ordre, quelle stratégie de vérification ? Et surtout : qu’est-ce qui manque ? Les tests dont il ne parle pas, le module que vous pensiez central et qu’il ignore, la migration qu’il ne mentionne nulle part. Ce sont les malentendus que vous payerez dans le diff.

Le plan travaille aussi dans l’autre sens. L’agent vient d’explorer votre repo, il est bien placé pour interroger votre intention. Demandez-lui de poser ses questions avant de proposer : chaque question révèle un point que votre demande laissait à sa discrétion, et chaque réponse rejoint la spécification.

Le tips Craftomancer

Un plan approuvé en diagonale est un chèque en blanc. Valider engage : à partir de là, l’agent traite chaque point du plan comme une consigne de votre main, et exécutera avec le même aplomb le point que vous n’avez pas lu. Le plan est le seul moment où le malentendu coûte zéro ligne de code. Dépensez-y l’attention que vous comptez économiser sur le diff, et lisez d’abord ce que le plan ne dit pas.

La spécification est un artefact, pas un message

Une spécification qui ne vit que dans le fil de la session meurt avec elle. Écrivez-la dans un support persistant (ticket, fichier de travail dans le repo, peu importe), pour trois raisons mécaniques :

Elle survit au redémarrage. Les longues sessions diluent l’attention, et le guide 01 concluait : redémarrez plutôt que d’insister. Repartir d’une session vierge ne coûte presque rien quand la spécification est un fichier à recharger. Ça coûte toute la négociation quand elle est éparpillée dans quarante tours de conversation.
Elle se relit et se partage. Un collègue (ou vous dans deux semaines) peut auditer ce qui a été demandé, pas seulement ce qui a été produit. La description de la PR est déjà à moitié écrite.
Elle s’amende explicitement. Le périmètre bougera en cours de tâche. Quand il bouge, c’est le document qu’on corrige, pas une consigne de plus empilée dans le contexte par-dessus celles qu’elle contredit.

Dernier réflexe : quand une exigence revient de spécification en spécification, elle demande sa promotion. C’est une convention, plus une consigne. Sa place est dans le dossier de contexte, payée une fois pour toutes les sessions à venir.

En pratique

Calibrez l’effort de spécification sur le coût du malentendu : taille du diff attendu, réversibilité, écart entre votre projet et la moyenne du corpus.
Donnez toujours une condition de fin vérifiable. Sans elle, c’est l’agent qui décide quand c’est fini.
Fermez le périmètre en négatif : ce qui ne doit pas bouger se dit explicitement.
Pour les tâches structurantes, exigez un plan avant le code, faites poser les questions, et lisez ce que le plan ne dit pas avant de valider.
Persistez la spécification hors de la session : elle survit aux redémarrages, se relit, et nourrit le dossier de contexte quand une exigence se répète.
Si le critère d’acceptation refuse de s’écrire, ne déléguez pas encore : découpez jusqu’à une fin descriptible.

La demande est posée ; reste à tenir la barre pendant qu’elle s’exécute. Prochaine étape : conduire la session. Lire ce que fait l’agent, corriger tôt, et savoir quand redémarrer.