Aller au contenu
English

Problème et critères d'acceptation

  • Leçon 4
  • 45 min
  • Module 2 : Rédiger des tâches exploitables

Où nous en sommes

Dans le module 1, nous avons préparé un environnement de travail sûr : trois modes, un point de départ propre et un périmètre écrit. Maintenant, nous pouvons demander une modification. Mais une demande vague laisse de nombreuses décisions ouvertes, et l'assistant prend chacune d'une façon raisonnable qui n'est pas la nôtre. Dans cette leçon, nous transformons le courriel de Grace en fiche de tâche avec des critères d'acceptation que tout le monde peut vérifier, en partant d'un gâteau commandé pour samedi.

Lue depuis YouTube. Rien ne se charge depuis YouTube avant que vous appuyiez sur lecture. Confidentialité

Ce que vous saurez faire

Transformez une demande en tâche qu’une autre personne peut terminer et vérifier. Écrivez ce qui se passe maintenant, ce qui devrait se passer, les entrées, les limites et les preuves du travail terminé. Un assistant ne peut pas lire dans vos pensées. Un collègue non plus.

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

Ce que vous devez savoir

Ce qu’il vous faut sur votre ordinateur

  • Le projet ~/projects/ticket-cleaner-assist du module 1, sur la branche feature/category-option, avec son environnement actif. python -m pytest affiche 25 passed (25 tests réussis), et git status indique working tree clean (répertoire de travail propre).
  • Si le projet manque ou ne fonctionne plus, copiez l’instantané end-of-m01, selon les étapes de réinitialisation de Contexte et limites.
  • Aucun compte, aucune clé et aucuns frais. Vous lisez deux séances enregistrées dans le dossier des exercices C15/transcripts/.

Vous appelez une pâtisserie : « J’ai besoin d’un gâteau pour samedi. » Samedi, vous recevez un gâteau au citron pour six personnes, avec « Félicitations » dessus. C’est un bon gâteau. Mais vous avez douze invités, l’un d’eux ne peut pas manger de noix, et c’est l’anniversaire de Sam.

La personne qui a préparé le gâteau n’a rien fait de mal. Votre commande laissait beaucoup de choix ouverts. Cette personne a fait chaque choix de façon raisonnable. Ce n’étaient pas vos choix.

Essayez de nouveau : « Un gâteau au chocolat pour douze personnes, avec Bonne fête, Sam, et sans noix. Je viens le chercher samedi à 10 h. » Vous pouvez vérifier chaque élément de cette commande en récupérant le gâteau. La pâtisserie peut aussi les vérifier avant votre arrivée.

Le problème : un changement raisonnable, mais incorrect

Section intitulée « Le problème : un changement raisonnable, mais incorrect »

L’équipe du cours a présenté la fonctionnalité de Grace à un assistant en une phrase (transcription feature-vague) :

Prompt
Add a way to filter the report by category.

L’assistant a demandé quatre fichiers, les a modifiés et a ajouté cinq tests. Son changement était petit : 4 fichiers, 77 lignes ajoutées et 3 supprimées. Tous les tests ont réussi : 29 passed. Avant ses modifications, il a annoncé ce qu’il ferait :

What the assistant printed (part)
I’ll add an optional `--category` argument that matches a report category exactly and combines with the status filter.

Relisez cette phrase. Elle contient trois décisions que personne n’a demandées :

  • Une catégorie. Grace a écrit « une seule catégorie, ou deux quand un responsable a deux équipes ». L’option n’en accepte qu’une.
  • Correspondance exacte. --category Billing ne trouve rien, parce que le rapport indique billing.
  • Une nouvelle clé dans chaque rapport. Le changement ajoute "category": null à chaque rapport, même quand personne n’utilise l’option. Dans Préparer le dépôt, le test de référence de base a détecté exactement cette clé.

Chaque décision est raisonnable, comme le gâteau au citron. Mais personne ne peut dire que le changement est incorrect, car la demande ne précisait jamais ce qui était correct. Les tests n’aident pas : l’assistant les a écrits pour ses propres décisions, alors ils réussissent.

