Atelier : premier projet guidé

Ce chapitre est un atelier, pas une lecture. L'idée est simple : appliquer sur un dépôt réel, en une seule séance, les mécanismes vus jusqu'ici — configuration, mode plan, permissions, revue humaine — plutôt que de les garder au niveau de la théorie. Trois tâches courtes suffisent à couvrir l'essentiel du flux de travail quotidien avec un agent CLIAgent CLIIAProgramme en terminal qui enchaîne raisonnement et outils (lecture, édition, commandes) pour accomplir une tâche dans un environnement local.Voir dans le glossaire : corriger un bug, écrire un test, mettre à jour une documentation.

L'objectif n'est pas de produire un résultat impressionnant. C'est de roder le geste — cadrer une demande, lire un plan avant de le valider, observer ce qui se passe quand une permission est demandée, relire un diff avant de commiter — jusqu'à ce qu'il devienne un réflexe plutôt qu'une checklist consultée à chaque fois.

Ces trois tâches ne sont pas interchangeables avec n'importe quel triptyque de mini-exercices. Elles correspondent aux trois familles d'actions qui reviennent le plus souvent dans un usage quotidien d'un agentagentIASystème qui enchaîne des appels d'outils de façon autonome pour atteindre un objectif : il planifie, agit, observe, recommence. Sa fiabilité décroît exponentiellement avec le nombre d'étapes.Voir dans le glossaire CLI sur du code existant : modifier un comportement, prouver qu'il est correct, et documenter ce qui a changé pour la prochaine personne — humaine ou agent — qui ouvrira ce dépôt.

Prérequis avant de commencer

• Claude CodeClaude CodeIAInterface en ligne de commande agentique qui lit, édite et exécute des actions dans un dépôt de code sous contrôle de permissions, par opposition à un simple chat web.Voir dans le glossaire installé et authentifié sur votre poste, comme vu dans les chapitres d'installation.
• Un terminal et des notions de base de Git (clone, branch, diff, commit).
• Un petit dépôt de travail : un projet personnel peu critique, un fork jetable, ou un dépôt d'exercice fourni avec la formation. La taille importe peu — quelques centaines de lignes suffisent pour que l'exercice soit représentatif.
• Environ 30 minutes sans interruption : l'atelier est court, mais chaque étape demande de la lecture attentive plutôt que de la vitesse.

Ne faites pas cet atelier directement sur la branche principale d'un dépôt partagé en production. Travaillez sur une copie, un fork, ou une branche dédiée créée pour l'occasion. Le but est d'observer le comportement de l'outil sans risque, y compris dans les cas où vous refuseriez une permission ou annuleriez une action à mi-parcours.

Étape 1 — État des lieux du dépôt

Avant d'écrire la moindre instruction, ouvrez une session dans le dossier du dépôt et laissez l'agent explorer la structure : arborescence, fichiers de configuration, présence de tests, présence d'un README. Demandez explicitement un résumé plutôt que de commencer directement une tâche — c'est cette étape qui donne à l'agent le contextefenêtre de contexteIAQuantité de texte qu'un modèle peut prendre en compte simultanément : question, documents fournis et historique. Au-delà, les éléments les plus anciens sortent du champ.Voir dans le glossaire nécessaire pour proposer des plans réalistes ensuite.

À ce stade, vérifiez aussi manuellement que le dépôt est propre : git status ne doit rien signaler d'inattendu. Un dépôt avec des modifications non commitées avant même de commencer rend la revue finale illisible, puisqu'on ne pourra plus distinguer ce qui vient de l'atelier de ce qui préexistait.

Profitez aussi de cette exploration initiale pour repérer la couverture de tests existante et les dépendances déclarées : un projet sans aucun test change la nature de l'atelier, puisque la tâche 2 devra alors créer un premier filet de sécurité plutôt qu'ajouter un cas à une suite déjà en place. Cette différence mérite d'être notée avant de commencer, pas découverte en cours de tâche 1.

Étape 2 — Rédiger un CLAUDE.md minimal

Le fichier CLAUDE.mdCLAUDE.mdIAFichier Markdown de consignes stables placé dans un projet pour orienter Claude Code (stack, conventions, périmètre, interdits) sans les répéter à chaque prompt.Voir dans le glossaire est lu au démarrage de chaque session dans ce dépôt. Il ne remplace pas une documentation projet complète : il donne à l'agent les informations qu'un nouveau contributeur humain chercherait en premier — comment lancer les tests, quelles conventions respecter, quelles zones du code éviter de toucher sans discussion préalable.

Pour cet atelier, un fichier de dix à vingt lignes suffit :

# Contexte du projet
Application de gestion de tâches, backend uniquement.

## Commandes
- Installer les dépendances : npm install
- Lancer les tests : npm test
- Lancer le linter : npm run lint

## Conventions
- Tests colocalisés avec le code (*.test.js)
- Pas de dépendance ajoutée sans validation humaine

## Zones sensibles
- Ne pas modifier le schéma de migration sans confirmation explicite

