Projet de synthèse : du début à la mise en ligne, relier tout ce que vous avez appris

📚 Navigation de la série : Le chapitre précédent [47 Mode Vocal (Voice)] vous a permis de remplacer le « tapage d'instructions » par la « formulation vocale des besoins », libérant ainsi vos mains. Ce chapitre est le projet de fin d'études de l'ensemble du tutoriel. Il n'enseigne aucune nouvelle fonctionnalité, mais utilise un projet réel plus grand que celui du chapitre 39 et s'étendant sur plusieurs sessions (conversations) pour mobiliser toutes les pièces en même temps : CLAUDE.md, permissions, MCP, subagents, points de contrôle (checkpoints) et git, afin de parcourir un flux d'ingénierie complet, du démarrage à la livraison.

En parcourant les projets accumulés avec Claude Code et en faisant une statistique approximative, on s'aperçoit que : aucun des travaux qui donnent vraiment l'impression que « cela en valait le coût » n'est une petite tâche consistant à « modifier une ligne avec une phrase ». Ce sont tous des projets de taille moyenne s'étendant sur trois à cinq sessions et mobilisant quatre ou cinq fonctionnalités.

Plus précisément, concevoir à partir de zéro un petit outil interne avec lui a nécessité l'ouverture de 4 sessions successives, environ deux heures et demie de travail, la connexion à un serveur MCP pour consulter la documentation, l'envoi d'un subagent pour effectuer un audit de sécurité, et l'utilisation de points de contrôle pour récupérer le code après une modification ratée. Enfin, en regardant l'historique des validations git, on constate 7 commits bien propres, chacun décrivant clairement ce qui a été fait. C'est à ce moment-là que l'on ressent vraiment que les outils appris précédemment ne sont pas des techniques isolées, mais qu'ils peuvent s'unir pour former un tout cohérent.

En clair, c'est précisément la dernière étape entre « avoir appris chaque fonctionnalité » et « être capable de les utiliser pour accomplir un projet sérieux ». Le chapitre 39 vous a guidé à travers une pratique minimale : une seule session, un seul script, purement local. Ce chapitre vise à élargir le champ d'action : le projet est plus complexe, nécessite un relais entre sessions, se connecte à l'extérieur, envoie des clones, et permet de revenir en arrière de manière élégante en cas d'erreur. Les 47 premiers chapitres vous ont enseigné les instruments un par un, ce chapitre vous propose d'en être le chef d'orchestre pour en faire une symphonie complète.

Analogie : Diriger un orchestre pour jouer un morceau complet. Vous avez pratiqué le violon, les cuivres, les percussions — chaque instrument vous est familier individuellement. Mais « savoir jouer de chaque instrument » et « pouvoir les faire jouer ensemble » sont deux choses différentes : vous devez savoir quand chaque pupitre doit intervenir, qui est principal, qui est secondaire, et comment caler le rythme. Dans ce chapitre, vous êtes le chef d'orchestre — CLAUDE.md, permissions, MCP, subagent, points de contrôle et git sont vos différents pupitres, et je vous guiderai pour les faire intervenir au bon moment afin de composer une performance complète.

À la fin de ce chapitre, vous obtiendrez :

• Une carte complète pour « mener un projet moyen de zéro à la livraison », montrant clairement à quelle étape chaque fonctionnalité apprise entre en scène et quel rôle elle joue
• Une méthode de relais inter-sessions : comment utiliser --resume, les documents SPEC et les points de contrôle pour répartir un travail important en toute sécurité sur plusieurs jours ou sessions
• Les étapes clés : « quoi saisir, quoi observer et où bloquer », avec les commandes et les sorties attendues
• Un projet concret à reproduire (un outil de gestion de tâches en ligne de commande avec stockage local, tests et documentation), reliant tout au long du processus CLAUDE.md → permissions → MCP → subagent → points de contrôle → git
• Un tableau comparatif « projet jouet vs projet réel » pour identifier les pièges où « tout déraille quand le projet grandit »

---

01 Vue d'ensemble : où interviennent les fonctionnalités dans un projet moyen

Avant de commencer, ouvrons la « partition générale » de notre morceau. De zéro à la livraison, l'ossature d'un projet moyen comporte toujours les mêmes étapes, mais chacune est plus lourde que dans le chapitre 39 et fait intervenir de nouveaux pupitres.

Ce schéma présente un projet de taille moyenne sous forme d'une ligne de production avec boucle de retour : six étapes se relaient, et la ligne pointillée est essentielle — un projet réel ne se termine pas en une seule session ; après validation d'un cycle, on revient à la « planification » pour ouvrir la session suivante afin d'avancer fonctionnalité par fonctionnalité. La ligne droite unidirectionnelle du chapitre 39 se transforme ici en une boucle à plusieurs cycles.

Les deux différences majeures avec le chapitre 39 à retenir absolument sont :

