# 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