Guide de Dépannage

Ce guide couvre les problèmes courants et leurs solutions lors de l'utilisation de Claude-Craft.

Table des Matières

Problèmes d'Installation
Problèmes d'Agents
Problèmes de Commandes
Problèmes de Configuration
Problèmes d'Outils
Problèmes de Performance
Obtenir de l'Aide

Problèmes d'Installation

Commandes Non Reconnues Après Installation

Symptômes :

Les commandes slash comme /symfony:check-compliance ne fonctionnent pas
Claude ne reconnaît pas les commandes installées

Solutions :

Redémarrer Claude Code

bash

# Quitter complètement Claude Code
exit

# Redémarrer
claude

Vérifier l'installation

bash

ls -la .claude/commands/
# Devrait afficher les répertoires de commandes

Vérifier le format des fichiers de commandes

bash

head -5 .claude/commands/symfony/check-compliance.md
# Devrait commencer par un en-tête markdown correct

Fichiers Non Trouvés Pendant l'Installation

Symptômes :

Erreurs "Fichier source non trouvé"
Règles ou templates manquants

Solutions :

Vérifier le chemin Claude-Craft

bash

# Vérifier que vous êtes dans le répertoire claude-craft
pwd
ls -la Dev/scripts/

Vérifier que les fichiers de langue existent
bash
```
ls -la Dev/i18n/fr/Symfony/rules/
```

Utiliser un chemin TARGET absolu

bash

# Au lieu de
make install-symfony TARGET=./backend

# Utilisez
make install-symfony TARGET=/chemin/complet/vers/backend

Erreurs Permission Denied

Symptômes :

Impossible d'exécuter les scripts d'installation
Impossible d'écrire dans le répertoire cible

Solutions :

Rendre les scripts exécutables

bash

chmod +x Dev/scripts/*.sh
chmod +x Project/*.sh
chmod +x Infra/*.sh
chmod +x Tools/*/*.sh

Vérifier les permissions du répertoire cible

bash

ls -la ~/mon-projet/
# S'assurer d'avoir les permissions d'écriture

Exécuter avec l'utilisateur approprié

bash

# N'utilisez pas sudo sauf si nécessaire
# Vérifier la propriété du répertoire
ls -la ~/mon-projet

L'Installation Crée un Répertoire Vide

Symptômes :

Répertoire .claude/ créé mais vide ou fichiers manquants

Solutions :

Vérifier les erreurs dans la sortie

bash

# Exécuter avec sortie verbeuse
make install-symfony TARGET=./backend 2>&1 | tee install.log

Vérifier que la source existe
bash
```
ls -la Dev/i18n/fr/Symfony/
```

Essayer l'exécution directe du script

bash

./Dev/scripts/install-symfony-rules.sh --lang=fr ./backend

Problèmes d'Agents

Agent Non Disponible

Symptômes :

@api-designer ou autres agents ne répondent pas
Erreurs de type "Agent inconnu"

Solutions :

Vérifier que les fichiers agents existent

bash

ls -la .claude/agents/
# Devrait lister les fichiers .md des agents

Vérifier le format du fichier agent

bash

head -20 .claude/agents/api-designer.md
# Devrait avoir un frontmatter correct avec name et description

Réinstaller les agents

bash

make install-common TARGET=. OPTIONS="--force"

L'Agent Donne des Réponses Non Pertinentes

Symptômes :

L'agent ne suit pas ses instructions spécialisées
Réponses génériques au lieu de conseils experts

Solutions :

Fournir plus de contexte

markdown

@symfony-reviewer Revois mon implémentation de UserService

Contexte :
- Symfony 7 avec API Platform
- Clean Architecture
- Approche DDD

Code à revoir :
[coller le code ici]

Être spécifique dans votre demande

markdown

# Au lieu de
@database-architect Aide-moi avec ma base de données

# Utilisez
@database-architect Conçois le schéma pour l'agrégat User avec :
- Entité User (id, email, password_hash)
- Entité Role (many-to-many avec User)
- Entité Permission (many-to-many avec Role)
- Piste d'audit pour les modifications utilisateur

Vérifier le fichier de contexte projet

bash

cat .claude/references/<your-tech>/project-context.md
# S'assurer qu'il décrit votre projet avec précision

Conflits entre Agent et Règles du Projet

Symptômes :

Les suggestions de l'agent contredisent les conventions du projet
Conseils incohérents

Solutions :

