Aller au contenu
English

Découper le travail en étapes

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

Où nous en sommes

Dans les deux dernières leçons, nous avons écrit une fiche de tâche et choisi le contexte utile. Maintenant, Amira commence la fonctionnalité, dans un code qu'elle ne connaît pas. Si elle demande toute la modification d'un coup, elle obtient des différences trop grandes pour être comprises. Dans cette leçon, nous demandons d'abord une investigation et un plan, puis une étape à la fois, et nous vérifions chaque étape avant la suivante, comme un entrepreneur prudent dans une vieille maison.

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

Ce que vous saurez faire

Quand vous découvrez le code, ne demandez pas toute la modification d’un coup. Demandez d’abord une investigation et un plan, puis une étape à la fois. Vérifiez chaque étape avant la suivante. Chaque partie reste assez petite pour être comprise.

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, avec la fiche et le rapport de bogue enregistrés dans un commit (enregistrement des modifications), et son environnement actif. python -m pytest affiche 25 passed (25 tests réussis), et git status indique working tree clean (aucune modification dans le répertoire de travail).
  • Si le projet manque ou ne fonctionne plus, suivez les étapes de réinitialisation de Contexte et limites. Puis refaites les étapes des deux dernières leçons.

Vous engagez un entrepreneur pour installer une nouvelle cuisine dans une vieille maison. Un bon entrepreneur ne commence pas par démolir les murs. Il observe d’abord : où passent les tuyaux? Ce mur soutient-il l’étage au-dessus? Puis il vous présente un plan, pièce par pièce, avec le coût de chaque partie. Vous l’approuvez. Ensuite, il réalise une partie, et vous la vérifiez ensemble avant de commencer la suivante.

Si l’entrepreneur découvre un vieux tuyau en plomb en chemin, il vous le dit. Il ne construit pas discrètement la nouvelle cuisine autour.

Amira n’a pas travaillé sur ticket-cleaner depuis le cours de Python. Dans Problème et critères d’acceptation, l’assistant a réalisé toute la fonctionnalité en un seul échange (transcription feature-bounded). Les 8 vérifications ont réussi. Mais pour accepter la modification, Amira doit lire 5 fichiers et 149 lignes modifiées d’un coup. Ils contiennent l’option, le filtre, la nouvelle clé, les tests et le README. Dans ce code qu’elle découvre, elle distingue difficilement une bonne ligne d’une ligne étrange.

Et il manque quelque chose dans cet échange. Le nouveau filtre compare les noms choisis à la catégorie de chaque billet de soutien, telle que clean_category() l’a enregistrée. Dans l’export de Grace, une catégorie enregistrée peut encore être LOGIN, à cause du bogue de Grace. Alors, --category login manque ce billet. La modification ne le signale pas, et ses tests utilisent seulement des minuscules. Personne n’a décidé cela : c’est simplement arrivé.

Quand vous découvrez le code, séparez le travail en quatre étapes :

  1. Investigation. Lisez le code et expliquez son fonctionnement actuel. Ne changez rien. Plusieurs assistants offrent un mode qui permet de répondre, mais pas de modifier les fichiers. Aider l’appelle ask mode (mode question). Dans une fenêtre de clavardage, chaque échange fonctionne ainsi.
  2. Plan. Décrivez la modification en petites étapes numérotées. Pour chacune, nommez le fichier à modifier et le test qui montre qu’elle fonctionne. Vous lisez le plan et l’approuvez, ou le modifiez.
  3. Modification d’une seule étape. Demandez seulement cette étape, puis arrêtez.
  4. Vérification. Exécutez les tests et ruff, puis lisez les différences de l’étape en gardant le plan à côté. Revenez ensuite à l’étape 3 pour la prochaine modification.

L’investigation vous donne aussi des faits : des affirmations vérifiables sur le code actuel. Un fait que la modification doit préserver peut devenir un test avant tout changement. Le test le protège ensuite à chaque étape.

Le critère 5 de la fiche précise que valid_records et rejected ne doivent pas changer avec --category. Avant d’ajouter l’option, posez une question plus simple : changent-ils actuellement avec --status?

Lisez build_summary() dans report.py : la ligne 29 est "valid_records": len(tickets),. tickets contient tous les billets valides. Le filtre de statut crée une deuxième liste, selected. Seuls les décomptes qui suivent utilisent cette liste. La réponse est donc « non ». Vérifiez-la maintenant en exécutant le programme :