Demandez d'abord à l'agent de proposer un premier jet de CLAUDE.md en observant le dépôt, puis relisez et corrigez vous-même. C'est plus rapide que d'écrire à partir de rien, mais ne validez jamais une commande que vous n'avez pas vérifiée : un CLAUDE.md qui prétend que npm test fonctionne alors que la commande réelle est npm run test:unit produira des échecs incompréhensibles dans toutes les sessions suivantes.

Ce fichier reste versionné avec le code. Il évolue au fil des sessions : chaque fois qu'une convention implicite cause une incompréhension, c'est le signal qu'elle mérite une ligne dans CLAUDE.md.

Étape 3 — Tâche 1 : correction d'un bug, en mode plan

Choisissez un bug réel si le dépôt en contient un signalé, ou introduisez-en un simple et documenté pour l'exercice — une condition inversée, une valeur par défaut incorrecte, un cas limite non géré. Formulez une demande précise : symptôme observé, comportement attendu, fichier ou fonction concernée si vous le savez déjà.

Un bon signalement de bug tient en trois éléments : les étapes pour le reproduire, le comportement observé, le comportement attendu. Cette discipline ne sert pas seulement l'agent — c'est la même rigueur qu'attend un mainteneur humain sur un ticket, et elle réduit dans les deux cas le nombre d'allers-retours nécessaires avant de converger vers la bonne correction.

Demandez explicitement un plan avant toute modification. Sur un changement aussi limité, la différence entre laisser l'agent agir directement et lui demander un plan d'abord semble mineure — mais c'est précisément l'habitude qu'il faut ancrer avant de l'appliquer à des changements plus larges, où l'écart de coût entre les deux devient important.

Demande : « La fonction calculerRemise applique la remise même quand le panier est vide, ce qui produit un total négatif. Corrige ce cas et explique ton plan avant de modifier quoi que ce soit. » Réponse attendue : un plan qui identifie le fichier, décrit la condition à ajouter, et signale s'il compte aussi ajouter un test — sans avoir encore touché au code.

Validez le plan seulement s'il est cohérent avec le comportement attendu. S'il propose une modification plus large que nécessaire — par exemple refactoriser toute la fonction — c'est le moment de recadrer, pas après exécution.

Étape 4 — Tâche 2 : écrire un test de non-régression

Une fois le bug corrigé, demandez un test qui aurait échoué avant le correctif et qui passe désormais. Cette contrainte — « le test doit échouer sur l'ancien code » — est plus utile qu'elle n'y paraît : elle empêche un test qui teste en réalité autre chose, ou qui passe même sans le correctif parce qu'il ne couvre pas le bon cas.

Si l'agent dispose de la permission d'exécuter des commandes, laissez-le lancer la suite de tests lui-même et observer le résultat plutôt que de le lui décrire. C'est l'un des apports concrets d'un agent outillé par rapport à un assistant de complétion de code : il peut vérifier une hypothèse au lieu de simplement l'énoncer.

Si la suite complète contient déjà des échecs sans rapport avec votre correctif, ne les ignorez pas silencieusement : signalez-les explicitement dans votre demande suivante, ou notez-les dans CLAUDE.md comme échecs connus. Un agent qui découvre un test rouge préexistant sans le savoir peut à tort l'attribuer à sa propre modification, ou pire, tenter de le « corriger » en marge de la tâche demandée.

Étape 5 — Tâche 3 : mettre à jour la documentation

Si le comportement corrigé était documenté — README, commentaire de fonction, changelog — mettez cette documentation à jour pour refléter le nouveau comportement. C'est la tâche la plus souvent négligée dans un flux de travail réel, et c'est pour cela qu'elle figure ici : un bug corrigé sans documentation à jour laisse une trace fausse pour le prochain contributeur.

Exigez de la documentation factuelle, alignée sur le code tel qu'il est après le correctif — pas une reformulation générique ni un ajout de section qui n'apporte rien. Une phrase précise sur le cas limite désormais géré vaut mieux qu'un paragraphe qui reformule ce que le code montre déjà.

Limitez la mise à jour au périmètre réellement concerné par le correctif — README, commentaire de la fonction, ou entrée de changelog selon l'endroit où le comportement était déjà décrit. Réécrire une section entière de documentation à cette occasion sort du cadre de l'atelier et complique la revue du diff final, qui doit rester lisible en quelques minutes.

Étape 6 — Permissions et revue humaine

À chaque action qui touche le système de fichiers ou exécute une commande, l'agent doit disposer d'une permission — accordée par vous, une fois ou pour la session. C'est le point de contrôle qui distingue un agent outillé d'un simple générateur de texte : il ne modifie rien sans que ce passage soit franchi.

Accorder toutes les permissions par réflexe pour aller plus vite est la première mauvaise habitude à éviter, y compris — surtout — sur un dépôt d'exercice sans conséquence réelle : c'est là qu'on prend l'habitude qui posera problème ailleurs. Portez une attentionattentionIAMécanisme par lequel un modèle pondère l'importance de chaque token du contexte lorsqu'il en traite un autre, quelle que soit la distance qui les sépare.Voir dans le glossaire particulière aux commandes destructrices ou irréversibles (suppression de fichiers, réécriture d'historique Git, migrations de base de donnéesdonnéesIAEnsemble d'informations structurées ou non utilisées pour entraîner, évaluer ou alimenter un modèle. La qualité, la quantité et la représentativité des données sont les facteurs décisifs pour les performances en apprentissage automatique.Voir dans le glossaire) et à tout ce qui pourrait exposer un secret — clé d'API, jeton, mot de passe — présent dans le dépôt ou dans une variable d'environnement. Un CLAUDE.md ne doit jamais contenir de secret, puisqu'il est versionné et lu par chaque session.