• Le projet s'étend sur plusieurs sessions. Dès que le contexte d'une session est saurée, il faut la terminer (le chapitre 19 explique comment un espace de travail saturé altère les performances de l'IA), et continuer dans une nouvelle session propre. La manière de passer le relais en toute sécurité à la session suivante est donc un savoir-faire en soi.
• Il faut mobiliser de nouveaux pupitres. Un simple script n'a pas besoin de MCP ou de subagent, mais dans un projet moyen, ils sont indispensables pour consulter des documentations externes, isoler les tâches ingrates ou faire relire le code par un modèle frais.

Cette phrase des bonnes pratiques officielles résume parfaitement l'esprit de ce chapitre :

一旦你对一个 Claude 有效，通过并行会话、非交互模式和扇出模式来增加你的输出。

En d'autres termes : une fois qu'une méthode de travail efficace est établie, vous pouvez démultiplier vos résultats en exécutant plusieurs sessions en parallèle, en utilisant des scripts non interactifs pour des tâches en lot et en distribuant les tâches à des clones — plutôt que de tâtonner à chaque fois. Ce chapitre montre comment mettre en œuvre ces techniques étape par étape.

Au début de chaque section ci-dessous, j'indiquerai clairement à quel chapitre précédent correspond chaque étape, afin que vous puissiez faire le lien. Une fois la carte bien en tête, il ne reste plus qu'à observer quand chaque pupitre doit entrer en scène.

💡 En résumé : La structure d'un projet moyen reste « Initialisation → Planification → Connexion externe → Répartition → Tolérance aux pannes → Livraison », mais avec deux spécificités par rapport aux petites tâches : la nécessité de passer le relais entre sessions et d'activer de nouveaux pupitres comme MCP et subagent ; la ligne pointillée retournant à la « planification » est la norme dans les projets réels.

---

02 Initialisation : définir le projet, rédiger le CLAUDE.md et configurer la base des permissions

Première étape — L'initialisation. Correspond aux chapitres 12 et 18 (CLAUDE.md) et au chapitre 20 (permissions). Pour de petites tâches, cette étape consiste simplement à « écrire quelques lignes dans CLAUDE.md ». Dans un projet moyen, il faut poser à la fois les « règles du projet » et la « base des permissions », car les sessions suivantes s'appuieront sur ces fondations.

Le projet de ce chapitre : un outil de gestion de tâches en ligne de commande (todo-cli) — capable d'ajouter des tâches, de les lister et de les marquer comme terminées, avec stockage des données dans un fichier JSON local, accompagné de tests et d'un fichier README. Il est plus grand que le script à fichier unique du chapitre 39 : plusieurs fichiers, persistance, tests et réalisation par étapes sur plusieurs sessions, mais il utilise uniquement la bibliothèque standard de Python, ce qui permet à tout le monde de l'exécuter.

Étape 1 : Créer la structure du projet et l'initialiser avec git

mkdir todo-cli && cd todo-cli && git init

Pourquoi la première étape du travail est-elle git init ? Parce que c'est votre filet de sécurité le plus solide pour tout le projet. Les points de contrôle (chapitre 37) peuvent annuler les modifications de Claude, mais git et les points de contrôle sont deux outils distincts gérant des étapes différentes. Un premier commit propre est le point d'ancrage auquel vous pouvez toujours revenir, peu importe les erreurs commises par la suite — un principe du chapitre 39 qui devient d'autant plus crucial que le projet grandit.

Étape 2 : Démarrer à la racine du projet et rédiger un fichier CLAUDE.md suffisant

claude

Une fois à l'intérieur, demandez-lui de générer CLAUDE.md (pour un projet moyen, il est recommandé de spécifier manuellement quelques règles clés au départ, ce qui est plus précis que de laisser /init scanner l'ensemble du dossier qui ne contient pas encore de code) :

帮我在项目根目录建一个 CLAUDE.md，写清这几条：
1. 这是个纯 Python 标准库的命令行工具，不要引入任何第三方依赖
2. 数据持久化到项目根的 todos.json，所有读写都走这一个文件
3. 每加一个功能都要配 unittest 测试，改完跑 python3 -m unittest 验证
4. 提交信息用中文，前缀用 feat: / fix: / docs:

Résultat attendu : Claude vous présente d'abord le contenu, puis demande votre autorisation pour écrire le fichier (mécanisme de permission décrit au chapitre 20). Une fois autorisé, un fichier CLAUDE.md est créé pour graver ces quatre règles dans le marbre. Notez bien — il ne compte actuellement qu'une dizaine de lignes. La recommandation officielle mérite d'être rappelée :

保持简洁。对于每一行，问自己：「删除这个会导致 Claude 犯错吗？」如果不会，删除它。

Ces quatre règles sont impossibles à deviner pour Claude et seront utilisées de manière répétée, c'est pourquoi elles doivent être conservées. Au cours des trois ou quatre sessions suivantes, il chargera automatiquement ces instructions à chaque démarrage, vous évitant ainsi de répéter à chaque session « n'importe pas de bibliothèque tierce, lance les tests après modifications ».

Étape 3 : Configurer la base des permissions — l'étape clé supplémentaire par rapport aux tâches simples lorsque le projet grandit

Pour les petites tâches, vous pouvez accorder des autorisations au cas par cas. Mais pour un projet moyen impliquant plusieurs sessions et la modification d'une dizaine de fichiers, les bonnes pratiques officielles soulignent directement ce problème : « Après la dixième autorisation, vous n'examinez plus vraiment, vous vous contentez de cliquer pour valider. » Il convient donc de définir la base des permissions dès le début du travail. Trois approches s'offrent à vous selon la situation :

Approche	Utilisation	Scénarios adaptés
Liste d'autorisation des permissions	/permissions pour ajouter les commandes que vous jugez sûres (comme python3 -m unittest, git status)	Commandes sûres exécutées de manière répétée dans le projet, pour éviter d'être sollicité à chaque fois
Mode plan (mode planification)	Basculez avec Shift+Tab ou démarrez avec claude --permission-mode plan	Modifications peu familières, lorsqu'il est nécessaire de valider la solution avant d'agir
Mode auto (mode automatique)	claude --permission-mode auto, le classificateur ne bloquant que les opérations dangereuses	Lorsque vous faites confiance à l'orientation générale de la tâche et ne souhaitez pas valider chaque étape

