claude-code-best-practice/fr/CLAUDE.md

CLAUDE.md

Ce fichier fournit des consignes à Claude Code (claude.ai/code) lorsqu'il travaille avec le code de ce dépôt.

Vue d'ensemble du dépôt

Ceci est un dépôt de bonnes pratiques pour la configuration de Claude Code, démontrant des patterns pour skills, sous-agents, hooks et commandes. Il sert d'implémentation de référence plutôt que de codebase applicative.

Composants clés

Système météo (workflow d'exemple)

Une démonstration de deux patterns de skills distincts via l'architecture Commande → Agent → Skill :

• Commande /weather-orchestrator (.claude/commands/weather-orchestrator.md) : point d'entrée — demande C/F à l'utilisateur, invoque l'agent, puis invoque le skill SVG
• Agent weather-agent (.claude/agents/weather-agent.md) : récupère la température avec son skill préchargé weather-fetcher (pattern agent skill)
• Skill weather-fetcher (.claude/skills/weather-fetcher/SKILL.md) : préchargé dans l'agent — instructions pour récupérer la température depuis Open-Meteo
• Skill weather-svg-creator (.claude/skills/weather-svg-creator/SKILL.md) : skill — crée une carte météo SVG, écrit orchestration-workflow/weather.svg et orchestration-workflow/output.md

Deux patterns de skills : agent skills (préchargés via le champ skills:) vs skills (invoqués via l'outil Skill). Voir orchestration-workflow/orchestration-workflow.md pour le diagramme de flux complet.

Structure de définition des skills

Les skills dans .claude/skills/<name>/SKILL.md utilisent un frontmatter YAML :

• name : nom d'affichage et /slash-command (par défaut le nom du répertoire)
• description : quand invoquer (recommandé pour l'auto-découverte)
• argument-hint : indice d'autocomplétion (par ex. [issue-number])
• disable-model-invocation : mettre true pour empêcher l'invocation automatique
• user-invocable : mettre false pour masquer du menu / (connaissance d'arrière-plan uniquement)
• allowed-tools : outils autorisés sans demandes de permission quand le skill est actif
• model : modèle à utiliser quand le skill est actif
• context : mettre fork pour exécuter dans un contexte de sous-agent isolé
• agent : type de sous-agent pour context: fork (défaut : general-purpose)
• hooks : hooks de cycle de vie limités à ce skill

Système de présentation

Voir .claude/rules/presentation.md — le travail de présentation est délégué par présentation à presentation-vibe-coding (pour presentation/vibe-coding-to-agentic-engineering/) ou presentation-claude-gemini (pour presentation/2026-04-25-gdg-kolachi-cli-claude-code-gemini/).

Système de hooks

Système multiplateforme de notifications sonores dans .claude/hooks/ :

• scripts/hooks.py : gestionnaire principal des événements hook Claude Code
• config/hooks-config.json : configuration partagée de l'équipe
• config/hooks-config.local.json : overrides personnels (ignorés par git)
• sounds/ : fichiers audio organisés par événement hook (générés via ElevenLabs TTS)

Événements hook configurés dans .claude/settings.json : PreToolUse, PostToolUse, UserPromptSubmit, Notification, Stop, SubagentStart, SubagentStop, PreCompact, SessionStart, SessionEnd, Setup, PermissionRequest, TeammateIdle, TaskCompleted, ConfigChange.

Traitement spécial : les commits git déclenchent le son pretooluse-git-committing.

Patterns critiques

Orchestration de sous-agents

Les sous-agents ne peuvent pas invoquer d'autres sous-agents via des commandes bash. Utilise l'outil Agent (renommé depuis Task en v2.1.63 ; Task(...) fonctionne encore comme alias) :

Agent(subagent_type="agent-name", description="...", prompt="...", model="haiku")

Sois explicite sur l'usage des outils dans les définitions de sous-agents. Évite les termes vagues comme "launch", qui pourraient être interprétés comme des commandes bash.

Structure de définition des sous-agents

Les sous-agents dans .claude/agents/*.md utilisent un frontmatter YAML :

• name : identifiant du sous-agent
• description : quand invoquer (utilise "PROACTIVELY" pour l'auto-invocation)
• tools : allowlist d'outils séparée par des virgules (hérite de tout si omis). Supporte la syntaxe Agent(agent_type)
• disallowedTools : outils à refuser, retirés de la liste héritée ou spécifiée
• model : alias de modèle : haiku, sonnet, opus ou inherit (défaut : inherit)
• permissionMode : mode de permission (par ex. "acceptEdits", "plan", "bypassPermissions")
• maxTurns : nombre maximal de tours agentiques avant arrêt du sous-agent
• skills : liste de noms de skills à précharger dans le contexte de l'agent
• mcpServers : serveurs MCP pour ce sous-agent (noms de serveurs ou configs inline)
• hooks : hooks de cycle de vie limités à ce sous-agent (tous les événements hook sont supportés ; PreToolUse, PostToolUse et Stop sont les plus courants)
• memory : portée de mémoire persistante — user, project ou local (voir reports/claude-agent-memory.md)
• background : mettre true pour toujours exécuter comme tâche en arrière-plan
• effort : surcharge du niveau d'effort : low, medium, high, max (défaut : hérite de la session)
• isolation : mettre "worktree" pour exécuter dans un worktree git temporaire
• color : couleur de sortie CLI pour distinction visuelle

Hiérarchie de configuration

1. Managed (managed-settings.json / plist MDM / Registry) : imposé par l'organisation, non surchargeable
2. Arguments de ligne de commande : overrides pour une seule session
3. .claude/settings.local.json : paramètres projet personnels (ignorés par git)
4. .claude/settings.json : paramètres partagés par l'équipe
5. ~/.claude/settings.json : valeurs globales personnelles par défaut
6. hooks-config.local.json surcharge hooks-config.json

Désactiver les hooks

Mettre "disableAllHooks": true dans .claude/settings.local.json, ou désactiver des hooks individuels dans hooks-config.json.

Répondre aux questions de bonnes pratiques

Quand l'utilisateur pose une question de bonnes pratiques Claude Code, cherche toujours d'abord dans ce dépôt (best-practice/, reports/, tips/, implementation/ et README.md) avant de t'appuyer sur la connaissance d'entraînement ou des sources externes. Ce dépôt est la source d'autorité — ne bascule vers les docs externes ou le web que si la réponse n'est pas trouvée ici.

Bonnes pratiques de workflow

Tirées de l'expérience avec ce dépôt :

• Garder CLAUDE.md sous 200 lignes par fichier pour une adhérence fiable
• .claude/rules/*.md avec frontmatter YAML paths: sont chargés paresseusement seulement quand Claude touche des fichiers correspondants ; sans frontmatter, ils se chargent dans chaque session comme CLAUDE.md
• Utiliser les commandes pour les workflows plutôt que des agents autonomes
• Créer des sous-agents spécifiques aux fonctionnalités avec skills (divulgation progressive), plutôt que des agents généralistes
• Faire un /compact manuel vers ~50 % d'usage du contexte
• Commencer avec plan mode pour les tâches complexes
• Utiliser un workflow de liste de tâches avec validation humaine pour les tâches multi-étapes
• Découper les sous-tâches assez petites pour tenir sous 50 % du contexte

Astuces de débogage

• Utilise /doctor pour les diagnostics
• Lance les commandes terminal longues comme tâches en arrière-plan pour une meilleure visibilité des logs
• Utilise les MCP d'automatisation navigateur (Claude in Chrome, Playwright, Chrome DevTools) pour que Claude inspecte les logs console
• Fournis des captures d'écran quand tu signales des problèmes visuels

Règles de commit Git

Quand tu commits des changements, crée des commits séparés par fichier. NE regroupe PAS plusieurs changements de fichiers dans un seul commit. Chaque fichier obtient son propre commit avec un message descriptif spécifique à ses changements.

Par exemple, si README.md, best-practice/claude-subagents.md et un fichier de skill ont tous changé :

• Commit 1 : git add README.md → commit avec message spécifique au README
• Commit 2 : git add best-practice/claude-subagents.md → commit avec message spécifique à la doc subagents
• Commit 3 : git add .claude/skills/weather-fetcher/SKILL.md → commit avec message spécifique au skill

Cela rend l'historique git plus propre et plus facile à relire, revert ou cherry-pick changement par changement.

Documentation

Voir .claude/rules/markdown-docs.md pour les standards de documentation. Docs clés :

• best-practice/claude-subagents.md : frontmatter des sous-agents, hooks et agents du dépôt
• best-practice/claude-commands.md : patterns de commandes slash et référence des commandes intégrées
• orchestration-workflow/orchestration-workflow.md : diagramme de flux du système météo