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.
Leçon 4 sur 15 · Développement logiciel assisté par l'IAProblème et critères d'acceptation
1. Mettre en place un environnement de travail sûr
2. Rédiger des tâches exploitables
3. Réviser le travail généré
4. Déboguer et tester avec l'assistant
5. Livrer un travail facile à maintenir
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 main
Ce que vous devez savoir
- Le point de départ propre et le test de référence de base, dans Préparer le dépôt.
- Les options et les codes de sortie d’un programme en ligne de commande, dans L’interface en ligne de commande du cours Python pour l’ingénierie de l’IA en pratique.
- Comment un test vérifie un comportement, dans Des tests ciblés.
Ce qu’il vous faut sur votre ordinateur
- Le projet
~/projects/ticket-cleaner-assistdu module 1, sur la branchefeature/category-option, avec son environnement actif.python -m pytestaffiche25 passed(25 tests réussis), etgit statusindiqueworking 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/.
Un gâteau pour samedi
Section intitulée « Un gâteau pour samedi »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) :
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 :
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 Billingne trouve rien, parce que le rapport indiquebilling. - 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 :
- Comportement observé : ce qui se passe maintenant. Utilisez une commande et sa sortie réelle.
- Comportement attendu : ce qui devrait se passer après le changement.
- Entrées : les fichiers, les options et les exemples que la tâche utilise.
- Contraintes : les limites. Quels fichiers peuvent changer, aucune nouvelle dépendance, les règles de style.
- 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.
Un petit exemple : une phrase devient deux critères
Section intitulée « Un petit exemple : une phrase devient deux critères »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 billingconserve T-1001 et T-1005. Doncselectedvaut 2,by_categoryvaut{"billing": 2}, etaverage_priorityvaut (2 + 3) / 2 = 2,5. - Deux catégories.
--category billing --category shippingconserve trois billets. Doncselectedvaut 3, etby_categoryvaut{"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.
Larkfield : Amira écrit la fiche
Section intitulée « Larkfield : Amira écrit la fiche »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.
# 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 everycategory of the chosen status.
Expected: `python -m ticket_cleaner data/tickets.csv --category billing` countsonly 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 :
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.
- Une catégorie :
--category billingdonne selected 2, by_category{"billing": 2}et average_priority 2.5. - Plusieurs fois :
--category billing --category shippingdonne selected 3 et by_category{"billing": 2, "shipping": 1}. - Majuscules et espaces :
--category " Billing "donne le même résultat que le critère 1. - La clé « categories » seulement avec l’option :
--category Shipping --category billingdonne categories["billing", "shipping"]. Sans l’option,tests/test_baseline.pyréussit encore. - Comptes du fichier entier :
--category billingdonne encore valid_records 9 et 6 lignes rejetées, comme sans l’option. - Catégorie inconnue :
--category gardendonne selected 0, un by_category vide et le code de sortie 0. - Aide et README :
python -m ticket_cleaner --helppré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.
Ajoutez la fiche à votre projet
Section intitulée « Ajoutez la fiche à votre projet »-
Vérifiez l’état de départ.
git statusdoit indiquernothing to commit, working tree clean(rien à valider, répertoire de travail propre), etpython -m pytestdoit afficher25 passed. -
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. -
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 billingSortie usage: ticket_cleaner [-h] [--status {closed,open,pending}] [--output OUTPUT]inputticket_cleaner: error: unrecognized arguments: --category billingAffichez ensuite le code de sortie. Sur macOS et Linux, exécutez
echo $?; dans PowerShell, exécutez$LASTEXITCODE. La commande affiche2: elle est incorrecte, comme l’indique le tableau des codes de sortie du README. -
Créez le dossier
docs/tasks, puis copiez-y la fiche depuis l’instantanéend-of-m02:Fenêtre de terminal mkdir -p docs/taskscp ../nextia-learning-labs/C15/snapshots/end-of-m02/docs/tasks/category-option.md docs/tasks/Fenêtre de terminal New-Item -ItemType Directory -Force docs\tasksCopy-Item ..\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.
-
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 pytestruff check .ruff format --check .Output (the end of each command) ============================== 25 passed in 0.03s ==============================All checks passed!18 files already formatted -
Faites un commit (enregistrement des modifications) de la fiche :
Fenêtre de terminal git add docs/tasks/category-option.mdgit commit -m "Write the task brief for the category option"Sortie [feature/category-option c1757ff] Write the task brief for the category option1 file changed, 39 insertions(+)create mode 100644 docs/tasks/category-option.mdVotre 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.
La même fonctionnalité, avec la fiche
Section intitulée « La même fonctionnalité, avec la fiche »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 :
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
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é.
Quand écrire une fiche, et ce qu’elle coûte
Section intitulée « Quand écrire une fiche, et ce qu’elle coûte »É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.
- « L’option devrait fonctionner avec les autres options. »
- « Les entrées incorrectes devraient être traitées. »
- « 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.
- Avec
--status, les catégories s’appliquent seulement à ce statut.--status pending --category billingconserve seulement T-1004, le seul billet billing en attente. Résultat attendu :selected1,by_category{"billing": 1},average_priority2,0. Dansdata/tickets.csv, les billets en attente sont T-1004 (billing, priorité 2) et T-1010 (LOGIN, priorité 1). - « 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. - « Ne pas se dégrader » signifie « rester identique », et vous pouvez vérifier cela. « Sans
--category, le rapport dedata/tickets.csvest exactement le même qu’aujourd’hui :tests/test_baseline.pyré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érification des connaissances
Section intitulée « Vérification des connaissances »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.csvcompte toujours toutes les catégories du statut choisi. » - Comportement attendu : «
--category billingcompte seulement les billets de facturation ayant le statut choisi. » - Entrées :
data/tickets.csvet l’option--category NAME, qui peut être fournie plusieurs fois. - Contraintes : « Modifiez seulement
cli.py,report.py,README.mdet les tests. Aucune nouvelle dépendance. » - Preuves d’achèvement : «
python -m pytestré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.
Votre réponse contient-elle les points principaux de la nôtre ?
Connectez-vous et inscrivez-vous au cours pour enregistrer vos réponses. Chaque vérification compte pour le certificat.
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.
Votre réponse contient-elle les points principaux de la nôtre ?
Connectez-vous et inscrivez-vous au cours pour enregistrer vos réponses. Chaque vérification compte pour le certificat.
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.
Votre réponse contient-elle les points principaux de la nôtre ?
Connectez-vous et inscrivez-vous au cours pour enregistrer vos réponses. Chaque vérification compte pour le certificat.
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) surfeature/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