Aller au contenu
English

Utilisateurs et flux de travail

  • Leçon 2
  • 50 min
  • Module 1 : Commencer par les besoins

Où nous en sommes

Dans la leçon précédente, nous avons préparé le dossier de conception et sa règle : chaque nombre est une mesure, un prix ou une hypothèse. Mais avant tout nombre sur la demande ou le coût, nous devons savoir qui utilise l'assistant et ce dont chaque personne a besoin. Une conception qui part des services répond à des questions que personne n'a posées. Dans cette leçon, nous partons des personnes et de leurs parcours, comme une architecte qui commence par visiter la famille.

Ce que vous saurez faire

Notez qui utilise l’assistant documentaire partagé, ce que chaque personne fait avec lui et ce qu’il ne fera pas. Faites-le avant de choisir un serveur ou un service. Une conception qui part des services répond à des questions que personne n’a posées et manque celles qui comptent.

Avant de commencerCe qu’il faut savoir et avoir sous la mainEnviron 50 minutes

Ce que vous devez savoir

Ce qu’il vous faut sur votre ordinateur

  • Votre dossier design-pack de la dernière leçon, ouvert dans VS Code. Vous modifiez requirements.md, un fichier Markdown. Vous n’exécutez aucune commande dans cette leçon.

Une architecte doit concevoir une maison. Elle ne commence pas par le nombre d’étages ou la marque de l’ascenseur. Elle commence par une visite. Qui habite ici? Un couple, deux enfants et une grand-mère qui ne peut pas monter les escaliers. Que fait chaque personne dans une journée normale? La grand-mère cuisine pour tout le monde. Les enfants font leurs devoirs le soir. Un parent travaille à la maison et participe à des appels vidéo.

Ces quelques faits orientent la conception. La grand-mère a besoin d’une chambre et de la cuisine au rez-de-chaussée. Le bureau à domicile a besoin d’une porte qui ferme. Et l’architecte note ce que la maison n’aura pas : aucune piscine, aucune aile pour les invités. Ainsi, personne n’est surpris, et personne ne paie pour des pièces que personne n’utilise.

Une architecte qui commence par « trois étages et un ascenseur » peut construire une belle maison. Mais c’est une maison pour quelqu’un d’autre.

Tomás a un plan pour l’assistant partagé : « Il nous faut Kubernetes et un service de base de données vectorielle. Ensuite, on pourra grandir sans limite. » Ce sont deux vrais outils. Kubernetes exécute plusieurs copies d’une application sur plusieurs serveurs. Un service de base de données vectorielle est une base de données hébergée pour les vecteurs de recherche. Mais Tomás les a choisis avant de savoir qui utilise l’assistant ou ce que ces personnes font avec lui.

Voici ce que cela coûte, avec un fait tiré du cours RAG : créer une IA qui utilise vos données. Six des 36 documents de Larkfield sont réservés au personnel, comme les limites d’approbation des remboursements et le rabais du personnel. Les 67 questions de test de Grace comprennent 7 questions sur des faits réservés au personnel. Les clients utiliseront aussi l’assistant sur le site Web de la boutique. Le plan de Tomás ne précise pas qui pose les questions. Rien n’empêche donc un client de recevoir une réponse réservée au personnel.

Un service plus gros ne règle pas ce problème. La solution vient d’une phrase sur le comportement : « Un client obtient des réponses provenant uniquement des documents publics. » La conception doit tenir compte de cette phrase avant de choisir un service. Il en va de même pour les 8 questions de test auxquelles les documents ne peuvent pas répondre. Quelqu’un doit décider ce que l’assistant dit alors.

L’idée : des exigences fonctionnelles rédigées sous forme de parcours

Section intitulée « L’idée : des exigences fonctionnelles rédigées sous forme de parcours »

Une exigence fonctionnelle dit ce que le système doit faire : un comportement qu’une personne peut observer. « Un client obtient des réponses provenant uniquement des documents publics » en est une. Elle ne dit pas comment le système le fait. Comparez-la à un attribut de qualité, qui précise à quel point le système le fait bien : rapidité, disponibilité, confidentialité. La prochaine leçon porte sur les attributs de qualité.

