Fournir le contexte utile
- Leçon 5
- 40 min
- Module 2 : Rédiger des tâches exploitables
Où nous en sommes
Dans la dernière leçon, nous avons écrit une fiche de tâche pour la fonctionnalité, et les modifications de l'assistant sont devenues vérifiables. Vient maintenant le bogue de Grace. L'assistant ne sait rien de notre projet, sauf ce que nous lui envoyons, et avec le mauvais fichier, il cherche au mauvais endroit. Dans cette leçon, nous choisissons ce qu'il doit voir pour cette seule tâche, et rien de plus, comme un appel clair au garage au sujet d'un bruit étrange.
Leçon 5 sur 15 · Développement logiciel assisté par l'IAFournir le contexte utile
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
Donnez à l’assistant ce dont un nouveau collègue aurait besoin pour cette seule tâche. Cela comprend l’observation exacte, le résultat attendu, un petit exemple, ainsi que les fichiers et les noms importants. Omettez tout le reste et n’incluez jamais de secret.
Avant de commencerCe qu’il faut savoir et avoir sous la main
Ce que vous devez savoir
- Les descriptions de tâches et les critères d’acceptation, présentés dans Problème et critères d’acceptation.
- Le plan du dépôt et ce qu’un agent envoie au modèle, présentés dans Modes d’interaction avec l’assistant.
- Comment
ticket-cleanernettoie une ligne (parsing.py) et la compte (report.py), présenté dans Les enregistrements structurés du cours de Python.
Ce qu’il vous faut sur votre ordinateur
- Le projet
~/projects/ticket-cleaner-assist, avec la description de la dernière leçon enregistrée dans un commit (enregistrement des changements), et son environnement actif.python -m pytestaffiche25 passed(25 tests réussis), etgit statusindiqueworking tree clean(répertoire de travail sans modifications). - Si le projet manque ou ne fonctionne plus, suivez les étapes de réinitialisation de Contexte et limites. Refaites ensuite Ajoutez la fiche à votre projet.
Téléphoner au garage
Section intitulée « Téléphoner au garage »Votre voiture fait un bruit étrange, alors vous téléphonez au garage. « Ma voiture fait du bruit. Pouvez-vous la réparer? » Le mécanicien ne peut que poser des questions : quel bruit, quand, d’où vient-il?
Comparez : « Un grincement aigu vient de la roue avant gauche quand je freine. Ça a commencé mardi et ça cesse après dix minutes de conduite. Je l’ai enregistré : voici une vidéo de dix secondes. » Le mécanicien sait maintenant quoi examiner d’abord et comment vérifier la réparation.
Vous n’avez pas envoyé tout l’historique d’entretien de la voiture, vos documents d’assurance ni la clé de votre maison. Le mécanicien n’en a pas besoin pour ce bruit, et certains sont privés.
Le problème : l’assistant voit la mauvaise partie
Section intitulée « Le problème : l’assistant voit la mauvaise partie »L’équipe du cours a soumis le bogue de Grace à l’assistant avec très peu d’information. Un seul fichier, ticket_cleaner/report.py, aucun plan du dépôt et une phrase (transcription bug-little-context) :
The categories in the report are wrong. Fix it.L’assistant n’a rien changé. Il a répondu par une question :
Could you share a sample of the incorrect category counts and the expected result? Currently, the report counts categories only for tickets matching therequested status, and treats category names with different capitalization or whitespace as distinct. Which behavior should change?Cette fois, l’assistant a posé une question au lieu de deviner. C’est bien, mais ne comptez pas là-dessus : une autre exécution ou un autre modèle peut deviner. Et regardez ce qu’il pouvait voir. report.py compte les catégories qu’il reçoit. Le bogue n’est pas là. La cause est dans parsing.py, que l’assistant n’a jamais vu. Il s’est même trompé au sujet des espaces : le programme les supprime déjà, dans un fichier qu’il ne pouvait pas lire.
La session a donc consommé 2,220 jetons (tokens) sans rien changer. La requête n’avait ni observation, ni résultat attendu, ni exemple. Son seul fichier était l’endroit où le bogue se manifeste, pas celui où il se trouve.
L’idée : le contexte utile
Section intitulée « L’idée : le contexte utile »Le contexte d’une requête comprend tout ce que le modèle reçoit avec elle. Cela comprend votre requête (prompt), les fichiers, le plan du dépôt et les échanges précédents de la conversation. Le modèle travaille uniquement à partir de son contexte. Il ne sait rien d’autre de votre projet.
Le contexte utile est la partie dont cette tâche a besoin. Pour un bogue ou un changement, il comprend cinq types d’information :
- L’observation : la commande exécutée et sa sortie exacte ou son message d’erreur, collés, sans reformulation.
- Le résultat attendu : ce que la sortie devrait être.
- Un exemple minimal : la plus petite entrée qui montre encore le problème.
- Les références de fichiers : où se trouve le code, avec les chemins.
- Les interfaces : les noms et les signatures que le changement doit conserver, comme
clean_category(value: object) -> str.
Omettez ce qui est inutile à la tâche : d’autres fichiers, le fichier de données complet, les journaux (logs) du mois dernier. N’incluez jamais de secret, comme le jeton dans .env, ni les données personnelles de vrais clients. Plus de texte ne donne pas un meilleur contexte. Il consomme des jetons et multiplie les endroits où le modèle peut chercher. Chaque ligne collée quitte votre ordinateur.
Un tout petit exemple : de douze lignes à deux
Section intitulée « Un tout petit exemple : de douze lignes à deux »L’exportation de Grace contient 12 lignes. Lesquelles montrent le bogue? Regardez une seule équipe, celle des connexions. L’exportation contient quatre billets de soutien liés aux connexions, écrits de quatre façons : login, Sign-in, Login et LOGIN. Sign-in est un nom du formulaire Web, donc il devient déjà login. Il ne reste que les majuscules comme différence.
Deux lignes suffisent donc : une login et une LOGIN, toutes deux ouvertes.
id,status,category,priority,subjectT-1,open,login,1,OneT-2,open,LOGIN,1,TwoRésultat attendu : {"login": 2}, car les deux billets appartiennent à l’équipe des connexions. Si le programme donne {"LOGIN": 1, "login": 1}, le bogue est présent. Il tient en deux lignes que tout le monde peut lire en cinq secondes. Un exemple minimal, c’est cela : la plus petite entrée qui échoue encore. Reproduire d’abord montre comment en créer un, étape par étape.
Trouver où se trouve le bogue
Section intitulée « Trouver où se trouve le bogue »Grace voit le bogue dans le rapport. Mais où une catégorie reçoit-elle son texte? Le schéma suit une ligne dans le programme :
Description textuelle du diagramme
Le schéma suit une ligne avec la catégorie LOGIN dans le programme, en cinq étapes. D’abord, le fichier de données contient la ligne. Ensuite, read_rows() dans files.py lit la ligne comme du texte : « LOGIN ». Troisièmement, clean_category() dans parsing.py, en rouge, cherche le nom en minuscules parmi les noms du formulaire Web. « login » n’est pas un nom du formulaire Web, donc la fonction renvoie le texte d’origine, « LOGIN ». Le schéma indique à cette étape : la cause est ici. Quatrièmement, count_by_category() dans report.py compte le texte tel quel : {"LOGIN": 1, "login": 1}. Cinquièmement, reports/summary.json affiche deux lignes pour une équipe. Les étapes quatre et cinq portent la mention : le symptôme apparaît ici. Une note en pointillés sous report.py indique qu’il était le seul fichier de la session avec trop peu de contexte. Une note en pointillés sous les étapes du milieu énumère les fichiers de la session avec le contexte utile. Ce sont parsing.py, records.py avec les noms du formulaire Web, et tests/test_parsing.py.
Vous n’avez pas à deviner les fichiers. Cherchez le mot category dans le code :
grep -n category ticket_cleaner/*.pySelect-String -Pattern category -Path ticket_cleaner\*.pyticket_cleaner/parsing.py:18:def clean_category(value: object) -> str:ticket_cleaner/parsing.py:19: """Return the category, with the web form's names changed to the report's names."""ticket_cleaner/parsing.py:48: category=clean_category(raw["category"]),ticket_cleaner/records.py:5:REQUIRED_FIELDS = ("id", "status", "category", "priority")ticket_cleaner/records.py:21: category: strticket_cleaner/report.py:9:def count_by_category(tickets: list[Ticket]) -> dict[str, int]:ticket_cleaner/report.py:10: """Return the number of tickets in each category, sorted by category."""ticket_cleaner/report.py:13: counts[ticket.category] = counts.get(ticket.category, 0) + 1ticket_cleaner/report.py:31: "by_category": count_by_category(selected),Trois fichiers mentionnent les catégories. report.py ne fait que compter. records.py contient le champ, ainsi que les noms du formulaire Web, CATEGORY_ALIASES, quelques lignes après la ligne 5. parsing.py contient la fonction qui produit le texte : clean_category(), appelée à la ligne 48. C’est là qu’il faut chercher d’abord. Ce sont les références de fichiers à joindre au rapport de bogue.
Rédiger le rapport de bogue
Section intitulée « Rédiger le rapport de bogue »Amira rédige un court rapport de bogue avec les cinq types de contexte. Vous créez l’entrée minimale, observez vous-même le bogue et ajoutez le rapport au projet.
-
Exécutez le programme sur l’exportation de Grace et ouvrez le rapport :
Fenêtre de terminal python -m ticket_cleaner data/web-form-export.csvSortie 12 rows: 12 valid, 0 rejected.Report: reports/summary.jsonDans
reports/summary.json,by_categorycontient sept lignes :reports/summary.json (part) "by_category": {"Billing": 1,"LOGIN": 1,"Login": 1,"account": 1,"billing": 2,"login": 2,"shipping": 2}, -
Dans votre éditeur, créez un fichier
minimal.csvdans le dossier du projet. Ajoutez les trois lignes du petit exemple ci-dessus. -
Exécutez le programme sur ce fichier. Écrivez le rapport dans un nouveau fichier pour conserver celui de l’exportation :
Fenêtre de terminal python -m ticket_cleaner minimal.csv --output reports/minimal.jsonSortie 2 rows: 2 valid, 0 rejected.Report: reports/minimal.jsonreports/minimal.jsoncontient"by_category": {"LOGIN": 1, "login": 1}, sur quatre lignes. Les deux lignes sont valides, donc le programme n’affiche aucun avertissement : rien n’indique à Grace qu’il y a un problème. -
Copiez le rapport de bogue depuis l’instantané
end-of-m02:Fenêtre de terminal cp ../nextia-learning-labs/C15/snapshots/end-of-m02/docs/tasks/category-names-bug.md docs/tasks/Fenêtre de terminal Copy-Item ..\nextia-learning-labs\C15\snapshots\end-of-m02\docs\tasks\category-names-bug.md docs\tasks\ -
Supprimez
minimal.csv. Le rapport de bogue contient ses trois lignes, donc tout le monde peut le recréer. Sous Windows, utilisezRemove-Item minimal.csv.Fenêtre de terminal rm minimal.csv -
Vérifiez et créez un commit :
Fenêtre de terminal ruff format --check .git add docs/tasks/category-names-bug.mdgit commit -m "Write Grace's bug report with a minimal input"Sortie 19 files already formatted[feature/category-option de7db2e] Write Grace's bug report with a minimal input1 file changed, 48 insertions(+)create mode 100644 docs/tasks/category-names-bug.md
Voici le rapport. Repérez les cinq types de contexte :
# Bug: one team appears under several category names
Reported by: Grace (support lead), with this week's export from the new webform (`data/web-form-export.csv`).
## Steps to reproduce
1. Make a file `minimal.csv` with two tickets of the same team:
```text id,status,category,priority,subject T-1,open,login,1,One T-2,open,LOGIN,1,Two ```
2. Run `python -m ticket_cleaner minimal.csv --output reports/minimal.json`.
## Observed
`"by_category": {"LOGIN": 1, "login": 1}`: two lines for one team.
With Grace's export, the report has `Billing`, `LOGIN` and `Login` next to`billing` and `login`.
## Expected
`"by_category": {"login": 2}`. Capital letters and spaces around a category donot make a new category, as for the status and the ID. With Grace's export:account 1, billing 3, login 4, shipping 2.
## Not affected
The web form's other names (`Sign-in`, `Invoice`, `Delivery`) are alreadycounted under the report's names.
## Environment
The same result in a new virtual environment made from`requirements-lock.txt` (Python 3.14), and in Grace's own environment: not anenvironment problem. The rows are valid, so no warning is printed.
## Evidence of done
- A regression test with the two rows above fails on the current code and passes after the fix.- Grace's export gives one line per team.- All other tests and the sample file's report (`tests/test_baseline.py`) are unchanged.L’observation et le résultat attendu sont exacts. L’exemple contient deux lignes. « Not affected » (non touché) et « Environment » (environnement) évitent au lecteur deux fausses pistes. Le rapport n’a aucune référence de fichier : Grace n’est pas développeuse. Amira les ajoute dans la requête, à partir de la recherche ci-dessus. Le rapport ne dit pas non plus comment corriger le bogue. C’est le travail de la personne qui le corrige.
Le même bogue, avec le contexte utile
Section intitulée « Le même bogue, avec le contexte utile »Une deuxième session a reçu plus d’information (transcription bug-relevant-context). Elle avait le courriel de Grace, les deux lignes avec les résultats observé et attendu, trois fichiers et le plan du dépôt. La requête se terminait par les références de fichiers et une contrainte :
The categories are cleaned in ticket_cleaner/parsing.py (clean_category, to_ticket); the web form's names are in ticket_cleaner/records.py (CATEGORY_ALIASES). Fix the cause, add a regression test to tests/test_parsing.py, and change nothing else.L’assistant a nommé la cause dès sa première phrase. Ensuite, il a réécrit les trois lignes de clean_category() et ajouté un test :
`clean_category()` lowercases alias lookups but preserves case for other categories. Use `clean_text()` before resolving aliases so every category isnormalized.Description textuelle du diagramme
Le schéma compare deux sessions enregistrées avec le même modèle. La colonne de gauche présente la session avec trop peu de contexte. Sa requête était : « Les catégories du rapport sont incorrectes. Corrigez-les. » Elle avait un fichier, ticket_cleaner/report.py, aucun plan du dépôt et aucune entrée d’exemple. Elle n’a rien changé : l’assistant a demandé un échantillon des comptes de catégories incorrects et le résultat attendu. Elle a utilisé 2,220 jetons en entrée, en un appel au modèle. La colonne de droite présente la session avec le contexte utile. Sa requête contenait le courriel de Grace avec la sortie exacte, l’entrée de deux lignes et les résultats observé et attendu. Elle se terminait par la demande : « Corrigez la cause, ajoutez un test de régression et ne changez rien d’autre. » Elle avait trois fichiers, parsing.py, records.py et tests/test_parsing.py, ainsi que le plan du dépôt. Elle a modifié 2 fichiers, ajouté 20 lignes et supprimé 3 lignes. Les tests ont donné 31 passed, et les 5 vérifications du bogue ont réussi. Elle a utilisé 4,570 jetons en entrée, en un appel au modèle.
La session a modifié 2 fichiers (+20 −3), et les 5 vérifications cachées du bogue ont réussi. Parmi ses 7 nouveaux cas de test, 6 échouent sur le code non corrigé. Un cas, login → login, réussit dans les deux versions, donc il ne détecte rien.
N’appliquez pas cette correction maintenant. La session s’est déroulée dans une copie jetable, et le résultat est bon. Mais personne n’a vu un test échouer avant la correction. Personne n’a donc montré que son test détecte le bogue. Votre projet conserve le bogue jusqu’au module Déboguer et tester avec l’assistant, où vous le corrigerez avec cette preuve. La prochaine tâche reste la fonctionnalité de Grace.
Quand ajouter du contexte, et ce qu’il coûte
Section intitulée « Quand ajouter du contexte, et ce qu’il coûte »Le contexte consomme des jetons. La session avec peu de contexte a utilisé 2,220 jetons en entrée et coûté 0.0049 $ US. Celle avec le contexte utile en a utilisé 4,570 et coûté 0.0126 $ US. Cela représente environ deux fois plus de jetons et deux fois et demie le coût. La session moins chère n’a rien produit. Les prix changent : consultez la page actuelle de votre fournisseur. Avec une offre gratuite ou sans assistant, vous ne payez rien.
Le coût le plus important est votre temps : environ dix minutes pour créer l’entrée minimale et trouver les fichiers. Vous passez ce temps de toute façon quand vous vérifiez la correction.
Trop de contexte coûte aussi. Tomás aime envoyer tout le dépôt : « Comme ça, il a tout. » Mais « tout » ne contient ni observation ni résultat attendu : ils ne sont dans aucun fichier. Le dépôt contient beaucoup de fichiers inutiles à la tâche. Ils consomment des jetons et donnent au modèle plus d’endroits où faire des changements incorrects. Il peut aussi contenir ce qui ne doit jamais quitter votre ordinateur. ASSISTANT-SCOPE.md le dit déjà : .env n’est jamais lu.
Faites une vérification rapide avant d’envoyer : un nouveau collègue aurait-il besoin de cela pour accomplir cette tâche? Sinon, omettez-le. Pour une question sur une fonction, la fonction suffit comme contexte. Pour un bogue, fournissez les cinq types ci-dessus. Pour une fonctionnalité, fournissez la description de tâche et les fichiers qu’elle nomme.
Erreur courante
Le fichier d'exemple se retrouve dans le commit
Symptôme : après la rédaction du rapport de bogue, git status --short affiche un fichier que vous ne vouliez pas conserver :
?? minimal.csvUn git add -A le placerait dans le commit, à côté des vraies données dans data/.
Cause : l’entrée minimale est un fichier de travail créé dans le dossier du projet. Rien dans .gitignore ne l’exclut, donc Git le propose comme tout nouveau fichier.
Correction : avant chaque commit, lisez git status --short et ajoutez les fichiers par leur nom, comme à l’étape 6. Supprimez les fichiers de travail ou gardez-les hors du projet. Le rapport de bogue contient l’exemple sous forme de texte, donc vous ne perdez rien. ASSISTANT-SCOPE.md impose la même règle à l’assistant : il n’ajoute jamais de fichier de données.
À vous de jouer : le contexte d’un deuxième symptôme
Section intitulée « À vous de jouer : le contexte d’un deuxième symptôme »L’équipe de Grace produit le rapport des billets en attente à partir du fichier d’exemple du cours de Python :
python -m ticket_cleaner data/tickets.csv --status pending --output reports/pending.jsonExécutez la commande et ouvrez reports/pending.json. Répondez ensuite : est-ce un nouveau bogue? Rédigez l’observation, le résultat attendu, un exemple minimal et les références de fichiers que vous donneriez à un assistant. Ne créez aucun commit.
Afficher la réponse
Le rapport contient ceci :
"by_category": { "LOGIN": 1, "billing": 1},Le billet T-1010 a la catégorie LOGIN dans data/tickets.csv. Dans le cours de Python, clean_text() nettoyait chaque catégorie, donc le même rapport contenait "login": 1. Ce n’est pas un nouveau bogue : c’est le bogue de Grace, avec un autre fichier.
- Observation : la commande ci-dessus et
"by_category": {"LOGIN": 1, "billing": 1}. - Résultat attendu :
{"billing": 1, "login": 1}. - Exemple minimal : les deux lignes de
minimal.csvle montrent déjà. Vous n’avez pas besoin d’un deuxième exemple pour la même cause. - Références de fichiers :
ticket_cleaner/parsing.py(clean_category,to_ticket) etticket_cleaner/records.py(CATEGORY_ALIASES).
Ajoutez-le au rapport de bogue comme une observation supplémentaire, pas comme un nouveau bogue. Deux rapports pour une cause entraînent deux corrections, et la deuxième peut annuler la première. La requête de la session avec le contexte utile ci-dessus comprenait cette ligne.
Vérification des connaissances
Section intitulée « Vérification des connaissances »Vérifiez votre compréhension
Nommez les cinq types de contexte utile pour un bogue. Utilisez le bogue de Grace comme exemple pour chacun. Nommez ensuite deux éléments à exclure.
Afficher la réponse
- Observation :
python -m ticket_cleaner minimal.csv --output reports/minimal.jsondonne"by_category": {"LOGIN": 1, "login": 1}. - Résultat attendu :
{"login": 2}. - Exemple minimal : les deux lignes
T-1,open,login,1,OneetT-2,open,LOGIN,1,Two. - Références aux fichiers :
ticket_cleaner/parsing.pyetticket_cleaner/records.py. - Interfaces :
clean_category(value: object) -> str, appelée parto_ticket().
Excluez les fichiers inutiles pour la tâche, comme remote.py, et le dossier de données complet. N’incluez jamais .env, son jeton ou les données de vrais clients.
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
Dans la session bug-little-context, l'assistant avait report.py. Pourquoi ne pouvait-il pas trouver le bogue, même avec une meilleure requête?
Afficher la réponse
Le bogue apparaît dans le rapport, mais il ne se trouve pas dans report.py. count_by_category() compte le texte qu’elle reçoit. Les majuscules viennent d’une étape précédente, dans clean_category(), dans parsing.py. L’assistant n’a jamais vu ce fichier, et aucun plan du dépôt ne l’indiquait. Une meilleure requête avec l’observation et le résultat attendu l’aiderait à poser la bonne question. Pour trouver la cause, il lui faut le fichier qui la contient. C’est pourquoi vous cherchez dans le code, par exemple avec grep -n category, avant de choisir les fichiers.
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 : « Donnez-lui tout le dépôt et l'exportation complète chaque fois. Plus de contexte, c'est toujours mieux. » Donnez trois raisons de ne pas le faire.
Afficher la réponse
- Le contexte le plus important n’est dans aucun fichier : la sortie observée, le résultat attendu et l’exemple minimal. Un dépôt complet ne les contient pas.
- Plus de texte coûte plus de jetons (tokens). Cela donne au modèle plus d’endroits où chercher et plus de fichiers qu’il pourrait modifier. Le contexte utile du bogue de Grace comprenait 3 fichiers et deux lignes.
- Tout ce que vous envoyez quitte votre ordinateur. Un dossier complet peut contenir
.env, un jeton ou les données de vrais clients. Le fichier de périmètre précise que l’assistant ne lit jamais.env.
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
- Le contexte d’une requête comprend tout ce que le modèle reçoit avec elle. Il ne sait rien d’autre sur votre projet.
- Avec un seul fichier, aucun plan et « Corrigez ça. », l’assistant n’a rien changé et a demandé un exemple. Son fichier montrait le bogue, mais n’en contenait pas la cause.
- Le contexte utile pour un bogue : l’observation exacte, le résultat attendu, un exemple minimal, les références aux fichiers et les interfaces. Avec ces éléments, le même modèle a corrigé le bogue dans
clean_category(), et les 5 vérifications ont réussi. - Excluez ce qui est inutile pour la tâche et n’envoyez jamais de secret. Cherchez dans le code pour trouver les fichiers; n’envoyez pas tout.
- Votre projet contient le rapport de bogue
docs/tasks/category-names-bug.md, enregistré dans un commit (une version enregistrée). Le bogue reste présent jusqu’au module 4.
Ensuite, Amira commence à travailler sur la fonctionnalité. Elle ne connaît pas ce code. Elle demande donc une analyse et un plan avant tout changement.
Leçon suivante : Découper le travail en étapes