L’idée : une fiche de tâche avec des critères d’acceptation

Section intitulée « L’idée : une fiche de tâche avec des critères d’acceptation »

Une fiche de tâche est une courte description écrite d’une tâche. Elle comprend cinq parties :

  1. Comportement observé : ce qui se passe maintenant. Utilisez une commande et sa sortie réelle.
  2. Comportement attendu : ce qui devrait se passer après le changement.
  3. Entrées : les fichiers, les options et les exemples que la tâche utilise.
  4. Contraintes : les limites. Quels fichiers peuvent changer, aucune nouvelle dépendance, les règles de style.
  5. Preuves du travail terminé : les vérifications qui montrent que le travail est fini.

Le cœur de la fiche est une liste de critères d’acceptation. Un critère d’acceptation est un énoncé sur un comportement. Une personne ou un test peut le vérifier, et la réponse est oui ou non. Par exemple, « l’option est facile à utiliser » n’est pas un critère. Deux personnes peuvent ne pas être d’accord. « Vous pouvez fournir --category plusieurs fois » est un critère. Vous l’utilisez deux fois et vous observez le résultat.

Le nom vient des contrats. Quand un entrepreneur termine un travail, le client l’accepte si le travail respecte les critères convenus. Vous en avez vu une version plus simple dans Le contrat d’une fonction : ce qu’une fonction reçoit et ce qu’elle promet de retourner.

Le courriel de Grace contient cette phrase : « Puis-je demander au rapport une seule catégorie, ou deux quand un responsable a deux équipes? » Transformez-la en vérifications avec le fichier d’exemple du cours de Python, data/tickets.csv. Il contient 9 billets de soutien valides, dont 4 sont ouverts :

ID Catégorie Priorité
T-1001 billing 2
T-1003 login 1
T-1005 billing 3
T-1015 shipping 2

Écrivez maintenant chaque critère avec le résultat attendu, à partir de ce tableau :

  • Une catégorie. --category billing conserve T-1001 et T-1005. Donc selected vaut 2, by_category vaut {"billing": 2}, et average_priority vaut (2 + 3) / 2 = 2,5.
  • Deux catégories. --category billing --category shipping conserve trois billets. Donc selected vaut 3, et by_category vaut {"billing": 2, "shipping": 1}.

Vous avez calculé les résultats à la main, avant même que le code existe. C’est le but. Si le changement affiche selected 3 pour --category billing, vous savez immédiatement qu’il est incorrect. Vous n’avez pas besoin de lire le code pour le savoir.

Amira transforme le courriel de Grace en docs/tasks/category-option.md. Certains critères viennent directement du courriel. D’autres sont des décisions qu’Amira vérifie avec Grace avant de les écrire. Est-ce que Billing et billing doivent donner le même résultat? Grace dit oui. Le rapport doit-il rester identique sans l’option? Oui, parce qu’un tableur le lit.

docs/tasks/category-option.md
# Task: add a --category option to the report
Request: Grace (support lead) wants the report for one category, or a few.
Observed now: `python -m ticket_cleaner data/tickets.csv` always counts every
category of the chosen status.
Expected: `python -m ticket_cleaner data/tickets.csv --category billing` counts
only the billing tickets of the chosen status.
## Acceptance criteria
1. With `--category NAME`, "selected", "by_category" and "average_priority"
count only the tickets that have the chosen status and that category.
2. `--category` can be given more than once. A ticket in any of the given
categories counts.
3. Capital letters and spaces around the name do not matter:
`--category " Billing "` selects the billing tickets.
4. With `--category`, the report has one more key, "categories": the chosen
names, in small letters, sorted. Without `--category`, the report is exactly
the same as today.
5. "valid_records" and "rejected" do not change with `--category`: they
describe the whole file.
6. A category that no ticket has is not an error: "selected" is 0, and the
exit code is 0.
7. `--help` and the options table in README.md describe the option.
## Constraints
- Change only ticket_cleaner/cli.py, ticket_cleaner/report.py, README.md and
the tests.
- No new dependency.
- Keep the style: `ruff check .` and `ruff format --check .` pass.
## Evidence of done
- `python -m pytest` passes, with new tests for criteria 1 to 6.
- `ruff check .` and `ruff format --check .` pass.
- The commands in criteria 1, 3 and 6 give the results above.