Il est facile de mal rédiger les exigences fonctionnelles, sous forme d’une longue liste de fonctionnalités. Une façon plus claire consiste à les rédiger sous forme de parcours. Un parcours décrit une chose qu’un type de personne fait avec le système, du début à la fin, dans ses propres mots. Certaines équipes l’appellent un flux de travail ou un récit utilisateur. Chaque parcours comporte quatre parties :

  • Qui : une personne ou un rôle, comme « agent de soutien ».
  • Quand : la situation qui le déclenche, comme « pendant qu’il aide un client ».
  • Quoi : l’action, comme « pose une question ».
  • Résultat : ce que la personne voit quand cela fonctionne, comme « une réponse avec des citations, en quelques secondes ».

La dernière partie compte le plus. Le « résultat » transforme un souhait en quelque chose que vous pouvez vérifier. Vous pouvez observer une agente et dire : oui, elle a reçu une réponse avec des citations; non, elle n’en a pas reçu.

Un parcours laisse aussi volontairement certaines choses de côté. Il ne nomme aucune base de données, aucun modèle ni aucun serveur. Ces choix viennent plus tard, dans le module 2, et chacun doit servir un parcours. Gardez les parcours courts : environ cinq pour un petit produit. Chaque parcours a un identifiant court, de J1 à J5, pour que les fichiers suivants puissent y faire référence.

Deux autres parties complètent le portrait. L’énoncé du problème compte trois ou quatre phrases. Il dit qui a le problème, ce qui va mal aujourd’hui et ce qui doit être vrai après sa résolution. La liste des éléments hors portée dit ce que le système ne fera pas. Hors portée ne veut pas dire « jamais ». Cela veut dire « pas dans cette conception, donc ne vous y attendez pas et ne payez pas pour cela ».

Voici le même parcours rédigé de trois façons. Lisez chacune et demandez-vous : Grace pourrait-elle le vérifier?

Version Texte Pouvez-vous le vérifier?
Une fonctionnalité « L’assistant utilise une recherche hybride et un modèle de reclassement (reranker). » Non. Elle nomme une solution. Elle ne dit pas qui elle aide ni à quoi ressemble un fonctionnement réussi.
Un souhait « Les agents obtiennent de bonnes réponses. » À peine. Quels agents? Quand? Que veut dire « bonnes »?
Un parcours « J1. Qui : un agent de soutien. Quand : pendant qu’il aide un client. Quoi : pose une question. Résultat : une réponse avec des citations des documents de la boutique, en quelques secondes. » Oui. Observez un agent avec un client.

Le parcours n’est pas beaucoup plus long. Mais chaque partie élimine une question. « Avec des citations » indique à Amira que la réponse doit inclure ses sources. « Les documents de la boutique » indique à Kwame que chaque boutique cherche uniquement dans ses propres documents. « En quelques secondes » reste volontairement vague : la prochaine leçon en fait un nombre que Grace accepte.

Kwame commence le fichier requirements.md par l’énoncé du problème. Il le rédige avec Omar, dans des mots qu’une personne sans formation en ingénierie peut lire :

Le service de soutien de Larkfield a un assistant qui répond aux questions à partir des documents de Larkfield, avec des citations. Bramble Books veut le même assistant pour ses propres documents, et deux autres boutiques pourraient s’ajouter l’an prochain. Aujourd’hui, chaque boutique aurait besoin de sa propre copie. Il nous faut un assistant que plusieurs boutiques (locataires) partagent. Chaque boutique doit voir uniquement ses propres documents, à un coût par boutique qu’Omar peut intégrer à un prix.

Chaque phrase a un rôle. La première dit ce qui existe aujourd’hui. La deuxième dit qui en veut plus. La troisième dit ce qui va mal : une copie par boutique. La quatrième dit ce qui doit être vrai : un assistant partagé, des boutiques séparées et un coût par boutique.

Ensuite, Kwame rend visite aux personnes, comme l’architecte a rendu visite à la famille. Grace décrit la journée de ses agents. Ines décrit Bramble Books, où elle et une autre personne font tout. Mei décrit comment les documents changent. Ces discussions donnent cinq parcours :

