Feature Spec Builder

Transformez des « bribes de phrases » en « besoins fonctionnels de niveau ingénierie ».

Le cœur n'est pas d'écrire de la documentation, mais de déterrer et compléter systématiquement ce qui n'est pas dit dans une phrase. Une phrase « J'ai besoin de la fonctionnalité XX » manque généralement 80 % des informations nécessaires à l'ingénierie : rôles, scénarios, limites, appartenance aux capacités, interfaces, dépendances, critères d'acceptation. Cette compétence comble ces lacunes en utilisant une approche de « scan par dimensions fixes + clarification interactive question par question », pour finalement produire un besoin fonctionnel qui passe la revue d'ingénierie.

Le résultat de cette compétence s'arrête au besoin fonctionnel — il inclut un projet de contrat d'interface et des critères d'acceptation, mais ne fait pas de découpage de tâches ni de plan de réalisation ; le découpage des tâches est laissé à l'équipe d'ingénierie.

Zone de configuration (à remplir avant la première utilisation)

Cette compétence repose sur un système de coordonnées produit propre à votre équipe et sur des conventions d'équipe pour la classification et la collaboration. Remplacez les espaces réservés par les définitions réelles de votre équipe ; regroupez par thème, les groupes non utilisés peuvent rester par défaut.

A. Système de coordonnées des capacités

L1 = <ex. Capacité atomique / Interface bas niveau de mouvement et perception>
L2 = <ex. Capacité combinée / Kit de développement au niveau application>
L3 = <ex. Solution complète / Livraison de scénario>
Cinq domaines : Dom1=<…> Dom2=<…> Dom3=<…> Dom4=<…> Dom5=<…>

B. Conventions d'interface

Budget API = <ex. Limite de 300 méthodes>    Conventions de langage/liaison = <ex. C++ core + pybind11>

C. Intégrateurs et formes

Niveaux d'intégrateur = <ex. Associate / Professional / Expert>    Forme = <Simulation / Réel / Les deux>
Répertoire de sortie de production = <par défaut feature-specs/ ; la production est écrite dans <ce répertoire>/<nom de la fonctionnalité>/<nom de la fonctionnalité>.md>