Regardez ce que la fiche ne dit pas. Elle ne dit pas comment ajouter l’option, ni quelle fonction modifier. Elle dit ce qui doit être vrai après le changement. Elle laisse le comment à la personne, ou à l’assistant, qui fait le travail. Les contraintes sont les seules limites sur la façon de faire.

Chaque critère a une vérification. Le diagramme relie chacun à une commande et à son résultat attendu :

À gauche : le comportement observé et attendu de la fiche, ses sept critères d'acceptation et ses contraintes. À droite : pour chaque critère, la commande sur data/tickets.csv et le résultat qui le démontre. 1, --category billing : selected 2, by_category billing 2, average_priority 2.5. 2, --category billing --category shipping : selected 3, billing 2 et shipping 1. 3, --category avec une espace, Billing, puis une espace : le même résultat que le critère 1. 4, --category Shipping --category billing : categories billing et shipping, et test_baseline.py réussit encore. 5, --category billing : valid_records 9 et 6 lignes rejetées, comme sans l'option. 6, --category garden : selected 0, by_category vide, code de sortie 0. 7, --help présente --category, et le tableau des options du README contient une ligne. Contraintes : git diff --stat présente seulement cli.py, report.py, README.md et tests; les fichiers requirements ne changent pas; les deux vérifications ruff réussissent.
La fiche de tâche relie chaque exigence aux preuves qui montrent qu'elle est satisfaite. Chaque valeur attendue vient du fichier d'exemple, avant l'écriture du code.
Description textuelle du diagramme

Le diagramme a deux colonnes. La colonne de gauche contient la fiche. En haut, le comportement observé : –category provoque une erreur, avec le code de sortie 2. Comportement attendu : –category billing compte seulement les billets billing ayant le statut choisi. En dessous se trouvent les sept critères et les contraintes. La colonne de droite contient la vérification de chaque critère. Chaque commande commence par python -m ticket_cleaner data/tickets.csv.

  1. Une catégorie : --category billing donne selected 2, by_category {"billing": 2} et average_priority 2.5.
  2. Plusieurs fois : --category billing --category shipping donne selected 3 et by_category {"billing": 2, "shipping": 1}.
  3. Majuscules et espaces : --category " Billing " donne le même résultat que le critère 1.
  4. La clé « categories » seulement avec l’option : --category Shipping --category billing donne categories ["billing", "shipping"]. Sans l’option, tests/test_baseline.py réussit encore.
  5. Comptes du fichier entier : --category billing donne encore valid_records 9 et 6 lignes rejetées, comme sans l’option.
  6. Catégorie inconnue : --category garden donne selected 0, un by_category vide et le code de sortie 0.
  7. Aide et README : python -m ticket_cleaner --help présente –category, et le tableau des options du README contient une ligne pour cette option.