Qui Parcours À quoi ressemble le « résultat »
Agent de soutien (équipe de Grace) J1 : pose une question pendant qu’il aide un client une réponse avec des citations des documents de la boutique, en quelques secondes
Client sur le site Web de la boutique J2 : pose une question avant de rédiger un billet de soutien une réponse provenant uniquement des documents publics, ou « les documents ne le disent pas »
Propriétaire ou responsable des documents de la boutique (Ines, Mei) J3 : téléverse un document nouveau ou modifié le document devient consultable par recherche en quelques minutes, avec un court résumé; l’ancienne version reste pour les audits
Propriétaire de boutique J4 : voit ce que l’assistant a répondu chaque réponse avec sa question, ses citations et les versions des documents
Kwame et Amira J5 : ajoutent une boutique un nouveau locataire avec ses propres documents et utilisateurs, sans modification du code
Cinq personnes à gauche, chacune avec une flèche vers l'assistant documentaire partagé au centre. L'agent de soutien, J1, pose une question pendant qu'il aide un client. Le client sur le site Web de la boutique, J2, pose une question avant de rédiger un billet. Le responsable des documents de la boutique, J3, téléverse un document nouveau ou modifié. Le propriétaire de boutique, J4, vérifie les réponses données. Kwame et Amira, J5, ajoutent une boutique. À droite, cinq résultats : une réponse avec des citations en quelques secondes; documents publics seulement, ou les documents ne le disent pas; consultable par recherche en quelques minutes, ancienne version conservée; question, citations et versions des documents; un nouveau locataire sans modification du code.
Cinq parcours, cinq types de personnes. Chaque flèche représente une action; chaque case de résultat montre ce que la personne voit quand cela fonctionne.
Description textuelle du diagramme

À gauche, il y a cinq types de personnes. Chacun a une flèche vers l’assistant documentaire partagé au centre, avec le nom de son parcours. L’agent de soutien pose une question pendant qu’il aide un client (J1). Le client sur le site Web de la boutique pose une question avant de rédiger un billet (J2). Le responsable des documents de la boutique téléverse un document nouveau ou modifié (J3). Le propriétaire de boutique vérifie les réponses données (J4). Kwame et Amira ajoutent une boutique (J5). À droite, il y a cinq résultats, un par parcours. J1 donne une réponse avec des citations en quelques secondes. J2 donne une réponse provenant uniquement des documents publics, ou « les documents ne le disent pas ». J3 rend un document consultable par recherche en quelques minutes et conserve l’ancienne version. J4 montre chaque réponse avec sa question, ses citations et les versions des documents. J5 donne un nouveau locataire sans modification du code. La version pour téléphone montre les cinq parcours et une seule case pour tous les résultats.

Voyez ce que les cinq parcours indiquent déjà pour la conception, avant de choisir un service :

  • Deux types de personnes qui posent des questions. Les agents (J1) voient les documents publics et ceux du personnel. Les clients (J2) voient uniquement les documents publics. Chaque question doit donc indiquer qui la pose, et la recherche doit filtrer selon cette information. Une phrase règle le problème des documents réservés au personnel.
  • Un « non » honnête. Le « ou les documents ne le disent pas » de J2 couvre les 8 questions de test sans réponse dans les documents. L’assistant doit le dire, et non deviner.
  • Deux types de travail. J1 et J2 sont des questions : une personne attend la réponse. J3 est un téléversement : la personne peut attendre quelques minutes. Le module 2 utilise cette différence pour séparer le travail.
  • Des versions. J3 conserve les anciennes versions, et J4 montre quelle version une réponse a utilisée. Une nouvelle version ne supprime donc pas l’ancienne. Ines en a besoin pour ses contrats avec les fournisseurs.
  • Les locataires sont des données, pas du code. J5 dit « sans modification du code ». Une nouvelle boutique correspond donc à quelques lignes dans une base de données, pas à une nouvelle copie du programme.

Remarquez aussi qui n’est pas dans la liste. Priya, Omar et Mei ont d’autres rôles dans la proposition, mais n’utilisent pas l’assistant dans ces parcours. Une liste de parcours porte sur les personnes qui utilisent le produit, pas sur toutes les personnes du projet.

