Apprenez à définir la portée des tâches avec Claude Code pour transformer des demandes floues en critères d'acceptation clairs, un plan UI/API minimal et quelques petits commits.
Une demande vague semble anodine : « Améliorer la recherche », « Rendre l'onboarding plus fluide », « Les utilisateurs ont besoin de notifications. » Dans les équipes réelles, elle arrive souvent comme un message d'une ligne dans le chat, une capture d'écran avec des flèches, ou un appel client à moitié reconstitué. Tout le monde est d'accord, mais chacun imagine quelque chose de différent.
Le coût apparaît plus tard. Quand la portée est floue, les gens construisent à partir d'hypothèses. La première démo se transforme en un nouveau cycle de clarifications : « Ce n'est pas ce que je voulais dire. » Le travail est refait, et la fonctionnalité grandit discrètement. Des ajustements de design entraînent des changements de code, qui entraînent plus de tests. Les revues ralentissent parce qu'une modification floue est difficile à vérifier. Si personne ne peut définir à quoi ressemble le « correct », les relecteurs débattent du comportement au lieu de vérifier la qualité.
On repère généralement une tâche vague tôt :
Une tâche bien cadrée donne à l'équipe une ligne d'arrivée : des critères d'acceptation clairs, un plan UI et API minimal, et des limites explicites sur ce qui n'est pas inclus. C'est la différence entre « améliorer la recherche » et un petit changement facile à construire et à relire.
Une habitude pratique : séparer la « définition de fait » des « nice-to-have ». « Fait » est une courte liste de vérifications que vous pouvez exécuter (par exemple : « La recherche retourne des résultats par titre, affiche “Aucun résultat” si vide, et garde la requête dans l'URL »). Les « nice-to-have » sont tout ce qui peut attendre (synonymes, ajustements de ranking, mise en surbrillance, analytics). Les étiqueter dès le départ évite une croissance de périmètre non souhaitée.
Les demandes vagues commencent souvent par des solutions proposées : « Ajouter un bouton », « Passer à un nouveau flux », « Utiliser un modèle différent ». Faites une pause et traduisez la suggestion en résultat d'abord.
Un format simple aide : « En tant que [utilisateur], je veux [faire quelque chose], afin de [atteindre un objectif]. » Restez clair. Si vous ne pouvez pas le dire en une seule phrase, c'est encore trop flou.
Ensuite, décrivez ce qui change pour l'utilisateur quand c'est terminé. Concentrez-vous sur le comportement visible, pas sur les détails d'implémentation. Par exemple : « Après avoir soumis le formulaire, je vois une confirmation et je peux retrouver l'enregistrement dans la liste. » Cela crée une ligne d'arrivée claire et rend plus difficile l'ajout furtif de « juste un petit ajustement ».
Écrivez aussi ce qui reste inchangé. Les non-objectifs protègent votre portée. Si la demande est « améliorer l'onboarding », un non-objectif peut être « pas de refonte du dashboard » ou « pas de changement de logique de niveau tarifaire ».
Enfin, choisissez un chemin principal à supporter en premier : la tranche end-to-end qui prouve que la fonctionnalité marche.
Exemple : au lieu de « ajouter des snapshots partout », écrivez : « En tant que propriétaire de projet, je peux restaurer le dernier snapshot de mon application, afin d'annuler une mauvaise modification. » Non-objectifs : « pas de restauration en masse, pas de refonte UI. »
Une demande vague manque rarement d'effort. Elle manque de décisions.
Commencez par les contraintes qui changent discrètement la portée. Les délais comptent, mais aussi les règles d'accès et les besoins de conformité. Si vous construisez sur une plateforme avec des paliers et des rôles, décidez tôt qui obtient la fonctionnalité et sous quel plan.
Ensuite, demandez un exemple concret. Une capture d'écran, le comportement d'un concurrent, ou un ticket antérieur révèle ce que « mieux » veut dire réellement. Si le demandeur n'en a pas, demandez-lui de rejouer la dernière fois où il a senti la douleur : quel écran, sur quoi a-t-il cliqué, qu'attendait-il ?
Les cas limites sont là où la portée explose, alors nommez les principaux tôt : données vides, erreurs de validation, appels réseau lents ou échoués, et ce que signifie vraiment « annuler ».
Enfin, décidez comment vous vérifierez le succès. Sans résultat testable, la tâche devient une suite d'opinions.
Ces cinq questions lèvent la plupart des ambiguïtés :
Exemple : « Ajouter des domaines personnalisés pour des clients » devient plus clair une fois que vous décidez à quel palier cela appartient, qui peut le configurer, si la localisation d'hébergement a un impact sur la conformité, quel message d'erreur afficher pour un DNS invalide, et ce que « fini » signifie (domaine vérifié, HTTPS actif, et plan de rollback sûr).
Les demandes brouillon mélangent objectifs, suppositions et cas limites à moitié rappelés. Le travail consiste à transformer cela en énoncés que n'importe qui peut tester sans lire vos pensées. Les mêmes critères doivent guider le design, le code, la revue et la QA.
Un modèle simple garde la clarté. Vous pouvez utiliser Given/When/Then, ou de courtes puces qui disent la même chose.
Rédigez chaque critère comme un seul test qu'une personne pourrait exécuter :
Appliquez-le. Supposons que la note dise : « Rendre les snapshots plus faciles. Je veux pouvoir revenir en arrière si le dernier changement casse tout. » Transformez cela en énoncés testables :
Si la QA peut exécuter ces vérifications et que les relecteurs peuvent les vérifier dans l'UI et les logs, vous êtes prêt à planifier le travail UI et API et à le diviser en petits commits.
Un plan UI minimal est une promesse : le plus petit changement visible qui prouve que la fonctionnalité marche.
Commencez par nommer les écrans qui vont changer et ce qu'une personne remarquera en 10 secondes. Si la demande dit « rendre plus simple » ou « nettoyer », déclinez cela en un changement concret que vous pouvez montrer.
Rédigez-le comme une petite carte, pas une refonte. Par exemple : « Page Commandes : ajouter une barre de filtres au-dessus du tableau », ou « Paramètres : ajouter un nouveau toggle sous Notifications ». Si vous ne pouvez pas nommer l'écran et l'élément exact qui change, la portée est encore floue.
La plupart des changements UI ont besoin de quelques états prévisibles. Énoncez uniquement ceux qui s'appliquent :
Le contenu UI fait partie de la portée. Capturez les libellés et messages qui doivent être approuvés : texte des boutons, labels de champ, texte d'aide et messages d'erreur. Si le wording est encore ouvert, notez-le comme texte temporaire et indiquez qui le confirmera.
Gardez une petite note « pas maintenant » pour tout ce qui n'est pas requis pour utiliser la fonctionnalité (polish responsive, tris avancés, animations, nouvelles icônes).
Une tâche cadrée a besoin d'un petit contrat clair entre UI, backend et données. Le but n'est pas de concevoir tout le système, mais de définir l'ensemble minimal de requêtes et de champs qui prouvent la fonctionnalité.
Commencez par lister les données nécessaires et leur origine : champs existants que vous pouvez lire, nouveaux champs à stocker, et valeurs que vous pouvez calculer. Si vous ne pouvez pas nommer la source de chaque champ, vous n'avez pas encore de plan.
Gardez la surface API petite. Pour de nombreuses fonctionnalités, une lecture et une écriture suffisent :
GET /items/{id} renvoie l'état nécessaire pour rendre l'écranPOST /items/{id}/update accepte uniquement ce que l'utilisateur peut changer et renvoie l'état mis à jourÉcrivez entrées et sorties comme des objets simples, pas des paragraphes. Indiquez champs requis vs optionnels, et que se passe-t-il sur erreurs courantes (not found, validation failed).
Faites rapidement un passage auth avant de toucher la base. Décidez qui peut lire et qui peut écrire, et énoncez la règle en une phrase (par exemple : « tout utilisateur connecté peut lire, seuls les admins peuvent écrire »). Omettre cela mène souvent à des retours en arrière.
Enfin, décidez ce qu'il faut stocker et ce qui peut être calculé. Règle simple : stockez des faits, calculez des vues.
Claude Code fonctionne mieux quand vous lui donnez une cible claire et une boîte étroite. Commencez par coller la demande brouillon et toutes contraintes (date limite, utilisateurs concernés, règles de données). Puis demandez une sortie cadrée qui inclut :
Après sa réponse, lisez-la comme un relecteur. Si vous voyez des phrases comme « améliorer les performances » ou « rendre plus propre », demandez un libellé mesurable.
Demande : « Ajouter un moyen de mettre une subscription en pause. »
Une version cadrée pourrait dire : « L'utilisateur peut mettre en pause pour 1 à 3 mois ; la prochaine date de facturation se met à jour ; l'admin peut voir le statut de pause », et hors-scope : « pas de changement de prorata ».
À partir de là, le plan de commits devient pratique : un commit pour la DB et la forme API, un pour les contrôles UI, un pour la validation et les états d'erreur, un pour les tests end-to-end.
Les gros changements cachent des bugs. Les petits commits accélèrent les revues, rendent les rollbacks plus sûrs et aident à détecter quand vous vous éloignez des critères.
Règle utile : chaque commit doit débloquer un nouveau comportement, et inclure un moyen rapide de le prouver.
Une séquence courante ressemble à ceci :
Gardez chaque commit focalisé. Évitez les refactors « tant que j'y suis ». Gardez l'application fonctionnelle de bout en bout, même si l'UI est basique. Ne regroupez pas migrations, comportement et UI dans un seul commit sauf raison forte.
Un demandeur dit : « Peut-on ajouter Export reports ? » Ça cache beaucoup de choix : quel rapport, quel format, qui peut exporter, comment la livraison fonctionne.
Posez seulement les questions qui changent le design :
Supposons les réponses : « Sales Summary, CSV seulement, rôle manager, téléchargement direct, dernier 90 jours max. » La v1 devient concrète : les managers peuvent cliquer sur Export sur la page Sales Summary ; le CSV correspond aux colonnes du tableau ; l'export respecte les filtres ; exporter sur plus de 90 jours affiche une erreur claire ; le téléchargement se termine en moins de 30 secondes pour jusqu'à 50k lignes.
Plan UI minimal : un bouton Export près des actions du tableau, un état de chargement pendant la génération, et un message d'erreur indiquant comment corriger le problème (par ex. « Choisissez 90 jours ou moins »).
Plan API minimal : un endpoint qui prend les filtres et renvoie un CSV généré en réponse fichier, en réutilisant la même requête que le tableau tout en appliquant la règle 90 jours côté serveur.
Ensuite, livrez en quelques commits serrés : d'abord l'endpoint pour le chemin heureux fixe, puis la liaison UI, ensuite la validation et les erreurs côté utilisateur, puis tests et documentation.
Des demandes comme « ajouter des rôles d'équipe » cachent souvent des règles sur l'invitation, l'édition et ce qu'il advient des utilisateurs existants. Si vous vous surprenez à deviner, écrivez l'hypothèse et transformez-la en question ou en règle explicite.
Les équipes perdent des jours quand une tâche inclut à la fois « faire marcher » et « rendre joli ». Gardez la première tâche centrée sur le comportement et les données. Mettez le style, les animations et l'espacement dans une tâche suivante sauf si c'est nécessaire pour utiliser la fonctionnalité.
Les cas limites comptent, mais pas tous doivent être résolus immédiatement. Gérez ceux qui peuvent briser la confiance (double soumission, éditions conflictuelles) et différez le reste avec des notes claires.
Si vous ne les notez pas, vous les oublierez. Incluez au moins un chemin malheureux et au moins une règle de permission dans vos critères d'acceptation.
Évitez « rapide » ou « intuitif » sans chiffre ou vérification concrète. Remplacez-les par quelque chose que vous pouvez prouver en revue.
Verrouillez la tâche pour qu'un coéquipier puisse relire et tester sans lecture de pensée :
Exemple : « Ajouter des recherches enregistrées » devient « Les utilisateurs peuvent sauvegarder un filtre et le réappliquer plus tard », avec non-objectifs comme « pas de partage » et « pas de changement des tris ».
Une fois la tâche cadrée, protégez-la. Avant de coder, faites une revue rapide de sens commun avec les personnes qui ont demandé le changement :
Puis placez les critères là où le travail se passe : dans le ticket, dans la description de la PR, et partout où votre équipe regarde réellement.
Si vous construisez sur Koder.ai (koder.ai), il aide à verrouiller d'abord le plan puis à générer le code à partir de celui-ci. Planning Mode convient bien à ce flux, et les instantanés et la restauration permettent de garder les expériences sûres lorsque vous devez tenter une approche puis revenir en arrière.
Quand de nouvelles idées surgissent en plein développement, gardez la portée stable : notez-les pour un suivi, marquez-les pour re-cadrage si elles changent les critères, et gardez les commits liés à un seul critère à la fois.
Commencez par écrire le résultat en une phrase (ce que l'utilisateur pourra faire quand ce sera fini), puis ajoutez 3–7 critères d'acceptation que le testeur pourra vérifier.
Si vous ne pouvez pas décrire le comportement « correct » sans débat, la tâche est encore trop vague.
Utilisez ce format rapide :
Ajoutez ensuite un exemple concret du comportement attendu. Si vous ne pouvez pas donner d'exemple, rejouez la dernière fois où le problème est survenu et notez ce que l'utilisateur a cliqué et ce qu'il s'attendait à voir.
Rédigez d'abord une courte liste « Définition de fait » (les vérifications qui doivent réussir), puis une liste séparée « Nice-to-have ».
Règle par défaut : si ce n'est pas nécessaire pour prouver que la fonctionnalité fonctionne de bout en bout, c'est dans les nice-to-have.
Posez les quelques questions qui changent la portée :
Ces questions forcent les décisions manquantes à être explicites.
Considérez les cas limites comme des éléments de portée, pas des surprises. Pour la v1, couvrez ceux qui brisent la confiance :
Tout le reste peut être explicitement différé comme hors-scope.
Utilisez des déclarations testables que n'importe qui peut exécuter sans deviner :
Incluez au moins un cas d'échec et une règle de permission. Si un critère ne peut pas être testé, réécrivez-le jusqu'à ce qu'il le puisse.
Nommez les écrans exacts et le changement visible unique par écran.
Listez aussi les états UI requis :
Pensez aussi au texte (boutons, erreurs) même s'il s'agit de placeholders.
Gardez le contrat petit : une lecture et une écriture suffisent souvent pour la v1.
Définissez :
Stockez des faits ; calculez les vues quand c'est possible.
Demandez une livraison encadrée :
Puis reformulez toute expression vague comme « améliorer » en comportement mesurable.
Séquence par défaut :
Règle : un commit = un nouveau comportement visible + une façon rapide de le prouver. Évitez d'inclure des refactors « tant que j'y suis ».