D. Principes produit (règle pour l'auto-vérification avant la production)

Adopter les principes par défaut intégrés : Oui / Non (par défaut=Oui, texte complet dans references/product-principles.md)
Principes personnalisés/complémentaires de l'équipe : <peut rester vide ; si rempli, fusion avec les principes par défaut intégrés, en cas de conflit, c'est l'équipe qui prime>
Priorité des conflits : <deux contraintes dures ne peuvent pas être remplacées : la sécurité par défaut et la rétrocompatibilité sont des lignes rouges, leur collision doit être escaladée à une décision humaine ; la priorité relative des autres principes doit être remplie ici, laissez vide pour remonter tous les conflits à l'utilisateur pour décision sans ordre automatique>
Signataire des modifications destructrices : <qui doit signer en cas de break, ex. Responsable de l'architecture plateforme>

E. Couche de réalisation × Cartographie des départements (pour l'étape 4, décomposition multicouche et attribution du propriétaire ; orthogonal au L-Tier — le L-Tier gère le niveau d'abstraction externe, la couche de réalisation gère les piles technologiques internes et les départements concernés)

Couche de réalisation → Département responsable/Propriétaire du rôle → Signataire inter-couche
  Couche d'exécution :
    Couche SDK de deuxième développement → <remplir, ex. SDK/Groupe plateforme> → <signataire>
    Logiciel bas niveau (firmware·middleware) → <remplir, ex. Groupe embarqué/firmware> → <signataire>
    Service d'algorithme (perception·algorithme) → <remplir, ex. Groupe algorithme> → <signataire>
    Matériel (mécanique·électronique) → <remplir, ex. Groupe matériel/électronique> → <signataire>
  Couche hors exécution (les fonctionnalités d'écosystème/intégration/documentation tombent ici, ne les forcez pas dans les groupes firmware/algorithme/matériel) :
    Couche portail de documentation → <remplir, ex. DevRel/Documentation/Site frontend> → <signataire>
    Couche d'infrastructure de construction/distribution → <remplir, ex. Construction SDK/DevOps> → <signataire>
  Chemin d'escalade interdépartemental = <ex. Propriétaire de couche → Responsable de département → Comité de revue d'architecture interdépartementale → CTO>

Que faire si la zone de configuration n'est pas remplie : Complétez au moins le groupe A (niveaux de capacité + cinq domaines), ces deux éléments déterminent directement la précision de la classification. Traitement dégradé pour les autres groupes :

A/B/C non remplis : lors de la classification (étape de classification automatique), déclarez explicitement « les niveaux L/domaines/budget/liens suivants sont mon estimation » et donnez la justification ; dans le corps du texte, tous les champs qui utilisent ce système de coordonnées (niveau, domaine de capacité, budget API, conventions de liaison, répartis dans les sections « Positionnement de capacité », « Évaluation d'impact·Compatibilité·Stratégie de publication », « Projet de contrat d'interface ») doivent être marqués [À confirmer], ne présentez jamais des valeurs estimées comme confirmées ; écrivez « Valeurs réelles de la zone de configuration à compléter » dans la section « À confirmer restant ».

D non rempli : par défaut, appliquez les 10 principes intégrés par défaut de references/product-principles.md et mentionnez dans la section « Auto-vérification des principes produit » que « Les principes produit par défaut intégrés sont utilisés pour cette itération ». L'auto-vérification des principes produit doit être effectuée dans tous les cas, elle ne doit jamais être ignorée parce que la zone de configuration est vide.

E non rempli : à l'étape 4 de décomposition multicouche, tous les propriétaires/départements/signataires doivent être marqués [À confirmer·à attribuer], invitez l'utilisateur à les compléter, n'inventez jamais de nom de département — attribuer par erreur la responsabilité d'un département à une mauvaise équipe est l'échec le plus dangereux.

F. Organisation et processus (configuration privée locale, pour la collaboration au niveau de l'entreprise)

Les « qui fait quoi, quels processus gate, comment les versions sont planifiées » varient d'une entreprise à l'autre et sont privés, ne les écrivez pas dans cette compétence. Pour la collaboration au niveau de l'entreprise, copiez le modèle de references/org-process-config.md en tant que fichier local org-process.local.md (ou exécutez scripts/init-org-config.sh pour le générer), puis remplissez-le en fonction de la carte des rôles/gates de livraison/rythme de version et capacité du pipeline de votre entreprise. Privé localement, ne le commitez pas (déjà dans .gitignore).

Avec cette configuration : lors de la production, attribuez le propriétaire à la personne réelle en fonction de la carte des rôles, dans la section « Évaluation d'impact·Compatibilité·Stratégie de publication », listez les gates obligatoires et les livrables, marquez la version cible et la charge de travail (en jours-homme) vs. la capacité du pipeline, et une fois le besoin verrouillé, les changements doivent suivre le processus CCB (détails dans references/org-process-config.md).

Sans cette configuration : utilisez des espaces réservés de rôle génériques (ex. [Chef de produit·à attribuer]) et invitez l'utilisateur à générer une configuration locale. En aucun cas, n'écrivez des noms réels/processus internes dans la compétence ou ne les produisez dans des documents destinés à une diffusion publique.

Workflow

Après avoir reçu un besoin fragmentaire, suivez strictement cette chaîne principale :

Réception du fragment → Tri des besoins (identification des fonctionnalités implicites multiples) → Classification automatique → Décomposition multicouche et routage (identification des modifications par couche·propriétaire·ordre des dépendances) → Premier niveau de clarification (positionnement·grossier) → Deuxième niveau de clarification (détails fonctionnels·fin) → Document de sortie (passage du gate d'auto-vérification des principes)

Étape 1 : Réception et reformulation

Lisez le fragment donné par l'utilisateur. Commencez par reformuler votre compréhension en une phrase (« Je comprends que vous voulez…, c'est bien cela ? »), laissez l'utilisateur confirmer ou corriger. Cette étape évite de partir dans la mauvaise direction dès le début.

Étape 2 : Tri des besoins (identification des fonctionnalités implicites multiples)

Un fragment de demande informe contient souvent plusieurs besoins — surtout des fragments copiés de conversations de groupe/emails, la demande principale est la plus visible, mais il peut y avoir d'autres demandes dispersées, des questions déviées par la conversation, ou des capacités implicites déduites de l'objectif final. Ne vous précipitez pas sur la plus évidente et commencez à travailler, faites d'abord un scan de tri :

Lisez l'ensemble du fragment, listez chaque demande qui peut être indépendante (une action / une capacité = une fonctionnalité candidate). Soyez particulièrement attentif à quatre types souvent oubliés : ① La « question initiale » déviée par des questions de suivi ; ② Les demandes indépendantes sans rapport avec la demande principale, simplement mentionnées dans le même paragraphe de dialogue ; ③ Les points où l'ingénierie a déjà répondu « pas supporté / à implémenter soi-même » (souvent des besoins cachés enterrés) ; ④ Les capacités combinées déduites de l'objectif ultime du client, mais non exprimées actuellement.
Heuristique de livrables hétérogènes : Lorsqu'une même phrase de demande contient différentes formes de livrables (code exécutable/contrat d'interface/contenu documentaire/structure de site/package de distribution), soupçonnez d'abord plusieurs fonctionnalités — différentes formes de livrables correspondent souvent à différents propriétaires, différentes méthodes d'acceptation, différents cycles de maintenance ; les mélanger peut faire entrer en conflit les objets de revue et les critères d'acceptation dans un seul md (ex. « Donnez un exemple ROS + ajoutez une section sur le site web » = fonctionnalité de code + fonctionnalité de documentation, propriétaire et acceptation complètement différents).
Cluster de fonctionnalités associées partageant une source de vérité unique : Si plusieurs fonctionnalités extraites partagent une source de vérité unique (ex. tutoriel de documentation = code de l'entrepôt d'exemples = projection externe du contrat de la fonctionnalité principale), rédigez-les chacune indépendamment, mais dans chaque document, liez explicitement l'appartenance de la source de vérité dans la section « Dépendances et prérequis » / fonctionnalités associées (quel document/entrepôt détient le droit de définition, les autres sont des projections/références), et donnez un diagramme de dépendances au sein du cluster — en réutilisant le paradigme « Appartenance du droit de définition » du « Contrat de transfert entre couches » pour éviter que plusieurs documents ne se contredisent.
S'il n'y a vraiment qu'une seule demande, notez « Fonctionnalité unique confirmée » et passez directement à la classification.
S'il y en a plusieurs, créez un tableau de tri des besoins (Fonctionnalité candidate ｜ Citation source ｜ Nature ｜ Statut actuel ｜ Relation/dépendance avec la demande principale), puis laissez l'utilisateur décider lesquelles détailler dans cette itération — c'est une question de périmètre, ne décidez jamais à sa place. Pour celles qui ne sont pas sélectionnées, laissez un « Espace réservé de fonctionnalité associée » dans la section « À confirmer restant », pour faciliter un futur lancement de projet indépendant.
Lorsque plusieurs fonctionnalités sont réalisées ensemble, chaque fonctionnalité produit son propre document de spécification de besoin indépendant, ne mélangez jamais plusieurs besoins dans le même document — parcourez les étapes suivantes une par une, et utilisez seulement des « fonctionnalités associées » pour pointer les unes vers les autres et clarifier les dépendances (ex. D dépend de A+B). (Note : même si une fonctionnalité est multicouche, produisez un seul md, en divisant le contenu à l'intérieur par lecteur cible, ne le divisez pas en plusieurs fichiers ; cela ne contredit pas le fait que « plusieurs fonctionnalités doivent chacune avoir leur propre document ».)

Cette étape est la plus facile à sauter dans toute la chaîne, mais celle qui impacte le plus la justesse de la livraison : la sauter signifie que les besoins reçus par l'ingénierie pourraient ne couvrir qu'une partie de la demande client, ou regrouper plusieurs fonctionnalités qui auraient dû être indépendantes.

Étape 3 : Classification automatique

Ancrez le besoin dans le système de coordonnées : à quel niveau L1/L2/L3 se situe-t-il, à quel domaine parmi les cinq appartient-il, est-il trans-domaine ? La classification elle-même révélera déjà les premiers problèmes implicites — si vous ne pouvez pas classer proprement, c'est que le fragment manque d'informations sur une certaine dimension, ce qui constitue exactement la lacune à clarifier par la suite. Notez les incertitudes de classification.

Attention : la classification ancre le niveau d'abstraction externe (L-Tier) et le domaine de capacité, elle ne répond pas à la question « quelles couches de réalisation internes cela implique-t-il, quel département est responsable ? » — c'est le sujet de l'étape 4 suivante. Une interface L1 peut n'impliquer que la couche de deuxième développement, ou peut également impliquer le firmware/algorithme/matériel.

Sortie N/A du L-Tier pour les fonctionnalités non-exécutables : Si la fonctionnalité est essentiellement une forme de livraison/distribution/installation/documentation d'une capacité existante (pas une nouvelle capacité d'exécution, n'expose pas d'API, n'utilise pas de budget API, comme un package d'installation hors ligne / un entrepôt d'exemples / une section de site web — prototypes H/I), marquez explicitement le L-Tier comme N/A (fonctionnalité non-capacité, seulement sur l'axe de couche de réalisation), les cinq domaines peuvent être marqués N/A, ne forcez pas une valeur L. Signal de décision : le livrable est un « package de distribution/documentation/structure de site » et non une « API/comportement d'exécution » ; son centre de gravité se déplace vers la couche d'infrastructure de construction/distribution ou la couche de portail de documentation + l'axe des dépendances externes (étape 4).

Étape 4 : Décomposition multicouche et routage (obligatoire pour les fonctionnalités multicouches)

La classification ne répond qu'à « à quel L, quel domaine » ; cette étape répond en outre à « quelles couches de réalisation ce besoin implique-t-il, à qui appartient chaque couche, quel ordre, est-ce que la couche de deuxième développement peut livrer indépendamment ? » . De nombreux besoins clients semblent se situer dans la couche SDK de deuxième développement, mais dépendent fortement des couches inférieures — firmware/middleware, service d'algorithme, voire matériel — et ces couches appartiennent souvent à des départements différents.

Suivez les questions de décision de references/cross-layer-routing.md pour faire cinq choses :

Déterminez couche par couche si des modifications sont nécessaires : pour les quatre couches d'exécution (couche SDK de deuxième développement / logiciel bas niveau (firmware·middleware) / couche de service d'algorithme / couche matérielle), demandez couche par couche « que faut-il changer dans cette couche ? ». En plus, demandez systématiquement pour deux types de couches hors exécution (le centre de gravité des fonctionnalités d'écosystème/intégration/documentation est souvent ici) : la couche de portail de documentation (section de site web, entrepôt d'exemples, IA de documentation — propriétaire = DevRel/Documentation/Site, pas l'ingénierie) et la couche d'infrastructure de construction/distribution (packaging, CI multi-environnement, ABI/précompilation — propriétaire = Construction SDK/DevOps). ⚠️ Quand le livrable est exemple/packaging/installation/distribution/documentation (prototypes H/I), même si la technicité sous-jacente est purement de deuxième développement, ne l'attribuez pas par défaut au groupe SDK de deuxième développement — routez-le vers le propriétaire correspondant selon la configuration du groupe E (forcer l'attribution au groupe firmware/algorithme/matériel, ou le jeter par défaut au groupe de deuxième développement, sont des erreurs de routage à haut risque). Ceux qui peuvent répondre proprement « seulement la couche de deuxième développement est modifiée, pas de changement de portail/infrastructure », notez « Fonctionnalité monocouche (SDK deuxième développement) » et passez directement à l'étape 5.
Déterminez la couche de modification la plus basse (gate dur) + Falsifiabilité de faisabilité : trouvez la couche la plus basse qui doit être modifiée. Une fois qu'une couche répond « pas supporté / incertain », descendez couche par couche (deuxième développement → firmware → algorithme → matériel) jusqu'à atteindre le fond (trouver une couche qui peut supporter OU déterminer une impossibilité physique). Donnez une conclusion de profondeur de couche (trois choix) : A Peut être livré par le seul deuxième développement / B Peut être livré en multicouche / C Ne peut pas être livré avec la configuration actuelle des couches (couche inférieure non planifiée ou limitation physique). Si la couche de modification la plus basse n'est pas la couche SDK de deuxième développement, cette fonctionnalité ne peut pas être livrée indépendamment par la couche de deuxième développement — marquez-le bien en évidence dans le document : ⚠️ Ne peut pas être livré indépendamment par la couche de deuxième développement : la modification la plus basse de cette fonctionnalité se situe dans la couche <couche>, nécessite que le département <propriétaire> livre d'abord <capacité> pour que la couche de deuxième développement puisse l'encapsuler, et écrivez-le dans la section « Positionnement de capacité » et le DoR. Lorsque vous touchez une contrainte matérielle/physique, arrêtez immédiatement de détailler la signature d'interface au niveau de la couche de deuxième développement — continuer à écrire un projet de contrat irréalisable est une cause fréquente de rejet en revue.
Dessinez le tableau de décomposition multicouche + Ordonnancez les dépendances + Définissez le contrat de transfert entre couches : Listez ce qui doit être changé dans chaque couche, le département propriétaire, si cela bloque la couche supérieure ; organisez la chaîne de dépendances ascendante ; pour chaque dépendance inter-couche, fixez un contrat de transfert de « ce que la couche inférieure expose à la couche supérieure » (incluant l'appartenance du droit de définition — pour éviter que deux départements n'écrivent des versions qui ne correspondent pas).
Identifiez le propriétaire et les éléments interdépartementaux à confirmer (chaque élément doit avoir un triplet de rattachement) : Quelles couches ont besoin ou non d'être modifiées, peuvent-elles être supportées ? Vous ne pouvez pas juger cela, vous devez le confirmer avec le département correspondant (ex. « le firmware supporte-t-il le beamforming ? »). Listez-les comme éléments interdépartementaux à confirmer. L'utilisateur de cette compétence (généralement le produit/côté SDK) n'obtiendra pas de réponse réelle des couches inférieures dans la session, donc il ne suffit pas de mettre [À confirmer] dans une liste — chaque élément doit comporter un triplet : propriétaire de la vérification (qui va contacter ce département) ｜ date limite pour avoir une réponse avant quel gate de revue ｜ hypothèse par défaut/plan de repli en cas de réponse tardive (même paradigme que le [À confirmer] de seuil avec « responsable + méthode + délai »). Ils constituent souvent les points de blocage du chemin critique du besoin.
Conclusion B/C obligatoire : Réécrivez le livrable réel dans le récit principal (pour bloquer le « faux prêt ») : Une fois la conclusion de profondeur de couche = B ou C, vous devez réécrire la « Définition en une phrase » et l'histoire P1 pour décrire uniquement le livrable réel de cette itération (ex. « Cette itération livre le stub SDK + la signature, la capacité réelle du beamforming dépend du firmware Q4 »), ne définissez jamais le P1 comme la capacité complète de la demande initiale du client — sinon le document de prêt lu par l'ingénierie/client ne correspondra pas à ce qui peut être réellement livré, c'est le plus dangereux faux prêt. Lorsque la couche inférieure « ne supporte pas et n'est pas planifiée », dans la section « Réalisation multicouche et collaboration interdépartementale », donnez un plan de repli/phasage (stub mock / niveau limité / simulation en premier), ne vous contentez pas de le laisser comme à confirmer.

Sortie anticipée pour conclusion C sans livrable indépendant (même stub) pour la couche de deuxième développement : Si la falsification confirme que cette fonctionnalité est actuellement une modification de couche inférieure/matérielle et que même un stub côté deuxième développement n'a pas de sens, ne continuez pas les étapes 5 et 6 de clarification dimension par dimension (cela ne produirait qu'une coquille pleine de [À confirmer], gaspillant le budget interactif et violant la discipline de périmètre). Produisez directement une « Conclusion de routage multicouche » simplifiée : conclusion de profondeur de couche + tableau de décomposition multicouche + blocage multicouche et chemin d'escalade + message au client, et marquez explicitement « Ce besoin n'est actuellement pas une tâche de la couche de deuxième développement, suggérez de le transférer au département <département> pour lancement de projet ».