Ensuite, Kwame écrit ce que l’assistant ne fera pas. Chaque ligne vient d’une question posée pendant les discussions :

  • Réponses provenant d’Internet ou de connaissances générales : l’assistant utilise uniquement les documents de la boutique.
  • Actions (remboursements, modifications de commandes) : l’assistant répond; les personnes agissent.
  • Partage de documents entre boutiques.
  • Langues autres que l’anglais et le français.
  • Une application mobile.
Deux cases côte à côte. Dans la portée, l'assistant fait ceci : répond à partir des documents de la boutique, avec des citations; sépare les documents et les réponses de chaque boutique; accepte les documents nouveaux et modifiés et conserve les anciennes versions; conserve chaque réponse pour les audits. Hors portée, en rouge, il ne fait pas ceci : répondre à partir d'Internet ou de connaissances générales; agir, comme effectuer des remboursements ou modifier des commandes; partager des documents entre boutiques; parler d'autres langues que l'anglais et le français; offrir une application mobile.
La limite de la conception. Chaque élément de la case rouge vient d'une question, réglée une fois par « pas dans cette conception ».
Description textuelle du diagramme

La case de gauche énumère ce qui est dans la portée. L’assistant répond à partir des documents de la boutique, avec des citations. Il sépare les documents et les réponses de chaque boutique. Il accepte les documents nouveaux et modifiés et conserve les anciennes versions. Il conserve chaque réponse pour les audits. La case de droite, en rouge, énumère ce qui est hors portée. L’assistant ne répond pas à partir d’Internet ou de connaissances générales. Il n’agit pas, par exemple pour effectuer des remboursements ou modifier des commandes. Les boutiques ne partagent pas de documents. Il parle seulement anglais et français. Il n’y a pas d’application mobile.

Chaque ligne réduit le travail et le risque. « Les personnes agissent » signifie que l’assistant n’a jamais besoin de l’autorisation de modifier une commande. Cela élimine toute une catégorie de problèmes de sécurité. « Uniquement les documents de la boutique » signifie qu’une citation est toujours possible. « Aucun partage entre boutiques » garde la règle des locataires simple : aucune exception. Et chaque ligne économise de l’argent, car personne ne conçoit, ne construit ni n’exploite l’élément exclu.

Tomás demande : « Mais si une boutique veut une application mobile l’an prochain? » Kwame répond : « On décidera l’an prochain, avec les chiffres de l’an prochain. Aujourd’hui, c’est hors portée, et la proposition le dit. » Un élément hors portée est une décision écrite que vous pouvez modifier plus tard, volontairement.

Exercice guidé : rédiger la première moitié de requirements.md

Section intitulée « Exercice guidé : rédiger la première moitié de requirements.md »

Vous remplissez la première partie de requirements.md dans votre dossier : le responsable, le problème, les parcours et les éléments hors portée. La prochaine leçon ajoute les attributs de qualité.

  1. Ouvrez requirements.md dans VS Code. C’est un modèle : chaque <…> est un endroit à remplir.
  2. À la ligne Owner: (responsable), écrivez Kwame (architecte de solution). À Reviewed with: (révisé avec), écrivez Omar (produit), Grace (soutien de Larkfield) et Ines (Bramble Books).
  3. Sous Problem (problème), supprimez le texte à remplacer. Rédigez l’énoncé du problème dans vos propres mots, en quatre phrases ou moins. Dites qui a le problème, ce qui va mal aujourd’hui et ce qui doit être vrai.
  4. Sous Users and journeys (utilisateurs et parcours), écrivez J1 à partir du tableau ci-dessus. Vérifiez les quatre parties : qui, quand, quoi et résultat.
  5. Écrivez J2. Assurez-vous que son « résultat » dit ce qui arrive quand les documents ne répondent pas à la question.
  6. Écrivez J3, J4 et J5.
  7. Sous Out of scope (hors portée), écrivez les cinq lignes. Ajoutez une raison après un deux-points si elle n’est pas évidente.
  8. Lisez le « résultat » de chaque parcours à voix haute. Si vous ne pouvez pas imaginer quelqu’un le vérifier, rendez-le plus concret.
  9. Enregistrez le fichier. Comparez-le avec requirements.md dans le dossier d’exercices C26/snapshots/end-of-m01.