Mettre à jour le contexte projet
- Ajouter les conventions spécifiques dans 00-project-context.md
- Inclure les préférences et contraintes de l'équipe

Être explicite dans les demandes

markdown

@api-designer Conçois l'endpoint en suivant nos conventions RESTful
(voir 00-project-context.md pour nos standards API)

Problèmes de Commandes

Commande Non Trouvée

Symptômes :

/symfony:generate-crud retourne "commande inconnue"
Les suggestions de commandes n'apparaissent pas

Solutions :

Vérifier le répertoire des commandes

bash

ls .claude/commands/symfony/
# Devrait inclure generate-crud.md

Vérifier le namespace

bash

# Les commandes sont au format : /{namespace}:{commande}
# Namespaces disponibles :
ls .claude/commands/
# common/, symfony/, flutter/, python/, react/, reactnative/, docker/

Lister les commandes disponibles
bash
```
# Dans Claude Code, tapez :
/help
```

Erreurs d'Exécution de Commande

Symptômes :

La commande démarre mais échoue
Sortie ou erreurs inattendues

Solutions :

Vérifier les prérequis
- Certaines commandes nécessitent des outils spécifiques
- Vérifier que les dépendances requises sont installées

Examiner le fichier de commande

bash

cat .claude/commands/symfony/generate-crud.md
# Comprendre ce que la commande attend

Fournir les paramètres requis

bash

# Au lieu de
/symfony:generate-crud

# Utilisez
/symfony:generate-crud User --with-api --with-tests

Sortie de Commande Incorrecte

Symptômes :

Le code généré ne correspond pas au style du projet
Mauvais patterns technologiques utilisés

Solutions :

Mettre à jour le contexte projet

bash

# Éditer .claude/references/<your-tech>/project-context.md
# Ajouter les patterns et conventions spécifiques

Personnaliser les templates

bash

# Éditer les templates dans .claude/templates/
# Ajuster pour correspondre au style de votre projet

Problèmes de Configuration

Configuration YAML Invalide

Symptômes :

make config-validate échoue
Erreurs de syntaxe dans la configuration

Solutions :

Vérifier la syntaxe YAML

bash

# Valider le YAML
yq e '.' claude-projects.yaml

Erreurs YAML courantes :

yaml

# Incorrect : indentation incohérente
projects:
  - name: "projet"
    path: "/chemin"  # 2 espaces
     technologies: ["symfony"]  # 3 espaces - ERREUR !

# Correct : indentation cohérente
projects:
  - name: "projet"
    path: "/chemin"
    technologies: ["symfony"]

Valider avec l'outil

bash

make config-validate CONFIG=claude-projects.yaml

Projet Non Trouvé dans la Configuration

Symptômes :

"Projet non trouvé" lors de l'installation
Projet non listé

Solutions :

Vérifier l'orthographe du nom du projet

bash

# Lister les projets
make config-list CONFIG=claude-projects.yaml

# Les noms sont sensibles à la casse

Vérifier le chemin du fichier de configuration

bash

# Par défaut cherche claude-projects.yaml dans le répertoire courant
# Spécifier explicitement :
make config-install CONFIG=/chemin/vers/config.yaml PROJECT=monprojet

Configuration Non Appliquée

Symptômes :

Les changements de config ne prennent pas effet
Anciens paramètres persistent

Solutions :

Réinstaller avec force

bash

make config-install CONFIG=claude-projects.yaml PROJECT=monprojet OPTIONS="--force"

Vérifier les conflits

bash

# Supprimer l'installation existante
rm -rf /chemin/vers/projet/.claude

# Réinstaller
make config-install CONFIG=claude-projects.yaml PROJECT=monprojet

Problèmes d'Outils

StatusLine Ne S'Affiche Pas

Symptômes :

Barre de statut vide ou par défaut
Status line personnalisée ne s'affiche pas

Solutions :

Vérifier que le script est installé

bash

ls -la ~/.claude/statusline.sh
# Devrait exister et être exécutable

Vérifier settings.json

bash

cat ~/.claude/settings.json | jq '.statusLine'
# Devrait afficher :
# {
#   "type": "command",
#   "command": "~/.claude/statusline.sh"
# }

Tester le script manuellement

bash

echo '{"model":{"display_name":"Test","id":"claude-opus"}}' | ~/.claude/statusline.sh
# Devrait afficher une status line formatée

Vérifier jq

bash

which jq
# Installer si manquant : brew install jq / apt install jq

Problèmes de Profil MultiAccount

Symptômes :