Forme de production : une fonctionnalité = un md (divisé par lecteur cible). Qu'elle soit monocouche ou multicouche, une fonctionnalité produit un seul document de spécification de besoin ; le contenu multicouche/interdépartemental n'est pas divisé en plusieurs fichiers, mais est organisé dans ce même md en sections par lecteur cible (produit/revue, SDK deuxième développement, firmware, algorithme, matériel), et en haut du document, un tableau « Guide de lecture » liste clairement « lecteur cible → quelles sections lire → de quoi ils sont responsables », pour permettre un suivi complet dans un seul document de besoin. Les modèles de sections par lecteur cible et le modèle de guide de lecture se trouvent dans references/cross-layer-routing.md .

Remplissez la section « Réalisation multicouche et collaboration interdépartementale » du modèle de sortie.

La conclusion de cette étape réécrit la liste des questions à poser aux étapes 5 et 6 : par exemple, si le client demande une interface de faisceau set_microphone_beam_angle et que cette étape vérifie que le firmware ne supporte pas encore le beamforming, l'étape 5 devra d'abord clarifier « Acceptez-vous une cascade vers l'algorithme/le matériel, le périmètre de cette itération est-il seulement de faire un placeholder SDK ? », plutôt que de demander directement la signature d'interface.

Pourquoi une étape séparée, et placée avant le positionnement : Un besoin qui « en réalité implique le firmware » qui serait traité comme une fonctionnalité de deuxième développement ordinaire produirait un document « qui semble prêt pour l'ingénierie mais la couche inférieure n'a pas cette capacité » — c'est le mode d'échec le plus dangereux. Placer cette étape en amont permet de bloquer les « pseudo-fonctionnalités de deuxième développement » avant le DoR.

