Spécifications de fonctionnalités Claude Code depuis le code : un flux de travail simple

Pourquoi vous avez besoin de specs qui correspondent au code

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.

Qu’est-ce qu’une spec vivante et une liste de lacunes

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 :

• Comportement visible par l’utilisateur (ce qui se passe quand quelqu’un clique, soumet, se connecte)
• Règles et contraintes (champs requis, limites, calculs)
• Cas limites (états vides, erreurs, retentatives, timeouts)
• Permissions (qui peut voir, créer, modifier, supprimer)
• Sorties importantes (emails envoyés, enregistrements créés, changements de statut)

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 :

• Noms de fonctions et de classes, arbres de composants
• Débats d’architecture et plans de réécriture

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.

• Un bug : le code viole le comportement actuel ou une règle convenue.
• Une demande de fonctionnalité : vous voulez un nouveau comportement.
• Une lacune : vous ne pouvez pas déterminer quel devrait être le comportement correct, ou le comportement est incohérent entre écrans/rôles.

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.

Choisir un périmètre et un format de spec simple

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

• Si vous avez besoin des règles réelles, partez des routes et des handlers.
• Si vous avez besoin de l’expérience réelle, partez des points d’entrée UI.
• Si la fonctionnalité est emmêlée, commencez par la page/contrôleur de plus haut niveau et travaillez vers l’extérieur.

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.

Modèle de spec (répétez pour chaque flux utilisateur)

• Purpose : ce que l’utilisateur cherche à accomplir
• Entry points : où le flux commence (URL, menu, bouton)
• Preconditions : auth, rôles, données requises
• Main flow : 5–10 étapes en langage clair
• Data and side effects : enregistrements créés/mis à jour, emails, logs
• Errors and edge cases : ce qui se passe quand ça tourne mal
• Open questions : comportements peu clairs à confirmer

Utilisez cette structure de façon répétée et vos specs de fonctionnalité resteront lisibles, comparables et faciles à mettre à jour.

Extraire le comportement depuis les routes et handlers

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.

Extraire le comportement depuis les composants et les flux UI

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.

Transformer les constats en specs lisibles

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 :

• Unknown : quel message doit apparaître quand l’email n’est pas trouvé ?
• Unknown : doit-on autoriser 0 articles ou forcer au moins 1 ?
• Unknown : cette erreur doit-elle être visible par l’utilisateur ou seulement journalisée ?

Ces marqueurs deviennent des questions rapides pour l’équipe plutôt que des suppositions silencieuses.

Créer une liste de lacunes sans en faire un backlog

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 :

• Comportement peu clair : l’app fait quelque chose mais la règle n’est écrite nulle part.
• Incohérence : deux endroits se comportent différemment pour le même cas.
• Règle manquante : un cas limite existe mais aucune décision n’est visible dans le code ou la doc.

Quand vous notez une lacune, incluez trois parties pour rester ancré :

• Type : bug (le code semble incorrect) ou décision manquante (intention floue)
• Impact : confusion utilisateur, risque de sécurité, perte de données, ou mineur
• Preuve : où vous l’avez vu et ce que vous avez observé (route/handler/composant)

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.

Exemple : documenter une vraie fonctionnalité à partir du code

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 :

• Les codes promo sont validés côté serveur (expirés, limite d’utilisation, éligibilité client).
• Les totaux sont recalculés après l’application du promo, mais seulement après une vérification d’inventaire.
• Les options de livraison dépendent de la destination, du poids, et si un article est marqué « restricted ».
• La confirmation échoue si le stock des lignes a changé depuis le chargement du panier.
• Les taxes sont calculées après le choix de la livraison (pas lors de l’application du promo).

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.

Valider la spec avec l’équipe et la maintenir à jour

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 :

• Propriétaire de la spec : une personne qui fusionne les changements (souvent le propriétaire de la fonctionnalité ou le tech lead)
• Déclencheur de mise à jour : sur merge de PR pour des changements de comportement, ou à chaque release
• Vérification rapide : ajoutez une case « spec mise à jour ? » au template de PR
• Stockage : gardez-la proche du code afin qu’elle évolue avec lui

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.

Erreurs courantes et pièges

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

• Les échecs de validation et les messages exacts visibles par l’utilisateur
• La gestion des soumissions en double (idempotence)
• Le travail en arrière-plan (queues, cron) et ce qui se passe s’il échoue
• Les problèmes de concurrence (deux utilisateurs modifiant le même enregistrement)
• Le comportement temporel (timeouts, expirations, limites de taux)

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

Checklist rapide avant de partager une spec

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.

Clarté et compréhension partagée

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 :

• Test d’une page : l’ouverture indique l’objectif utilisateur, où commence le flux, et où il se termine.
• Rôles et accès : rôles clés et ce que chacun peut/ne peut pas faire.
• Résultats : à quoi ressemble le succès et ce que voit l’utilisateur en cas d’échec (messages, redirections, retentatives).
• Bords et limites : limites de taille, limites de taux, timeouts, règles de validation et ce qui se passe quand les données manquent.
• Langage : utilisez d’abord les termes visibles par l’utilisateur ; définissez le jargon inévitable une fois.

Des lacunes utiles, pas du bruit

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.

Étapes suivantes pour démarrer cette semaine

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.