Impossible de changer de profil
Profil non reconnu

Solutions :

Lister les profils
bash
```
./claude-accounts.sh list
```

Vérifier le répertoire des profils

bash

ls -la ~/.claude-profiles/
# Devrait contenir les répertoires de profils

Vérifier le fichier de mode du profil

bash

cat ~/.claude-profiles/monprofil/.mode
# Devrait contenir "shared" ou "isolated"

Recréer le profil problématique

bash

./claude-accounts.sh remove monprofil
./claude-accounts.sh add monprofil --mode=shared

Erreurs yq pour ProjectConfig

Symptômes :

"yq: command not found"
Erreurs de parsing YAML

Solutions :

Installer yq

bash

# macOS
brew install yq

# Linux
sudo snap install yq
# ou
sudo wget https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 -O /usr/local/bin/yq
sudo chmod +x /usr/local/bin/yq

Vérifier la version de yq

bash

yq --version
# Devrait être v4.x (mikefarah/yq, pas kislyuk/yq)

Problèmes de Hooks et Sandboxing

Les Hooks Ne S'Exécutent Pas

Symptômes :

Les hooks PreToolUse/PostToolUse ne se déclenchent pas
Les hooks PreCompact/PostCompact sont ignorés

Solutions :

Vérifier la configuration dans settings.json

bash

cat .claude/settings.json | jq '.hooks'
# Doit afficher la configuration des hooks

Vérifier la version de Claude Code

bash

claude --version
# Les hooks nécessitent v2.1.47+ (PreCompact: v2.1.76+, PostCompact: v2.1.76+)
# Recommandé : v2.1.193

Vérifier que le script hook est exécutable

bash