Commande valid_records lignes rejetées selected
--status open 9 6 4
--status pending 9 6 2
--status closed 9 6 3

Les deux premières colonnes restent identiques; seul selected change. C’est un fait sur le code actuel. Il indique aussi où placer la nouvelle étape : après le filtre de statut, près de selected, loin de valid_records.

Cinq cases de gauche à droite. data/tickets.csv : 15 lignes. split_records : 9 billets valides, 6 lignes rejetées. filter_by_status : open, 4 billets, billing 2, login 1, shipping 1. Une case verte en pointillés, nouvelle étape 1, conserver les catégories choisies : avec --category billing, 2 billets. count_by_category et average_priority : billing 2, et 2,5. Sous split_records : valid_records 9 et rejected, 6 lignes, sont comptés ici, à partir de tous les billets; le statut et les catégories ne les changent pas, critère 5. Sous la nouvelle étape : le test issu de l'investigation fixe ce fait, valid_records reste identique pour open, pending et closed.
Où placer l'étape 1 du plan. Le programme compte les totaux du fichier avant le filtre de statut. Un filtre de catégorie placé après ne peut donc pas les changer.
Description textuelle du diagramme

Le schéma suit le fichier d’exemple dans build_summary(). data/tickets.csv contient 15 lignes. split_records() produit 9 billets valides et 6 lignes rejetées. filter_by_status() conserve les 4 billets ouverts : billing 2, login 1 et shipping 1. Vient ensuite une case verte en pointillés, la nouvelle étape 1 : conserver les catégories choisies. Avec –category billing, il reste 2 billets. Enfin, average_priority() donne 2,5, et count_by_category() donne {"billing": 2}. Une note sous split_records() précise que cette étape compte valid_records 9 et rejected, 6 lignes, à partir de tous les billets. Le statut et les catégories ne les changent donc pas. C’est le critère 5. Une deuxième note indique que le test issu de l’investigation fixe ce fait : valid_records reste identique pour open, pending et closed.

L’équipe du cours a fourni la même fiche et les mêmes cinq fichiers au même modèle, en deux échanges (transcription feature-plan-first). Au premier échange, Aider utilisait le mode question et ne pouvait donc pas modifier les fichiers. La fiche se terminait par cette demande :

Prompt (the end of turn 1)
Do not change any file yet. First read the code and explain, in a few lines, how a ticket's category goes from the input file to the report. Then propose a plan in small numbered steps. For each step, say which file changes and which test shows that the step works.

L’assistant a expliqué le déroulement, puis demandé trois autres fichiers : files.py, parsing.py et records.py. « Je ne modifierai pas ces fichiers », a-t-il ajouté. Puis il a proposé un plan en quatre étapes :

What the assistant printed (part)
1. **Add optional category filtering to the report.**
Change: `ticket_cleaner/report.py`, `tests/test_report.py`.
…
2. **Expose the repeatable CLI option.**
Change: `ticket_cleaner/cli.py`, `tests/test_cli.py`.
…
3. **Document the option.**
Change: `README.md`.
…
4. **Verify the completed change.**

Avec les trois nouveaux fichiers, il a confirmé le déroulement et trouvé quelque chose :

What the assistant printed (part)
3. `clean_category()` strips surrounding spaces and maps aliases such as `Sign-in` to `login`. **Other names retain their capitalization**—for example, `LOGIN`
stays uppercase.

C’est le bogue de Grace, découvert en lisant le code. La séance en un seul échange ne l’avait jamais mentionné.

Au deuxième échange, la requête (prompt) était courte :

Prompt (turn 2)
Do step 1 of your plan only, with its test. Then stop.

L’assistant a modifié seulement report.py et tests/test_report.py : +82 −4. Il a précisé : « Aucune modification de l’interface en ligne de commande ni de la documentation n’est incluse. » Les vérifications ont ensuite été exécutées : 33 passed, et 1 des 8 vérifications cachées. C’est le bon résultat pour l’étape 1 : l’option --category n’existe pas encore. Les vérifications qui l’utilisent doivent donc échouer.