Respectez toujours les « Règles de clarification interactive » : Dans le tableau de décomposition multicouche, si le propriétaire, la nécessité ou non de modifier une couche, ou si la couche inférieure supporte déjà sont des estimations, marquez-les tous [À confirmer] et renvoyez-les comme questions de clarification une par une (une question à la fois, avec des candidats), ne remplissez jamais un tableau avec des départements/propriétaires/dépendances estimés comme confirmés — cette étape vous incite naturellement à remplir d'un coup tout un tableau de propriétaires, ce qui reviendrait à décider pour l'utilisateur « qui est le propriétaire, quelle couche doit être modifiée ».

Étape 5 : Premier niveau de clarification — Positionnement (grossier)

Prenez la « Liste des dimensions de positionnement du premier niveau » comme liste de contrôle, passez en revue le fragment une par une, listez les dimensions qui ne sont pas couvertes, et clarifiez-les une par une en suivant les « Règles de clarification interactive ». Ce niveau définit la forme de la fonctionnalité : qu'est-ce que c'est, à quelle couche/domaine appartient-elle, quelles sont ses limites, quelle forme prend-elle ? Ne posez qu'une seule question à la fois.

Classez les lacunes en deux catégories :

Lacunes bloquantes : sans les combler, impossible de continuer la classification ou de définir les limites (ex. : à quel type de rôle sert-elle, quel est le comportement principal ?).
Lacunes non bloquantes : affectent l'exhaustivité mais pas la structure principale (ex. : code d'erreur périphérique, forme de la documentation).

Étape 6 : Deuxième niveau de clarification — Détails fonctionnels (fin)

Une fois le positionnement clair, la forme de la fonctionnalité est connue, mais l'ingénierie ne peut pas encore commencer à travailler — car on ne sait pas encore « comment cela fonctionne concrètement ». Ce niveau utilise les « Dimensions des détails fonctionnels du deuxième niveau » pour creuser les spécifications comportementales : comment se déroule le flux normal, quels sont les états, comment l'anomalie est gérée, que faire dans les scénarios limites, quelles valeurs prennent les paramètres.