Une configuration pratique lors du développement de ce todo-cli : ajoutez immédiatement les commandes exécutées fréquemment comme python3 -m unittest, git diff et git status à la liste d'autorisation via /permissions ; et basculez systématiquement avec Shift+Tab vers le plan mode pour examiner la proposition avant toute modification impliquant plusieurs fichiers. Une fois cette base établie, le bruit lié aux demandes d'autorisation dans les sessions suivantes est réduit de plus de la moitié — si vous ne le configurez pas lors de votre premier projet moyen, la seule question « faut-il exécuter les tests » peut vous solliciter plus de vingt fois, au point de risquer de désactiver la confirmation par agacement (ce qui serait le vrai danger).

⚠️ Le relâchement des permissions est une arme à double tranchant — le auto mode et l'acceptation globale facilitent la tâche, mais vous renoncez à la fenêtre d'interception en cours de route. Les chapitres 21 et 22 ont traité spécifiquement de ce compromis : plus vous donnez de liberté, plus vous devez vous appuyer sur la validation ultérieure et les points de contrôle.

💡 En résumé : L'initialisation d'un projet moyen = git init pour conserver un point d'ancrage + rédaction d'un fichier CLAUDE.md d'une dizaine de lignes pour fixer les règles + configuration de la base des permissions avec /permissions, plan mode ou auto mode ; cette étape de base des permissions est la tâche supplémentaire indispensable par rapport aux petits projets, et mérite amplement d'y consacrer deux minutes.

---

03 Planification : élaborer une SPEC avant d'implémenter par étapes sur plusieurs sessions

Les bases étant posées, passons à la deuxième étape — La planification. Correspond au chapitre 16 (exploration), au chapitre 20 (plan mode) et au chapitre 19 (gestion du contexte). C'est sur cette étape que la différence entre projets moyens et petites tâches est la plus marquée : alors qu'une phrase suffit pour démarrer une tâche simple, un projet moyen nécessite de formaliser d'abord un « cahier des charges (SPEC) » avant de le traiter session par session.

Pourquoi un projet moyen exige-t-il toujours une SPEC préalable ? Parce que dès que les fonctionnalités se multiplient, les idées floues que vous avez en tête ne suffisent pas pour mener à bien l'implémentation — à mi-chemin, vous découvrirez des cas limites non définis ou des champs incompatibles, ce qui vous obligera à recommencer. Les bonnes pratiques officielles proposent une technique très efficace : demander à Claude de mener un entretien avec vous.

Étape 1 : Le laisser vous interviewer pour concevoir une SPEC

Basculez en plan mode (Shift+Tab) et soumettez-lui ce texte :

我想做一个命令行任务清单工具 todo-cli，数据存本地 JSON。
用 AskUserQuestion 工具详细采访我：技术实现、命令行接口怎么设计、
边界情况（比如空清单、重复任务、文件损坏）、有哪些权衡。
别问显而易见的，挖那些我可能没想到的硬骨头。
问完把完整规格写进 SPEC.md。

Résultat attendu : Claude vous posera des questions précises l'une après l'autre — « Les tâches doivent-elles avoir une priorité ? », « Si todos.json n'existe pas, faut-il lever une erreur ou le créer automatiquement ? », « Marquer comme terminé supprime-t-il la tâche ou la conserve-t-il cochée ? » Ce sont autant de détails que vous auriez oubliés en y réfléchissant seul. Une fois l'entretien terminé, il rédige un fichier SPEC.md détaillant les commandes, les champs, les cas limites et les critères de validation. Les documentations officielles soulignent la valeur d'une SPEC :

最有用的规范是自包含的：它们命名涉及的文件 and 接口，说明什么在范围之外，并以端到端验证步骤结束。

Lors du développement de cet outil, il soulèvera souvent des points auxquels vous n'auriez pas pensé : « Si deux tâches ont exactement le même texte, s'agit-il d'un doublon, faut-il le dédoublonner ? » C'est face à ce genre de question que l'on prend conscience qu'il s'agit d'une réelle décision de conception à valider. Consacrer dix minutes à son entretien permet d'économiser deux heures de reconstruction en cours de route — le calcul est vite fait.

Étape 2 : Découper le travail important en « une session par partie »

Une fois la SPEC établie, n'essayez pas de tout faire d'une seule traite dans une seule session. Dès que les fonctionnalités d'un projet moyen se multiplient, le contexte d'une session unique se sature rapidement, amenant Claude à « oublier des choses et commettre des erreurs » (comme détaillé au chapitre 19). La bonne méthode consiste à découper le travail selon la SPEC et à traiter une partie par session :

会话 1：搭骨架——文件结构、todos.json 读写、add 命令 + 测试
会话 2：list 和 done 命令 + 测试
会话 3：边界处理（文件损坏、空清单）+ 补全测试
会话 4：写 README、整体过一遍、交付

Étape 3 : Passer le relais en toute sécurité entre les sessions

C'est une technique propre aux projets de taille moyenne. Une fois qu'une partie est terminée dans une session, comment transférer le travail à la session suivante ? Deux leviers :