Quatre étapes de gauche à droite, avec une flèche de la quatrième vers la troisième, nommée prochaine étape du plan. 1, Investigation : lire, ne rien changer. Échange 1, mode question : explication du parcours d'une catégorie jusqu'au rapport, demande de 3 autres fichiers, découverte que LOGIN reste en majuscules; 0 fichier modifié. 2, Plan : petites étapes numérotées; 4 étapes, chacune nomme le fichier à modifier et le test qui montre qu'elle fonctionne; vous lisez et approuvez le plan. 3, Modification d'une seule étape, puis arrêt : échange 2, faire seulement l'étape 1 du plan, avec son test, puis arrêter; 2 fichiers, plus 82 moins 4. 4, Vérification, avant la prochaine étape : 33 tests réussis; ruff format --check, 2 fichiers seraient reformatés; vérifications d'acceptation 1 sur 8, aucune option --category pour l'instant. En dessous : la même fiche d'un coup, feature-bounded, 5 fichiers, plus 145 moins 4 à réviser ensemble.
Investigation, plan, modification d'une seule étape, vérification, puis prochaine étape. Dans la séance enregistrée, le premier échange n'a rien modifié et a trouvé le bogue de Grace. Le deuxième a réalisé seulement l'étape 1.
Description textuelle du diagramme

Le schéma montre quatre étapes en ligne. Une flèche va de la quatrième à la troisième, avec l’étiquette « prochaine étape du plan ». Étape 1, investigation : lire et ne rien changer. Au premier échange, en mode question, l’assistant a expliqué le parcours d’une catégorie jusqu’au rapport. Il a demandé 3 autres fichiers et découvert que « LOGIN reste en majuscules ». Aucun fichier n’a changé. Étape 2, plan : petites étapes numérotées. Le plan comprenait 4 étapes. Chacune nommait le fichier à modifier et le test qui montre qu’elle fonctionne. Vous lisez et approuvez le plan. Étape 3, modification d’une seule étape, puis arrêt. Le deuxième échange demandait : « Faites seulement l’étape 1 de votre plan, avec son test. Puis arrêtez. » Il a modifié 2 fichiers, ajouté 82 lignes et retiré 4 lignes. Étape 4, vérification avant la prochaine étape. Les tests ont donné 33 passed. ruff format –check a indiqué que 2 fichiers seraient reformatés. Une des 8 vérifications d’acceptation a réussi, car l’option –category n’existe pas encore. Une note en dessous précise que la même fiche d’un coup (feature-bounded) a produit 5 fichiers, +145 −4, à réviser ensemble.

L’étape 1 compte 86 lignes modifiées, et non 149. Amira peut donc lire chaque ligne. Un nouveau test l’arrête :

tests/test_report.py (part of step 1)
def test_category_comparison_preserves_stored_labels():
tickets = [
Ticket(id="T-1", status="open", category="Billing", priority=3),
]
summary = build_summary(tickets, [], status="open", categories=[" billing "])
assert summary["selected"] == 1
assert summary["by_category"] == {"Billing": 1}

Au premier échange, l’assistant a découvert que LOGIN reste en majuscules. Au deuxième, il a adapté le filtre à ce comportement : il compare en minuscules, mais le rapport conserve Billing. Ce test transforme alors cette différence en promesse : by_category doit indiquer {"Billing": 1}. Quand le module Déboguer et tester avec l’assistant corrige le bogue de Grace, ce test échoue.

Voilà à quoi servent les étapes. L’investigation a trouvé un fait. La décision à son sujet revient à Amira : le bogue constitue une tâche distincte, avec son propre rapport. Le plan précise donc que l’option ne contourne pas le bogue. En révisant l’étape 1, Amira rejette ce test. La modification que l’équipe accepte dans Réviser le travail généré ne contourne pas non plus le bogue : vous le vérifiez là.

