Apprenez à créer des spécifications de fonctionnalités Claude Code à partir du code en extrayant le comportement réel depuis les routes et les composants, puis en produisant une spec vivante et une liste de lacunes.
Les gens ne sont pas d’accord sur ce qu’une application fait parce qu’ils se souviennent de versions différentes. le support se souvient du dernier ticket furieux. Les commerciaux se souviennent du chemin de la démo. Les ingénieurs se souviennent de ce que la fonctionnalité était censée faire. Demandez à trois personnes et vous obtiendrez trois réponses assurées, et aucune ne correspond à la version actuelle.
Avec le temps, le code devient la seule source qui reste à jour. Les docs dérivent, les tickets sont fermés, et les corrections rapides s’accumulent. Une route reçoit une nouvelle règle de validation. Un toggle UI change une valeur par défaut. Un handler commence à retourner d’autres erreurs. Personne ne met à jour la spec parce que ça semble optionnel, et chaque modification paraît trop petite pour être documentée.
Cela crée des problèmes prévisibles. Les équipes livrent des changements qui cassent des cas limites dont elles n’avaient pas connaissance. QA teste le chemin heureux et manque des règles enfouies dans les handlers. Les nouveaux collègues reproduisent le comportement depuis l’UI sans comprendre les contraintes réelles. Les parties prenantes débattent d’opinions au lieu de se référer à un comportement convenu.
Un bon résultat n’est pas un document parfait. C’est la clarté partagée. Tout le monde devrait pouvoir répondre : « Que se passe-t-il si je fais X ? » et « Qu’est-ce que le système garantit ? » sans deviner. Vous avez moins de surprises, des cycles de revue plus courts, et moins de moments « Attendez, il le fait déjà » parce que l’équipe regarde la même vérité.
Quand une spec correspond au code, il devient sûr de planifier des changements. Vous pouvez repérer ce qui est stable, ce qui est accidentel et ce qui manque avant de livrer.
Une spec vivante est une description courte et modifiable de ce que l’app fait réellement aujourd’hui. Ce n’est pas un document ponctuel. Elle change chaque fois que le comportement change, afin que l’équipe puisse lui faire confiance.
Quand on parle de specs de fonctionnalité écrites à partir du code (par exemple, en utilisant Claude Code), l’objectif est simple : lire le comportement réel depuis les routes, handlers et écrans, puis l’écrire en langage clair.
Une spec vivante utile se concentre sur ce que les utilisateurs voient et sur ce que le système promet. Elle devrait couvrir :
Ce qu’elle ne doit pas couvrir, c’est l’organisation interne du code. Si vous commencez à nommer des fichiers et des plans de refactor, vous tombez dans les détails d’implémentation. Évitez :
Une liste de lacunes est séparée. C’est une petite liste de divergences et d’inconnues que vous trouvez en rédigeant la spec.
Exemple : une route rejette les fichiers de plus de 10 Mo, mais l’UI indique 25 Mo. C’est une lacune tant que l’équipe n’a pas décidé quelle règle est réelle et n’a pas mis à jour soit le code, soit la spec.
Commencez petit. Si vous essayez de documenter toute l’application, vous finirez avec une pile de notes en qui personne ne fait confiance. Choisissez une tranche que les utilisateurs peuvent décrire en une phrase, comme « inviter un coéquipier », « checkout » ou « réinitialiser le mot de passe ». De bons périmètres sont une zone fonctionnelle unique, un module, ou un parcours utilisateur d’un point d’entrée à un résultat.
Choisissez votre point d’entrée en fonction de l’endroit où réside la vérité :
Avant de lire le code, collectez quelques éléments d’entrée pour que les divergences sautent aux yeux : docs API existantes, anciennes notes produit, tickets support, et les « points douloureux connus » dont les gens se plaignent. Ils n’annulent pas le code, mais vous aident à remarquer les états manquants comme les erreurs, les cas limites et les permissions.
Gardez le format de la spec ennuyeux et cohérent. Les équipes s’alignent plus vite quand chaque spec se lit de la même manière.
Utilisez cette structure de façon répétée et vos specs de fonctionnalité resteront lisibles, comparables et faciles à mettre à jour.
Commencez par les points d’entrée serveur. Les routes et handlers montrent « ce que l’app fait » en termes concrets : qui peut l’appeler, ce qu’il faut envoyer, ce qu’on reçoit en retour et ce qui change dans le système.
Listez les routes dans le périmètre et cartographiez chacune à une intention utilisateur. N’écrivez pas « POST /api/orders. » Écrivez « Passer une commande » ou « Enregistrer un brouillon. » Si vous ne pouvez pas nommer l’intention en mots simples, c’est déjà une lacune de spec.
En lisant chaque handler, capturez les entrées et les règles de validation comme exigences visibles par l’utilisateur. Incluez les champs requis, les formats autorisés et les règles qui provoquent de vraies erreurs. Par exemple : « L’email doit être valide », « La quantité doit être au moins 1 », « La date de début ne peut pas être dans le passé. »
Documentez les vérifications d’auth et de rôle de la même manière. Au lieu de « middleware: requireAdmin », notez : « Seuls les admins peuvent annuler n’importe quelle commande. Les utilisateurs réguliers ne peuvent annuler que leur propre commande dans les 10 minutes. » Si le code vérifie la propriété, des feature flags ou des limites par tenant, incluez-les aussi.
Puis notez les sorties et les résultats. Que renvoie le succès (un ID créé, un objet mis à jour) ? À quoi ressemblent les échecs courants (401 non connecté, 403 non autorisé, 404 introuvable, 409 conflit, 422 erreur de validation) ?
Enfin, enregistrez les effets de bord car ils font partie du comportement : enregistrements créés ou mis à jour, emails ou notifications envoyés, événements publiés, jobs en arrière-plan en file, et tout ce qui déclenche d’autres flux. Ces détails évitent les surprises quand les équipes s’appuient sur la spec plus tard.
Les routes vous disent ce que l’app peut faire. Les composants vous disent ce que les utilisateurs vivent réellement. Considérez l’UI comme une partie du contrat : ce qui s’affiche, ce qui est bloqué, et ce qui arrive quand ça tourne mal.
Commencez par trouver les écrans d’entrée de la fonctionnalité. Cherchez le composant de page, l’habillage (layout) et quelques composants « décision » qui contrôlent le fetching, les permissions et la navigation. C’est généralement là que le vrai comportement vit.
En lisant les composants, capturez les règles que les utilisateurs ressentent : quand les actions sont désactivées, étapes requises, champs conditionnels, états de chargement, et comment les erreurs apparaissent (erreurs de champ inline vs toast, retentative automatique, boutons « réessayer »). Notez aussi le comportement d’état et de cache comme les données périmées affichées d’abord, les mises à jour optimistes, ou les timestamps « dernier enregistrement ».
Recherchez les flux cachés qui changent silencieusement ce que voit l’utilisateur. Cherchez les feature flags, les buckets d’expériences et les accès réservés aux admins. Notez aussi les redirections silencieuses, comme renvoyer les utilisateurs non connectés vers la connexion ou envoyer les utilisateurs sans accès vers un écran de mise à niveau.
Un exemple concret : sur un écran « Changer l’email », documentez que le bouton Enregistrer reste désactivé tant que l’email n’est pas valide, qu’un spinner s’affiche pendant la requête, que le succès déclenche une bannière de confirmation, et que les erreurs de validation backend s’affichent sous le champ. Si le code montre un flag comme newEmailFlow, notez les deux variantes et ce qui diffère.
Rédigez chaque flux UI en étapes courtes (ce que fait l’utilisateur, ce que l’UI fait en retour) et gardez les conditions et erreurs à côté de l’étape qu’elles affectent. Cela rend la spec lisible et facilite la détection des lacunes.
Les notes brutes issues des routes et composants sont utiles, mais difficiles à discuter. Réécrivez ce que vous avez observé en une spec qu’un PM, un designer, un QA et un ingénieur peuvent lire et accepter.
Un schéma pratique est une story utilisateur par route ou écran. Gardez-la petite et spécifique. Par exemple : « En tant qu’utilisateur connecté, je peux réinitialiser mon mot de passe pour retrouver l’accès. » Si le code montre un comportement différent selon les rôles (admin vs utilisateur), séparez en stories distinctes au lieu de les cacher en note de bas de page.
Ensuite, rédigez des critères d’acceptation qui reflètent les chemins réels du code, pas le produit idéal. Si le handler renvoie 401 quand le token manque, c’est un critère. Si l’UI désactive la soumission tant que le champ n’est pas valide, c’est un critère.
Incluez les règles de données en langage clair, surtout celles qui surprennent : limites, ordonnancement, unicité, champs requis. « Les noms d’utilisateur doivent être uniques (vérifié à l’enregistrement) » est plus clair que « index unique ».
Les cas limites font souvent la différence entre un joli document et un document utile. Signalez les états vides, les valeurs nulles, les retentatives, les timeouts, et ce que voient les utilisateurs quand un appel API échoue.
Quand vous tombez sur des inconnues, marquez-les au lieu de deviner :
Ces marqueurs deviennent des questions rapides pour l’équipe plutôt que des suppositions silencieuses.
Une liste de lacunes n’est pas un second Jira. C’est un enregistrement court et fondé sur des preuves des endroits où le code et le comportement attendu ne correspondent pas, ou où personne ne peut clairement expliquer ce qui est « correct ». Bien faite, elle devient un outil d’accord, pas un combat de planification.
Soyez strict sur ce qui compte comme une lacune :
Quand vous notez une lacune, incluez trois parties pour rester ancré :
Les preuves empêchent la liste de devenir des opinions. Exemple : « POST /checkout/apply-coupon accepte les coupons expirés, mais CouponBanner.tsx les bloque dans l’UI. Impact : revenus et confusion utilisateur. Type : bug ou décision manquante (confirmer la règle souhaitée). »
Gardez-la courte. Fixez un plafond, par exemple 10 éléments pour la première passe. Si vous trouvez 40 problèmes, regroupez-les en motifs (incohérences de validation, vérifications de permission, états vides) et ne gardez que les exemples principaux.
Évitez les dates et la planification dans la liste de lacunes. Si vous avez besoin d’un propriétaire, restez léger : notez qui devrait prendre la décision (produit) ou qui peut vérifier le comportement (ingénierie), puis déplacez la planification réelle dans votre backlog.
Choisissez un périmètre petit et à fort trafic : le checkout avec codes promo et options de livraison. Le but n’est pas de réécrire tout le produit, juste de capturer ce que l’app fait aujourd’hui.
Commencez par les routes backend. C’est souvent là que les règles apparaissent en premier. Vous pourriez trouver des routes comme POST /checkout/apply-promo, GET /checkout/shipping-options, et POST /checkout/confirm.
À partir de ces handlers, décrivez le comportement en termes simples :
Vérifiez ensuite les composants UI. Un PromoCodeInput peut n’actualiser les totaux qu’après une réponse réussie et afficher les erreurs sous le champ. Un composant ShippingOptions peut auto-sélectionner l’option la moins chère au premier chargement et déclencher un rafraîchissement complet du détail des prix quand l’utilisateur la change.
Vous avez maintenant une spec lisible et une courte liste de lacunes. Par exemple : les messages d’erreur diffèrent entre la route promo et l’UI (« Code invalide » vs « Non éligible »), et personne n’a de règle claire sur l’arrondi des taxes (par ligne vs total de la commande).
En planification, l’équipe s’accorde d’abord sur la réalité, puis décide quoi changer. Au lieu de débattre d’opinions, vous passez en revue des comportements documentés, choisissez une incohérence à corriger, et laissez le reste comme « comportement actuel connu » jusqu’à ce qu’il vaille la peine d’être revu.
Une spec n’aide que si l’équipe confirme qu’elle correspond à la réalité. Faites une relecture rapide avec un ingénieur et une personne produit. Restez concis : 20–30 minutes concentrées sur ce que les utilisateurs peuvent faire et ce que le système fait en réponse.
Pendant la relecture, transformez les affirmations en questions oui/non. « Quand un utilisateur atteint cette route, renvoyons-nous toujours 403 sans session ? » « Cet état vide est-il voulu ? » Cela sépare le comportement voulu des comportements accidentels introduits avec le temps.
Mettez-vous d’accord sur le vocabulaire avant d’éditer quoi que ce soit. Utilisez les mots visibles par les utilisateurs dans l’UI (libellés de boutons, titres de page, messages d’erreur). Ajoutez les noms internes seulement quand ils aident les ingénieurs à trouver le code (noms de routes, noms de composants). Cela évite des écarts comme produit disant « Workspace » tandis que la spec dit « Org ».
Pour la maintenir : clarifiez la propriété et la cadence :
Si vous utilisez un outil comme Koder.ai, les snapshots et les rollback peuvent vous aider à comparer le « avant » et « après » comportement lors d’une mise à jour de spec, surtout après un gros refactor.
La façon la plus rapide de perdre la confiance dans une spec est de décrire le produit souhaité, pas le produit existant. Règle stricte : chaque affirmation doit être appuyée par quelque chose que vous pouvez pointer dans le code ou sur un écran réel.
Un autre piège est de copier la forme du code dans le document. Une spec qui ressemble à « Controller -> Service -> Repository » n’est pas une spec, c’est une carte de dossiers. Rédigez en termes utilisateurs : ce qui déclenche l’action, ce que voit l’utilisateur, ce qui est sauvegardé, et à quoi ressemblent les erreurs.
Les permissions et les rôles sont souvent ignorés jusqu’à la fin, puis tout casse. Ajoutez les règles d’accès tôt, même si elles sont désordonnées. Indiquez quels rôles peuvent voir, créer, modifier, supprimer, exporter ou approuver, et où la règle est appliquée (UI seulement, API seulement, ou les deux).
Ne négligez pas les chemins non-happy. Le vrai comportement se cache dans les retentatives, les échecs partiels, et les règles basées sur le temps comme les expirations, cooldowns, tâches planifiées, ou limites « une fois par jour ». Traitez-les comme des comportements de première classe.
Une façon rapide de faire apparaître des lacunes : vérifiez
Enfin, faites évoluer votre liste de lacunes. Chaque lacune doit être étiquetée comme : « unknown, needs decision », « bug, fix » ou « missing feature, plan ». Si rien n’est étiqueté, la liste stagne et la spec cesse d’être « vivante ».
Faites un passage rapide pour la clarté, la couverture et l’actionnabilité. Quelqu’un qui ne l’a pas écrite devrait comprendre ce que la fonctionnalité fait aujourd’hui et ce qui reste flou.
Lisez la spec comme si vous étiez un nouveau collègue le jour 1. S’il peut résumer la fonctionnalité en une minute, vous êtes proche. S’il demande encore « où ça commence ? » ou « quel est le chemin heureux ? », resserrez l’ouverture.
Vérifiez :
Chaque lacune doit être spécifique et testable. Plutôt que « gestion des erreurs floue », écrivez : « Si le fournisseur de paiement renvoie 402, l’UI affiche un toast générique ; confirmer le message souhaité et le comportement de retentative. » Ajoutez une action suivante unique (demander au produit, ajouter un test, inspecter les logs) et notez qui doit répondre.
Choisissez une zone fonctionnelle et limitez-vous à 60 minutes. Choisissez quelque chose de petit mais réel (connexion, checkout, recherche, un écran admin). Écrivez une phrase de périmètre : ce qui est inclus et ce qui est exclu.
Exécutez le workflow une fois de bout en bout : survolez les routes/handlers clés, suivez le flux UI principal, et notez les comportements observables (entrées, sorties, validations, états d’erreur). Si vous bloquez, consignez la question comme une lacune et passez à la suite.
Quand c’est fini, partagez la spec là où l’équipe peut commenter, et appliquez une règle : tout changement de comportement livré doit mettre à jour la spec dans la même fenêtre de livraison, même si c’est cinq lignes.
Gardez les lacunes séparées du backlog. Regroupez-les en « comportement inconnu », « comportement incohérent » et « tests manquants », puis révisez-les brièvement chaque semaine pour décider de l’urgence.
Si la rédaction et l’itération semblent lentes, un constructeur basé sur le chat comme Koder.ai peut vous aider à obtenir une première version rapidement. Décrivez la fonctionnalité, collez des extraits clés ou des noms de routes, affinez la formulation en conversation et exportez la source quand vous en avez besoin. L’objectif est la vitesse et la clarté partagée, pas un processus plus lourd.
Commencez par une petite tranche visible par l’utilisateur (par exemple « réinitialiser le mot de passe » ou « inviter un coéquipier »). Lisez d’abord les routes/handlers pour capturer les règles et les résultats, puis parcourez le flux UI pour noter ce que les utilisateurs voient réellement (états désactivés, erreurs, redirections). Rédigez en utilisant un modèle cohérent et consignez les inconnues dans une liste de lacunes séparée.
Par défaut : considérez le comportement actuel du code comme source de vérité et documentez-le.
Si un comportement semble accidentel ou incohérent, ne le « corrigez » pas dans la spec — marquez-le comme une lacune avec des preuves (où vous l’avez vu et ce qu’il fait), puis obtenez une décision pour mettre à jour soit le code, soit la spec.
Restez simple et répétable. Un modèle pratique :
Cela maintient les specs lisibles et facilite la détection des incohérences.
Rédigez les règles comme des exigences visibles par l’utilisateur, pas comme des notes de code.
Exemples :
Capturez ce qui déclenche une erreur et ce que l’utilisateur voit quand elle survient.
Concentrez-vous sur ce qui est observable :
Les effets de bord comptent car ils impactent d’autres fonctionnalités et les attentes support/ops.
Si l’UI bloque quelque chose que l’API autorise (ou l’inverse), consignez-le comme une lacune jusqu’à décision.
Notez :
Puis choisissez une règle et mettez à jour le code et la spec pour qu’ils correspondent.
Gardez la liste de lacunes courte et fondée sur des preuves. Chaque élément doit contenir :
Évitez d’en faire un second backlog.
Documentez-les explicitement au lieu de les cacher.
Incluez :
Ce sont souvent les sources de surprises et de bugs.
Court et ciblé : une relecture de 20–30 minutes avec un ingénieur et une personne produit.
Transformez les affirmations en vérifications oui/non (par exemple : « Renvoie-t-on toujours 403 si non autorisé ? »). Alignez le vocabulaire sur celui de l’UI (libellés et messages) pour que tout le monde parle de la même chose.
Placez la spec près du code et faites des mises à jour lors des livraisons.
Defaults pratiques :
L’objectif : petites modifications fréquentes, pas une grosse réécriture.