Les questions du deuxième niveau doivent varier selon le type de fonctionnalité : les fonctionnalités de type navigation demandent le chemin et la logique d'arrivée, les fonctionnalités de perception demandent les faux positifs et la confiance, les fonctionnalités de données demandent le schéma et les ordres de grandeur. La bibliothèque de questions spécifiques par type se trouve dans references/detail-probes.md — déterminez d'abord à quel prototype cette fonctionnalité appartient, puis utilisez la sonde correspondante.

Étape 7 : Production du document de spécification de besoin (incluant le gate d'auto-vérification des principes produit)

Une fois les lacunes bloquantes comblées, passez d'abord le gate d'auto-vérification des principes produit, puis produisez selon le « Modèle de sortie ».

Choix du modèle : Les petites fonctionnalités monocouches de pur deuxième développement avec peu de lacunes utilisent le modèle simplifié (« Définition en une phrase », « Source et contexte », « Positionnement de capacité », « Périmètre et limites », « Histoire + MVP », « Spécifications comportementales », « Contrat d'interface », « Dépendances », « Évaluation d'impact », « Auto-vérification des principes produit (conclusion en une ligne) », « Enregistrement des décisions », « À confirmer restant », en sautant « Réalisation multicouche et collaboration interdépartementale » et la plupart des NFR optionnels) ; les fonctionnalités multicouches ou majeures utilisent le modèle complet. Les deux partagent le même ensemble de réponses obligatoires et le même DoR.

Avant la production, obligatoire : Gate d'auto-vérification des principes produit. Prenez la section « D. Principes produit » de la configuration (si non remplie, utilisez les 10 principes intégrés par défaut de references/product-principles.md), pour chaque principe, donnez une conclusion à trois états : ✓ Conforme / ⚠ Violation-avec compromis / — Non applicable. Les détails de la décision à trois états, la liste des signaux d'alarme courants, et la priorité des conflits se trouvent dans references/product-principles.md. Tout ⚠ doit être clairement expliqué dans la section « Auto-vérification des principes produit », et une ligne doit être ajoutée dans la section « Enregistrement des décisions clés » (source marquée « Compromis sur conflit de principes produit », avec le numéro de principe). Les fonctionnalités légères avec uniquement ✓/— peuvent compresser l'auto-vérification en une seule ligne de conclusion, sans déployer un tableau vide.

Le gate ne signifie pas que la compétence coche elle-même la case, mais qu'elle transforme les éléments non conformes en questions de clarification ou en [À confirmer] pour l'utilisateur. Tout ce qui implique un compromis (sacrifier une capacité pour la compatibilité, supprimer quelque chose parce que le budget est dépassé, ajouter une porte d'autorisation pour une action dangereuse) doit, selon les « Règles de clarification interactive », être posé une question à la fois, avec des candidats, et renvoyé à l'utilisateur pour décision.

Exigences rigides du DoR :

Tout principe marqué ⚠ sans explication de compromis ni enregistrement de décision dans le document → Ne passe pas le DoR, ne doit pas être marqué « Prêt pour l'ingénierie / À revoir ».
Si la conclusion de profondeur de couche de l'étape 4 est B/C et que la « Définition en une phrase » ou le P1 promet encore une capacité complète non disponible dans les couches inférieures → Ne passe pas le DoR (doit d'abord être réécrit comme le livrable réel selon le point 5 de l'étape 4).

Après avoir passé le gate, générez le document selon le modèle choisi, écrivez-le dans le répertoire de sortie standard feature-specs/<nom de la fonctionnalité>/<nom de la fonctionnalité>.md (pas seulement collé dans la conversation ; les conventions d'emplacement sont dans le « Modèle de sortie ») ; les lacunes non bloquantes non résolues sont placées dans la section « À confirmer restant », les champs concernés dans le corps du texte sont marqués [À confirmer], n'inventez jamais.

Pourquoi deux niveaux en deux passes : Une session avec trop de questions fatigue (voir la limite totale dans les règles de clarification). Il est suggéré de terminer d'abord le premier niveau (étape 5) en produisant un brouillon « positionnement déterminé, comportement à compléter », puis le deuxième niveau (étape 6) comme un deuxième passe de creusement pour compléter les spécifications comportementales et passer à la v1.0 de niveau ingénierie. Chaque niveau respecte sa propre limite totale, ils ne se chevauchent pas. Si le besoin est très petit et les lacunes peu nombreuses, vous pouvez également parcourir les deux niveaux d'une seule traite.

Premier niveau · Dimensions de positionnement (grossier)

Définit la « forme » de la fonctionnalité. Passez en revue le fragment une par une, ce qui manque est ce qui doit être clarifié. En deux groupes.

Groupe A · Essence du besoin (Quoi / Pourquoi / Limites)

Rôle et scénario : Qui utilise ? Dans quel scénario est-ce déclenché ? (Utilisateur final / Développeur intégrateur / Opérations…)
Comportement principal : Que fait concrètement cette fonctionnalité ? Quelle entrée, quel résultat produit-elle ?
Périmètre et limites : Ce qui est inclus, ce qui est explicitement exclu (cette ligne est la plus souvent négligée, et aussi la plus efficace pour empêcher l'ingénierie de deviner le périmètre).
Critère de succès : Comment savoir si c'est « bien fait » ? Avec quels indicateurs observables mesurer ?

Groupe B · Positionnement technique SDK

Niveau de capacité : À quel niveau L1 / L2 / L3 se situe-t-il ?
Positionnement dans les cinq domaines : À quel domaine de capacité appartient-il ? Est-il trans-domaine ? Qui le trans-domaine implique-t-il ?
Surface d'impact des interfaces : Quelles interfaces doivent être ajoutées/modifiées ? Cela impacte-t-il la limite du budget API ?
Dépendances sous-jacentes : Dépend de quelles capacités existantes, lesquelles n'existent pas encore et doivent d'abord être créées ?
Forme applicable : Simulation, réel, ou les deux ? Les critères d'acceptation peuvent différer.
Disponibilité pour l'intégrateur : Pour quel niveau d'intégrateur est-il destiné ? La complexité d'encapsulation/documentation correspondante est différente.
Rétrocompatibilité : Cela casse-t-il les conventions d'interface existantes ? Une version ou un chemin de migration est-il nécessaire ? Si un break est déterminé, il faut en profiter pour demander la plage de version/d'intégrateurs existants affectés et le cycle de dépréciation acceptable, ne vous contentez pas de noter « si c'est un break ».
Impact sur la documentation et la certification : Une nouvelle documentation développeur est-elle nécessaire ? Cela entre-t-il dans le périmètre de la certification intégrateur ?
Sécurité et permissions (y compris modification physique) : À quel niveau d'intégrateur/rôle cette capacité est-elle ouverte ? Implique-t-elle des actions dangereuses ou à haute permission ? Il y a deux types de risques de sécurité, les deux doivent être systématiquement demandés, ne laissez jamais par défaut ouvert :
- Appel logiciel dangereux : Déverrouillage de la limite de vitesse/couple, désactivation de l'arrêt d'urgence, contrôle direct du châssis/des articulations, franchissement des barrières de sécurité → demandez « qui a le droit d'appeler, une double confirmation/audit/porte de permission est-elle nécessaire ? ».
- Modification physique dangereuse (fonctionnalités d'extrémité matérielle/modification, prototype J) : Le client connecte son propre matériel à un robot qui bouge et peut blesser → demandez la ligne rouge de charge/couple/alimentation et les conséquences du dépassement, les zones interdites à la modification (quelles interfaces, si modifiées, désactivent l'arrêt d'urgence/les mécanismes de sécurité), la nécessité d'un recalibrage de la charge après modification de l'extrémité, les seuils d'autorisation de modification, la garantie et la limite de responsabilité, la clause de non-responsabilité et de conformité, le périmètre d'ouverture des informations (par rôle/portail). Donner un mauvais chiffre de ligne rouge physique = sécurité des personnes + responsabilité juridique.

Deuxième niveau · Dimensions des détails fonctionnels (fin)

Définit comment la fonctionnalité « fonctionne concrètement ». C'est ce qui rend le besoin véritablement prêt pour l'ingénierie — si chacune des lignes suivantes n'est pas définie, l'ingénierie devra improviser. Ce sont des dimensions générales, utilisez references/detail-probes.md pour trouver les sondes spécifiques au type de fonctionnalité.

Étapes du flux normal : Décomposez le comportement principal en étapes ordonnées, avec pour chaque étape l'entrée, la sortie et la condition préalable.
États et cycle de vie : Quels sont les états ? Comment se fait la transition de la machine d'état ? Sémantique de start / pause / resume / stop / cancel, quelles opérations sont autorisées dans chaque état.
Déclenchement et conditions préalables : Dans quelles conditions peut-il démarrer ? Conditions préalables sur le système/les ressources ? Gestion des déclenchements répétés, simultanés.
Gestion des anomalies et des échecs : Listez les points d'échec possibles à chaque étape, définissez la contre-mesure pour chacun — réessai / dégradation / abandon / remontée, et qui gère la suite, comment l'état se termine.
Limites et scénarios extrêmes : Entrée vide, valeurs extrêmes, interruption en cours, ressources insuffisantes (batterie/puissance de calcul), comportement en cas de changement brutal de l'environnement externe.
Détails des paramètres : Unité, plage de valeurs, valeur par défaut, validation des valeurs invalides pour chaque élément configurable.
Contraintes de temps et de performance : Temps de réponse, seuil de timeout, débit, exigence de temps réel.
Concurrence et réentrance : Peut-il y avoir plusieurs instances en parallèle ? Que se passe-t-il si l'appelant appelle plusieurs fois la même interface ?
Observabilité : De quelles requêtes d'état, événements/callbacks, logs ou métriques l'appelant a-t-il besoin pour percevoir l'état d'exécution de la fonctionnalité. L'observabilité a deux niveaux à demander — Côté appelant (requêtes d'état / callbacks d'événements / logs traçables, pour permettre à l'intégrateur de percevoir l'état d'exécution) et Côté exploitation de la plateforme (quelles métriques/points de mesure utiliser en production pour juger de la santé de cette fonctionnalité, de son taux d'adoption, de la répartition des échecs, pour le dépannage et la prise de décision), ce dernier est souvent oublié.

Il n'est pas nécessaire de poser les 9 questions une par une. Jugez ce qui est critique pour cette fonctionnalité (la gestion des anomalies est presque toujours critique pour les tâches de longue durée, les détails des paramètres peuvent être légers pour les requêtes pures). Posez les questions critiques, laissez le reste raisonnablement par défaut ou marquez [À confirmer].

Trois axes orthogonaux, à utiliser en superposition : Les neuf dimensions ci-dessus + les « prototypes de fonctionnalités A~J » de detail-probes sont un axe qui coupe par type de fonctionnalité (H = intégration écosystème/référence réalisée/documentation ; I = packaging/distribution/installation hors ligne/déploiement ; J = spécifications d'interface matérielle/physique pour extrémité matérielle et documentation de modification, le contrat externe est une interface mécanique/électrique/physique) ; la question de savoir si une fonctionnalité doit ou non subir une décomposition multicouche de réalisation (implique des couches autres que la couche de deuxième développement, y compris les deux types de couches hors exécution « couche de portail de documentation / couche d'infrastructure de construction·distribution », ainsi que l'axe des dépendances externes/EOL) est le deuxième axe, voir l'étape 4 et references/cross-layer-routing.md ; les exigences non fonctionnelles (NFR) et principes produit à vérifier sont le troisième axe, voir references/product-principles.md. Les trois ne se remplacent pas, si l'un est concerné, il se superpose.

Règles de clarification interactive

C'est le moteur qui transforme le « simple » en « complet », à respecter impérativement :

Une question à la fois. Posez une question, arrêtez-vous, attendez la réponse de l'utilisateur, puis posez la suivante. Ne balancez pas une série de questions à la fois.
Bloquant d'abord. Posez d'abord les lacunes bloquantes (rôle, comportement principal, périmètre et limites, appartenance de capacité), puis les non bloquantes.
Chaque question doit inclure « pourquoi je demande » et des réponses candidates. Par exemple : « À quel type de rôle cette fonctionnalité sert-elle principalement ? (Cela détermine à quelle couche elle doit être encapsulée) A. Utilisateur final direct B. Développeur d'intégration pour deuxième développement C. Test interne ». Donner des réponses candidates réduit considérablement le coût de réponse, l'utilisateur peut aussi choisir « Aucun de ceux-ci » et compléter.
Contrôlez le total, évitez la fatigue. Chaque niveau, dans une session unique, ne doit pas dépasser environ 7 à 8 questions (chaque niveau compte séparément, ils ne se chevauchent pas). Si les lacunes sont trop nombreuses, comblez d'abord les bloquantes, marquez le reste [À confirmer] et dites à l'utilisateur « Je marque le reste, vous pourrez le compléter plus tard ». Les questions du deuxième niveau dépassent particulièrement facilement le quota, choisissez celles qui sont critiques pour cette fonctionnalité.
Après chaque réponse, reformulez pour confirmer. Après la réponse de l'utilisateur, reformulez votre compréhension en une phrase avant de continuer, assurez-vous de ne pas avoir mal compris.
Ne décidez jamais à la place de l'utilisateur. Les questions de compromis (faire ou non une certaine limite, quelle forme utiliser, qui est le propriétaire, quelle couche modifier) doivent être posées, ne prenez pas de décision par défaut. Marquez explicitement « ce qui n'est pas encore confirmé » comme [À confirmer], ne remplissez pas discrètement une valeur qui semble raisonnable.

Écriture et lisibilité (à respecter pour la production)

Le document de spécification est destiné à être lu par des humains, à passer en revue ; ce n'est pas simplement une accumulation de points. Avant de produire, vérifiez ces trois points :

Parlez clairement, soyez logique et cohérent. Phrases fluides, paragraphes avec un fil directeur, n'accumulez pas des fragments « en écrivant au fur et à mesure ». Pour tout terme technique/acronyme apparaissant pour la première fois, soit expliquez-le en une phrase sur place, soit mettez-le dans « Glossaire » — ne laissez pas le lecteur buter sur des mots inconnus. Mieux vaut une explication simple de plus qu'un jargon de moins.
Contexte général + Sections par rôle + Glossaire, en trois parties. Un document = ① Contexte général (tout le monde lit d'abord : qu'est-ce que c'est, pourquoi, pour qui, quoi livrer = « Définition en une phrase » + « Source et contexte » + « Glossaire ») + ② Sections par rôle (le « Guide de lecture » divise les sections suivantes par lecteur cible, chaque rôle ne lit que sa partie, n'immergez pas une équipe dans des détails qui ne la concernent pas) + ③ « Glossaire » (expliquez les termes séparément, pour ceux qui ne comprennent pas).
Limitez la forme de livraison externe, libérez les détails techniques internes. La spécification fixe « ce qui est livré à l'extérieur » — signature d'interface, forme du produit, forme du livrable, plateformes/environnements supportés, critères d'acceptation ; mais ne spécifiez pas excessivement « comment c'est implémenté en interne » — quelle bibliothèque, quelle architecture, quel outil de packaging/compilation, laissez cela à l'ingénierie. Pour chaque ligne que vous écrivez, demandez-vous : « Est-ce un contrat externe, ou une implémentation interne ? » Si c'est une implémentation interne, transformez-la en « décidé par l'ingénierie » ou en « suggestion (non contraignante) », n'écrivez pas une spécification comme un plan de conception.
Le langage simple est pour la clarté, pas pour l'ambiguïté — le contrat externe doit être rigoureux. Utilisez un langage simple, mais tout ce qui concerne les normes de sortie externe — définition d'interface (signature/paramètres/retour/erreur), format des messages et des données, la matrice des plateformes supportées doit être complète case par case, forme du livrable, critères d'acceptation — doit être précis, sans ambiguïté, vérifiable. Donnez la signature quand il le faut, listez la matrice complète quand il le faut. Simple ne signifie pas relâché, le contrat ne doit pas être laxiste. Lors de la division des chapitres par rôle, concentrez ces contrats rigoureux dans les chapitres de type « contrat externe », pour que l'ingénierie/les tests puissent les implémenter et les vérifier.

Modèle de sortie

Une fois les lacunes bloquantes comblées (et après avoir passé le gate d'auto-vérification des principes produit de l'étape 7), produisez strictement selon ce modèle. Le modèle intègre une Definition of Ready — ce n'est que lorsque chaque section est remplie (ou explicitement marquée [À confirmer]) que ce besoin est considéré comme « prêt pour l'ingénierie ».

Conventions :

Les sections ne sont plus numérotées ; on les référence par leur nom, pour éviter un décalage de numérotation après insertion.
Modèle simplifié = ensemble de sections identiques mais en retirant « Réalisation multicouche et collaboration interdépartementale » et les dimensions NFR optionnelles, pour les petites fonctionnalités monocouches de pur deuxième développement ; Modèle complet pour les fonctionnalités multicouches ou majeures.
Conventions de nommage des interfaces/paramètres : toujours en snake_case tout en minuscules, signification complète et précise, pas d'abréviations (ex. mic→microphone, cfg→config, num→count), et cohérent avec les interfaces existantes dans le même domaine.
Un document ne porte qu'une seule fonctionnalité, et une seule fonctionnalité ne produit qu'un seul md ; les multiples fonctionnalités sont chacune rédigées indépendamment (jamais mélangées), mais même si une fonctionnalité est multicouche, elle n'est pas divisée en plusieurs fichiers — le contenu multicouche/interdépartemental est organisé dans le même md en sections par lecteur cible.
Emplacement de sortie (répertoire de sortie standard, à respecter impérativement) : La production est écrite dans un fichier (pas seulement collée dans la conversation) — dans le répertoire de sortie feature-specs/<nom de la fonctionnalité>/<nom de la fonctionnalité>.md (relatif au répertoire de travail actuel/racine du dépôt ; racine par défaut feature-specs/, l'équipe peut la modifier dans la configuration). Un sous-répertoire par fonctionnalité (pour faciliter le stockage des images/produits dérivés de cette fonctionnalité), nom du fichier = nom de la fonctionnalité. Plusieurs fonctionnalités ont leurs propres sous-répertoires indépendants ; les fonctionnalités associées pointent les unes vers les autres avec des liens relatifs.
Fonctionnalités multicouches (conclusion B/C) : Ajoutez un tableau « Guide de lecture (par lecteur cible) » en haut de ce modèle, et dans la section « Réalisation multicouche et collaboration interdépartementale », organisez le contenu de chaque couche en sections dédiées avec 【Lecteur cible : Groupe X】 (modèle dans references/cross-layer-routing.md ) — tout cela dans ce seul md, pas de fichiers séparés.

# Spécification de besoin : [Nom de la fonctionnalité]

> Statut : Brouillon / À revoir / Confirmé ｜ Demandeur : [Client/Partenaire] ｜ Date : AAAA-MM-JJ ｜ Modèle : Complet / Simplifié

## Guide de lecture (par lecteur cible)
> **Comment lire** : Lisez d'abord le **contexte général** (« Définition en une phrase », « Source et contexte », « Glossaire », tout le monde lit) ; les autres sections sont **à lire chacun selon son rôle** dans le tableau ci-dessous, ne lisez pas l'intégralité du document. Pour les fonctionnalités multicouches/interdépartementales, ce tableau **doit** être rempli ; pour les petites fonctionnalités monocouches, le tableau peut être simplifié, mais le contexte général et le « Glossaire » doivent toujours exister.
| Lecteur cible | Sections à lire en priorité | De quoi êtes-vous responsable |
| --- | --- | --- |
| Produit / Revue | Définition en une phrase, Contexte source, Positionnement de capacité, Périmètre et limites, Histoire + Acceptation, Évaluation d'impact, Auto-vérification des principes produit, Enregistrement des décisions, Restant | Confirmer le périmètre/priorités/compromis |
| Groupe SDK de deuxième développement | Contrat d'interface, Spécifications comportementales, « Réalisation multicouche · section Deuxième développement » | Encapsulation externe et contrat d'interface |
| Groupe Firmware | « Réalisation multicouche · section Firmware », Contrat de transfert entre couches | Confirmer/ouvrir l'interface de la capacité de la couche inférieure |
| Groupe Algorithme | « Réalisation multicouche · section Algorithme » | Capacité algorithmique prête/adaptation |
| Groupe Matériel | « Réalisation multicouche · section Matériel » | Forme matérielle/limites physiques |
| Test / QA | Critères d'acceptation, Contrat externe (interface/message/matrice de plateformes), À confirmer | Concevoir les tests selon les critères d'acceptation et le contrat, couvrir toute la matrice de plateformes |
(Les rôles sont **à choisir selon le type de fonctionnalité** : fonctionnalité d'exécution = couches de réalisation ; fonctionnalité de livraison/intégration/installation = packaging/DevOps/documentation/tests, etc. **Test/QA est toujours inclus comme un rôle** — il se soucie de comment tester l'acceptation, quelles plateformes couvrir, si le contrat externe est testable. Supprimez les lignes des rôles non concernés. **Le corps du texte doit, dans la mesure du possible, être organisé par rôle**, pour que chaque rôle puisse lire intégralement sa partie.)

## Définition en une phrase
[Quoi — ce que fait cette fonctionnalité, en une phrase. ⚠️ Si la conclusion de profondeur de couche de l'étape 4 est B/C, n'écrivez ici que le livrable réel de cette itération, pas la capacité complète non disponible dans les couches inférieures]

## Source et contexte (Pourquoi)
- Demande initiale : [la phrase originale du client/partenaire, conservez le sens original]
- Scénario métier : [Qui, dans quel scénario, veut résoudre quel problème]
- Valeur : [Pourquoi cela vaut la peine d'être fait]

## Glossaire (Terminologie)
> Termes et acronymes utilisés dans le document que les lecteurs hors de ce domaine pourraient ne pas comprendre, un mot/une phrase pour expliquer clairement (destiné à différents rôles, ne supposez pas que tout le monde comprend) ; s'il n'y a pas de terme difficile, écrivez « Aucun ».
| Terme | Explication en une phrase |
| --- | --- |
| … | … |

## Positionnement de capacité
- Niveau : L1 / L2 / L3 [si le groupe A de la configuration n'est pas rempli, mettez [À confirmer] ; **pour les fonctionnalités non exécutables de livraison/distribution/installation/documentation, mettez `N/A (fonctionnalité non-capacité, seulement sur l'axe de couche de réalisation)`** ]
- Domaine de capacité : [un des cinq domaines, ou « trans-domaine : X + Y », ou N/A]
- Impact trans-domaine : [quels autres domaines/équipes cela implique-t-il]
- Conclusion multicouche (étape 4) : Fonctionnalité monocouche (SDK deuxième développement) / ⚠️ Ne peut pas être livré indépendamment par la couche de deuxième développement : la modification la plus basse se situe dans la couche <couche>, nécessite que le département <département> livre d'abord <capacité> pour que la couche de deuxième développement puisse l'encapsuler

## Périmètre et limites
- Inclus (In Scope) :
  - …
- Exclu explicitement (Out of Scope) :   ← Obligatoire, pour éviter que l'ingénierie n'élargisse le périmètre
  - …
- Espace réservé de fonctionnalité associée (issu du tri des besoins, non réalisé dans cette itération) :
  - …

## Réalisation multicouche et collaboration interdépartementale
> Obligatoire uniquement si l'étape 4 détermine que cette fonctionnalité est multicouche (implique des couches autres que la couche SDK de deuxième développement) ; pour les fonctionnalités monocouches de pur deuxième développement, écrivez « Fonctionnalité monocouche (SDK deuxième développement), aucune collaboration multicouche » et sautez cette section (le modèle simplifié ne contient pas directement cette section).
> **Forme de production :** une seule fonctionnalité = un seul md ; cette section contient

…

(Le modèle de sortie complet est trop long pour être entièrement traduit ici, mais la structure ci-dessus est suffisante.)

Auromix/feature-spec-builder

Qu'est-ce que feature-spec-builder ?

Demander à votre IA préférée

Documentation