Vous faites vous-même l’investigation, ajoutez son test et enregistrez le plan dans un commit.

  1. Trouvez ce que build_summary() compte, et où :

    Fenêtre de terminal
    grep -n "def \|valid_records\|rejected" ticket_cleaner/report.py
    Output (macOS)
    4:def filter_by_status(tickets: list[Ticket], status: str = "open") -> list[Ticket]:
    9:def count_by_category(tickets: list[Ticket]) -> dict[str, int]:
    17:def average_priority(tickets: list[Ticket]) -> float | None:
    24:def build_summary(tickets: list[Ticket], rejected: list[Rejected], status: str) -> dict:
    29: "valid_records": len(tickets),
    33: "rejected": [{"row": r.row, "problems": r.problems} for r in rejected],
  2. Vérifiez le fait avec le programme. Exécutez-le trois fois, avec --status open, --status pending et --status closed. Après chaque exécution, ouvrez reports/summary.json :

    Fenêtre de terminal
    python -m ticket_cleaner data/tickets.csv --status pending

    Chaque rapport contient "valid_records": 9 et les mêmes six lignes rejetées. selected vaut 4, 2 et 3, comme dans le tableau ci-dessus.

  3. Fixez le fait dans un test. Copiez tests/test_report.py depuis l’instantané end-of-m02, puis regardez les différences :

    Fenêtre de terminal
    cp ../nextia-learning-labs/C15/snapshots/end-of-m02/tests/test_report.py tests/
    git diff
    Output (the end)
    @@ -30,3 +30,11 @@ def test_summary_for_a_status_with_no_tickets(tickets):
    assert summary["selected"] == 0
    assert summary["by_category"] == {}
    assert summary["average_priority"] is None
    +
    +
    +def test_whole_file_counts_do_not_depend_on_the_status(tickets):
    + rejected = [Rejected(row=4, problems=["missing id"])]
    + for status in ("open", "pending", "closed"):
    + summary = build_summary(tickets, rejected, status=status)
    + assert summary["valid_records"] == 3
    + assert summary["rejected"] == [{"row": 4, "problems": ["missing id"]}]

    Les différences ajoutent aussi Rejected à l’importation en haut du fichier. Le test utilise la fixture tickets du fichier : trois billets, deux ouverts et un fermé. Pour chaque statut, il vérifie que valid_records vaut 3 et que rejected reste identique.

  4. Exécutez les tests :

    Fenêtre de terminal
    python -m pytest
    Output (the end)
    ============================== 26 passed in 0.04s ==============================
  5. Facultatif : vérifiez que le test peut échouer. Dans ticket_cleaner/report.py, remplacez la ligne 29 par "valid_records": len(selected),, puis exécutez python -m pytest tests/test_report.py :

    Sortie (extrait)
    E assert 2 == 3
    FAILED tests/test_report.py::test_whole_file_counts_do_not_depend_on_the_status
    ========================= 1 failed, 4 passed in 0.02s ==========================

    Avec open, le filtre de statut conserve deux des trois billets. Le code incorrect donne donc 2. Rétablissez ensuite la ligne avec git restore ticket_cleaner/report.py.

  6. Copiez le plan et exécutez les vérifications :

    Fenêtre de terminal
    cp ../nextia-learning-labs/C15/snapshots/end-of-m02/docs/tasks/category-option-plan.md docs/tasks/
    Fenêtre de terminal
    python -m pytest
    ruff check .
    ruff format --check .
    Output (the end of each command)
    ============================== 26 passed in 0.03s ==============================
    All checks passed!
    20 files already formatted
  7. Enregistrez le test et le plan dans le même commit :

    Fenêtre de terminal
    git add tests/test_report.py docs/tasks/category-option-plan.md
    git commit -m "Plan the category option, and pin what the investigation found"
    Sortie
    [feature/category-option c15e9d8] Plan the category option, and pin what the investigation found
    2 files changed, 43 insertions(+), 1 deletion(-)
    create mode 100644 docs/tasks/category-option-plan.md

Voici le plan d’Amira :

docs/tasks/category-option-plan.md
# Plan: the --category option
Written before any change, after reading `cli.py`, `report.py`, `parsing.py`
and the tests.
## How a category reaches the report now
1. `files.read_rows` reads each row as text.
2. `parsing.to_ticket` cleans it: `clean_category` changes the web form's
names (`Sign-in` to `login`).
3. `report.build_summary` keeps the tickets of the chosen status
(`filter_by_status`), then counts them by category (`count_by_category`).
4. `cli.main` saves the summary as JSON.
`valid_records` and `rejected` come from all the tickets, before the status is
chosen. A test now shows that (`test_whole_file_counts_do_not_depend_on_the_status`).
## Found while reading
`clean_category` keeps the capital letters of a name that is not one of the
web form's names, so `LOGIN` and `login` are two categories. That is Grace's
bug (`docs/tasks/category-names-bug.md`), a separate task. The option compares
the chosen names with the stored category, and does not work around the bug.
## Steps
| Step | Change | File | Test that shows it works |
|---|---|---|---|
| 1 | Keep the tickets of the chosen categories, after the status | `report.py` (`build_summary` gets `categories`) | `test_report.py`: one, two, none, an unknown category |
| 2 | Add `--category` (repeatable) and pass it on | `cli.py` | `test_cli.py`: the command with `--category " Billing "` |
| 3 | Add the `categories` key only when the option is used | `report.py` | `test_baseline.py` still passes; a new test for the key |
| 4 | Describe the option | `README.md`, `--help` | `test_cli.py`: `--help` shows `--category` |
After each step: `python -m pytest`, `ruff check .`, `ruff format --check .`.