Vos mots seront différents de ceux de Kwame, et c’est correct. Vérifiez que les mêmes faits sont présents : deux types de personnes qui posent des questions, un « non » honnête, des versions de documents, des réponses conservées pour les audits et de nouvelles boutiques sans code. Le fichier de l’instantané contient aussi les attributs de qualité; vous les rédigerez dans la prochaine leçon.

Rédigez-les d’abord, avant toute architecture, chaque fois qu’un système a plus d’un type d’utilisateur. Ils coûtent peu : une page, quelques discussions. Ils permettent aussi de trouver des règles comme « les clients voient uniquement les documents publics » avant qu’un client découvre le problème.

Ne rédigez pas un parcours pour chaque bouton. Cinq à huit parcours couvrent un petit produit. Si vous en avez trente, certains sont des fonctionnalités d’un seul parcours, et la liste cache les plus importants. Ne rédigez pas non plus de parcours pour les parties internes. « Le processus crée le plongement d’un segment » est une étape dans le système, pas une action qu’une personne accomplit.

Les parcours ont un coût : ils exigent la participation des personnes. Kwame ne peut pas bien rédiger J2 sans Grace, qui sait ce que les clients demandent. Il ne peut pas bien rédiger J3 sans Mei, qui sait comment les documents changent. Un parcours que l’architecte invente seul est une hypothèse, et doit être indiqué comme tel.

Erreur courante

Un parcours qui décrit une solution

Symptôme : un parcours nomme un outil ou une technique, comme « J6 : le système stocke les vecteurs dans un index HNSW ». Personne ne peut dire qui en profite. Personne à l’extérieur de l’équipe ne peut le vérifier.

Cause : la personne qui rédige part de la conception, pas d’une personne. C’est l’erreur de Tomás à petite échelle : les services avant le comportement.

Solution : demandez « qui remarque si cela fonctionne, et que voit cette personne? » La réponse est peut-être « un agent obtient une réponse en quelques secondes ». C’est J1, déjà écrit, et l’index est une façon possible d’y répondre. Déplacez l’outil dans l’architecture, au module 2. Si personne ne remarque le résultat, cette ligne n’a pas sa place dans les exigences.

Erreur courante

Aucune liste d'exclusions

Symptôme : après la première démonstration, Ines demande : « Peut-il aussi effectuer le remboursement? Le client en a demandé un. » Personne n’a écrit qu’il ne peut pas le faire. Chaque personne a donc supposé quelque chose de différent. Ines pensait que cette fonction allait venir; Amira ne l’avait jamais prévue.

Cause : les exigences disent seulement ce que le système fait. Tout le reste demeure ouvert, et chaque lecteur comble le vide selon ses souhaits.

Solution : écrivez la liste d’exclusions et examinez-la avec les utilisateurs, comme Kwame l’a fait. « Actions : l’assistant répond; les personnes agissent » règle la question avant la démonstration. Si Ines veut toujours les remboursements, cela devient une décision avec son propre coût, pas une surprise.

Changez une condition : un nouveau type de personne. Priya, la scientifique des données, dit : « Avant tout changement au modèle ou à la requête, j’exécute le jeu d’évaluation. Si la proportion de réponses correctes diminue, le changement n’est pas mis en production. » Est-ce un parcours? Si oui, écrivez-le avec ses quatre parties. Est-ce que cela change la liste d’exclusions?

Afficher une réponse possible

Oui. Priya utilise le système et remarque s’il fonctionne. Voici une façon de l’écrire :

Qui Parcours À quoi ressemble le résultat attendu
Priya, scientifique des données J6 : vérifie un changement au modèle ou à la requête avant sa mise en production le résultat du jeu d’évaluation à côté du précédent; le changement est bloqué si la proportion de réponses correctes diminue

Cela ajoute un comportement : le système doit exécuter un ensemble fixe de questions sur demande et conserver chaque résultat. Cela ne change pas la liste d’exclusions. Cela rejoint toutefois la prochaine leçon : « la proportion de réponses correctes diminue » nécessite une cible, comme « au moins 85 % de réponses correctes ». Le fichier requirements.md du dossier n’ajoute pas J6 comme parcours. Il place la vérification de Priya dans les attributs de qualité, comme moyen de mesurer la qualité des réponses. Les deux choix sont raisonnables; l’important est de consigner la vérification.