• Conclure avec /clear, reprendre avec --resume. Lorsqu'une partie est terminée et qu'il faut passer à une autre tâche non liée, utilisez /clear pour réinitialiser le contexte (les consignes officielles insistent sur le fait d'utiliser fréquemment /clear entre des tâches indépendantes) ; si vous souhaitez poursuivre sur la même lancée, utilisez claude --resume pour sélectionner cette session dans la liste.
• Utiliser SPEC.md comme « carnet de liaison ». Au début de chaque session, demandez-lui de lire rapidement SPEC.md et git log. En quelques secondes, il rattrapera le fil de l'étape précédente — c'est pourquoi la SPEC doit être rédigée sous forme de fichier, et non pas simplement discutée dans le chat : les conversations s'effacent avec les sessions, contrairement aux fichiers.

Voici une phrase d'introduction prête à l'emploi pour lancer le relais, à envoyer au début de chaque nouvelle session :

先读 SPEC.md 和 git log 看我们做到哪了，别改任何代码，
告诉我下一块该做什么、有没有遗留的坑。

Lors de la création de todo-cli, le moindre raccourci peut provoquer un échec — si vous ne lui demandez pas de lire la SPEC au début de la deuxième session et dites simplement de mémoire « continue avec la commande list », il risque de redéfinir différemment les noms de champs JSON déjà établis lors de la première session, provoquant une incompatibilité de format de données inter-sessions et une perte de temps. La règle d'or est donc la suivante : la première phrase d'une nouvelle session doit toujours être « lis d'abord la SPEC et git log », pour lui permettre de se recalibrer de lui-même, ce qui est bien plus précis qu'une reformulation orale.

La documentation officielle le souligne très justement :

Claude Code 在本地保存对话，所以当任务跨越多个会话时，你不必重新解释 context。

Cette sauvegarde des conversations mentionnée officiellement signifie que les fichiers d'historique sont conservés — cependant, attention : recharger ces anciennes conversations consomme de l'espace dans la fenêtre de contexte, et une fois saturé, le modèle perdra en efficacité (le piège décrit au chapitre 19). La SPEC constitue donc un point d'ancrage de relais bien plus fiable que les anciennes conversations : un seul fichier lu en quelques secondes par la nouvelle session suffit pour rétablir le fil, sans encombrer inutilement la fenêtre de contexte.

💡 En résumé : La planification d'un projet moyen = demander d'abord à Claude de vous interviewer pour générer un fichier SPEC.md, puis découper le travail important en « une session par partie » ; utiliser /clear pour terminer et --resume pour reprendre, le fichier SPEC servant de carnet de liaison — les conversations s'effacent, mais pas les fichiers.

---

04 Connexion externe : utiliser MCP pour connecter ce qui est hors de portée

Dès que la structure commence à prendre forme, on arrive rapidement à la troisième étape — La connexion externe. Correspond au chapitre 22 (MCP). Cette étape est totalement inutile pour le petit script local du chapitre 39, mais elle est presque incontournable dans un projet moyen : vous aurez toujours besoin qu'il consulte une documentation externe, lise une base de données ou ouvre une PR.

Quand faut-il penser à MCP ? Le critère officiel est extrêmement simple :

当您发现自己从另一个工具复制数据到聊天中时，请连接一个服务器。

Une situation réelle fréquente lors de la création de todo-cli : au moment de rédiger les tests, vous avez un doute sur l'utilisation exacte d'une méthode d'assertion de unittest. Votre premier réflexe est de chercher dans votre navigateur, puis de copier-coller le résultat pour lui fournir — c'est le signal pour utiliser MCP. Plutôt que de faire ces allers-retours manuels, laissez-le effectuer la recherche lui-même.

Analogie : Brancher un câble réseau sur un ordinateur disposant uniquement d'un disque dur local. Sans connexion, l'ordinateur ne peut lire que le contenu de son disque, et vous devez utiliser une clé USB pour importer des données externes. En branchant le câble, il peut aller les chercher lui-même. Par défaut, Claude est comme cet ordinateur « non connecté » — il n'a accès qu'à vos fichiers et commandes locaux ; MCP est ce câble réseau : configurez-le une fois, et il pourra accéder de lui-même à ce qui était hors de sa portée. La seule différence réside dans ce qui se trouve à l'autre bout du câble : un site de documentation, une base de données ou GitHub.

Ici, nous allons connecter le serveur MCP de documentation officielle, idéal pour s'exercer. Il s'agit d'un serveur HTTP hébergé, ne nécessitant ni connexion ni configuration, ce qui en fait le choix le plus stable pour débuter.

Étape 1 : Ajouter le serveur (dans le terminal, pas dans la session claude)

claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp

Note : Ce serveur est un service hébergé à distance, son ajout nécessite une connexion Internet ; si l'accès à code.claude.com échoue, vérifiez votre connexion réseau ou vos paramètres de proxy.

Résultat attendu : Affichage d'une ligne de confirmation, similaire à Added HTTP MCP server claude-code-docs ....

Étape 2 : Confirmer la connexion

claude mcp list

Résultat attendu : Le serveur claude-code-docs apparaît dans la liste avec la mention ✓ Connected. Ce coche vert signifie que la connexion est établie ; si vous voyez ✗ Failed to connect, il s'agit probablement d'un problème réseau, vérifiez votre connexion.

Étape 3 : Indiquer explicitement dans la session d'utiliser ce serveur pour la recherche

用 claude-code-docs server 查一下 Claude Code 的 subagent 是怎么定义的，
配置文件放哪、有哪些字段。

Résultat attendu : Claude s'arrêtera lors du premier appel à ce serveur pour demander votre approbation (l'approbation requise lors du premier appel d'un outil mentionnée au chapitre 22) — autorisez-le. Il retournera ensuite les explications sur le subagent, et le nom du serveur claude-code-docs sera affiché à côté de l'appel d'outil dans la console. Cette mention garantit que la réponse provient bien de la documentation consultée, et non d'une invention du modèle.

Dans un projet moyen, l'usage réel de MCP dépasse largement la simple consultation de documentation. Voici d'autres exemples courants pour illustrer ses possibilités :

Élément à connecter	Quel serveur connecter	Possibilités offertes
Issues / PR du projet	GitHub MCP	« Implémenter la fonctionnalité décrite dans l'issue #12, puis ouvrir une PR »
Base de données de l'entreprise	MCP PostgreSQL, etc.	« Consulter le nombre de nouvelles tâches ajoutées ce mois-ci » (utilisez systématiquement un compte en lecture seule pour la base de production)
Maquettes de conception	Figma MCP	« Ajuster le format de sortie de la ligne de commande selon cette version de la maquette »

Cependant, plus le projet est grand, plus il est crucial de garder en tête l'avertissement de sécurité avant de connecter un serveur (abordé aux chapitres 21 et 22) :

在连接每个服务器之前，请验证您信任该服务器。获取外部内容的服务器可能会使您面临提示注入风险。

Les serveurs MCP contiennent du code tiers, et Anthropic ne les audite pas pour vous. Privilégiez le catalogue officiel et les serveurs d'éditeurs reconnus, et utilisez systématiquement un compte en lecture seule pour les bases de données — c'est le moyen le plus simple et efficace de minimiser les risques. N'oubliez pas non plus cette remarque officielle : chaque serveur connecté consomme une partie de la fenêtre de contexte. Par conséquent, après avoir testé le serveur de documentation, pensez à le retirer avec claude mcp remove claude-code-docs pour libérer de l'espace.

💡 En résumé : Les projets de taille moyenne peuvent difficilement se passer de MCP — dès que vous vous surprenez à « copier-coller des données pour lui fournir », c'est le moment de connecter un serveur ; commencez avec le serveur de documentation officiel sans connexion pour plus de sécurité, puis connectez GitHub, votre base de données ou Figma pour les besoins réels, en veillant à vérifier la confiance avant connexion, utiliser le mode lecture seule pour les bases de données et déconnecter les serveurs inutilisés.

---

05 Répartition : envoyer un subagent faire les tâches ingrates, et solliciter un modèle frais pour la relecture

À mesure que le code s'accumule, nous arrivons à la quatrième étape — La répartition. Correspond au chapitre 23 (subagent) et au chapitre 29 (agent teams). Cette étape est superflue pour les petites tâches, mais dans un projet moyen, elle constitue un pilier majeur pour éviter d'encombrer la conversation principale et garantir la qualité du code.

Utiliser un subagent pour l'exploration, afin d'éviter d'encombrer la conversation principale

Arrivé à la troisième session de todo-cli, le nombre de fichiers augmente. Supposons que vous souhaitiez identifier où se situe la logique de lecture et d'écriture de todos.json. Ne demandez pas directement à la conversation principale d'ouvrir et de lire chaque fichier — cela saturerait votre contexte principal avec le contenu des fichiers, réduisant l'espace disponible pour le travail de fond (le problème de saturation abordé au chapitre 19). La bonne approche consiste à envoyer un subagent faire cette recherche :

派一个 subagent 去摸清 todos.json 的所有读写都发生在哪些函数里，
只把「哪些文件、哪些函数、各自干啥」的清单报给我，别贴文件全文。

Résultat attendu : Le subagent parcourt les fichiers dans son propre contexte indépendant, puis retourne uniquement une liste synthétique dans la conversation principale. La documentation officielle est très explicite :

由于 context 是你的基本约束，subagents 是可用的最强大的工具之一……它们在单独的 context windows 中运行并报告摘要。

Analogie : Envoyer un stagiaire chercher des documents aux archives. Vous voulez savoir « ce qu'il a trouvé », pas qu'il apporte toute l'armoire d'archives sur votre bureau. Le subagent est ce stagiaire — il fouille les archives (contexte indépendant) de fond en comble et revient avec une simple note de synthèse, laissant votre bureau (contexte principal) parfaitement ordonné.

Faire relire le code par un modèle frais — « pour éviter que l'auteur ne s'auto-évalue »

Une fois la fonctionnalité implémentée, ne demandez pas au Claude qui vient d'écrire le code de le relire lui-même — il aura tendance à justifier ce qu'il vient de faire. Une étape indispensable dans un projet moyen consiste à ouvrir un contexte tout frais dédié à la critique. La documentation officielle l'explique clairement :

在新鲜的 subagent context 中运行的审查者只看到差异和你给它的标准，而不是产生更改的推理，所以它按自己的条件评估结果。

Le plus simple est d'exécuter la commande intégrée /code-review, qui analysera le diff actuel dans un sous-agent frais et signalera les éventuels défauts :

/code-review

Vous pouvez également rédiger vos propres consignes de relecture, en précisant « quoi analyser, selon quels critères et ce qui constitue un défaut » :

用 subagent 对照 SPEC.md 审一遍刚才的改动：每条要求是否实现、
列出的边界情况有没有测试、有没有动到范围外的代码。
只报影响正确性的问题，别报风格偏好。

Lors de la création de todo-cli, le subagent de relecture détectera souvent un bug qui avait échappé à la session principale : nous pensions avoir géré les cas d'erreur de todos.json, mais nous n'avions intercepté que l'absence de fichier (FileNotFoundError), sans gérer le cas où le contenu n'est pas un JSON valide. C'est là toute la valeur d'un « modèle frais » — il n'a pas le biais consistant à croire que « ce qui vient d'être écrit fonctionne ». La documentation officielle conseille toutefois de ne pas s'éparpiller :

告诉审查者只标记影响正确性或陈述要求的缺陷，将其余的视为可选。

Note sur les fonctionnalités expérimentales : Les équipes d'agents (Agent teams, chapitre 29) constituent la « version automatisée et renforcée » de cette étape, et peuvent évoluer avec les versions. Elles permettent à plusieurs sessions de collaborer automatiquement autour d'une liste de tâches partagée — par exemple, un agent écrit le code pendant qu'un autre assure une relecture continue. Pour un projet moyen, commencez par « ouvrir manuellement un subagent pour la relecture » ; lorsque le volume de travail devient trop important pour être suivi individuellement, vous pourrez utiliser les équipes d'agents pour exécuter cette boucle de manière autonome.

💡 En résumé : Deux outils majeurs à activer quand le projet grandit — déléguer l'exploration ingrate à un subagent (parcourt les fichiers dans un contexte indépendant et ne renvoie qu'un résumé pour préserver la conversation principale) ; sécuriser la qualité du code avec un modèle frais pour la critique (/code-review ou consignes personnalisées pour éviter l'auto-évaluation) ; et utiliser les équipes d'agents pour les projets d'envergure (expérimental).

---

06 Tolérance aux pannes : en cas d'erreur, ne bricolez pas de correctifs, revenez proprement en arrière

À mesure qu'un projet grandit, les régressions et les erreurs de modification deviennent monnaie courante, et la pfilième étape est dédiée à ce problème — La tolérance aux pannes. Correspond au chapitre 37 (points de contrôle). Cette étape a été esquissée au chapitre 39, mais elle prend une tout autre importance dans un projet moyen : plus les modifications sont complexes, plus les risques de dérive augmentent, et vous ne pouvez plus vous contenter d'un simple coup d'œil rapide sur les diffs comme pour les petites tâches.

Commençons par l'erreur la plus fréquente chez les débutants : demander à l'IA de « corriger sur cette base » alors que le code est déjà désordonné.

Ne procédez jamais ainsi. Appliquer des correctifs successifs sur un état déjà instable ne fait qu'aggraver la situation — à chaque étape, l'IA s'appuie sur le contexte erroné de la version précédente, creusant ainsi le problème. La bonne approche consiste à revenir proprement à un point connu comme fonctionnel, puis à relancer la modification en formulant plus clairement vos instructions. Il existe deux niveaux de retour en arrière :

Niveau de retour	Outil à utiliser	Point de retour	Cas d'usage
Niveau léger : annuler la dernière modification	Points de contrôle, /rewind ou double appui sur Esc	Avant les modifications apportées par Claude sur ce lot de fichiers	Une ou deux erreurs de modification identifiées immédiatement
Niveau lourd : restaurer un commit propre	git, git restore . (annuler les modifications non indexées) ou git reset --hard <SHA> (revenir à un commit spécifique)	Un état stable validé précédemment	Dérive complète du projet nécessitant de repartir d'un jalon

Le niveau léger est le plus courant : saisissez /rewind pour ouvrir le menu de retour en arrière, qui permet d'annuler uniquement le code, uniquement la conversation, ou les deux. La documentation officielle définit précisément cet outil, avec un point crucial à retenir pour les projets moyens : les points de contrôle ne suivent que les modifications effectuées par Claude au cours de la session active, ne suivent pas les fichiers modifiés par les commandes bash, et ne remplacent en aucun cas git.

C'est pourquoi il est essentiel de réaliser des commits fréquents dans un projet moyen. Les points de contrôle ne gèrent que l'édition de Claude au sein de la session courante ; or, votre projet s'étend sur plusieurs sessions, a exécuté des tests et installé des dépendances — les points de contrôle ne peuvent pas suivre ces actions, contrairement à git. Lors de la création de todo-cli, il est facile de commettre cette erreur : demander dans la troisième session de refactoriser la lecture/écriture JSON, ce qui amène l'IA à modifier trois fichiers et à « optimiser » au passage la logique add sans autorisation, déviant totalement du but. Heureusement, chaque bloc terminé ayant fait l'objet d'un commit, un simple git reset --hard permet de revenir au commit stable précédent et de retrouver l'état initial en trente secondes — si vous n'aviez compté que sur les points de contrôle, les modifications inter-sessions n'auraient pas pu être démêlées.

Une fois revenu en arrière, ne vous précipitez pas pour répéter exactement la même chose. Réfléchissez d'abord à la cause de la dérive — dans la grande majorité des cas, il s'agit d'une omission de contraintes clés dans vos instructions (le principe de « formulation claire » du chapitre 15). Lors de la nouvelle tentative, ajoutez une précision comme « refactorise uniquement ces deux fonctions de lecture et d'écriture, ne touche absolument pas à add », et la modification se déroulera correctement. Le retour en arrière n'est pas un échec, c'est une limitation des pertes.

💡 En résumé : Les erreurs de modification sont fréquentes dans les grands projets — votre premier réflexe doit toujours être de « revenir proprement en arrière » et non de bricoler des correctifs sur un code instable ; utilisez /rewind (léger) pour annuler les éditions de code ou git (lourd) pour restaurer un commit stable ; les points de contrôle ne suivent que les modifications de la session en cours et ne remplacent pas git, d'où l'importance de faire des commits réguliers.

---

07 Pratique : mener un projet réel de l'initialisation à la livraison

La théorie ne suffit pas, il faut maintenant passer à la pratique pour diriger cet orchestre. Voici un processus complet que vous pouvez reproduire à l'identique pour réaliser les deux premières parties de notre todo-cli (structure de base et commandes add/list), en reliant les six étapes décrites précédemment. Il utilise uniquement la bibliothèque standard de Python, la commande python3 suffit (intégrée sous Mac/Linux, disponible après installation de Python sous Windows).

Étape 1 : Initialisation (correspond à la section 02)

mkdir todo-cli && cd todo-cli && git init && claude

Une fois dans la session, demandez de rédiger le CLAUDE.md :

建一个 CLAUDE.md：纯 Python 标准库别引第三方依赖；数据存项目根的 todos.json；
每个功能配 unittest，改完跑 python3 -m unittest 验证；提交信息用中文带 feat:/fix: 前缀。

Résultat attendu : Claude vous présente le contenu, demande votre approbation, puis génère le fichier CLAUDE.md d'une dizaine de lignes. Après approbation, profitez-en pour ajouter la commande de test à la liste d'autorisation : saisissez /permissions dans la session, et ajoutez Bash(python3 -m unittest*) à allow. Résultat attendu : la ligne Bash(python3 -m unittest*) apparaît dans la liste d'autorisation, confirmant l'ajout.

Étape 2 : Planification (correspond à la section 03)

Basculez en plan mode (Shift+Tab), et demandez-lui d'élaborer une solution avant d'agir :

我要做 todo-cli：todo.py 提供 add「文字」加任务、list 列出所有任务（带编号和完成状态），
数据存 todos.json。先告诉我文件结构和你打算怎么实现，等我说「开始」再动手。

Résultat attendu : Il propose une solution comportant todo.py (contenant les fonctions de lecture/écriture de todos.json), les deux sous-commandes add et list (utilisant argparse), ainsi qu'un fichier de test test_todo.py. Il s'arrête en attendant votre validation.

Étape 3 : Implémentation et relecture du diff (correspond à la section 02 sur les permissions)

方案可以，开始吧。先实现 add 和 list，再写对应的 unittest。

Résultat attendu : Claude commence à créer todo.py et test_todo.py en soumettant chaque diff à votre approbation. Examinez-les rapidement pour vérifier trois points : ① Il implémente bien les commandes add et list (conformément au plan) ; ② Aucune dépendance tierce n'est introduite (règle de CLAUDE.md) ; ③ Il ne modifie rien d'autre. Si tout concorde, validez.

Étape 4 : Validation — testez par vous-même, ne croyez pas sur parole le « j'ai fini » (règle absolue)

Lancez d'abord les tests (cette commande ayant été ajoutée à la liste d'autorisation, aucune confirmation ne sera demandée) :