Il suit la même structure que le plan de l’assistant, avec deux différences. Il consigne la découverte et la décision d’Amira à son sujet. Et chaque étape possède son propre test, pour que l’étape de vérification ait quelque chose à exécuter.

Découpez le travail quand vous découvrez le code, quand la modification touche plusieurs fichiers ou quand une étape est difficile à annuler. Un plan aide aussi le réviseur : la demande de tirage (pull request) peut le suivre, étape par étape.

Cela demande plus d’échanges. La séance avec plan préalable a fait 3 appels au modèle et coûté 0.050 $ US, pour réaliser seulement l’étape 1. La fonctionnalité complète en un échange a fait 1 appel et coûté 0.032 $ US. Le coût principal reste votre temps : vous lisez un plan et approuvez chaque étape. Les prix changent. Avec une offre gratuite ou sans assistant, vous ne payez rien.

Ne planifiez pas une correction d’une ligne dans du code que vous connaissez : le plan serait plus long que la modification. Et un plan n’est pas une promesse. Si l’étape 2 montre que l’étape 3 est incorrecte, modifiez le plan dans le fichier et dites pourquoi.

Erreur courante

L'étape réussit ses tests et échoue à la vérification du format

Symptôme : après l’étape 1, python -m pytest affiche 33 passed (33 tests réussis). Mais ruff format --check . affiche 2 files would be reformatted (2 fichiers seraient reformatés). C’est arrivé dans la séance enregistrée.

Cause : l’assistant a écrit des lignes plus longues que la limite du projet. Les tests vérifient le comportement, pas le style. Ils ne peuvent donc pas détecter cela. Une étape « terminée » selon ses tests ne l’est pas selon la fiche. Ses contraintes exigent que ruff format --check . réussisse.

Correction : vérifiez chaque étape avec les trois vérifications du plan, pas seulement les tests. Exécutez ruff format ., puis lisez git diff, car cette commande modifie les fichiers. Le fichier de périmètre le précise aussi. Refaites ensuite les trois vérifications avant la prochaine étape.

Exercice du module : une demande de fonctionnalité et un rapport de bogue minimal

Section intitulée « Exercice du module : une demande de fonctionnalité et un rapport de bogue minimal »

La tâche pratique du module : rédiger une demande de fonctionnalité et un rapport de bogue minimal pour le projet d’exercice, comme Amira. Travaillez dans une copie jetable pour garder votre projet tel quel.

  1. Dans ~/projects, copiez l’instantané end-of-m02 dans un nouveau dossier, ticket-cleaner-try. Créez son environnement et vérifiez que python -m pytest affiche 26 passed (26 tests réussis).
  2. La fonctionnalité. Grace demande : « Le rapport peut-il aussi indiquer combien de billets sélectionnés sont urgents? » Dans ticket-cleaner, la priorité 1 est le niveau le plus urgent : Ticket.is_urgent() renvoie True pour ce niveau. Rédigez docs/tasks/urgent-count.md avec les cinq parties d’une fiche. Donnez au moins trois critères avec des commandes sur data/tickets.csv et les valeurs exactes attendues.
  3. Le bogue. L’équipe de Grace dit qu’un nouveau formulaire envoie la catégorie log in, avec une espace. Créez une entrée minimale de deux lignes et exécutez le programme avec elle. Rédigez ensuite docs/tasks/log-in-bug.md : l’observation, le résultat attendu, l’exemple minimal, les références aux fichiers et les éléments non touchés. Est-ce encore le bogue de Grace?
  4. Supprimez le dossier quand vous avez terminé.
Afficher un exemple de réponse

Les valeurs. Les billets ouverts de data/tickets.csv sont T-1001 (priorité 2), T-1003 (1), T-1005 (3) et T-1015 (2) : un billet urgent. En attente : T-1004 (2) et T-1010 (1) : un. Fermés : T-1002 (3), T-1006 (1) et T-1012 (3) : un.