ls -la ~/.claude/hooks/
chmod +x ~/.claude/hooks/*.sh

Erreur de Sandbox

Symptômes :

Messages d'erreur liés au sandboxing
Les sous-processus échouent avec des erreurs de permission

Solutions :

Vérifier le support du sandbox

bash

# Le sandboxing PID namespace nécessite Linux
# Sur macOS, le sandbox utilise une approche différente

Désactiver temporairement si nécessaire
- Vérifier sandbox.failIfUnavailable dans settings.json
- Sur les systèmes sans support PID namespace, le sandbox se dégrade gracieusement

Les Serveurs MCP Ne Répondent Pas

Symptômes :

Les outils MCP ne sont pas disponibles
Erreurs de connexion MCP

Solutions :

Vérifier que le serveur MCP est lancé

bash

# Vérifier les processus MCP
ps aux | grep mcp

Utiliser ToolSearch pour le chargement paresseux
- Les outils MCP peuvent être chargés à la demande avec ToolSearch
- Cela réduit la consommation de contexte de 95%
Vérifier la sécurité MCP
- Auditer le code source des serveurs MCP tiers
- Utiliser Claude Code v2.1.97+ avec des serveurs MCP (corrections de sécurité CVE)
- Voir .claude/rules/11-security.md pour la checklist de vetting MCP

Problèmes de Performance

Exécution de Commande Lente

Symptômes :

Les commandes mettent du temps à répondre
StatusLine se met à jour lentement

Solutions :

Vérifier les paramètres de cache

bash

# Dans ~/.claude/statusline.conf
SESSION_CACHE_TTL=60   # Réduire si trop lent
WEEKLY_CACHE_TTL=300   # Réduire si trop lent

Vider les caches
bash
```
rm /tmp/.ccusage_*
```
Vérifier le réseau
- Certaines fonctionnalités nécessitent le réseau (ccusage)
- Réseau lent = mises à jour lentes

Utilisation Élevée de la Fenêtre de Contexte

Symptômes :

L'indicateur 📊 montre un pourcentage élevé rapidement
Avertissements "Limite de contexte"

Solutions :

Utiliser /context pour des suggestions d'optimisation
```
/context
```
Compacter proactivement à 70%
```
/compact
```

Ajuster l'effort selon la tâche

/effort low     # Pour les tâches simples
/effort high    # Pour l'architecture complexe

Démarrer une nouvelle conversation
bash
```
exit
claude
```
Être concis dans les demandes
- Éviter de coller de gros blocs de code
- Référencer les fichiers au lieu de coller
Configurer RTK pour réduire les tokens
```
/common:setup-rtk
```
RTK réduit la consommation de tokens de 55-65% sur les commandes CLI.

Utiliser les agents pour les tâches complexes

markdown

# Au lieu de coller tout le codebase
@research-assistant Trouve tous les fichiers liés à l'authentification dans src/

Obtenir de l'Aide

Consulter la Documentation

Docs principales : répertoire docs/
Référence agents : docs/AGENTS.md
Référence commandes : docs/COMMANDS.md
Guide technologies : docs/TECHNOLOGIES.md

Obtenir les Infos de Version

bash

# Scripts d'installation
./Dev/scripts/install-symfony-rules.sh --version

# Outils
./Tools/MultiAccount/claude-accounts.sh --version
./Tools/ProjectConfig/claude-projects.sh --version

Signaler des Problèmes

Si vous rencontrez des bugs :

Collecter les informations :
- Version Claude-Craft
- Système d'exploitation
- Étapes pour reproduire
- Messages d'erreur
Vérifier les issues existantes sur GitHub
Créer une nouvelle issue avec les détails

Demander de l'Aide

markdown

@research-assistant J'ai un problème avec [décrire le problème]

Environnement :
- OS : [votre OS]
- Version Claude-Craft : [version]
- Technologie : [symfony/flutter/etc.]

Ce que j'ai essayé :
1. [étape 1]
2. [étape 2]

Message d'erreur :
[coller l'erreur]

Checklist de Corrections Rapides

Quand quelque chose ne fonctionne pas :

[ ] Redémarrer Claude Code
[ ] Vérifier l'installation (ls .claude/)
[ ] Vérifier les permissions des fichiers
[ ] Valider la configuration
[ ] Vider les caches
[ ] Vérifier les dépendances (jq, yq)
[ ] Essayer la réinstallation avec --force
[ ] Consulter la documentation
[ ] Demander de l'aide

← Référence des Outils | Gestion du Backlog →

Guide de Dépannage ​

Table des Matières ​

Problèmes d'Installation ​

Commandes Non Reconnues Après Installation ​

Fichiers Non Trouvés Pendant l'Installation ​

Erreurs Permission Denied ​

L'Installation Crée un Répertoire Vide ​

Problèmes d'Agents ​

Agent Non Disponible ​

L'Agent Donne des Réponses Non Pertinentes ​

Conflits entre Agent et Règles du Projet ​

Problèmes de Commandes ​

Commande Non Trouvée ​

Erreurs d'Exécution de Commande ​

Sortie de Commande Incorrecte ​

Problèmes de Configuration ​

Configuration YAML Invalide ​

Projet Non Trouvé dans la Configuration ​

Configuration Non Appliquée ​

Problèmes d'Outils ​

StatusLine Ne S'Affiche Pas ​

Problèmes de Profil MultiAccount ​

Erreurs yq pour ProjectConfig ​

Problèmes de Hooks et Sandboxing ​

Les Hooks Ne S'Exécutent Pas ​

Erreur de Sandbox ​

Les Serveurs MCP Ne Répondent Pas ​

Problèmes de Performance ​

Exécution de Commande Lente ​

Utilisation Élevée de la Fenêtre de Contexte ​

Obtenir de l'Aide ​

Consulter la Documentation ​

Obtenir les Infos de Version ​

Signaler des Problèmes ​

Demander de l'Aide ​

Checklist de Corrections Rapides ​

Guide de Dépannage

Table des Matières

Problèmes d'Installation

Commandes Non Reconnues Après Installation

Fichiers Non Trouvés Pendant l'Installation

Erreurs Permission Denied

L'Installation Crée un Répertoire Vide

Problèmes d'Agents

Agent Non Disponible

L'Agent Donne des Réponses Non Pertinentes

Conflits entre Agent et Règles du Projet

Problèmes de Commandes

Commande Non Trouvée

Erreurs d'Exécution de Commande

Sortie de Commande Incorrecte

Problèmes de Configuration

Configuration YAML Invalide

Projet Non Trouvé dans la Configuration

Configuration Non Appliquée

Problèmes d'Outils

StatusLine Ne S'Affiche Pas

Problèmes de Profil MultiAccount

Erreurs yq pour ProjectConfig

Problèmes de Hooks et Sandboxing

Les Hooks Ne S'Exécutent Pas

Erreur de Sandbox

Les Serveurs MCP Ne Répondent Pas

Problèmes de Performance

Exécution de Commande Lente

Utilisation Élevée de la Fenêtre de Contexte

Obtenir de l'Aide

Consulter la Documentation

Obtenir les Infos de Version

Signaler des Problèmes

Demander de l'Aide

Checklist de Corrections Rapides