Contraintes : git diff --stat présente seulement cli.py, report.py, README.md et des fichiers dans tests/. Les fichiers requirements ne changent pas. ruff check . et ruff format --check . réussissent.

  1. Vérifiez l’état de départ. git status doit indiquer nothing to commit, working tree clean (rien à valider, répertoire de travail propre), et python -m pytest doit afficher 25 passed.

  2. Lisez le courriel de Grace : nextia-learning-labs/C15/emails/grace-feature-request.md. Retrouvez-y chaque critère de la fiche, ou indiquez qu’il s’agit d’une décision d’Amira.

  3. Observez vous-même le comportement actuel. Exécutez la commande de la ligne « Expected » (attendu) de la fiche :

    Fenêtre de terminal
    python -m ticket_cleaner data/tickets.csv --category billing
    Sortie
    usage: ticket_cleaner [-h] [--status {closed,open,pending}] [--output OUTPUT]
    input
    ticket_cleaner: error: unrecognized arguments: --category billing

    Affichez ensuite le code de sortie. Sur macOS et Linux, exécutez echo $?; dans PowerShell, exécutez $LASTEXITCODE. La commande affiche 2 : elle est incorrecte, comme l’indique le tableau des codes de sortie du README.

  4. Créez le dossier docs/tasks, puis copiez-y la fiche depuis l’instantané end-of-m02 :

    Fenêtre de terminal
    mkdir -p docs/tasks
    cp ../nextia-learning-labs/C15/snapshots/end-of-m02/docs/tasks/category-option.md docs/tasks/

    Vous pouvez aussi la saisir à partir de l’encadré ci-dessus. L’écrire vous-même est un meilleur exercice.

  5. Exécutez les vérifications. Une fiche ne modifie aucun code, donc les tests ne changent pas. ruff vérifie aussi le format des fichiers Markdown, donc il compte un fichier de plus :

    Fenêtre de terminal
    python -m pytest
    ruff check .
    ruff format --check .
    Output (the end of each command)
    ============================== 25 passed in 0.03s ==============================
    All checks passed!
    18 files already formatted
  6. Faites un commit (enregistrement des modifications) de la fiche :

    Fenêtre de terminal
    git add docs/tasks/category-option.md
    git commit -m "Write the task brief for the category option"
    Sortie
    [feature/category-option c1757ff] Write the task brief for the category option
    1 file changed, 39 insertions(+)
    create mode 100644 docs/tasks/category-option.md

    Votre empreinte de commit est différente.

La fiche est dans le dépôt, à côté du code. Un réviseur peut la lire avec les différences, et la demande de tirage (pull request) peut y faire référence.

L’équipe du cours a donné cette fiche au même assistant et au même modèle, avec les cinq fichiers nécessaires (transcription feature-bounded). L’assistant a commencé par un plan différent :

What the assistant printed (part)
I’ll add a repeatable category option, normalize and apply the category filter after the status filter, and keep whole-file validation totals unchanged.

Chaque partie de cette phrase vient d’un critère. « Repeatable » (répétable) correspond au critère 2, et « normalize » (normaliser) au critère 3. « After the status filter » (après le filtre de statut) et « whole-file … totals unchanged » (totaux du fichier entier inchangés) correspondent aux critères 1 et 5. Après chaque séance, un script a exécuté huit vérifications cachées, une par critère (le critère 4 en a deux). Voici trois séances enregistrées :

Séance Requête (prompt) Fichiers modifiés Lignes Tests Vérifications cachées
feature-vague une phrase 4 +77 −3 29 passed 4 sur 8
feature-bounded la fiche 5 +145 −4 35 passed 8 sur 8
feature-bounded-small la fiche, modèle plus petit 5 +86 −3 30 passed 8 sur 8
  • Demande en une phrase
  • La fiche de tâche
Le plus petit changement était incorrect. Avec la fiche, les deux modèles ont réussi les 8 vérifications; la demande en une phrase en a réussi 4.
Description textuelle du graphique

Un nuage de points. L’axe horizontal indique le nombre de lignes modifiées, de 0 à 200. L’axe vertical indique le nombre de vérifications cachées réussies, sur 8; l’axe va jusqu’à 10. La demande en une phrase (« vague ») a modifié 80 lignes et réussi 4 vérifications. La fiche avec le plus grand modèle (« brief ») a modifié 149 lignes et réussi 8 vérifications. La fiche avec le plus petit modèle (« brief, small ») a modifié 89 lignes et réussi 8 vérifications.

Le changement issu de la demande vague a échoué à quatre vérifications : deux catégories, majuscules et espaces, clé categories, et rapport inchangé. Ses propres tests ne pouvaient pas le détecter. Seuls les critères de la fiche le pouvaient.