Dans la plupart des cas, la permission se négocie à un niveau plus fin qu'un tout ou rien : lecture de fichiers, écriture de fichiers, exécution de commandes peuvent être distinguées, tout comme la portée — une seule fois, pour la session en cours, ou de façon permanente pour ce dépôt. Sur cet atelier, privilégiez l'accord au cas par cas : c'est plus lent de quelques secondes par action, mais cela vous garde au contact de ce que l'agent modifie réellement.

Une fois les trois tâches exécutées, relisez le diff complet avant de commiter — git diff ou l'équivalent dans votre client Git. La revue humaine n'est pas une formalité : c'est le moment où vous vérifiez que le plan validé plus tôt correspond réellement à ce qui a été fait, et que rien d'inattendu ne s'est glissé dans les fichiers modifiés.

RappelrappelIAProportion des cas positifs réels effectivement détectés par un modèle. Sur un jeu déséquilibré, c'est un indicateur bien plus parlant que l'exactitude globale.Voir dans le glossaire utile à ce stade de l'atelier : un agent CLI comme celui utilisé ici diffère d'un chat web par sa capacité à lire, modifier et exécuter directement dans votre environnement. C'est ce qui rend l'exercice possible, et c'est aussi ce qui justifie la rigueur autour des permissions et de la revue — un chat web n'a jamais ce pouvoir d'action.

Rétrospective : erreurs courantes d'un premier atelier

Une fois les trois tâches terminées, prenez cinq minutes pour repasser sur ce qui s'est mal passé, même légèrement. C'est cette relecture qui transforme un atelier ponctuel en réflexe durable. Les erreurs les plus fréquentes en première session :

• Demande trop vague — « corrige le bug de remise » sans préciser le comportement attendu produit un plan qui devine à votre place, avec un risque réel d'écart. Reformuler après coup coûte plus cher que de préciser dès la première phrase.
• Plan sauté sur un changement risqué — accepter l'exécution directe par habitude, y compris sur une modification qui touche plusieurs fichiers. Le coût de demander un plan est de quelques secondes ; celui de défaire une modification mal engagée se compte en minutes, parfois plus.
• Diff non relufonction d'activationIAOpération non linéaire appliquée en sortie d'un neurone. Sans elle, empiler des couches serait inutile : une succession d'opérations linéaires reste équivalente à une seule.Voir dans le glossaire avant commit — faire confiance au résumé donné par l'agent plutôt qu'à la lecture réelle du changement. Un résumé fidèle à l'intention peut malgré tout omettre un détail visible seulement dans le diff, comme une ligne de configuration modifiée par effet de bord.
• CLAUDE.md trop ambitieux — vouloir tout documenter dès la première version, ce qui produit un fichier long, jamais tenu à jour, et donc plus trompeur qu'utile. Un fichier court et exact vaut mieux qu'un fichier exhaustif et obsolète.
• Commit sans tests exécutés — considérer qu'un test écrit suffit, sans vérifier qu'il a réellement été lancé et qu'il passe. Un test jamais exécuté n'apporte aucune garantie, quelle que soit la qualité apparente de son code.
• Permissions accordées trop largement — autoriser l'exécution de commandes pour toute la session plutôt qu'au cas par cas sur les premières sessions, le temps de prendre la mesure du comportement de l'outil. La granularité se relâche naturellement avec l'expérience ; elle ne devrait pas être maximale dès la première session.

Aucune de ces erreurs n'est grave sur un dépôt d'exercice. Elles le deviennent sur un dépôt de production si l'habitude n'a pas été corrigée avant.

Checklist finale avant de clore la session

• git status ne montre que les fichiers attendus, rien d'accidentel.
• Les tests ont été exécutés et passent, pas seulement écrits.
• Le diff complet a été relu ligne par ligne avant tout commit.
• Le message de commit a été rédigé ou validé par vous, pas accepté sans lecture.
• CLAUDE.md a été mis à jour si une convention implicite est apparue pendant l'atelier.
• Aucun secret n'apparaît dans le diff ni dans les fichiers de configuration modifiés.
• Les permissions accordées pendant la session correspondent à ce qui a réellement servi, sans excès conservé par défaut.

Cette checklist n'a pas vocation à être suivie mécaniquement à vie. Elle sert de garde-fou le temps que le réflexe s'installe — après quelques sessions, la plupart de ces points deviennent automatiques.

Vers la suite

Cet atelier couvre le cœur du flux de travail quotidien avec un agent CLI : cadrer, planifier, vérifier les permissions, exécuter, relire. Les chapitres suivants s'appuient sur ces réflexes pour aborder des situations plus avancées, sans jamais remettre en cause ce socle.