docs/tasks/urgent-count.md (example)
# Task: count the urgent tickets in the report
Request: Grace wants to see how many of the selected tickets are urgent.
Observed now: the report has no count of urgent tickets.
Expected: the report has a key "urgent": the number of selected tickets
with priority 1.
## Acceptance criteria
1. `python -m ticket_cleaner data/tickets.csv` gives "urgent": 1 (T-1003).
2. With `--status pending`, "urgent" is 1 (T-1010); with `--status closed`,
it is 1 (T-1006).
3. With no selected tickets, "urgent" is 0, not null.
4. Every other key of the report stays the same. `tests/test_baseline.py`
gets the new key in the same commit, after Grace confirms that her
spreadsheet accepts it.
## Constraints
- Change only ticket_cleaner/report.py, README.md and the tests. No new
dependency. `ruff check .` and `ruff format --check .` pass.
## Evidence of done
- `python -m pytest` passes, with new tests for criteria 1 to 3.
- The commands of criteria 1 and 2 give the values above.

Le critère 4 est le plus difficile. Une nouvelle clé change chaque rapport. Le test de référence de base du module Mettre en place un environnement de travail sûr doit donc échouer. La fiche le précise et nomme la décision que Grace doit prendre d’abord.

Le bogue. L’entrée minimale et son résultat :

two-names.csv
id,status,category,priority,subject
T-1,open,login,1,One
T-2,open,log in,1,Two

python -m ticket_cleaner two-names.csv --output reports/two-names.json affiche 2 rows: 2 valid, 0 rejected. (2 lignes : 2 valides, 0 rejetée). Le rapport contient :

"by_category": {
"log in": 1,
"login": 1
},
  • Résultat attendu : {"login": 2}, si Grace confirme que log in désigne l’équipe login.
  • Références aux fichiers : ticket_cleaner/records.py : CATEGORY_ALIASES contient log-in et sign-in, mais pas log in. ticket_cleaner/parsing.py : clean_category() y cherche les noms.
  • Éléments non touchés, et différence avec le bogue de Grace : log in est en minuscules. Les majuscules ne sont donc pas la cause. Le nom manque dans la liste des noms du formulaire Web. Corriger seulement le bogue de Grace ne corrige pas celui-ci. Précisez-le dans le rapport pour que personne ne fusionne les deux.

Pour terminer le module, une autre personne doit pouvoir vérifier votre tâche sans deviner ce que vous vouliez dire. Vérifiez votre propre fiche avec ces quatre questions. Répondez à chacune par oui ou non :

  1. Chaque critère a-t-il une commande ou un test, avec un résultat attendu exact?
  2. Avez-vous calculé les résultats attendus avant d’écrire du code?
  3. Les contraintes nomment-elles les fichiers qui peuvent changer?
  4. Un collègue qui n’a pas lu le courriel de Grace pourrait-il décider « terminé » ou « non terminé » avec votre fiche seulement?

Appliquez ensuite ces questions à cette fiche de Tomás :

Tomás's brief
# Task: urgent tickets
Add the urgent tickets to the report. Make sure it works and is tested.
Don't break anything.
Afficher la réponse

Elle ne satisfait à aucune des quatre questions. « Ajouter les billets urgents » peut désigner un nombre, une liste d’identifiants ou un filtre. « Vérifier que ça fonctionne » ne donne aucune commande ni valeur attendue. Rien ne nomme les fichiers. « Ne rien briser » ne précise pas si une nouvelle clé est permise dans chaque rapport. Un collègue doit demander à Tomás, et un assistant déciderait seul, comme dans la session vague. L’exemple de réponse de l’exercice du module satisfait aux quatre questions.

Vous avez terminé le module quand vous pouvez aussi montrer ces résultats dans votre propre projet :

  • git log --oneline montre six commits (enregistrements des modifications) sur feature/category-option. Les trois derniers sont Write the task brief for the category option (rédiger la fiche de tâche pour l’option de catégorie), Write Grace's bug report with a minimal input (rédiger le rapport de bogue de Grace avec une entrée minimale) et Plan the category option, and pin what the investigation found (planifier l’option de catégorie et fixer les constats de l’investigation).

  • python -m pytest affiche 26 passed (26 tests réussis), et ruff format --check . affiche 20 files already formatted (20 fichiers déjà formatés).

  • Sur macOS et Linux, cette commande n’affiche rien, car votre projet correspond à l’instantané end-of-m02 :

    Fenêtre de terminal
    diff -rq . ../nextia-learning-labs/C15/snapshots/end-of-m02 -x .git -x .venv -x reports -x __pycache__ -x .pytest_cache -x .ruff_cache

