Définir la portée des tâches avec Claude Code : des demandes vagues aux commits

Pourquoi les demandes vagues font perdre du temps

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 :

• Pas d'exemple pas-à-pas de ce que l'utilisateur doit pouvoir faire
• Pas de cas limites (états vides, permissions, erreurs)
• Du travail « au cas où » qui enfle en une grosse PR
• Des commentaires de revue qui discutent du comportement, pas de l'implémentation
• « On verra au fur et à mesure » devient le plan

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.

Partir du résultat, pas de la solution

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. »

Posez les quelques questions qui lèvent l'ambiguïté

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 :

• Qui y a accès (palier et rôles) ?
• Quelle est la date limite, et quelle est la version la plus petite acceptable ?
• Quel est un exemple du comportement attendu ?
• Que se passe-t-il en cas d'état vide, d'erreurs et de connexions lentes ?
• Comment confirmerons-nous que ça marche (critères ou métrique) ?

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).

Convertir des notes brouillon en critères d'acceptation

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.

Un modèle rapide de critères d'acceptation

Rédigez chaque critère comme un seul test qu'une personne pourrait exécuter :

• Étant donné un état de départ, quand l'utilisateur fait X, alors Y se produit.
• Incluez les règles de validation (quelles saisies sont autorisées).
• Incluez au moins un cas d'échec (quel message d'erreur l'utilisateur voit).
• Définissez le « signal de fait » (ce que la QA vérifie, ce que les relecteurs attendent).

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 :

• Étant donné un projet avec 2 snapshots, quand j'ouvre Snapshots, alors je vois les deux avec l'heure et un court libellé.
• Étant donné un snapshot, quand je clique sur Restaurer et confirme, alors le projet revient à ce snapshot et l'application se reconstruit avec succès.
• Étant donné que je ne suis pas le propriétaire du projet, quand j'essaie de restaurer, alors je vois une erreur et rien ne change.
• Étant donné qu'une restauration est en cours, quand je rafraîchis la page, alors je peux toujours voir le statut et le résultat final.
• Étant donné qu'une restauration échoue, quand elle s'arrête, alors je vois un message clair et la version actuelle reste active.

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.

Rédiger un plan UI minimal

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.

Définir les états UI clés

La plupart des changements UI ont besoin de quelques états prévisibles. Énoncez uniquement ceux qui s'appliquent :

• Chargement
• Vide
• Erreur (et si un retry existe)
• Succès (toast, message inline, liste mise à jour)

Confirmer les textes visibles

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).

Rédiger un plan API et données minimal

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'écran
• POST /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.

Utiliser Claude Code pour produire une tâche cadrée

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 :

1. Une reformulation en langage courant de la portée et une courte checklist de critères d'acceptation.
2. Une petite séquence de commits (visez 3 à 7), chacun avec un résultat clair.
3. Les fichiers ou dossiers probablement modifiés par commit, et ce qui change à l'intérieur.
4. Un plan de test rapide par commit (un happy path et un cas limite).
5. Des notes explicites hors-scope.

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.

Mini-exemple (à quoi ressemble le « bien »)

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.

Diviser le travail en petits commits relisables

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 :

• Modèle de données ou migration (si besoin) plus tests
• Comportement API et validation
• Liaison UI avec états vide/erreur
• Logging ou analytics seulement si requis, puis petit polish

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.

Parcours : « Exporter des rapports »

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 :

• Quels types de rapport pour la v1 ?
• Quel format pour la v1 (CSV, PDF) ?
• Qui peut exporter (admins, rôles spécifiques) ?
• Téléchargement direct ou export par email ?
• Des limites (plage de dates max, cap de lignes, timeouts) ?

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.

Erreurs courantes de cadrage (et comment les éviter)

Des exigences cachées se glissent

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.

Le polish UI se mélange au comportement essentiel

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é.

Vous essayez de résoudre tous les cas limites en v1

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.

Les états d'erreur et permissions sont repoussés

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.

Des critères que vous ne pouvez pas vérifier

Évitez « rapide » ou « intuitif » sans chiffre ou vérification concrète. Remplacez-les par quelque chose que vous pouvez prouver en revue.

Checklist rapide avant de commencer à coder

Verrouillez la tâche pour qu'un coéquipier puisse relire et tester sans lecture de pensée :

• Résultat et non-objectifs : une phrase pour le résultat, plus 1 à 3 non-objectifs explicites.
• Critères d'acceptation : 5 à 10 vérifications testables en langage clair.
• États UI : les états minimums de chargement, vide, erreur et succès.
• Notes API et données : la forme d'endpoint la plus petite et les changements de données éventuels, plus qui peut lire et écrire.
• Plan de commits avec tests : 3 à 7 commits, chacun avec une preuve rapide.

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 ».

Étapes suivantes : garder la portée stable pendant la construction

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 :

• Lisez les critères et confirmez qu'ils correspondent au résultat.
• Confirmez permissions, états vides et comportements en cas d'échec.
• Reconfirmez ce qui est hors-scope.
• Mettez-vous d'accord sur les plus petits changements UI et API qui satisfont les critères.
• Décidez comment vous allez le démontrer et ce que signifie « fini ».

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.