1% ------------------------------------------------------------------------------2\section{Dépannage}3\label{sec:depannage}4% ------------------------------------------------------------------------------56\begin{enbref}7Les pannes d'un agent sont prévisibles : contexte saturé, mauvaise convention, fausse réussite, boucle sans progrès, fichier introuvable, permission refusée, limite atteinte. Ce chapitre relie chaque symptôme à sa cause et au geste qui le corrige, et indique où regarder quand rien ne marche (\texttt{/doctor}, \texttt{/status}, \texttt{/bug}, journaux).8\end{enbref}910{\small\Needspace{9\baselineskip}11\begin{tabularx}{\textwidth}{R{3.8cm}XX}12\caption{Symptômes en cours de travail, causes et remèdes}\label{tab:depannage}\\13\rowcolor{uqoRouge} \hc{Symptôme} & \hc{Cause probable} & \hc{Remède} \\14\endfirsthead15\captionsuite{Symptômes en cours de travail, causes et remèdes}16\rowcolor{uqoRouge} \hc{Symptôme} & \hc{Cause probable} & \hc{Remède} \\17\endhead18\suitepage{3}19\endfoot20\finTableau21\endlastfoot22L'agent « oublie » une consigne donnée au début & Contexte saturé ; les premières instructions pèsent moins. & \texttt{/context} pour voir ; \texttt{/compact} avec consigne ou \texttt{/clear} ; mettre la consigne dans \texttt{CLAUDE.md} avec \texttt{\#}. \\23\rowcolor{uqoBgClair}24Il applique une convention générique (moyenne simple, profit dans les indirects) & La convention du cours n'est pas dans \texttt{CLAUDE.md}, ou le fichier est trop long pour qu'il la retienne. & Ajouter la règle, courte et impérative, avec le pourquoi ; raccourcir le reste. \\25« C'est fait » mais rien n'a changé, ou c'est faux & Fausse réussite : la boucle s'est arrêtée sur l'apparence, sans test. & Exiger la preuve brute : « montre la formule exacte en I12 », « exécute et colle la sortie ». Fournir un test (\texttt{/verif-chaine}). \\26\rowcolor{uqoBgClair}27Il tourne en rond, réessaie la même chose & Aucun critère d'arrêt exécutable. & \kbd{Échap} ; reformuler avec un test précis ; si deux corrections échouent, \texttt{/clear} et repartir avec une requête qui intègre ce qu'on a appris. \\28Il modifie un fichier que vous ne vouliez pas toucher & Zèle : objectif interprété largement. & \texttt{/rewind} pour restaurer ; règle \emph{deny} dans \texttt{settings.json} ; hook \texttt{PreToolUse} (§\ref{sec:hooks}) ; nommer les fichiers autorisés dans la requête. \\29\rowcolor{uqoBgClair}30Il a collé des valeurs à la place de formules & Il optimise le résultat visible, pas la structure. & Interdit explicite dans \texttt{CLAUDE.md} ; test de la chaîne après chaque édition (hook \texttt{PostToolUse}). \\31« File not found » sur un fichier qui existe & Mauvais dossier de départ, ou chemin avec espaces ou accents mal cité. & \texttt{!pwd} et \texttt{!ls} pour voir où vous êtes ; désigner le fichier avec \texttt{@} (autocomplétion) ; éviter espaces et accents dans les noms. \\32\rowcolor{uqoBgClair}33Une commande Python échoue : module absent & \texttt{openpyxl}, \texttt{pandas} non installés dans le Python que l'agent appelle. & « Installe les dépendances dans un environnement virtuel \texttt{.venv} et utilise-le » ; ou \texttt{!python3 -m pip install openpyxl pandas}. \\34Il ne peut pas lire le PDF ou l'image & Fichier trop gros, protégé, ou scanné sans texte. & Extraire les pages utiles ; pour un scan, coller une capture de la page ; vérifier que le PDF n'est pas verrouillé. \\35\rowcolor{uqoBgClair}36« Permission denied » ou action bloquée sans question & Règle \emph{deny} active, ou hook qui refuse. & \texttt{/permissions} pour voir les règles ; lire le message du hook ; c'est souvent la protection qui fait son travail. \\37Limite d'usage atteinte & Fenêtre de cinq heures ou plafond hebdomadaire de l'abonnement. & \texttt{/usage} pour l'heure de renouvellement ; \texttt{/export} ; noter l'état dans \texttt{JOURNAL.md} ; revenir plus tard avec \texttt{claude -c}. \\38\rowcolor{uqoBgClair}39Réponses très lentes & Modèle Opus, contexte plein, ou sous-agents nombreux. & \texttt{/model sonnet} ; \texttt{/compact} ; \texttt{/fast} si offert. \\40Le terminal affiche des caractères cassés & Police sans les symboles, ou terminal ancien. & Police « Nerd Font » ; Windows Terminal ou iTerm2 ; \texttt{/config} pour un thème sans icônes. \\41\rowcolor{uqoBgClair}42Claude Code ne démarre plus, ou une commande a disparu & Mise à jour automatique ; nom de commande changé. & \texttt{claude doctor} ; \texttt{claude update} ; \texttt{/help} pour le nom actuel ; consulter le journal des versions. \\43\end{tabularx}44}4546\subsection{Où regarder quand rien ne marche}4748\begin{enumerate}[label=\textbf{\arabic*.},leftmargin=2em]49 \item \textbf{\texttt{/status}} : compte connecté, modèle, dossier de travail, version. La moitié des problèmes sont « je ne suis pas dans le bon dossier » ou « je ne suis pas connecté au bon compte ».50 \item \textbf{\texttt{/doctor}} (ou \texttt{claude doctor} hors session) : diagnostic de l'installation et des mises à jour \parencite{cc_troubleshooting}.51 \item \textbf{\texttt{/context}} : ce qui occupe la fenêtre ; si \texttt{CLAUDE.md} y pèse 15\,\%, il est trop long.52 \item \textbf{\texttt{/permissions}} et \textbf{\texttt{/hooks}} : ce qui est autorisé, interdit, et ce qui s'exécute automatiquement.53 \item \textbf{Les journaux} : les sessions sont dans \texttt{\textasciitilde/.claude/projects/}, un dossier par dossier de travail ; \texttt{/export} en produit une version lisible.54 \item \textbf{\texttt{/bug}} : envoie un rapport à Anthropic avec le contexte de la session (relisez ce qu'il contient avant d'envoyer, surtout s'il y a des données du TP).55 \item \textbf{La documentation} \parencite{cc_troubleshooting} et la page des versions : les commandes de ce guide sont celles du 6~septembre 2026.56\end{enumerate}5758\begin{astuce}[Le réflexe qui règle le plus de cas]59Quand l'agent part de travers, ne le corrigez pas une troisième fois dans la même conversation. \kbd{Échap}, \texttt{/clear}, puis une requête neuve qui contient ce que vous avez appris : le fichier exact, la règle exacte, le test qui dira si c'est réussi. Une conversation encombrée d'échecs produit des réponses de moins en moins bonnes ; une requête propre en produit une bonne du premier coup.60\end{astuce}61