Vérifiez votre compréhension

Lesquels de ces énoncés sont des exigences fonctionnelles, et lesquels ne le sont pas? (a) Un client obtient des réponses provenant uniquement de documents publics. (b) 95 % des réponses arrivent en 6 secondes ou moins. (c) Utiliser un service de base de données vectorielle. (d) Un propriétaire de boutique peut voir chaque réponse avec ses citations.

Afficher la réponse

(a) et (d) sont des exigences fonctionnelles : chacune décrit un comportement observable, sans préciser comment le système est construit. (b) est un attribut de qualité : il indique à quel point le système répond bien, ici en matière de rapidité. La prochaine leçon transforme des mots comme « rapide » en cibles comme celle-ci. (c) n’est ni l’un ni l’autre : c’est un choix de conception. Il appartient à l’architecture, et seulement s’il répond mieux à un parcours que les autres options.

Vérifiez votre compréhension

Faites une prédiction : Kwame oublie la règle de J2 « documents publics seulement ». Il écrit « J2 : un client pose une question; résultat attendu : une réponse avec citations ». Selon les faits du cours RAG : créer une IA qui utilise vos données, quel problème survient? Quand l'équipe le découvrirait-elle?

Afficher la réponse

La conception permettrait à la recherche d’un client d’inclure des documents réservés au personnel. Six des 36 documents sont réservés au personnel. Sept des 67 questions de test de Grace portent sur des faits réservés au personnel. Le problème n’est donc pas rare. Rien dans l’architecture ne filtrerait selon la personne qui pose la question, car aucune exigence ne le demandait. L’équipe le découvrirait tard : pendant les tests, avec de la chance, ou lorsqu’un client lit les limites d’approbation des remboursements. Ajouter le filtre à ce moment exige de modifier la recherche, les requêtes et les tests. Une phrase dans le parcours aurait évité ce problème.

Vérifiez votre compréhension

Vérification pratique : que contient votre fichier requirements.md après cette leçon? Nommez les sections et, pour chacune, un fait que la conception doit respecter.

Afficher la réponse
  • Responsable et réviseurs : Kwame, avec une révision par Omar, Grace et Ines.
  • Problème : un assistant partagé par plusieurs boutiques; chacune voit seulement ses propres documents, avec un coût par boutique.
  • Utilisateurs et parcours : J1 à J5, chacun précisant qui, le parcours et le résultat attendu. Par exemple, J2 : un client obtient uniquement des documents publics, ou « les documents ne le précisent pas ».
  • Exclusions : cinq lignes. Par exemple, « Actions : l’assistant répond; les personnes agissent ».

Les sections Attributs de qualité et Faits vérifiés et hypothèses sont encore vides. Les deux prochaines leçons les remplissent.

Récapitulatif

  • Partez des personnes, pas des services. « Kubernetes et un service de base de données vectorielle » ne dit rien sur les 7 questions réservées au personnel. « Un client obtient uniquement des documents publics » le fait.
  • Une exigence fonctionnelle décrit ce que le système doit faire, sous forme de comportement observable par une personne. Écrivez ces exigences comme des parcours : qui, quand, quoi et à quoi ressemble le résultat attendu.
  • L’assistant de Larkfield a cinq parcours : les agents posent des questions (J1), les clients aussi (J2), les éditeurs téléversent (J3), les propriétaires vérifient (J4) et l’équipe ajoute une boutique sans code (J5).
  • Les parcours façonnent déjà la conception : deux types de personnes qui posent des questions, un « non » honnête, deux types de travail, des versions de documents et des locataires représentés comme données.
  • La liste d’exclusions règle les questions avant qu’elles deviennent des surprises : aucune réponse tirée d’Internet, aucune action, aucun partage entre boutiques, deux langues, aucune application mobile.

Ensuite, vous transformerez « en quelques secondes », « toujours disponible », « privé » et « peu coûteux » en cibles mesurables.

Leçon suivante : Attributs de qualité