python3 -m unittest

Sortie attendue (l'élément clé étant la ligne OK à la fin) :

...
----------------------------------------------------------------------
Ran 3 tests in 0.00s

OK

Exécutez ensuite manuellement les fonctionnalités réelles :

python3 todo.py add "写第48篇教程"
python3 todo.py add "跑通动手环节"
python3 todo.py list

Sortie attendue (numérotation + indicateur d'état non complété, les symboles exacts dépendant de son implémentation, globalement sous cette forme) :

[1] [ ] 写第48篇教程
[2] [ ] 跑通动手环节

Le fait de voir les tests passer (OK) et la commande list afficher les deux tâches ajoutées confirme que cette partie est fonctionnelle. « L'IA dit que c'est fait » est une hypothèse, le tester et le faire fonctionner est une réalité — ce principe du chapitre 39 est d'autant plus crucial à mesure que le projet grandit.

Étape 5 : Solliciter un modèle frais pour la critique (correspond à la section 05)

/code-review

Résultat attendu : Il examine le diff récent au sein d'un sous-agent frais et rapporte ses constatations (par exemple : « le cas où todos.json n'existe pas n'est pas géré »). Ne corrigez que ce qui affecte la correction du code, laissez de côté les préférences de style pour le moment.

Étape 6 : Livraison (correspond à la section 06 et à git)

我改了哪些文件？给个改动概览。然后用一句话描述这次改动、提交它。

Résultat attendu : Il exécute git status et git diff pour vous montrer le périmètre des modifications, puis propose un message de commit (par exemple : feat: 实现 todo-cli 的 add 和 list 命令) et demande l'autorisation d'exécuter git commit — il s'agit à nouveau de la barrière de permissions décrite au chapitre 20 : il doit vous solliciter avant toute modification de votre historique git.

Étape 7 : Sécuriser la ligne rouge du push

À cette étape, la partie courante est livrée. Mais il existe une frontière sur laquelle aucun compromis n'est possible, quel que soit le projet :

Vous pouvez lui déléguer les commits locaux en toute confiance, mais pour l'étape du git push (publication vers le dépôt distant), vous devez impérativement garder le contrôle.

Avant de pousser votre travail vers un dépôt distant comme GitHub, vous devez impérativement vérifier et valider l'action par vous-même — c'est le sujet abordé en détail au chapitre 43 « Flux de travail Git ». Vous pouvez laisser l'IA gérer les commits locaux après confirmation ; mais l'envoi vers le dépôt distant doit être effectué exclusivement par vos soins.

En suivant ces sept étapes, vous avez orchestré et expérimenté concrètement la séquence complète « Initialisation → Planification → Implémentation → Validation → Critique → Livraison → Sécurisation » sur un projet réel. Il vous suffit ensuite de suivre le même rythme pour implémenter la commande done et gérer les cas limites pour obtenir un todo-cli complet — la méthode reste identique, il s'agit simplement de répéter le même cycle.

💡 En résumé : Passer à la pratique consiste à dérouler les six étapes sur un projet réel — initialisation des règles et permissions → plan mode pour élaborer la solution → validation du diff lors de l'écriture → exécution manuelle des tests et validation fonctionnelle → /code-review pour la critique → commit après vérification du périmètre ; gardez en tête la règle absolue : déléguez le commit local, gérez vous-même le push distant.

---

08 Comparatif : projet jouet vs projet réel, quelles sont les différences

L'utilisation de Claude pour de petits exercices se déroule très différemment d'un projet réel de taille moyenne — la différence réside dans les points de friction qui ne se révèlent que lorsque le projet prend de l'ampleur. Voici une liste comparative des pièges les plus courants pour vous aider à vous auto-évaluer :

Étape	❌ Approche informelle (projet jouet)	✅ Approche structurée (projet réel)
Règles	Rédiger trois lignes de CLAUDE.md suffit	Configurer dès le départ les règles et la base des permissions pour encadrer toutes les sessions ultérieures
Planification	Démarrer l'implémentation sur la base d'une simple consigne d'une phrase	Commencer par un entretien mené par l'IA pour générer SPEC.md, puis découper le projet en plusieurs sessions
Session	Travailler dans une seule session du début à la fin, sans se soucier de sa saturation	Traiter une seule partie par session, utiliser /clear pour conclure, --resume pour reprendre, et SPEC comme carnet de liaison
Ressources externes	Copier-coller manuellement les données dans le chat	Connecter un serveur MCP dès que nécessaire, en validant la confiance et en utilisant le mode lecture seule pour les bases de données
Qualité	Laisser l'auteur du code réviser son propre travail	Confier la critique à un modèle frais (/code-review), pour éviter que l'auteur ne s'auto-évalue
Tolérance aux pannes	Essayer de corriger sur une base de code instable en cas d'erreur	Revenir proprement en arrière (/rewind ou git), et réaliser des commits réguliers pour conserver des points de restauration
Livraison	Laisser les modifications en l'état ou réaliser un commit sans vérifier le périmètre	Vérifier le périmètre → Proposer un message de commit → Réaliser le commit ; gérer le push personnellement

L'essentiel de ce tableau tient en une phrase : les étapes que vous pouvez éviter dans un petit exercice sont indispensables dans un projet réel — car lorsque l'envergure augmente, chaque raccourci pris se paiera doublement par la suite. Lors de la transition d'un « projet jouet » à un « projet réel », on a naturellement tendance à conserver les habitudes informelles des tâches simples, ce qui se traduit par une session saturée dans laquelle on s'entête, des corrections appliquées à la va-vite sur du code instable, et des commits réalisés sans relecture préalable, menant à une série d'erreurs où une tâche censée prendre deux heures finit par occuper une demi-journée. Il faut donc retenir ce principe : plus le projet est grand, plus le processus doit être rigoureux — la rigueur n'est pas une contrainte qui vous ralentit, c'est l'ossature qui vous permet de voir grand en toute sécurité.

Une question revient fréquemment : « Toutes ces étapes ne ralentissent-elles pas le développement d'un projet moyen ? » Bien au contraire — c'est précisément grâce à cette rigueur que vous pouvez déléguer des tâches plus importantes et aller plus loin. Faire l'économie de la planification et de la validation donne l'illusion de la rapidité, mais ne fait que de reporter ce temps sur la correction des erreurs ultérieures.

💡 En résumé : La différence entre un projet jouet et un projet réel réside uniquement dans votre capacité à ne pas sauter ces quelques étapes indispensables lorsque l'envergure augmente ; règles, planification, relais de sessions, confiance externe, critique fraîche, points de restauration et contrôle du push — ces sept aspects ne tolèrent aucun raccourci dans un projet réel, sous peine de le payer cher par la suite.

---

09 Résumé

Ce chapitre constitue le projet de fin d'études de l'ensemble du tutoriel — il n'enseigne aucune nouvelle fonctionnalité, mais vous propose de diriger l'orchestre pour faire jouer ensemble les éléments appris au cours des 47 premiers chapitres sur un projet de taille moyenne.

En reprenant la « partition générale » de notre projet, vous pouvez visualiser à quelle étape chaque pupitre entre en scène :

Étape	Objectif de l'étape	Pupitre mobilisé (chapitres précédents)	Point clé en une phrase
Initialisation	Définir le projet + Rédiger CLAUDE.md + Configurer la base des permissions	12 / 18 / 20	Les règles et la base des permissions sont définies une fois pour toutes pour encadrer toutes les sessions ultérieures
Planification	Réaliser l'entretien pour la SPEC, découper le projet en sessions	16 / 19 / 20	Les conversations s'effacent, seule la SPEC rédigée sous forme de fichier permet un relais inter-sessions fiable
Connexion externe	Connecter MCP à la documentation, à la base de données ou à GitHub	22	Le fait de copier-coller manuellement des données est le signal pour connecter un serveur
Répartition	Exploration par subagent + Relecture par un modèle frais	23 / 29	Isoler les tâches ingrates pour préserver le contexte principal, et éviter que l'auteur ne s'auto-évalue
Tolérance aux pannes	Revenir proprement en arrière en cas d'erreur	37	/rewind pour annuler les éditions, git pour restaurer un commit stable ; réalisez des commits fréquents
Livraison	Validation → commit → Contrôle du push	43 / 44	Déléguez le commit local, gardez le contrôle exclusif du push vers le dépôt distant

Vous devriez maintenant être en mesure de : prendre en charge un besoin de taille moyenne comme « aidez-moi à concevoir un outil/service XX à partir de zéro », sans vous limiter à écrire un script simple au sein d'une seule session — gardez en tête cette partition générale, configurez les règles et les permissions dès l'initialisation, rédigez une SPEC durant la phase de planification, découpez le travail en plusieurs sessions successives, connectez un serveur MCP quand nécessaire, déléguez la relecture à un subagent, revenez proprement en arrière en cas d'erreur, et assurez une livraison propre en gardant le contrôle sur la ligne rouge du push. Une fois ce processus assimilé, tous les outils appris au cours des 47 premiers chapitres prennent vie et s'unissent pour vous permettre de réaliser des projets sérieux.

La partie pratique de ce tutoriel se termine ici — depuis la version minimale du chapitre 39 jusqu'à ce flux de travail complet de projet moyen, vous avez expérimenté à la fois le rôle de musicien et de chef d'orchestre.

---

Le chapitre suivant 49 « Bonnes pratiques » — après avoir vu « comment faire », nous prendrons de la hauteur pour aborder « comment faire mieux » : en synthétisant les retours d'expérience officiels et pratiques sous forme de liste de contrôle. Pensez-y — pourquoi certains règlent-ils ce processus en trois phrases tandis que d'autres font cinq allers-retours ? La différence réside souvent dans ces petites habitudes discrètes mais déterminantes, que nous détaillerons au prochain chapitre.

---

Lectures recommandées

• Quatre tâches courantes : exploration de la base de code, correction de bugs, refactorisation et écriture de tests
• Manuel de référence de la CLI : commandes et options
• Plugins : regrouper les configurations éparses en un clic