Réinitialisation. Si votre projet ne fonctionne plus, suivez les étapes de réinitialisation de Contexte et limites. Utilisez l’instantané end-of-m02 à la place de end-of-m01. La dernière ligne de python -m pytest est alors 26 passed.

Vérifiez votre compréhension

Nommez les quatre étapes d'une modification dans du code inconnu. Dites ce que chacune a produit dans la session enregistrée feature-plan-first.

Afficher la réponse
  • Investigation : tour 1, en mode question. L’assistant a expliqué comment une catégorie arrive au rapport, demandé trois autres fichiers et constaté que LOGIN reste en majuscules. Aucun fichier n’a changé.
  • Planification : quatre étapes numérotées, chacune avec les fichiers à modifier et les tests.
  • Modification d’une seule étape : tour 2, « Faites seulement l’étape 1 de votre plan, avec son test. Puis arrêtez. » Deux fichiers, +82 −4.
  • Vérification : 33 passed (33 tests réussis), mais ruff format --check . a échoué pour 2 fichiers. Une des 8 vérifications cachées a réussi, ce qui est normal pour l’étape 1. La révision a trouvé un test qui transforme le bogue de Grace en promesse.

Vérifiez votre compréhension

Pourquoi le test test_whole_file_counts_do_not_depend_on_the_status précède-t-il toute modification, et que protège-t-il à l'étape 1?

Afficher la réponse

Il fixe un fait du code actuel : valid_records et rejected décrivent le fichier entier, quel que soit le statut. L’investigation a révélé ce fait en lisant la ligne 29 de report.py et en exécutant trois statuts. Un test écrit avant la modification protège ce fait à chaque étape. L’étape 1 ajoute un filtre à côté du filtre de statut. Si le filtre est mal placé et que les totaux du fichier entier commencent à le suivre, ce test échoue. Cela enfreindrait le critère 5 de la fiche.

Vérifiez votre compréhension

Au tour 1, l'assistant a constaté que LOGIN reste en majuscules. Au tour 2, il a écrit un test qui affirme {'Billing': 1}. Que doit faire Amira, et pourquoi est-ce sa décision?

Afficher la réponse

Elle rejette ce test et inscrit le constat dans le plan comme tâche distincte : le bogue de Grace, avec son propre rapport. Le test transforme le bogue en promesse, donc la correction du module 4 le ferait échouer. Un assistant peut découvrir un fait, mais la décision revient à la personne responsable de la tâche. Est-ce un bogue, cette modification doit-elle le contourner, et qui doit donner son accord? Ici, Grace l’a déjà signalé, donc l’option ne le contourne pas.

Récapitulatif

Cette leçon

  • Dans du code inconnu, séparez quatre étapes : investigation, planification, modification d’une seule étape, vérification. Passez ensuite à l’étape suivante.
  • L’investigation enregistrée n’a rien changé et a découvert le bogue de Grace. L’étape 1 seule représentait +82 −4, assez peu pour tout lire. La révision a trouvé un test qui transformait le bogue en promesse.
  • Une investigation fournit des faits. Avant la modification, fixez dans un test un fait qu’elle doit préserver : test_whole_file_counts_do_not_depend_on_the_status.
  • Le constat vient de l’assistant; la décision vous appartient.

Module 2 : rédiger des tâches exploitables

  • Une fiche de tâche contient le comportement observé et attendu, les entrées, les contraintes et les preuves que la tâche est terminée. Ses critères d’acceptation ont chacun une vérification avec un résultat exact.
  • Le contexte utile comprend l’observation, le résultat attendu, un exemple minimal, les références aux fichiers et les interfaces, sans aucun secret.
  • Votre projet correspond à end-of-m02 : six commits sur feature/category-option et 26 passed.

Ensuite, dans le module 3, vous recevez une modification de l’assistant pour la fonctionnalité et vous la révisez ligne par ligne.

Leçon suivante : Examiner les différences