Remarquez deux autres choses. D’abord, les petites différences n’étaient pas les bonnes : la taille n’est donc pas la mesure, les critères le sont. Ensuite, la fiche n’a pas rendu le travail parfait. Le changement du plus grand modèle a échoué à ruff format --check (2 files would be reformatted, soit deux fichiers à reformater). La fiche demandait pourtant cette vérification. Et la même fiche, envoyée une deuxième fois, a produit un changement différent : +129 −5 au lieu de +145 −4. Une fiche vous indique quoi vérifier. Vous devez quand même le vérifier, dans Réviser le travail généré.

Écrivez une fiche pour tout changement qu’une autre personne réalise, assistant ou collègue, et que vous devrez accepter. Cela prend environ quinze minutes pour une tâche comme celle de Grace. La plupart de ce temps sert à poser des questions à Grace. Quelqu’un doit de toute façon répondre à ces questions : vous maintenant, ou l’assistant avec ses suppositions plus tard.

Gardez-la courte. Une fiche d’un écran suffit pour une tâche touchant quelques fichiers. Pour un changement d’une ligne, comme « renommer cette variable », une phrase constitue une fiche : son critère est « les tests réussissent encore ».

Une fiche a des coûts. Les valeurs attendues demandent de la réflexion : vous les calculez à la main. Un critère peut aussi être incorrect, et un changement correct échoue alors à la vérification. Si une vérification échoue, demandez-vous d’abord si le critère est correct. Modifiez ensuite la fiche volontairement, dans un commit, et informez Grace.

Ne laissez pas la fiche devenir le code. « Utilisez action="append" dans make_parser() » est un choix de conception, pas un critère. Ajoutez-le à la fiche seulement s’il y a une raison, par exemple une règle d’équipe. Sinon, décrivez le comportement et laissez la personne qui fait le travail choisir la méthode.

Erreur courante

Un critère que personne ne peut vérifier

Symptôme : Tomás écrit une fiche avec ce critère : « Le filtre de catégorie devrait fonctionner correctement et être facile à utiliser. » Le changement de l’assistant réussit tous les tests. Grace découvre que --category Billing ne sélectionne rien, et Tomás dit « mais il fonctionne correctement ».

Cause : « correctement » et « facile à utiliser » n’ont pas de vérification par oui ou non. Chaque lecteur leur donne son propre sens, donc le critère accepte n’importe quel changement. C’est encore la demande vague, avec plus de mots.

Solution : pour chaque critère, écrivez la commande ou le test qui le vérifie, et le résultat attendu. Si vous ne pouvez pas écrire cette vérification, le critère n’est pas terminé. Ici : --category " Billing " donne selected 2 sur data/tickets.csv.

À vous : rendez les critères de Tomás vérifiables

Section intitulée « À vous : rendez les critères de Tomás vérifiables »

Tomás a écrit trois autres lignes pour une version ultérieure de l’option. Réécrivez chacune comme un critère d’acceptation, avec une commande sur data/tickets.csv et le résultat attendu. Utilisez le tableau des billets ouverts ci-dessus, et pensez à --status.

  1. « L’option devrait fonctionner avec les autres options. »
  2. « Les entrées incorrectes devraient être traitées. »
  3. « Le rapport ne devrait pas se dégrader. »
Afficher un exemple de réponse

Il existe plusieurs bonnes réponses. Vérifiez que chacune des vôtres contient une commande et un résultat exact.

  1. Avec --status, les catégories s’appliquent seulement à ce statut. --status pending --category billing conserve seulement T-1004, le seul billet billing en attente. Résultat attendu : selected 1, by_category {"billing": 1}, average_priority 2,0. Dans data/tickets.csv, les billets en attente sont T-1004 (billing, priorité 2) et T-1010 (LOGIN, priorité 1).
  2. « Entrée incorrecte » doit préciser l’entrée. Par exemple : « Un nom vide est une erreur : --category "" donne le code de sortie 2 et le message --category needs a name (un nom est requis pour –category). » C’est une nouvelle décision. Grace doit l’accepter avant son ajout à la fiche. Le critère 6 couvre déjà un nom qu’aucun billet ne possède : ce n’est pas une erreur.
  3. « Ne pas se dégrader » signifie « rester identique », et vous pouvez vérifier cela. « Sans --category, le rapport de data/tickets.csv est exactement le même qu’aujourd’hui : tests/test_baseline.py réussit. » Le critère 4 le dit déjà.

Les deux derniers montrent un résultat fréquent : une ligne vague cache une nouvelle décision ou un critère que vous avez déjà.

Vérifiez votre compréhension

Nommez les cinq parties d'une fiche de tâche. Donnez une ligne de la fiche d'Amira pour chaque partie.

Afficher la réponse
  • Comportement observé : « python -m ticket_cleaner data/tickets.csv compte toujours toutes les catégories du statut choisi. »
  • Comportement attendu : « --category billing compte seulement les billets de facturation ayant le statut choisi. »
  • Entrées : data/tickets.csv et l’option --category NAME, qui peut être fournie plusieurs fois.
  • Contraintes : « Modifiez seulement cli.py, report.py, README.md et les tests. Aucune nouvelle dépendance. »
  • Preuves d’achèvement : « python -m pytest réussit, avec de nouveaux tests pour les critères 1 à 6 ». Les commandes des critères 1, 3 et 6 donnent les résultats attendus.

Vérifiez votre compréhension

Prédisez : avec data/tickets.csv, que donnent --category billing --category shipping et --category garden pour « selected »? Expliquez à partir des quatre billets ouverts.

Afficher la réponse

Les billets ouverts sont T-1001 (billing), T-1003 (login), T-1005 (billing) et T-1015 (shipping). --category billing --category shipping conserve T-1001, T-1005 et T-1015 : selected (nombre sélectionné) vaut 3, et by_category (par catégorie) vaut {"billing": 2, "shipping": 1}. Aucun billet n’a la catégorie garden, donc selected vaut 0, by_category vaut {}, et le code de sortie vaut 0 (critère 6). Vous pouvez prédire les deux résultats avant d’écrire du code. C’est ce qui en fait des critères.

Vérifiez votre compréhension

Tomás dit : « La demande vague a donné moins de différences, et les 29 tests ont réussi. Un changement plus petit est meilleur. C'était donc le meilleur résultat. » Répondez-lui à partir des sessions enregistrées.

Afficher la réponse

La taille n’est pas la mesure. La demande d’une phrase a modifié 4 fichiers (+77 −3). Ses tests ont réussi, mais seulement 4 des 8 vérifications cachées ont réussi. Elle acceptait une seule catégorie, exigeait une correspondance exacte du nom et ajoutait "category": null à chaque rapport. Ses tests ont réussi parce que l’assistant les avait écrits pour ses propres décisions. Les sessions utilisant la fiche ont modifié plus de lignes et réussi les 8 vérifications. Sans critères écrits, personne ne pouvait dire que le petit changement était incorrect.

Récapitulatif

  • Une demande vague laisse des décisions ouvertes, et l’assistant les prend. « Ajoutez un moyen de filtrer le rapport par catégorie » a donné une seule catégorie, une correspondance exacte et une nouvelle clé dans chaque rapport. Ses propres tests ont réussi.
  • Une fiche de tâche comprend cinq parties : comportement observé, comportement attendu, entrées, contraintes et preuves d’achèvement.
  • Un critère d’acceptation décrit un comportement qu’une vérification peut confirmer ou non. Écrivez la commande et le résultat attendu, calculé à la main, avant d’écrire du code.
  • Avec la fiche, les deux modèles enregistrés ont réussi les 8 vérifications. Le plus petit ensemble de différences était incorrect, et la fiche n’a pas éliminé le besoin de révision.
  • Votre projet contient la fiche dans docs/tasks/category-option.md, enregistrée dans un commit (enregistrement des modifications) sur feature/category-option.

Ensuite, vous rédigez la deuxième tâche, le bogue de Grace, et vous choisissez ce que l’assistant doit voir.

Leçon suivante : Fournir le contexte utile