Ce guide n’est pas la documentation officielle d’Anthropic. C’est une ressource communautaire fondée sur mon exploration de Claude Code au cours de plusieurs mois.
Ce que vous y trouverez :
Des patterns qui ont fonctionné pour moi
Des observations qui ne s’appliquent pas nécessairement à votre workflow
Des estimations de temps et des pourcentages qui sont des approximations, pas des mesures
Ce que vous n’y trouverez pas :
Des réponses définitives (l’outil est trop récent)
Des affirmations de performances mesurées
La garantie qu’une technique fonctionnera pour vous
Utilisez ce guide de façon critique. Expérimentez. Partagez ce qui fonctionne.
⚠️ Note (Jan 2026) : Si vous avez entendu parler de ClawdBot récemment, c’est un outil différent. ClawdBot est un chatbot hébergé en local, accessible via des messageries (Telegram, WhatsApp, etc.), conçu pour l’automatisation personnelle et la domotique. Claude Code est un outil CLI pour développeurs (intégration terminal/IDE) axé sur les workflows de développement logiciel. Les deux utilisent des modèles Claude mais s’adressent à des publics et des cas d’usage distincts. Plus de détails dans l’Annexe B : FAQ.
Claude Code est disponible sous deux formes : le CLI (sur lequel ce guide se concentre) et l’onglet Code dans l’application de bureau Claude. Même moteur sous-jacent, interface graphique à la place du terminal. Disponible sur macOS et Windows, aucune installation de Node.js requise.
Ce que l’application de bureau ajoute par rapport à Claude Code standard :
Fonctionnalité
Détails
Révision visuelle des diffs
Réviser les modifications de fichiers en ligne avec des commentaires avant de les accepter
Aperçu d’application en direct
Claude démarre votre serveur de développement, ouvre un navigateur intégré, vérifie automatiquement les modifications
Surveillance des PR GitHub
Correction automatique des échecs CI, fusion automatique une fois les vérifications passées
Sessions parallèles
Plusieurs sessions dans la barre latérale, chacune avec isolation automatique par Git worktree
Connecteurs
GitHub, Slack, Linear, Notion (configuration GUI, pas de configuration MCP manuelle)
Pièces jointes
Joindre des images et des PDF directement aux invites
Sessions distantes
Exécuter des tâches longues sur le cloud d’Anthropic, continuer après la fermeture de l’application
Sessions SSH
Se connecter à des machines distantes, des VMs cloud, des conteneurs de développement
Quand choisir Desktop plutôt que CLI :
Utiliser Desktop quand…
Utiliser CLI quand…
Vous voulez une révision visuelle des diffs
Vous avez besoin de scripts ou d’automatisation (--print, redirection de sortie)
Vous intégrez de nouveaux collègues
Vous utilisez des fournisseurs tiers (Bedrock, Vertex, Foundry)
Vous voulez la gestion des sessions dans une barre latérale
Vous avez besoin du mode de permission dontAsk
Vous faites une démo en direct ou une révision en pair
Vous êtes sur Linux (Desktop est macOS + Windows uniquement)
Ce qui N’est PAS disponible dans Desktop (CLI uniquement) : fournisseurs d’API tiers, options de scripting (--print, --output-format), --allowedTools/--disallowedTools, équipes d’agents, --verbose, Linux.
Configuration partagée : Desktop et CLI lisent les mêmes fichiers : CLAUDE.md, serveurs MCP (via ~/.claude.json ou .mcp.json), hooks, skills et paramètres. Votre configuration CLI se retrouve automatiquement dans Desktop.
Conseil de migration : exécutez /desktop dans le terminal pour déplacer une session CLI active vers l’application Desktop. Sur macOS et Windows uniquement.
Note sur les serveurs MCP : Les serveurs MCP configurés dans claude_desktop_config.json (l’onglet Chat) sont séparés de Claude Code. Pour utiliser des serveurs MCP dans l’onglet Code, configurez-les dans ~/.claude.json ou le .mcp.json de votre projet. Voir Section 8.1 : MCP.
Contraste élevé : Assurez-vous que le texte et les diagrammes sont clairement visibles
Recadrage pertinent : Supprimez les éléments d’interface inutiles pour une analyse ciblée
Annoter si nécessaire : Encerclez/surlignez les zones spécifiques sur lesquelles vous voulez que Claude se concentre
Combiner avec du texte : « Concentre-toi sur la section d’en-tête » apporte un contexte supplémentaire
Exemple de flux de travail :
Vous : [Coller une capture d'écran d'un message d'erreur dans la console du navigateur]
Cette erreur apparaît quand les utilisateurs cliquent sur le bouton d'envoi. Débogue-la.
Claude : Je vois l'erreur "TypeError: Cannot read property 'value' of null".
Cela suggère que la référence au champ de formulaire est incorrecte. Laissez-moi vérifier votre code de gestion de formulaire...
[Lit les fichiers pertinents et propose une correction]
Limitations :
Les images consomment des tokens de contexte significatifs (équivalent à ~1000-2000 mots de texte)
Utilisez /status pour surveiller l’utilisation du contexte après avoir collé des images
Envisagez de décrire textuellement les diagrammes complexes si le contexte est limité
Certains terminaux peuvent ne pas prendre en charge le collage d’images depuis le presse-papiers (solution de repli : enregistrer et référencer le chemin du fichier)
💡 Conseil pro : Prenez des captures d’écran des messages d’erreur, des maquettes de conception et de la documentation plutôt que de les décrire par écrit. L’entrée visuelle est souvent plus rapide et plus précise que les descriptions écrites.
Outils de wireframing pour le développement avec IA
Lors de la conception d’interfaces avant l’implémentation, des wireframes basse fidélité aident Claude à comprendre l’intention sans trop contraindre le résultat. Voici des outils recommandés qui fonctionnent bien avec Claude Code :
Outil
Type
Prix
Support MCP
Idéal pour
Excalidraw
Style dessiné à la main
Gratuit
✓ Communautaire
Wireframes rapides, diagrammes d’architecture
tldraw
Canevas minimaliste
Gratuit
Émergent
Collaboration en temps réel, intégrations personnalisées
Pencil
Canevas natif IDE
Gratuit*
✓ Natif
Intégré à Claude Code, agents IA, basé sur git
Frame0
Basse-fi + IA
Gratuit
✓
Alternative moderne à Balsamiq, assisté par IA
Croquis papier
Physique
Gratuit
N/A
Itération la plus rapide, configuration zéro
Excalidraw (excalidraw.com) :
Open-source, esthétique dessinée à la main réduit la sur-spécification
Idéal pour : Ingénieurs-concepteurs souhaitant le paradigme design-as-code, équipes sur Cursor/Claude Code
⚠️ Note : Lancé en janvier 2026, forte traction (1M+ vues, adoption par des entreprises FAANG) mais encore en développement. Actuellement gratuit ; modèle de tarification à définir. Recommandé pour les adopteurs précoces à l’aise avec l’itération rapide.
Papier + Photo :
Sérieusement, ça fonctionne extrêmement bien
Prenez une photo avec votre smartphone → collez directement dans Claude Code
Conseils : Bonne lumière, recadrage serré, éviter les reflets et les ombres
Claude gère bien les rotations et les artefacts dessinés à la main
Paramètres d’export recommandés : format PNG, 1000-1200px sur le côté le plus long, contraste élevé
Figma fournit un serveur MCP officiel (annoncé en 2025) qui donne à Claude un accès direct à vos fichiers de conception, réduisant considérablement l’utilisation de tokens par rapport aux seules captures d’écran.
Options de configuration :
Terminal window
# MCP distant (tous les plans Figma, n'importe quelle machine)
Photos uniquement, les artefacts de compression nuisent à la détection de lignes
GIF
À éviter (statique uniquement, mauvaise qualité)
Liste de contrôle d’optimisation :
Recadrer à la zone pertinente uniquement
Redimensionner à 1000-1200px si plus grand
Utiliser PNG pour les wireframes/diagrammes
Vérifier /status après collage pour surveiller l’utilisation du contexte
Envisager une description textuelle si le contexte est > 70%
💡 Conseil sur les tokens : Un wireframe 1000×1000 utilise ~1 334 tokens. Les mêmes informations sous forme de texte structuré (via Figma MCP) pourraient utiliser 200-400 tokens. Utilisez les captures d’écran pour le contexte visuel, les données structurées pour l’implémentation.
Claude Code vous permet de continuer des conversations précédentes entre les sessions de terminal, en restaurant le contexte enregistré. La reprise ne restaure pas un instantané des fichiers ni l’état d’un service distant.
Façons de reprendre :
Continuer la dernière session (--continue ou -c) :
Terminal window
# Reprend automatiquement votre conversation la plus récente
claude--continue
# Forme abrégée
claude-c
Reprendre une session spécifique (--resume <id> ou -r <id>) :
Terminal window
# Reprend une session spécifique par son ID
claude--resumeabc123def
# Forme abrégée
claude-rabc123def
Lier à une PR GitHub (--from-pr <numéro>, v2.1.49+) :
Terminal window
# Démarrer une session liée à une PR spécifique
claude--from-pr123
# Les sessions créées via gh pr create pendant une session Claude
# sont automatiquement liées à cette PR — utilisez --from-pr pour les reprendre
ghprcreate--title"Add auth"--body"..."
# Plus tard :
claude--from-pr123# Reprend le contexte de session pour cette PR
Utile pour continuer le travail sur une fonctionnalité exactement là où vous l’avez laissé par rapport à une PR spécifique, pas besoin de se souvenir des IDs de session.
Trouver les IDs de session :
Terminal window
# Natif : Sélecteur de session interactif
claude--resume
# Recommandé : Recherche rapide avec commandes de reprise prêtes à l'emploi
# Voir examples/scripts/session-search.sh (bash, recherche locale dans les transcriptions)
# Voir examples/scripts/cc-sessions.py (Python, index incrémental, reprise partielle, filtre par branche)
cs# Lister les 10 sessions les plus récentes
cs"authentication"# Recherche en texte intégral dans toutes les sessions
# Les sessions sont aussi affichées à la sortie
Vous:/exit
SessionID:abc123def (sauvegardé pourreprise)
Outils de recherche de sessions : Pour une recherche rapide de sessions, voir session-search.sh (bash, léger) et cc-sessions.py (Python, fonctionnalités avancées : index incrémental, reprise par ID partiel, filtre par branche, et discover pour l’analyse automatique de patterns, voir GitHub). Voir aussi : Guide d’observabilité.
Cas d’usage courants :
Scénario
Commande
Pourquoi
Travail interrompu
claude -c
Reprendre là où vous vous êtes arrêté
Fonctionnalité sur plusieurs jours
claude -r abc123
Continuer une tâche complexe au fil des jours
Après une pause ou une réunion
claude -c
Reprendre sans perdre le contexte
Projets parallèles
claude -r <id>
Passer d’un contexte de projet à un autre
Suite d’une revue de code
claude -r <id>
Traiter les commentaires dans le contexte d’origine
Exemple de workflow :
Terminal window
# Day 1: Start implementing authentication
cd~/project
claude
You:ImplementJWTauthenticationwithrefreshtokens
Claude: [Analysis andinitialimplementation]
You:/exit
SessionID:auth-feature-xyz (27% contextused)
# Day 2: Continue the work
cd~/project
claude--continue
Claude:Resumingsessionauth-feature-xyz...
You:Addratelimitingtotheauthendpoints
Claude: [Continues withfullcontextofDay1work]
Bonnes pratiques :
Quitter correctement : Utilisez /exit ou Ctrl+D, plutôt qu’un arrêt forcé, pour permettre l’enregistrement de la session.
Dernier message descriptif : Terminez avec le contexte (« Prêt pour les tests ») pour retrouver l’état à la reprise.
Gestion proactive du contexte : Consultez /context et compactez ou préparez une passation lorsque la transcription ne convient plus à la tâche. Le pourcentage utilisé indique la capacité consommée, sans constituer un seuil validé de qualité du raisonnement. La compaction automatique dépend du modèle actif et de la configuration.
Noms de session : Utilisez /rename pour attribuer des noms descriptifs, surtout avec plusieurs sessions parallèles (voir Renommage automatique ci-dessous).
Reprendre ou repartir de zéro :
Reprendre lorsque…
Repartir de zéro lorsque…
Vous continuez une fonctionnalité ou tâche précise
Vous passez à un travail sans rapport
Vous vous appuyez sur les décisions précédentes
La session précédente s’est égarée
Le contexte reste pertinent pour la tâche
L’ancien contexte distrait ou induit en erreur
Une implémentation à plusieurs étapes continue
Vous avez des questions ponctuelles
Limites et vérifications à la reprise :
Les transcriptions locales de la CLI sont stockées sur la machine. Leur conservation dépend de cleanupPeriodDays et des paramètres de compte ou paramètres gérés applicables.
Une conversation reprise peut utiliser un autre modèle. L’accès aux modèles et la disponibilité des serveurs MCP dépendent de la configuration actuelle.
La transcription peut contenir d’anciennes versions de fichiers, des résultats d’outils et des résumés. Vérifiez les fichiers actuels et les modifications Git avant de vous y fier.
Les instructions, permissions et connexions MCP actuelles doivent être vérifiées. Reprendre ne restaure ni les fichiers ni l’état en mémoire d’un serveur MCP.
Utiliser les outils MCP après une reprise :
Exécutez /mcp dans Claude Code pour inspecter les serveurs configurés et vous reconnecter ou vous authentifier si nécessaire. Un serveur comme Serena peut proposer ses propres outils de mémoire du projet ; leur persistance et leurs noms relèvent du contrat documenté de ce serveur. Demandez à Claude d’inspecter les outils disponibles avant de les invoquer.
Terminal window
# From the project directory, resume the latest conversation
claude--continue
Demandez ensuite à Claude de vérifier le diff Git actuel, de rouvrir les fichiers nécessaires à l’étape suivante et de résumer les différences avec le plan enregistré.
Votre historique de sessions est une source de données. Chaque fois que vous demandez à Claude de faire le même type de chose dans plusieurs sessions, c’est un signal : extrayez-le sous forme de skill, de commande ou de règle CLAUDE.md et arrêtez de payer la taxe de contexte à chaque requête.
cc-sessions discover automatise cette analyse. Il lit votre historique de sessions, identifie les patterns récurrents dans les messages utilisateur et vous indique ce qu’il faut extraire.
La règle des 20% intégrée dans le scoring : les patterns présents dans plus de 20% des sessions deviennent des suggestions de règle CLAUDE.md (chargement permanent), ceux entre 5 et 20% deviennent des suggestions de skill (chargement à la demande), et ceux en dessous de 5% deviennent des suggestions de command (invocation explicite). Le bonus inter-projets (1,5×) priorise les patterns qui réapparaissent dans différentes bases de code, ceux-là valent la peine d’être extraits même à faible fréquence.
Lorsque vous exécutez plusieurs sessions Claude Code en parallèle (terminaux divisés, onglets WebStorm, flux de travail parallèles), le sélecteur /resume affiche les sessions par horodatage ou par première invite tronquée, impossible à distinguer d’un coup d’œil.
Deux approches complémentaires résolvent ce problème. Utilisez l’une ou les deux ensemble.
Approche A : instruction comportementale dans CLAUDE.md (en cours de session)
Une instruction comportementale dans ~/.claude/CLAUDE.md amène Claude à appeler /rename automatiquement après 2 à 3 échanges. Aucun outillage requis, fonctionne dans tous les IDE et terminaux.
# Session Naming (auto-rename)
## Expected behavior
1.**Early rename**: Once the session's main subject is clear (after 2-3 exchanges),
run `/rename` with a short, descriptive title (max 50 chars)
2.**End-of-session update**: If scope shifted significantly, propose a re-rename before closing
## Title format
`[action] [subject]` — examples:
- "fix whitepaper PDF build"
- "add auth middleware + tests"
- "refactor hook system"
- "update CC releases v2.2.0"
## Rules
- Max 50 characters, no "Session:" prefix, no date
- Action verb first (fix, add, refactor, update, research, debug...)
- Multi-topic: dominant subject only, not an exhaustive list
- Do NOT ask for confirmation on early rename (just do it)
Cela fonctionne bien pendant les sessions actives, mais dépend de la cohérence avec laquelle Claude suit l’instruction.
Approche B : hook SessionEnd (automatique, généré par IA)
Un hook SessionEnd lit directement le fichier JSONL de la session depuis ~/.claude/projects/, extrait les premiers messages utilisateur comme contexte, et appelle claude -p --model claude-haiku-4-5-20251001 pour générer un titre descriptif de 4 à 6 mots. Si Haiku est indisponible, il bascule sur une version assainie du premier message.
Le hook met à jour à la fois sessions-index.jsonl (pour les navigateurs de sessions personnalisés) et le champ slug dans le fichier JSONL (pour la compatibilité native avec /resume).
Les deux approches couvrent des moments différents du cycle de vie d’une session. L’approche A renomme tôt pour que la session soit identifiable pendant qu’elle est encore active. L’approche B renomme à la fin avec un titre qui reflète la portée complète de la session, écrasant potentiellement le nom donné en cours de session avec quelque chose de plus précis.
Limitation (les deux approches) : les noms des onglets de terminal dans WebStorm et iTerm2 ne sont pas affectés. JetBrains filtre les séquences d’échappement ANSI. C’est la session Claude qui est renommée, pas l’onglet du système d’exploitation.
You: Turn on auto-accept for the rest of this session
Claude approuve automatiquement les modifications de fichiers mais demande encore confirmation pour les commandes shell. À utiliser quand vous faites confiance aux modifications et souhaitez aller plus vite.
⚠️ Avertissement : N’utilisez l’auto-acceptation que pour des opérations bien définies et réversibles.
Refuse automatiquement les outils sauf ceux pré-approuvés via /permissions ou les règles permissions.allow. Claude n’interrompt jamais l’exécution avec des demandes de permission : si un outil n’est pas explicitement autorisé, il est silencieusement refusé.
À utiliser pour les flux de travail restrictifs où vous souhaitez un contrôle strict sur les outils exécutés, sans confirmation interactive.
Le mode Auto délègue les décisions de permission à un modèle classificateur dédié. Au lieu de s’arrêter pour demander une approbation à chaque action, une seconde instance IA exécutant Sonnet 5 évalue chaque appel d’outil avant son exécution. Les actions sûres sont exécutées automatiquement ; les actions risquées sont bloquées, et Claude reçoit la raison afin de pouvoir essayer une approche différente.
.claude/settings.json
{ "permissionMode": "auto" }
Deux couches de défense
Le mode Auto effectue deux vérifications parallèles sur tout ce que Claude touche :
Sonde d’entrée : avant que tout contenu entre dans le contexte de Claude (lectures de fichiers, requêtes web, sorties shell, réponses MCP), une sonde côté serveur analyse les injections de prompt. Lorsqu’elle détecte des instructions suspectes, elle ajoute un avertissement au contexte de Claude plutôt que de filtrer silencieusement, afin que Claude sache que ce contenu tente peut-être de le manipuler.
Classificateur de transcript (Sonnet 5) : évalue chaque appel d’outil selon trois catégories de risque avant l’exécution. Le classificateur ne voit que les messages utilisateur et les appels d’outils en attente de Claude ; les sorties d’outils et le raisonnement propre à Claude sont supprimés pour éviter la manipulation du raisonnement.
Les trois catégories vérifiées par le classificateur :
Catégorie
Ce qu’il recherche
Escalade de portée
Claude fait plus que ce que la tâche demandait
Infrastructure non fiable
Action ciblant un hôte, une API ou un système non reconnu dans le contexte
Injection de prompt
Action semblant pilotée par un contenu hostile lu dans un fichier, un dépôt ou une page web
Performances et limites
Mesures sur le trafic de production d’Anthropic : 94% des opérations dangereuses correctement identifiées, 2% des opérations sûres faussement signalées, taux de faux négatifs (FNR) de 17%.
Un test de résistance indépendant (arXiv 2604.04978) ciblant spécifiquement l’escalade de portée a trouvé un FNR de 81% de bout en bout (IC : 73,8%–87,4%). Même en se limitant aux actions que le classificateur évalue effectivement, le FNR était de 70,3%. Une lacune structurelle clé : les modifications de fichiers dans le projet sont exemptées de classification par conception, ce qui a produit un FNR de 92,9% sur les tâches de nettoyage d’artefacts lorsque les agents se rabattaient sur l’outil Edit. Ce sont des benchmarks adversariaux contre la frontière d’autorisation, pas des moyennes de production, mais ils établissent le plafond réel : le mode Auto est un réducteur de friction, pas une frontière de sécurité.
Escalade et retour visuel
Si le classificateur bloque Claude 3 fois consécutives, ou 20 fois au total dans une session, le mode Auto bascule vers une demande de permission manuelle pour sortir de la boucle. Pendant une vérification, le spinner de statut devient rouge, vous permettant de distinguer un blocage du classificateur d’un outil en cours d’exécution.
Configuration des règles du classificateur
La clé autoMode vous permet d’étendre les règles intégrées en utilisant la sentinelle "$defaults". Incluez-la pour ajouter vos règles aux côtés des règles par défaut ; omettez-la pour remplacer entièrement la liste intégrée :
Règles de blocage absolu (settings.autoMode.hard_deny, v2.1.136)
Règles de blocage inconditionnel qui s’appliquent avant le classificateur et ne peuvent être remplacées ni par l’intention de l’utilisateur ni par des exceptions allow :
{
"autoMode": {
"hard_deny": [
{ "tool": "Bash", "pattern": "rm -rf" },
{ "tool": "Write", "pathPattern": "/etc/**" },
{ "tool": "Write", "pathPattern": "**/.env" }
]
}
}
Contrairement aux règles du classificateur (qui pèsent le contexte et l’intention de l’utilisateur), les entrées hard_deny sont absolues. Utilisez-les pour les opérations qui ne doivent jamais s’exécuter sans surveillance : commandes destructives, fichiers de credentials, chemins de configuration système.
Générer les entrées d’environnement avec /auto-mode-setup (v2.1.228+, v2.1.233+ sur Windows natif)
Exécutez /auto-mode-setup pour que Claude Code prépare des entrées autoMode.environment, et parfois allow/soft_deny/hard_deny, à partir du projet courant et de vos sessions récentes sur ce projet. Accepter la proposition l’écrit dans ~/.claude/settings.json. Il faut un abonnement Pro, Max ou Team et la récupération des feature flags activée ; la commande n’est pas disponible dans Claude Code sur le web.
Éléments lus :
Toujours analysés
Facultatifs, après demande
CLAUDE.md, README.md, fichiers de configuration et remotes Git du projet
Premier mot de chaque commande de l’historique shell
Réglages autoMode et permissions.allow
Hôtes distants et noms de dépôts dans votre dossier personnel
Hôtes, buckets et noms de commandes exécutées par Claude dans les sessions récentes du projet, jamais vos messages
Acceptez ou rejetez la proposition entière, puis ajustez les entrées individuelles dans ~/.claude/settings.json. Lors de l’acceptation, Claude Code écrit la liste environment sans "$defaults", car elle détaille les valeurs intégrées inchangées. Il ajoute "$defaults" aux listes allow/soft_deny/hard_deny modifiées afin de conserver les règles intégrées, et propose de retirer les règles permissions.allow ignorées par le mode Auto ou qui préapprouvent des commandes destructives, par exemple Bash(*).
Après plusieurs blocages sans entrées autoMode.environment, une boîte « Teach auto mode about your environment? » propose l’assistant. « Don’t show again » supprime la proposition mais garde la commande. Pour désactiver les deux :
/auto-mode-setup est une commande intégrée, pas un skill fourni. disableBundledSkills ne la désactive pas ; seul skillOverrides le fait.
Commandes d’inspection associées : claude auto-mode defaults (règles intégrées en JSON), claude auto-mode config (configuration effective), claude auto-mode critique (revue IA des règles personnalisées), claude auto-mode reset (v2.1.212+, retire vos personnalisations ; les paramètres gérés restent applicables).
Quand utiliser le mode Auto
Contexte
Verdict
Notes
Conteneur ou VM isolé, sans credentials de production
Go
Le cas d’utilisation prévu
Tâches Dispatch en arrière-plan
Go
Aucun humain présent pour confirmer ; le mode Auto est requis
Machine de dev locale, projet personnel, branche en lecture seule
OK
Faibles enjeux ; utilisez le contrôle de version comme filet de sécurité
Environnement de staging avec données réelles
Prudence
Limitez les credentials en lecture seule ; assurez des sauvegardes
Production, données personnelles, données financières, périmètre de conformité
Non
Utilisez le mode par défaut ou dontAsk avec une liste d’autorisation explicite
Pour une utilisation en équipe : conservez des journaux d’audit des actions auto-approuvées, définissez une identité git committer distincte pour les commits de Claude afin de les tracer, et revoyez les commits de Claude avant de les fusionner.
Prérequis : Tous les abonnements (les abonnés Max ont obtenu un accès transparent à la v2.1.111 ; tous les abonnements à la v2.1.114). Les abonnements Team et Enterprise nécessitent une activation par l’administrateur dans les paramètres d’administration de Claude Code. Le coût et la latence sont légèrement supérieurs aux autres modes car un second modèle s’exécute à chaque appel d’outil.
Mode contournement des permissions (bypassPermissions)
Approuve automatiquement tout, y compris les commandes shell. Aucune demande de permission.
⚠️ Avertissement : À utiliser uniquement dans des environnements CI/CD sandboxés. Nécessite --dangerously-skip-permissions pour être activé depuis le CLI. N’utilisez jamais ce mode sur des systèmes de production ni avec du code non fiable.
Invariant de sécurité : certains chemins déclenchent toujours une demande, même en mode bypassPermissions :
Certaines écritures sont considérées trop sensibles pour être auto-approuvées dans n’importe quelle configuration. Claude Code demande toujours une confirmation avant de modifier :
Les règles allow spécifiques à un contenu (ex. Bash(npm publish:*)) définies dans settings.json ou CLAUDE.md survivent également à bypassPermissions, elles continuent de s’appliquer comme filtres supplémentaires par-dessus tout mode de permission. Cela vous permet de créer des garde-fous précis (ex. « toujours demander avant de publier sur npm ») qui tiennent quelle que soit la façon dont la session est lancée.
Un piège courant : vous êtes au milieu d’une tâche, les demandes continuent d’apparaître, vous commencez à les approuver sans les lire. C’est la fatigue des permissions, et elle annule complètement l’utilité du système de permissions.
La solution consiste à choisir le bon mode dès le départ plutôt que de cliquer sur les demandes une par une :
Situation
Bon mode
Pourquoi
Travail exploratoire, base de code inconnue
Mode Plan
Impossible de modifier quoi que ce soit accidentellement
Modifications locales de confiance, sans opérations shell
acceptEdits
Approuve les modifications silencieusement, bloque toujours les commandes
Longues tâches agentiques, abonnement Max
Mode Auto
Claude juge les actions ; moins d’interruptions avec moins de risque qu’un bypass
Pipeline automatisé, environnement sandboxé
bypassPermissions
Aucune demande, mais uniquement sûr en isolation
Vous avez besoin qu’un seul outil soit auto-approuvé
permissions.allow dans CLAUDE.md
Granulaire, pas tout ou rien
Nouvelle session par défaut
Mode par défaut
Revue explicite de chaque action
L’échec à éviter : recourir à --dangerously-skip-permissions sur une machine de dev avec des clés SSH, des tokens API ou un accès production dans la portée. Le système de permissions n’a de valeur que si vous lisez réellement ce que vous approuvez, ou si vous configurez un mode qui correspond à votre niveau de confiance réel.
Changement de mentalité clé : Claude Code est un système de contexte structuré, pas un chatbot ou un outil d’autocomplete. Vous construisez un contexte persistant (CLAUDE.md, skills, hooks) qui se capitalise avec le temps, voir §2.5.
Flux de travail natif terminal - Aucune dépendance à un IDE ; fonctionne via SSH, en CI/CD, dans n’importe quel terminal
Système de contexte persistant - CLAUDE.md + skills + hooks se capitalisent avec le temps ; les instructions personnalisées de Copilot sont plus récentes et moins granulaires
Modèle à la consommation - Pas de quotas de requêtes premium ; le mode agent de Copilot est limité par des quotas mensuels (300/mois sur Pro, 1500/mois sur Pro+)
Mode headless/CI - Exécution dans des pipelines, automatisations, contextes non interactifs
Personnalisation poussée - Commandes slash personnalisées, hooks d’événements, modules de skills, composition de serveurs MCP
Le code généré par l’IA nécessite une vérification proportionnelle au niveau de risque. Accepter aveuglément toute la production ou examiner paranoïaquement chaque ligne fait perdre du temps dans les deux cas. Cette section vous aide à calibrer votre niveau de confiance.
La génération peut dépasser la capacité de vérification. Les rapports sur les défauts du code généré, les findings de review et les incidents de livraison étudient des populations et des résultats différents. Leurs pourcentages ne constituent ni un taux universel de défauts ni une promesse de détection. Mesurez les défauts confirmés, les défauts échappés, l’effort de revue et la récupération sur vos changements, avec des dénominateurs explicites et une référence comparable.
Classez les conséquences et les interactions avant de choisir la profondeur de revue. Une configuration peut modifier des permissions ; un utilitaire peut appartenir à un chemin critique.
Risque du changement
Vérification et autorité
Comportement borné et réversible, contrôles éprouvés
Première passe automatisée, tests de comportement pertinents et échantillonnage humain selon une politique explicite
Règles métier ou exigences incomplètes
Revue de l’intention et des cas limites ; versionner les critères découverts et relancer les contrôles concernés
Authentification, autorisations, cryptographie ou données sensibles
Validation du responsable désigné et contrôles statiques, comportementaux et adversariaux adaptés
Intégrations externes ou données persistantes
Tests d’intégration et d’échec, compatibilité et exercice de restauration ou de compensation
PR qui interagissent ou nouvelle base
Reclasser le changement combiné et vérifier la révision candidate à l’intégration
En solo : utilisez un reviewer séparé du contexte de rédaction, inspectez les changements inattendus et exécutez des contrôles comportementaux pertinents. Un pourcentage de couverture et un test nominal ne prouvent pas que le résultat suffit. Gardez la responsabilité de l’intention, des comportements sensibles et de la récupération. Sollicitez une revue de domaine lorsque les conséquences dépassent vos preuves actuelles. Dimensionnez l’examen selon le risque, pas le nombre de lignes.
En équipe : les agents peuvent détecter et vérifier des défauts en première passe. Mesurez leurs résultats sans supposer un pourcentage fixe de détection. Affectez un responsable humain aux chemins sensibles et aux décisions métier. Une passe automatisée propre peut réduire la revue humaine approfondie pour une classe de changements dont le faible risque est établi, selon la politique retenue. Elle n’autorise pas à contourner les approbations requises.
Dans les deux cas, enregistrez le head, la base, les critères et l’état d’intégration testé. Si une exigence ou un changement combiné modifie le risque, relancez les vérifications concernées. Un verdict d’agent contraignant établit une autorité dans le workflow, pas l’exactitude du jugement.
Commencer prudemment : tout relire quand vous débutez avec Claude Code
Suivre les patterns d’échec : où les bugs passent-ils entre les mailles ?
Renforcer les chemins critiques : redoubler d’attention sur les zones ayant connu des incidents
Assouplir les zones à faible risque : ajuster la politique d’une classe de changements selon les résultats observés et la récupération exercée
Audits périodiques : vérifier ponctuellement le code « de confiance »
Modèle mental : considérez l’IA comme un développeur junior compétent. Vous ne déployeriez pas son code sans relecture, mais vous ne réécririez pas non plus tout ce qu’il produit.
Générer → classer conséquences et interactions → vérifications requises
→ preuves acceptées sur l'état d'intégration actuel + validations requises
→ fusion éligible selon la politique du dépôt
Preuves manquantes, défauts non résolus ou nouveaux critères → réviser ou escalader
Erreur acceptée puis détectée → contenir, restaurer ou compenser, évaluer
La reprise d’une tâche, le rollback de la configuration du reviewer, celui de l’application et la récupération des données sont des opérations distinctes. Exercez la récupération du produit avant d’invoquer la réversibilité pour réduire la revue humaine. Voir Loop & Graph Engineering et la review multi-provider.
Attribution : le cadrage de la revue sélective s’appuie sur AI Code Review d’Addy Osmani. La politique proposée ici est une méthode à évaluer localement, pas un résultat de performance mesuré.
1.8 Huit erreurs de débutant (et comment les éviter)
Erreur : « Corrige le bug d’auth ET refactorise la base de données ET ajoute de nouveaux tests »
Correction : une tâche ciblée par session. /clear entre les tâches différentes.
Comment dimensionner une tâche pour Claude Code :
Signal
Trop grande
Bonne taille
Trop petite
Description
Utilise « ET » entre des comportements
Une tranche verticale, un comportement utilisateur
Une modification d’une ligne que vous pourriez faire plus vite manuellement
Session
Épuise le contexte ou dérive
Se termine en une seule session
Prend 30 secondes
Revue
Le relecteur ne peut pas garder l’ensemble du diff en tête
Le diff est relu en une seule passe
Ça ne vaut pas une relecture
Rollback
Revenir en arrière casse d’autres choses
git revert annule tout proprement
N/A
Heuristique de découpage : si la description de votre tâche nécessite « et » entre deux comportements visibles par l’utilisateur, découpez-la. « Les utilisateurs peuvent réinitialiser leur mot de passe » est une tâche. « Les utilisateurs peuvent réinitialiser leur mot de passe ET les administrateurs peuvent forcer l’expiration des sessions » en sont deux.
Erreur : saisir des instructions ad hoc à chaque session. Répéter les conventions du projet, ré-expliquer l’architecture, appliquer manuellement les contrôles de qualité.
Correction : construisez un contexte structuré qui se capitalise dans le temps :
CLAUDE.md : vos conventions, votre stack et vos patterns, chargés automatiquement à chaque session
Skills : workflows réutilisables (/review, /deploy) pour une exécution cohérente
Hooks : garde-fous automatisés (lint, sécurité, formatage), zéro effort manuel
Commencez avec CLAUDE.md la première semaine. Voir §2.6 Modèle mental pour le cadre complet.
Vérifiez toujours le pourcentage de contexte avant de démarrer des tâches complexes. Un contexte élevé = qualité dégradée.
Lisez cette section si : Vous voulez éviter l’erreur n°1 (dépassement de contexte)
Passez si : Vous avez juste besoin d’une référence rapide des commandes (allez à la Section 10)
Temps de lecture : 20 minutes
Niveau : Jour 1-3
Objectif : Comprendre comment Claude Code fonctionne
La fenêtre de contexte dépend du modèle et du fournisseur. Opus 5.5, Sonnet 5.5 et Fable 5.1 disposent de 1M tokens sur l’API directe ; Haiku 4.5 de 200K. Consultez /context pour la session active. La capacité ne garantit pas que chaque détail sera retrouvé de façon fiable.
La barre de statut par défaut peut être enrichie avec des informations plus détaillées comme la branche git, le nom du modèle et les modifications de fichiers.
Quand /compact tourne mal : La compaction se déclenche quand le modèle a le plus de contexte accumulé, ce qui signifie qu’il est aussi à son point de distraction maximal. Si le modèle ne peut pas prédire où va le travail (par exemple, l’auto-compact se déclenche en plein débogage et votre prochain message est « maintenant corrige cet avertissement dans bar.ts »), il peut laisser tomber des informations pertinentes pour la suite du résumé. Atténuez ce risque en compactant de manière proactive et avec du contexte : /compact focus on the auth refactor, drop the test debugging oriente le résumé vers ce qui compte ensuite. (Source : recommandations internes Anthropic)
Option 2 : Clear (/clear)
Repart de zéro
Perd tout le contexte
À utiliser lors d’un changement de sujet
« Une tâche, un chat » : mélanger des sujets sans rapport au fil des échanges dégrade la précision du modèle d’environ 39%. Le contexte accumule du bruit (« pourrissement du contexte ») qui fausse le jugement même quand l’utilisation totale de tokens reste faible. Utilisez /clear de manière agressive entre des tâches distinctes, pas seulement quand la barre de contexte devient rouge.
Option 3 : Résumer depuis ici (v2.1.32+)
Utilisez /rewind (ou Esc + Esc) pour ouvrir la liste des points de contrôle
Sélectionnez un point de contrôle et choisissez « Summarize from here »
Claude résume tout depuis ce point en avant, en conservant le contexte antérieur intact
Libère de l’espace tout en conservant le contexte critique
Plus précis qu’un /compact complet
Option 4 : Approche ciblée
Soyez précis dans vos requêtes
Évitez « lis l’intégralité du fichier »
Utilisez des références symboliques : « lis la fonction calculateTotal »
Quand vous approchez de la zone rouge (75%+), /compact seul peut ne pas suffire. Vous devez décider activement quelles informations préserver avant de compacter.
Priorité : Conserver
Conserver
Pourquoi
Contenu de CLAUDE.md
Les instructions principales doivent persister
Fichiers en cours de modification
Contexte du travail en cours
Tests pour le composant actuel
Contexte de validation
Décisions critiques prises
Choix d’architecture
Messages d’erreur en cours de débogage
Contexte du problème
Priorité : Évacuer
Évacuer
Pourquoi
Fichiers lus mais plus pertinents
Consultations ponctuelles
Sortie de débogage des problèmes résolus
Encombrement historique
Longue histoire de conversation
Résumée par /compact
Fichiers des tâches terminées
Plus nécessaires
Grands fichiers de configuration
Peuvent être relus si nécessaire
Liste de vérification pré-compact :
Documentez les décisions critiques dans CLAUDE.md ou une note de session
Committez les modifications en attente dans git (crée un point de restauration)
Notez la tâche actuelle explicitement (« Nous implémentons X »)
Lancez /compact pour résumer et libérer de l’espace
Conseil pro : Si vous savez que vous aurez besoin d’informations spécifiques après le compact, dites-le explicitement à Claude : « Avant qu’on compacte, rappelle-toi qu’on a décidé d’utiliser la Stratégie A pour l’authentification à cause de X. » Claude inclura cela dans le résumé.
Sauvegardée explicitement avec write_memory("key", "value")
Persiste entre les sessions
Idéale pour : décisions d’architecture, patterns d’API, conventions de codage
Pattern : Sauvegarde en fin de session
# Avant de terminer une session productive :
"Save our authentication decision to memory:
- Chose JWT over sessions for scalability
- Token expiry: 15min access, 7d refresh
- Store refresh tokens in httpOnly cookies"
# Claude calls: write_memory("auth_decisions", "...")
# Next session:
"What did we decide about authentication?"
# Claude calls: read_memory("auth_decisions")
Quand utiliser lequel :
Mémoire de session : Résolution active de problèmes, débogage, exploration
Mémoire automatique : Décisions et contexte que vous voulez que Claude redécouvre à la prochaine session sans effort manuel (v2.1.59+)
Mémoire persistante (Serena) : Stockage clé-valeur structuré pour les décisions d’architecture sur de nombreux projets
CLAUDE.md : Conventions d’équipe, structure du projet (versionné avec git)
Auto-compact et capture de mémoire PostToolUse, un conflit à connaître :
Claude Code compacte automatiquement la conversation quand le contexte restant tombe en dessous d’un seuil de tampon fixe (environ les derniers 6-7% de la fenêtre de contexte, soit environ 13K tokens avant la limite effective). En pratique, cela se déclenche quelque part dans la plage 90-95% d’utilisation selon la fenêtre de contexte du modèle et les tokens de sortie réservés. Avant que la compaction complète ne s’exécute, Claude Code applique également la micro-compaction, un passage plus léger qui compresse sélectivement les anciens résultats d’outils (lectures de fichiers, sorties bash, résultats de recherche) pour libérer de l’espace de manière incrémentale sans résumer toute la conversation. Si l’auto-compact échoue (par exemple en raison d’une limite de débit), il réessaie jusqu’à 3 fois consécutives avant d’abandonner pour cette session.
Si vous utilisez un outil de capture de mémoire basé sur des hooks (comme claude-mem) qui sauvegarde l’historique de session via PostToolUse, l’auto-compact peut se déclencher et supprimer l’historique de conversation avant que le pipeline de sauvegarde n’ait eu l’occasion de le capturer.
Deux façons de gérer cela :
// Option 1 : désactiver l'auto-compact dans settings.json de votre projet
// (vous gérez la compaction manuellement via /compact)
{
"autoCompactEnabled": false
}
Terminal window
# Option 2 : gardez l'auto-compact activé, mais configurez le seuil de sauvegarde de votre outil
# pour se déclencher bien en dessous de 80% (par exemple, à 60% d'utilisation du contexte)
# — vérifiez les délais/configuration de seuil de votre plugin de mémoire
L’option 1 donne un contrôle total mais requiert de la discipline. L’option 2 est plus sûre si vous oubliez de compacter manuellement. Le conseil général du guide (utiliser /compact de manière proactive à 75%) s’applique toujours, l’auto-compact désactivé signifie simplement que vous gérez le timing.
La recherche montre que les performances des LLM se dégradent significativement avec un contexte accumulé :
Écart de performance de 20 à 30% entre des prompts ciblés et pollués (Chroma, 2025)
La dégradation commence à ~16K tokens pour les anciens modèles Claude (Chroma, 2025) ; Anthropic signale une dégradation notable autour de 300-400K tokens sur la fenêtre de contexte 1M (dépend de la tâche, pas un seuil fixe)
Les tentatives échouées, les traces d’erreurs et l’historique d’itérations diluent l’attention
Au lieu de gérer le contexte au sein d’une session, vous pouvez redémarrer avec une session fraîche par tâche tout en persistant l’état en externe.
Note sur le nom : « Ralph Loop » est utilisé de deux manières distinctes dans la communauté. Le pattern original de Geoffrey Huntley (ci-dessus) concerne la rotation du contexte : créer des sessions fraîches pour éviter le pourrissement du contexte. Une utilisation distincte, popularisée par Addy Osmani et d’autres en 2026, applique le même terme à l’itération atomique de tâches dans des équipes multi-agents : choisir une tâche → implémenter → valider → committer → réinitialiser le contexte → répéter. Les deux partagent le même mécanisme central (boucle sans état avec état externe), mais la portée diffère. Quand le terme apparaît sans attribution, clarifiez quelle variante est visée.
L’état persiste via :
TASK.md : définition de la tâche actuelle avec les critères d’acceptation
Commits git : chaque itération committe de manière atomique
Variante : tasks/lessons.md
Une alternative légère pour les sessions interactives (sans boucle requise) : après chaque correction de l’utilisateur, Claude met à jour tasks/lessons.md avec la règle pour éviter la même erreur. Révisé au début de chaque nouvelle session.
tasks/
├── todo.md # Current plan (checkable items)
└── lessons.md # Rules accumulated from corrections
La différence avec PROGRESS.md : lessons.md capture des règles comportementales (« toujours diff avant de marquer comme terminé », « ne jamais mocker sans demander ») plutôt que l’état des tâches. Il se cumule dans le temps, le taux d’erreurs diminue à mesure que le jeu de règles grandit.
Tâches avec des critères de succès clairs (les tests passent, le build réussit)
Mauvais pour :
Exploration interactive
Design sans spécification claire
Tâches avec des boucles de retour lentes/ambiguës
Variante : Pipeline session-par-préoccupation
Au lieu de boucler sur la même tâche, dédiez une session fraîche à chaque dimension de qualité :
Session de planification : architecture, portée, critères d’acceptation
Session de tests : écrire d’abord les tests unitaires, d’intégration et E2E (TDD)
Session d’implémentation : code jusqu’à ce que tous les linters et tests passent
Sessions de révision : sessions séparées pour l’audit de sécurité, les performances, la revue de code
Répéter : itérer avec des ajustements de portée si nécessaire
Cela combine le contexte frais (200K propres par phase) avec OpusPlan (Opus pour les sessions de révision/stratégie, Sonnet pour l’implémentation). Chaque session génère des artefacts de progression qui alimentent la suivante.
Remarque : Anthropic a annoncé un crédit mensuel distinct pour l’usage programmatique (claude -p, l’Agent SDK, les applications tierces) au 15 juin 2026, puis l’a suspendu. Vérifié le 2026-09-30 : cet usage consomme toujours les limites de votre abonnement. Voir §9.13 : The Interactive/Programmatic Billing Split pour le plan annoncé et les étapes d’audit, et AI FinOps pour l’ensemble de la section coûts.
L’utilisation de Claude Code peut consommer l’allocation d’un abonnement, des crédits d’usage ou une facturation API. Vérifiez le compte actif et le mode de facturation avant d’interpréter une estimation du coût des tokens.
Modèle de tarification (tarifs vérifiés le 6 octobre 2026) {#pricing-model-rates-checked-october-6-2026}
Claude Code v2.1.280 et les versions suivantes utilisent Opus 5.5 par défaut sur Pro, Max, Team, Enterprise, l’API Anthropic, Claude Platform on AWS, Bedrock et Google Cloud’s Agent Platform. Microsoft Foundry conserve Sonnet 4.5 comme modèle par défaut du compte. La politique de l’organisation, les paramètres du modèle et les variables d’environnement peuvent modifier ce choix. Consultez /model et /status pour votre session.
Modèle
Entrée / MTok
Sortie / MTok
Lecture du cache / MTok
Contexte
Effort par défaut dans Claude Code
Opus 5.5
$4
$20
$0.20
1M
medium
Sonnet 5.5
$2
$10
$0.20
1M
high
Haiku 4.5
$1
$5
$0.10
200K
Pas de paramètre d’effort
Fable 5.1
$10
$50
$0.25
1M
high
Il s’agit des tarifs standard de l’API Anthropic en USD, vérifiés le 6 octobre 2026. Les allocations des abonnements, les crédits d’usage, les écritures du cache, les remises par lot, la résidence des données et les tarifs des clouds partenaires sont distincts. Sonnet 5.5 (claude-sonnet-5-5) a remplacé Sonnet 5 comme Sonnet par défaut sur l’API Anthropic dans Claude Code v2.1.284 (28 septembre 2026), aux mêmes tarifs de $2/$10 ; Sonnet 5 est désormais un modèle legacy, et la hausse annoncée pour septembre n’a pas eu lieu. Tarifs officiels des modèles.
Le mode rapide prend en charge Opus 5.5 ($8/$40 par MTok), Opus 5 et Opus 4.8 ($10/$50). Il n’est pas disponible sur Sonnet et Haiku. Anthropic décrit une sortie jusqu’à 2.5 fois plus rapide, sans garantie pour chaque requête. Le mode rapide des abonnements utilise des crédits d’usage. Référence du mode rapide.
Fable 5.1 est disponible sur sélection explicite, sous réserve d’accès du compte et de l’organisation. Ce n’est pas un modèle par défaut associé à un type de compte. Les tarifs des générations précédentes figurent dans le tableau officiel des anciens modèles, pas dans les lignes des modèles par défaut ci-dessus.
Contexte 200K et 1M : performances, coûts et usages {#200k-vs-1m-context-performance-cost—use-cases}
Opus 5.5, Sonnet 5.5 et Fable 5.1 disposent d’un contexte natif de 1M sur l’API Anthropic. Les anciens Opus 4.6 et Sonnet 4.6 utilisent une variante [1m] avec un accès dépendant de l’offre. Les passerelles et fournisseurs cloud peuvent exposer une autre fenêtre ; consultez /context et les règles des fournisseurs.
Les modèles actuels à 1M natif conservent leurs tarifs standard au-delà de 200K tokens d’entrée. Les anciens conseils sur l’en-tête bêta et le supplément long contexte de Sonnet 4/4.5 ne s’appliquent pas à eux. La sortie maximale est de 128K pour Opus 5.5, Sonnet 5.5 et Fable 5.1, et de 64K pour Haiku 4.5. Caractéristiques des modèles.
Factures de tokens illustratives, sans mesure de sessions, hors cache et reprises :
Exemple
Entrée
Sortie
Sonnet 5.5
Opus 5.5
Relecture bornée
50K
5K
$0.15
$0.30
Refactorisation d’un module
150K
20K
$0.50
$1.00
Analyse avec contexte volumineux
500K
50K
$1.50
$3.00
Une fenêtre plus grande représente une capacité, sans garantie sur la recherche d’information ou le raisonnement. Chargez le contexte pertinent et évaluez la tâche entière. Les anciennes mesures de recherche d’Opus 4.6 et Sonnet 4.5 décrivent ces modèles et les conditions de leur benchmark ; elles n’établissent pas les performances de la gamme actuelle.
Les sessions à 1M natif déclenchent normalement la compaction automatique vers 967K tokens. Utilisez /autocompact auto pour rétablir le défaut du modèle ou /autocompact 500k pour choisir une fenêtre plus petite. Compactez ou ouvrez une nouvelle session lorsque l’accumulation du contexte nuit à la tâche ; un pourcentage fixe n’est pas un seuil universel d’exactitude.
# Évaluer Haiku pour les tâches simples ($1/$5 par MTok entrée/sortie)
claude--modelhaiku"Fix this typo in README.md"
# Choisir Sonnet explicitement pour le travail standard
claude--modelsonnet"Refactor this module"
# Utiliser Opus uniquement pour les tâches critiques/complexes
claude--modelopus"Design the entire authentication system"
Stratégie 4 : Limiter les serveurs MCP
// ❌ Coûteux - 5 serveurs MCP chargés
{
"mcpServers": {
"serena": {...},
"context7": {...},
"sequential": {...},
"playwright": {...},
"postgres": {...}
}
}
// ~10K tokens de surcharge par session
// ✅ Moins coûteux - ne charger que ce dont vous avez besoin
{
"mcpServers": {
"serena": {...} // Uniquement pour ce projet
}
}
// ~2K tokens de surcharge
Stratégie 5 : Regrouper les opérations
Terminal window
# ❌ Coûteux - 5 invites séparées
"Read file1.ts"
"Read file2.ts"
"Read file3.ts"
"Read file4.ts"
"Read file5.ts"
# ✅ Moins coûteux - une seule requête groupée
"Read file1.ts, file2.ts, file3.ts, file4.ts, file5.ts and analyze them together"
# Contexte partagé, réponse unique
Stratégie 6 : Utiliser la mise en cache des invites pour un contexte répété (API)
Si vous appelez l’API Anthropic directement (par exemple pour des agents ou pipelines personnalisés), la mise en cache des invites réduit les coûts jusqu’à 90 % sur les préfixes répétés.
# Marquer les sections stables avec cache_control
response = client.messages.create(
model="claude-sonnet-5",
max_tokens=1024,
system=[
{
"type": "text",
"text": "<your large system prompt / codebase context>",
"cache_control": {"type": "ephemeral"} # Cache this prefix
}
],
messages=[{"role": "user", "content": "Fix the bug in auth.ts"}]
)
Économie de la mise en cache des invites :
Opération
Multiplicateur de coût
TTL
Écriture en cache
1,25× le prix de base
5 minutes (par défaut)
Écriture en cache (étendue)
2× le prix de base
1 heure
Lecture en cache (succès)
0,1× le prix de base
—
Réduction de latence
Jusqu’à 85 % pour les longues invites
—
Seuil de rentabilité : 2 succès de cache avec TTL de 5 minutes. Au-delà, économies pures.
Règles :
Maximum 4 points de rupture de cache par requête
Clé de cache = correspondance exacte du préfixe (un seul caractère de différence = échec de cache)
Placez les points de rupture après les grandes sections stables : invite système, définitions d’outils, contexte de la base de code
Pour Claude Code lui-même : la mise en cache est gérée automatiquement par le CLI, cela s’applique aux workflows basés sur l’API que vous construisez par-dessus Claude
Claude Code gère la mise en cache des invites sans aucune configuration de votre part. Comprendre les mécanismes vous aide à prendre des décisions qui maintiennent des taux de succès de cache élevés et des coûts bas.
Hiérarchie des préfixes de cache
Chaque appel API effectué par Claude Code structure le contenu dans cet ordre fixe : tools → system → messages. La correspondance de cache commence toujours depuis le début de ce préfixe. Une liste d’outils stable + un CLAUDE.md stable + un historique de conversation croissant signifie que les deux premières couches sont presque toujours des succès de cache, tandis que seuls les nouveaux tours de messages nécessitent un calcul frais.
Le lookback de 20 blocs : le piège des longues sessions
La correspondance de cache utilise un lookback borné d’environ 20 blocs. Dans une longue session avec de nombreux appels d’outils et échanges, les blocs du début de la conversation tombent hors de cette fenêtre et deviennent des échecs de cache. Conséquence pratique : les très longues sessions perdent progressivement l’efficacité du cache au niveau de la couche des messages. La solution est /compact : il compresse l’historique de la conversation en un seul bloc de résumé, réinitialisant la fenêtre de lookback et restaurant des taux de succès élevés.
Seuils minimaux de tokens par modèle
Un bloc doit atteindre une taille minimale pour être éligible à la mise en cache. Les blocs plus petits que le seuil ne sont jamais mis en cache, quelle que soit leur stabilité :
Famille de modèles
Tokens minimaux
Claude Opus 4.7, Opus 4.6, Opus 4.5, Haiku 4.5
4 096
Claude Sonnet 4.6
2 048
Claude Opus 5, Fable 5
512
Claude Sonnet 5, Opus 4.8
1 024
Claude Sonnet 4.5, Sonnet 4, Sonnet 3.7, Opus 4.1, Opus 4
1 024
Claude Haiku 3.5, Haiku 3
2 048
Les fichiers CLAUDE.md courts (moins de ~1 000 tokens) peuvent ne pas être mis en cache du tout sur les modèles Sonnet. Si l’optimisation des coûts est importante, assurez-vous que votre invite système dépasse le seuil pour votre modèle cible.
Taille des résultats d’outils et économie du cache
Les résultats des outils atterrissent dans l’historique des messages et y restent pour le reste de la session. Chaque appel API ultérieur relit cet historique, au prix de lecture en cache (0,1×), mais toujours proportionnel à la taille. Une sortie git status de 500 tokens coûte 500 × 0,1× à lire à chaque tour qui suit. La même sortie à 50 tokens (filtrée par un outil comme RTK) coûte 50 × 0,1×, 90 % de moins, en se cumulant à chaque tour de la session. Des sorties d’outils compactes ne sont pas seulement plus rapides à traiter ; elles rendent l’ensemble du préfixe mis en cache moins coûteux à maintenir.
La même logique s’applique aux écritures en cache : un préfixe d’historique plus petit signifie des écritures initiales moins chères (1,25× × moins de tokens).
Surveiller les performances du cache dans vos propres pipelines
Lors de la construction d’agents ou de pipelines sur l’API Anthropic, l’objet usage de la réponse expose directement les métriques de cache :
response = client.messages.create(...)
print(response.usage.cache_creation_input_tokens) # Tokens écrits en cache lors de cette requête
print(response.usage.cache_read_input_tokens) # Tokens lus depuis le cache (succès)
print(response.usage.input_tokens) # Tokens d'entrée non mis en cache
Calculez votre taux de succès comme cache_read / (cache_read + cache_creation) entre les requêtes. Un ratio supérieur à 0,8 signifie que la structure de votre invite fonctionne bien. Les ratios faibles signifient généralement que le contenu du préfixe stable change entre les requêtes, vérifiez la présence d’horodatages, d’identifiants aléatoires ou de contenu dynamique intégré dans votre invite système.
/usage inclut les statistiques du cache de prompts de la conversation principale dans les versions actuelles compatibles. Pour les pipelines API personnalisés, inspectez les champs de réponse ci-dessus. Voir la documentation des coûts et du cache.
Règles pratiques
Gardez le CLAUDE.md stable entre les sessions, les modifications invalident le cache système en une seule fois, puis il se rechauffe à la requête suivante
Exécutez /compact avant que la conversation ne devienne très longue, pas après que les performances se dégradent
Évitez le contenu dynamique dans les sections stables (dates, valeurs aléatoires, contexte par requête)
Un CLAUDE.md plus grand = écriture en cache plus coûteuse, mais aussi plus de tokens économisés par lecture, rentable après ~2 succès
Bugs de cache connus (v2.1.69+)
Deux bugs actifs cassent silencieusement la mise en cache sur v2.1.69+. Appliquez ces contournements immédiatement :
—resume/—continue provoque une reconstruction complète du cache (ratio de succès 0 %) à chaque reprise car le JSONL de session supprime les enregistrements d’outils différés avant l’écriture. Contournement : évitez --resume jusqu’à correction.
L’en-tête de facturation par session injecte un hash unique comme premier bloc d’invite système, provoquant un échec à froid à chaque démarrage de session et appel de sous-agent. Contournement : "CLAUDE_CODE_ATTRIBUTION_HEADER": "false" dans ~/.claude/settings.json.
Pourquoi utiliser ccusage plutôt que /cost (alias de /usage depuis la v2.1.118) ?
Tendances historiques : suivez les habitudes d’utilisation sur des jours/semaines/mois
Répartition par modèle : voyez quel niveau de modèle génère les coûts
Planification budgétaire : fixez des objectifs de dépenses mensuelles
Analytique d’équipe : agrégez les coûts entre développeurs
Pour un inventaire complet des outils communautaires de suivi des coûts, visionneuses de sessions, gestionnaires de configuration et interfaces alternatives, voir Third-Party Tools.
Suivi mensuel :
Consultez votre console Anthropic pour le détail d’utilisation :
Estimez-le à partir des tokens d’entrée, de sortie, du cache et des reprises mesurés sur des tâches représentatives acceptées. Les relevés du fournisseur font foi pour les montants facturés ; les outils locaux fournissent des estimations. Consultez le guide des commandes ccusage pour les rapports disponibles.
Mettre les coûts en perspective : Si Claude Code vous fait gagner un temps significatif sur une tâche, le coût API est généralement négligeable par rapport à votre tarif horaire. Ne réduisez pas les coûts de tokens au détriment de la productivité.
Quand optimiser :
✅ Budget limité (étudiant, usage personnel)
✅ Usage important (>4 heures/jour)
✅ Usage en équipe (5+ développeurs)
Quand ne PAS optimiser :
❌ Votre temps coûte plus cher que l’API
❌ Vous passez plus de temps à optimiser que ne le justifient les économies
❌ Les restrictions nuisent à votre productivité
Workflows attentifs aux coûts {#cost-conscious-workflows}
Choisissez un modèle et un niveau d’effort qui satisfont les critères d’acceptation de la tâche, puis comparez le coût total, reprises et relecture comprises. Confiez les tâches répétitives à un modèle moins cher uniquement si le résultat mesuré le justifie. Un pilote en équipe doit consigner les tâches acceptées, l’usage des modèles, les échecs et l’effort de relecture humaine avant de fixer un budget.
Observation
Investigation
Le coût augmente pendant les longues sessions
Inspecter la croissance du contexte et les échecs de cache avec /usage
Des appels répétés renvoient les mêmes données
Préciser la demande et réutiliser un résultat explicite
Un modèle moins cher exige de nombreuses reprises
Comparer son coût par tâche acceptée à celui d’un modèle plus capable
Plusieurs agents répètent l’exploration du dépôt
Leur attribuer un périmètre borné et un contexte écrit partagé
Abonnements et limites {#subscription-plans—limits}
Consultez les offres actuelles et l’utilisation du compte connecté. Les allocations des abonnements ne correspondent pas à des budgets fixes publiés en tokens ; les rapports de prix API ne déterminent pas la consommation des quotas. L’accès aux modèles et les politiques d’organisation peuvent changer indépendamment du nom de l’offre. Pro ne se limite pas à Sonnet : les valeurs par défaut et les choix disponibles figurent dans le tableau des modèles ci-dessus.
Suivre votre utilisation
/usage # Session estimates, subscription limits and usage breakdown
/model # Available models for this account and provider
/status # Active account and session configuration
L’estimation en dollars de la session ne représente pas à elle seule la facture d’un abonné. /usage inclut les barres de consommation de l’offre pour les abonnements et, lorsqu’ils sont activés, les crédits d’usage. Consultez la page de facturation Claude ou du fournisseur concerné pour connaître les montants effectivement facturés. Documentation du suivi des coûts.
Si vous choisissez opusplan, Opus gère la planification et Sonnet l’exécution. Haiku nécessite une sélection explicite distincte. Évaluez cette politique de routage sur votre travail ; elle ne promet ni économie fixe ni nombre garanti d’heures utilisables.
Lorsqu’une limite interrompt le travail, consultez sa date de réinitialisation et la politique actuelle du compte. Enregistrez l’état de la tâche avant de changer de modèle, de compte ou de mode d’exécution. Les anciens témoignages sur les quotas et les heures de pointe ne sont pas des limites actuelles fiables.
Contamination du contexte (bleeding) {#context-poisoning-bleeding}
Lorsque vous terminez une session ou changez de contexte, créez un document de passation pour maintenir la continuité.
Objectif : Assurer le relais entre les sessions en documentant l’état, les décisions et les prochaines étapes.
Modèle :
# Session Handoff - [Date] [Time]
## What Was Accomplished
- [Key task 1 completed]
- [Key task 2 completed]
- [Files modified: list]
## Current State
- [What's working]
- [What's partially done]
- [Known issues or blockers]
## Decisions Made
- [Architectural choice 1: why]
- [Technology selection: rationale]
- [Trade-offs accepted]
## Next Steps
1. [Immediate next task]
2. [Dependent task]
3. [Follow-up validation]
## Context for Next Session
- Branch: [branch-name]
- Key files: [list 3-5 most relevant]
- Dependencies: [external factors]
Quand créer un document de passation :
Scénario
Pourquoi
Fin de journée de travail
Reprendre demain sans réexpliquer le contexte
Avant la limite du contexte
Préserver l’état avant /clear
Changement de sujet
Une autre tâche nécessite un contexte neuf
Interruption attendue
Une urgence ou une réunion interrompt le travail
Débogage complexe
Documenter les hypothèses et les tests effectués
Emplacement de stockage : claudedocs/handoffs/handoff-YYYY-MM-DD.md
Conseil pratique : Demandez à Claude de générer la passation :
You: "Create a session handoff document for what we accomplished today"
Claude analysera l’état Git et l’historique de conversation, puis générera une passation structurée.
Pattern des trois commandes de passation : Pour les équipes ou les workflows multisessions, un protocole en trois commandes ajoute des règles de fusion explicites à la passation de base. Les trois commandes fonctionnent ensemble :
Commande
Rôle
/handoff:create
Génère le document structuré à partir du contexte de la session courante
/handoff:resume
Charge un document de passation, confirme sa compréhension et attend l’approbation avant de commencer
/handoff:update
Met à jour une passation existante avec des règles de fusion propres à chaque section (voir ci-dessous)
L’ajout déterminant concerne les règles de fusion par section dans update :
Section
Règle de fusion
Tâche, périmètre
Conserver ou préciser
Fichiers
Fusionner : combiner la liste initiale avec les nouveaux fichiers touchés
Découvertes
Ajouter : consigner les nouvelles observations sans supprimer les précédentes
Travail réalisé
Ajout uniquement : ajouter de nouvelles entrées sans jamais supprimer l’historique, inclure les hashes de commits
État
Remplacer : décrire l’état actuel
Prochaines étapes
Remplacer : écrire la checklist mise à jour
La section Travail réalisé, alimentée uniquement par des ajouts, crée une piste d’audit entre les sessions. Même si un travail antérieur est révisé, la révision apparaît comme une nouvelle entrée au lieu d’écraser la précédente.
Des modèles prêts à adapter sont disponibles dans examples/commands/handoff/ dans ce dépôt.
Fréquence recommandée : Boris Cherny, responsable de Claude Code chez Anthropic, commence environ 80 % de ses tâches en mode Plan et laisse Claude préparer son approche avant d’écrire une ligne de code. Une fois le plan approuvé, l’exécution est presque toujours correcte dès le premier essai.
Lenny’s Newsletter, 19 février 2026
Appuyez sur Shift+Tab pour revenir au mode normal, aussi appelé mode Act. Vous pouvez également écrire un message ; Claude demandera alors si vous souhaitez mettre le plan en œuvre.
Remarque : Shift+Tab permet de changer de mode pendant une session. Depuis le mode normal, appuyez deux fois sur Shift+Tab pour entrer en mode Plan, puis une fois pour en sortir.
Bénéfice attendu : relire un plan avant l’exécution permet de repérer les ambiguïtés et les limites de périmètre avant de modifier des fichiers. Mesurez les économies de tokens et les résultats acceptés sur votre propre travail ; aucun pourcentage général n’est établi ici.
Les alias dépendent du fournisseur et peuvent être redéfinis dans la configuration. Vérification effectuée le 24 septembre 2026 dans la documentation officielle des modèles :
Fournisseur
opus
sonnet
Anthropic API
Opus 5.5
Sonnet 5.5 (depuis v2.1.284)
Claude Platform on AWS
Opus 5.5
Sonnet 4.6
Amazon Bedrock / Google Cloud’s Agent Platform
Opus 5.5
Sonnet 4.5
Microsoft Foundry
Opus 4.6
Sonnet 4.5
Sélection
Signification
default
Supprime la sélection explicite et utilise le modèle par défaut du compte ou de l’organisation
haiku
Alias de la famille Haiku ; le modèle actuel du service direct est Haiku 4.5
fable
Fable 5.1, sauf via la passerelle des applications Claude, qui utilise Fable 5
best
Équivalent à fable lorsque disponible, sinon opus
opus[1m], sonnet[1m]
Demande une variante 1M lorsque le fournisseur ou le modèle l’exige
opusplan
opus pour la planification, sonnet pour l’exécution
opusplan[1m]
Demande 1M dans les deux phases lorsque ce n’est pas natif ; /model l’accepte depuis la v2.1.265
Pour fixer une version, utilisez son identifiant exact chez le fournisseur, par exemple claude-opus-5-5, ou la variable ANTHROPIC_DEFAULT_*_MODEL correspondante. Un alias qui pointe vers un ancien modèle ne signifie pas que les identifiants explicites des modèles plus récents sont indisponibles.
/model <name> enregistre un choix par défaut pour les nouvelles sessions. Dans le sélecteur, appuyez sur s pour limiter le choix à la session en cours. claude --model <name> et ANTHROPIC_MODEL s’appliquent à la session lancée. Les paramètres du projet et les paramètres gérés peuvent se réappliquer au lancement suivant ; une session reprise retrouve généralement son modèle enregistré. ANTHROPIC_DEFAULT_MODEL est un choix par défaut de priorité inférieure, qui ne remplace pas ces sélections explicites.
Utilisez la barre d’état, /model ou les métadonnées de réponse de l’API pour identifier le modèle actif. Les déclarations du modèle sur sa propre identité ne sont pas fiables. Les dates limites de connaissances fiables sont juin 2026 pour Opus 5.5, Sonnet 5.5 et Fable 5.1, et février 2025 pour Haiku 4.5. Caractéristiques des modèles.
Principe : utiliser Opus pour la planification, grâce à ses capacités de raisonnement, et Sonnet pour l’implémentation, à moindre coût.
Pourquoi OpusPlan ?
Maîtrise des coûts : les tokens Opus coûtent plus cher que ceux de Sonnet.
Complémentarité : planification avec Opus et exécution rapide avec Sonnet.
Économie de tokens : la planification est généralement plus courte que l’implémentation.
Activation :
/model opusplan
Ou dans ~/.claude/settings.json :
{
"model": "opusplan"
}
Fonctionnement :
En mode Plan (/plan ou deux pressions sur Shift+Tab), utilise Opus.
En mode Act, lors de l’exécution normale, utilise Sonnet.
Le changement de modèle suit automatiquement le mode.
Déroulement recommandé :
1. /model opusplan → Enable OpusPlan
2. Shift+Tab × 2 → Enter Plan Mode (Opus)
3. Describe your task → Get Opus-quality planning
4. Shift+Tab → Exit to Act Mode (Sonnet)
5. Execute the plan → Sonnet implements efficiently
Autre approche avec les sous-agents :
Vous pouvez aussi choisir le modèle de chaque agent :
.claude/agents/planner.md
---
name: planner
model: opus
tools: Read, Grep, Glob
---
# Strategic Planning Agent
.claude/agents/implementer.md
---
name: implementer
model: haiku
tools: Write, Edit, Bash
---
# Fast Implementation Agent
Pour les abonnés Pro : OpusPlan est particulièrement utile lorsque le quota de tokens Opus est limité. Il réserve le raisonnement d’Opus aux étapes de planification importantes et préserve des tokens pour d’autres sessions.
Variante économique : SonnetPlan, une astuce communautaire
opusplan associe Opus et Sonnet de manière fixe. Il n’existe pas d’alias natif sonnetplan. Vous pouvez toutefois redéfinir les modèles associés aux alias opus et sonnet grâce aux variables d’environnement, et ainsi créer une combinaison Sonnet→Haiku :
En mode Act, Haiku 4.5 via l’alias sonnet redéfini.
Attention : la réponse à « quel modèle es-tu ? » n’est pas fiable ; les modèles ne connaissent pas toujours leur propre identité. Fiez-vous à la barre d’état (Model: Sonnet 5 en mode Plan) ou vérifiez le tableau de bord de facturation. L’issue GitHub #9749 suit la prise en charge native de cette combinaison.
Fixer Opus 4.6, une astuce communautaire
Opus 4.7 utilise un nouveau tokenizer qui convertit une même entrée en environ 1.0 à 1.35 fois plus de tokens selon le contenu. Aux niveaux d’effort élevés, il produit aussi davantage de tokens de sortie, avec plus d’étapes de raisonnement. Lorsque cette dépense supplémentaire n’améliore pas les résultats, fixer Opus 4.6 conserve un modèle et un tokenizer plus anciens. Mesurez le compromis entre coût et qualité sur votre propre tâche.
Option A : Opus 4.6 partout, la plus simple
~/.claude/settings.json
{
"model": "claude-opus-4-6"
}
Toutes les sessions utilisent Opus 4.6, sans alternance. Ajoutez [1M] si vous avez besoin de la fenêtre de contexte 1M : "claude-opus-4-6[1M]".
Option B : conserver OpusPlan et fixer volontairement l’ancien modèle Opus
~/.claude/settings.json
{
"model": "opusplan",
"env": {
"ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-6"
}
}
opusplan continue d’alterner entre les modes Plan et Act, mais le mode Plan utilise désormais Opus 4.6 à la place du modèle associé à l’alias Opus actuel du fournisseur. Le modèle Sonnet du mode Act ne change pas.
Variante shell non persistante, utile pour tester :
Option C : changer de modèle pour une session, sans modifier la configuration
/model claude-opus-4-6
Le choix est réinitialisé à la session suivante. Cette approche permet de tester avant de changer la configuration.
Vérification : consultez la barre d’état en mode Plan et vérifiez l’identifiant Opus 4.6 effectivement utilisé. Le tableau de bord de facturation confirme le modèle facturé.
Compromis : Opus 4.6 ne prend pas en charge xhigh, mais accepte max. Le fixer conserve un modèle, un tokenizer et une date limite de connaissances plus anciens. Comparez les résultats acceptés et le total des tokens au modèle actuel par défaut avant de considérer ce choix comme une économie.
Principe : enchaîner plusieurs tours de planification et de réflexion approfondie avant l’exécution, comme on fait chauffer un moteur avant de partir.
Déroulement standard : réfléchir → planifier → exécuter.
Rev the Engine : réfléchir → planifier → approfondir → affiner le plan → approfondir encore → finaliser → exécuter.
Quand l’utiliser :
Pour des décisions d’architecture critiques, difficiles à inverser et à fort impact.
Pour des migrations complexes qui touchent plus de 10 fichiers.
Dans un domaine inconnu où la première intuition est souvent trompeuse.
Exemple :
## Round 1: Initial analysis
User: /plan
User: Analyze the current auth system. What are the key components,
dependencies, and potential risks of migrating to OAuth2?
Claude: [Initial analysis]
## Round 2: Deep challenge
User: Now use extended thinking. Challenge your own analysis:
- What assumptions did you make?
- What failure modes did you miss?
- What would a senior security engineer flag?
Claude: [Deeper analysis with self-correction]
## Round 3: Final plan
User: Based on both rounds, write the definitive migration plan.
Include rollback strategy and risk mitigation for each step.
Claude: [Refined plan incorporating both rounds]
## Execute
[approve the plan, or Shift+Tab to leave plan mode]
User: Implement the plan from round 3.
Objectif : chaque tour pose une question distincte sur les hypothèses, les contraintes manquantes ou la consolidation. Des tours supplémentaires peuvent simplement répéter les précédents ; arrêtez quand ils n’apportent plus rien. Des critères d’acceptation et des vérifications indépendantes restent nécessaires.
📊 Données empiriques : Anthropic AI Fluency Index, février 2026
Une étude Anthropic portant sur 9 830 conversations sur une semaine en janvier 2026 a observé que l’itération et l’affinement étaient associés à 5.6 fois plus de questionnement du raisonnement du modèle et à 4 fois plus d’identification de contexte manquant. Ces associations ne mesurent pas la détection de bugs et ne démontrent pas de causalité ; l’étude ne testait pas ce workflow de relecture en trois tours.
La méthode Rev the Engine applique ce constat : chaque tour de remise en question déclenche le comportement associé à de meilleurs plans mesurés.
Revue de code réalisée dans le cloud par plusieurs agents en parallèle. Les agents examinent simultanément les modifications et signalent les bugs et problèmes de conception qu’une relecture attentive pourrait relever.
Activation :
Terminal window
/ultrareview# Review current branch (diff from base)
/ultrareview<PR#># Review a specific GitHub PR
Ultrareview travaille sur les différences, pas sur l’ensemble du code : il examine les changements de la branche courante ou ceux d’une PR donnée. La session cloud distribue l’analyse à plusieurs agents. Les résultats arrivent dans le navigateur et peuvent être renvoyés vers le terminal.
Offre de lancement : les abonnés Pro et Max bénéficient de trois ultrareviews gratuites pour essayer la fonctionnalité.
Toutes les tâches n’exigent pas toutes ces couches. Adaptez leur nombre à l’impact de la décision :
Impact de la décision
Nombre de couches
Exemple
Faible, correction d’une faute
0
Exécution directe
Moyen, ajout d’une fonctionnalité
1 à 2
Mode Plan et réflexion étendue
Élevé, architecture
3 à 4
Rev the Engine et rôles distincts
Critique, migration
4 à 5
Ensemble des mécanismes
À éviter : empiler les mécanismes pour des décisions triviales. Si la modification est réversible et peu risquée, exécutez-la directement. Trop planifier gaspille autant que trop peu planifier.
Rewind propose quatre actions distinctes depuis la liste des points de contrôle :
Action
Effet
Restore code and conversation
Rétablit les modifications de fichiers et la conversation au point sélectionné
Restore conversation
Conserve le code actuel, rembobine uniquement la conversation
Restore code
Rétablit les modifications de fichiers, conserve la conversation
Summarize from here
Compresse la conversation depuis le point sélectionné (libère de l’espace sans rétablissement)
Distinction clé : Restore = annulation (rétablit l’état). Summarize = compression (libère de l’espace sans rétablissement). Les points de contrôle persistent entre les sessions (nettoyage après 30 jours).
Modifications committées, rollback complet nécessaire
Niveau 3
git reset
Branche expérimentale mal tournée
Niveau 3
git checkout main
Contexte corrompu, comportement étrange
Nouveau départ
/clear + reformuler l’objectif
Conseil pro : La commande /rewind affiche une liste des modifications à annuler. Vous pouvez rétablir sélectivement des fichiers spécifiques plutôt que toutes les modifications.
Pattern de point de contrôle : expérimentation sécurisée
Choisir le bon modèle pour chaque tâche est l’amélioration du ROI la plus rapide que la plupart des utilisateurs de Claude Code puissent réaliser. Une décision par tâche, sans trop réfléchir.
Augmenter depuis medium si l’évaluation le justifie
Travail long ou ambigu sous le niveau de qualité attendu
Évaluer Fable 5.1
Commencer à high
Workflow multi-agents
Affecter selon le rôle et les résultats mesurés
Selon le modèle pris en charge
Le nom d’un modèle ne détermine pas un coût fixe par tâche. Mesurez les tokens d’entrée, de sortie et de cache, les nouvelles tentatives et l’effort de revue avec les mêmes critères d’acceptation. Voir le tableau de tarification.
Fable 5.1 (claude-fable-5-1, Claude Code v2.1.257+) est une option explicite lorsque les évaluations d’Opus 5.5 restent insuffisantes. /model fable le sélectionne normalement ; les sessions via la passerelle Claude apps associent cet alias à Fable 5, donc utilisez un identifiant complet pris en charge pour fixer la nouvelle version. La disponibilité et la facturation en crédits dépendent du compte. Un modèle plus puissant ne dispense pas de vérifier les décisions de sécurité ou de production. Accès et facturation Fable.
L’effort contrôle le raisonnement adaptatif et peut modifier l’usage des outils, la longueur des réponses, la latence et le coût. Il ne garantit pas l’exactitude.
Modèles
Niveaux d’effort Claude Code pris en charge
Défaut
Opus 5.5
low, medium, high, xhigh, max
medium
Sonnet 5, Opus 5 / 4.8, Fable 5 / 5.1
low, medium, high, xhigh, max
high
Opus 4.7
low, medium, high, xhigh, max
xhigh
Opus 4.6, Sonnet 4.6
low, medium, high, max
high
Haiku 4.5
Aucun paramètre effort
Sans objet
/effort et le sélecteur /model enregistrent les niveaux pris en charge de low à xhigh par modèle avec Enter ; s limite le choix à la session. /effort max ne s’applique qu’à la session. Les réglages persistants modelSettings et effortLevel n’acceptent pas max. CLAUDE_CODE_EFFORT_LEVEL peut surcharger la session et les règles de l’organisation peuvent plafonner les niveaux disponibles.
/effort ultracode active l’orchestration dynamique des workflows avec un raisonnement xhigh. C’est un réglage Claude Code, pas un sixième niveau d’effort du modèle. Le mot-clé ultrathink ajoute une consigne de raisonnement plus approfondi sans modifier la valeur envoyée à l’API.
Opus 5.5 commence à medium et n’hérite pas de l’ancien effortLevel global des paramètres utilisateur. Un choix par modèle, une surcharge explicite à l’exécution ou les paramètres de projet, locaux ou gérés peuvent néanmoins le modifier. Règles officielles d’effort.
Les skills peuvent déclarer leur propre niveau d’effort dans le frontmatter. La valeur du skill remplace le paramètre de session pendant toute la durée d’exécution de ce skill, puis revient à la valeur précédente. Cela élimine le besoin de basculer manuellement l’effort entre les tâches mécaniques et analytiques.
# Skill mécanique — toujours rapide, ne gaspille jamais le budget de raisonnement
# Skill analytique — toujours approfondi, quel que soit le paramètre de session
---
name: architecture-review
description: Full architectural analysis with trade-off evaluation
effort: high
---
Tableau de décision pour les types de skills courants :
Type de skill
Effort recommandé
Justification
Commit, push, sync
low
Étapes séquentielles, aucune décision de conception
Changelog, notes de version
low
Lit git + formate, mécanique
Scaffolding, boilerplate
low
Instanciation de modèle
Revue de code (PR unique)
medium
Reconnaissance de modèles, périmètre borné
Triage d’issues, backlog
medium
Catégorisation + quelques analyses
Audit de sécurité
high
Modélisation des menaces, raisonnement adversarial
Revue d’architecture
high
Décisions de conception, raisonnement inter-composants
Orchestration multi-agents
high
Coordination + planification
Modèle de coût : l’effort low signifie moins d’appels d’outils, pas de préambule, sortie directe. L’effort high signifie plus d’appels d’outils avec explications, résumés détaillés, exploration approfondie. Adaptez l’effort là où l’analyse apporte de la valeur, pas selon le principe « effort = qualité » de manière uniforme.
description: Mechanical execution agent. Scope must be defined explicitly in the task.
model: haiku
tools: Write, Edit, Bash, Read, Grep, Glob
---
Note : Haiku est réservé aux tâches mécaniques uniquement. Si l’implémentation nécessite des décisions de conception ou une logique métier complexe, utilisez Sonnet, précisez-le dans le prompt de tâche.
Architecture Reviewer (examples/agents/architecture-reviewer.md) : revue de conception critique
---
name: architecture-reviewer
description: Architecture and design review — read-only. Never modifies code.
model: opus
tools: Read, Grep, Glob
---
Conseil pro : Ajoutez un rappel de modèle dans votre CLAUDE.md :
# Model reminder
Project preference: Sonnet for routine work, Haiku for bounded tasks, Opus for harder reasoning. This is a chosen policy, not the account default.
État d’exécution : Claude ne peut pas voir les processus en cours
Services externes : Claude ne peut pas accéder directement à vos bases de données
Votre intention : Claude a besoin d’instructions claires
Fichiers cachés : Claude respecte .gitignore par défaut
⚠️ Amplification des modèles : Claude reproduit les modèles qu’il trouve. Dans des bases de code bien structurées, il produit un code cohérent et idiomatique. Dans des bases de code désordonnées sans abstractions claires, il perpétue le désordre. Si votre code manque de bons modèles, fournissez-les explicitement dans CLAUDE.md ou utilisez des ancres sémantiques (section 2.9).
Pensez à vous comme un ordonnanceur de CPU. Les instances de Claude Code sont des threads de travail. Votre rôle est d’orchestrer le travail, pas d’écrire le code.
┌─────────────────────────────────────────┐
│ VOUS (Thread principal) │
│ ┌────────────────────────────────────┐ │
│ │ Responsabilités : │ │
│ │ • Définir les tâches et priorités │ │
│ │ • Allouer les budgets de contexte │ │
│ │ • Réviser les résultats │ │
│ │ • Prendre les décisions arch. │ │
│ │ • Gérer les exceptions/escalades │ │
│ └────────────────────────────────────┘ │
│ │ │ │ │
│ ┌────▼───┐ ┌────▼───┐ ┌────▼───┐ │
│ │Worker 1│ │Worker 2│ │Worker 3│ │
│ │(Claude)│ │(Claude)│ │(Claude)│ │
│ │Feature │ │Tests │ │Review │ │
│ └────────┘ └────────┘ └────────┘ │
└─────────────────────────────────────────┘
Implications :
N’écrivez pas de code quand Claude peut le faire. Votre temps est consacré aux décisions, pas aux frappes au clavier.
Ne microgérez pas. Donnez des instructions claires, puis examinez les résultats.
Changez de contexte délibérément. Comme un ordonnanceur, regroupez les tâches similaires.
Escaladez vers vous-même. Quand Claude est bloqué, intervenez, puis redéléguez.
Ce modèle mental passe à l’échelle : un seul développeur peut orchestrer 2 à 5 instances de Claude sur des tâches indépendantes (voir §9.17 Scaling Patterns).
L’erreur la plus courante est de traiter Claude Code comme un chatbot : taper des requêtes ad hoc en espérant obtenir de bons résultats. Ce qui distingue l’usage occasionnel des workflows de production est un changement de perspective :
Mode chatbot : vous rédigez de bons prompts. Système de contexte : vous construisez un contexte structuré qui améliore chaque prompt.
« Arrêtez de le traiter comme un chatbot. Donnez-lui un contexte structuré. CLAUDE.md, hooks, skills, mémoire de projet. Ça change tout. »
— Robin Lorenz, Ingénieur IA (commentaire)
Claude Code dispose de quatre couches de contexte persistant qui se renforcent mutuellement dans le temps :
Couche
Ce qu’elle fait
Section
Quand la configurer
CLAUDE.md
Règles persistantes, conventions, connaissances du projet
Ce ne sont pas des fonctionnalités indépendantes. Ce sont des couches du même système :
CLAUDE.md enseigne à Claude ce dont votre projet a besoin (conventions, stack, modèles)
Skills enseigne à Claude comment réaliser des workflows spécifiques (revue, déploiement, tests)
Hooks applique des garde-fous automatiquement (blocage des secrets, auto-formatage, linting)
Mémoire préserve les décisions entre les sessions (choix architecturaux, compromis résolus)
Avant (mode chatbot) :
« Utilise pnpm, pas npm. Et n’oublie pas que notre convention de nommage est… »
(À chaque session. À chaque fois. Copier-coller du contexte.)
Après (système de contexte) :
CLAUDE.md charge les conventions automatiquement. Les skills garantissent des workflows cohérents.
Les hooks appliquent la qualité sans effort manuel. La mémoire transmet les décisions d’une session à l’autre.
Le changement ne concerne pas la rédaction de meilleurs prompts. Il s’agit de construire un système où Claude commence chaque session en sachant déjà ce dont vous avez besoin.
Les prompts structurés en XML offrent une organisation sémantique pour les requêtes complexes, aidant Claude à distinguer les différents aspects de votre tâche pour une meilleure compréhension et de meilleurs résultats.
Les balises XML fonctionnent comme des conteneurs étiquetés qui séparent explicitement les types d’instructions, le contexte, les exemples, les contraintes et le format de sortie attendu.
Syntaxe de base :
<instruction>
Your main task description here
</instruction>
<context>
Background information, project details, or relevant state
Surcharge en tokens : Les balises XML consomment des tokens. Pour les requêtes simples, le langage naturel est plus efficace.
Non obligatoire : Claude comprend parfaitement le langage naturel. Utilisez XML quand la structure apporte une réelle valeur ajoutée.
La cohérence est importante : Si vous utilisez des balises XML, soyez cohérent. Mélanger les styles au sein d’une même session peut perturber le contexte.
Courbe d’apprentissage : Les membres de l’équipe doivent comprendre le système de balises. Documentez vos conventions dans CLAUDE.md.
💡 Conseil pro : Commencez par des prompts en langage naturel. Introduisez la structure XML lorsque :
Les requêtes comportent 3 aspects distincts ou plus (instruction + contexte + contraintes)
L’ambiguïté amène Claude à mal interpréter votre intention
Vous créez des modèles de prompts réutilisables
Vous travaillez avec des développeurs juniors qui ont besoin de schémas de communication structurés
L’équipe Claude Code traite en interne les prompts comme des défis lancés à un pair, et non comme des instructions données à un assistant. Ce glissement subtil produit des résultats de meilleure qualité, car il oblige Claude à démontrer son raisonnement plutôt qu’à simplement s’exécuter.
Trois schémas de provocation utilisés par l’équipe :
1. Le gardien : obliger Claude à défendre son travail avant de livrer :
"Grill me on these changes and don't make a PR until I pass your test"
Claude examine votre diff, pose des questions précises sur les cas limites, et ne poursuit que lorsqu’il est satisfait. Cela permet de détecter des problèmes qu’une revue passive laisserait passer.
2. L’exigence de preuve : demander des preuves, pas des affirmations :
"Prove to me this works — show me the diff in behavior between main and this branch"
Claude exécute les deux branches, compare les sorties et présente des preuves concrètes. Élimine le mode d’échec « fais-moi confiance, ça marche ».
3. La remise à zéro : après une première tentative médiocre, déclencher une réécriture en plein contexte :
"Knowing everything you know now, scrap this and implement the elegant solution"
Cela impose une deuxième tentative substantielle avec le contexte accumulé, plutôt que des corrections incrémentales sur une base fragile. L’insight clé : la deuxième tentative de Claude avec le contexte complet surpasse systématiquement les correctifs itératifs.
Pourquoi ça fonctionne : La provocation active des chemins de raisonnement plus profonds que les requêtes polies. Lorsque Claude doit convaincre plutôt que s’exécuter, il met en œuvre une analyse plus approfondie et détecte ses propres raccourcis.
Une ancre sémantique est le nom d’une méthode, d’un motif ou d’un cadre établi, utilisé comme raccourci dans un prompt. Elle donne à Claude une référence plus précise que « écris de bons tests ». La reconnaissance du terme et son application correcte dépendent encore du modèle, de la tâche et des instructions qui l’entourent.
« Écris de bons tests » laisse l’approche ouverte. « Utilise le TDD, London School ; commence par un test de comportement de l’extérieur vers l’intérieur » nomme une méthode et précise ce qui est attendu. Cette précision compte : un modèle peut reconnaître le terme sans bien l’appliquer au code du projet.
Demande vague
Ancre et direction pour la tâche
Point à vérifier
« Gère les erreurs »
« Utilise Railway Oriented Programming avec un type Result pour les échecs attendus »
Les échecs attendus restent explicites ; les défaillances imprévues restent observables
« Améliore la conception »
« Applique Deep Modules : cache les détails d’implémentation derrière une interface réduite »
Les appelants dépendent de moins de détails sans perdre le comportement requis
« Modernise cette fonctionnalité »
« Utilise Strangler Fig : remplace un comportement derrière une frontière »
Les anciens et nouveaux chemins coexistent sans rupture pendant la migration
« Conçois l’API »
« Vise le niveau 2 du Richardson Maturity Model »
Les ressources, méthodes HTTP et codes de statut respectent le contrat de l’API
L’ancre doit convenir au problème. Ajoutez le comportement attendu, les limites et les critères de vérification. Par exemple, CQRS et Event Sourcing sont deux choix distincts ; nommer l’un ne justifie pas d’adopter les deux.
Le plan d’évaluation du projet Semantic Anchors distingue la reconnaissance d’un terme de son application et compare les prompts avec ancre à des descriptions ordinaires. Il décrit une méthode d’évaluation, pas un gain de qualité mesuré pour les exemples de ce guide. Si le modèle applique mal un terme, explicitez la méthode et vérifiez le résultat.
- Architecture : architecture hexagonale (Ports & Adapters). Garder le code du prestataire hors du domaine.
- Erreurs : utiliser un type Result pour les échecs de paiement attendus ; rendre les défaillances imprévues observables.
- Tests : utiliser le TDD, London School à la frontière du service ; ajouter un test d'intégration de l'adaptateur du prestataire.
- Documentation : consigner la décision sur cette frontière dans un ADR.
Ce sont des choix de projet, pas des valeurs par défaut à copier dans chaque dépôt. Un prompt structuré en XML (section 2.8) peut regrouper les mêmes instructions ; les balises seules ne rendent pas l’ancre plus fiable.
Deux techniques au niveau du prompt qui réduisent l’écart entre des prompts bien structurés et des sorties fiables : les exemples few-shot pour calibrer le format et le style, et les boucles de validation avec nouvelle tentative pour détecter et corriger les échecs d’extraction.
Les exemples few-shot montrent au modèle à quoi ressemble une sortie correcte avant qu’il traite l’entrée réelle. Ils sont particulièrement efficaces pour établir le format de sortie, calibrer le ton et définir le style de traitement propre à chaque entrée. Ils ne peuvent pas imposer des règles métier ni garantir la conformité ; utilisez la validation par schéma pour cela.
Nombre optimal : 2 à 4 exemples. En dessous de 2, le patron est trop faible pour ancrer le comportement. Au-delà de 4, les exemples consomment le budget de contexte sans amélioration proportionnelle, et le modèle risque de faire du pattern-matching trop littéral sur des caractéristiques superficielles.
Format en paires de messages pour l’utilisation d’outils :
Lorsque la tâche implique des appels d’outils, les exemples doivent inclure l’échange complet, pas seulement les entrées utilisateur et les sorties textuelles finales :
messages =[
# Example 1
{"role": "user", "content": "Invoice: Acme Corp, 15 Jan 2025, $4,200.00"},
Le deuxième exemple ci-dessus démontre explicitement la gestion des valeurs null. Sans lui, le modèle peut inventer un nom de fournisseur plutôt que de retourner null pour un champ ambigu.
Calibrage des taux de faux positifs :
Dans les tâches de revue de type CI (analyse de sécurité, contrôle qualité du code, vérifications de conformité), les faux positifs détruisent la confiance plus vite que les faux négatifs. Un ensemble d’exemples few-shot incluant un cas limite qui NE doit PAS déclencher d’alerte enseigne explicitement la frontière :
# In the system prompt or early in the conversation:
CALIBRATION_EXAMPLES="""
Examples of what triggers a HIGH severity flag vs what does not:
Example 1 (HIGH, triggers):
Input: SELECT * FROM users WHERE id = ' + user_input + '
Reason: Direct string concatenation in SQL, classic injection vector.
Example 2 (NOT flagged, near-miss):
Input: query = f"SELECT * FROM users WHERE id = {user_id}"
Reason: f-string with a typed integer variable. No injection risk if user_id is
Reason: Direct shell execution from unsanitized request parameter.
"""
Les exemples de cas limites réduisent les taux de faux positifs en apprenant au modèle où se situe la frontière réelle, et pas seulement à quoi ressemble une violation évidente.
Limites du few-shot :
Les exemples few-shot enseignent le style et le format. Ils ne peuvent pas imposer des contraintes de schéma (utilisez strict: true pour cela), garantir la conformité aux règles métier (utilisez un validateur programmatique), ni remplacer des instructions explicites. Si une règle doit s’appliquer sans exception, formulez-la comme une règle, pas seulement comme un exemple.
La boucle de validation avec nouvelle tentative détecte programmatiquement les échecs d’extraction structurée et renvoie au modèle un retour d’erreur spécifique pour régénération, plutôt que de silencieusement rejeter les mauvaises sorties ou de faire échouer toute la tâche.
f"The extraction has {len(errors)} validation error(s):\n\n"
f"{error_feedback}\n\n"
f"Please correct these specific issues and re-extract."
)
}
])
returnExtractionResult(
success=False,data=None,
error=f"Failed after {max_attempts} attempts: {errors}",
attempts=max_attempts
)
defformat_errors(errors, raw_output):
lines =[]
for err in errors:
lines.append(f"- Field `{err.field}`: {err.message}")
if err.field in raw_output:
lines.append(f" Got: {raw_output[err.field]!r}")
return"\n".join(lines)
Le triple de retour d’information est crucial. Un retour d’information efficace pour la nouvelle tentative comprend (1) l’extrait du document source où le problème s’est produit, (2) le JSON échoué produit par le modèle, et (3) une liste d’erreurs spécifiques par champ. Un retour vague (« veuillez réessayer, il y avait des erreurs ») dégénère en variation aléatoire. Un retour spécifique (« le champ date attendait le format ISO 8601, reçu ‘15th January’ ») résout presque toujours le problème dès la deuxième tentative.
Lorsque les données source sont absentes :
Si le document ne contient genuinement pas le champ requis, une boucle de nouvelle tentative n’aidera pas. Le modèle continuera à halluciner ou à osciller entre null et des valeurs inventées. Condition de sortie : si le même champ échoue deux fois avec des valeurs inventées différentes, marquez-le comme absent_from_source et passez à la suite. Ne gaspillez pas le budget complet de 3 tentatives sur un champ qui n’est pas présent.
Demander à la même instance du modèle qui a généré une sortie de réviser sa propre sortie produit des résultats avec un biais d’auto-préférence de 15 à 30 % : le modèle tend à s’accorder avec lui-même, trouvant le contenu généré « correct » à des taux supérieurs à ce que des réviseurs indépendants constateraient. La fenêtre de contexte partagée entre génération et révision est le vecteur de contamination.
Atténuation : instance de révision indépendante
# Generation pass
generation_response = client.messages.create(
model="claude-opus-4-5",
max_tokens=2048,
messages=[
{"role": "user", "content": f"Analyze this contract:\n\n{contract_text}"}
]
)
analysis = generation_response.content[0].text
# Review pass: fresh conversation, no generation context
review_response = client.messages.create(
model="claude-opus-4-5",
max_tokens=1024,
system="You are a critical reviewer. Identify gaps, errors, and unsupported claims.",
messages=[
{
"role": "user",
"content": (
f"Review this contract analysis for accuracy:\n\n"
f"CONTRACT:\n{contract_text}\n\n"
f"ANALYSIS TO REVIEW:\n{analysis}\n\n"
f"Identify any errors, gaps, or claims not supported by the contract text."
)
}
]
)
L’instance de révision reçoit le document source et l’analyse générée, mais n’a aucun souvenir de l’avoir générée. Cela élimine presque entièrement le biais d’auto-préférence. Utilisez-le pour les extractions à enjeux élevés (juridique, financier, médical), les contenus destinés aux clients où les erreurs nuisent à la confiance, et toute tâche où une hallucination non détectée est inacceptable.
Pour les classifications ambiguës, un champ reasoning dans le schéma de sortie expose la chaîne de preuves qui a produit la classification. Il ne s’agit pas de prompting par chaîne de pensée ; c’est un champ de sortie structuré qui force le modèle à articuler les preuves clés avant de s’engager sur un label.
"description": "The specific evidence from the input that determined this classification"
},
"confidence": {"type": "number"}
}
Lorsque classification: "urgent" et reasoning: "customer explicitly states production outage affecting 10,000 users", un filtre en aval peut vérifier la classification en une seule lecture. Lorsque reasoning est vague ou circulaire (« classifié comme urgent parce que cela semble urgent »), c’est un signal fiable pour escalader vers une révision humaine indépendamment du score de confiance.
2.11 Sorties structurées et conception des schémas {#211-structured-outputs—schema-design}
La conception du schéma détermine quelle part du travail d’extraction revient au modèle et quelle part revient à la validation en aval. Un bon schéma exprime ce que le modèle sait réellement ; un mauvais schéma le force à inventer des valeurs pour des champs qu’il ne trouve pas.
Calibration de la confiance {#confidence-calibration}
Un score de confiance de 0.9 ne signifie rien sans un jeu de validation annoté montrant que les champs auxquels ce modèle attribue 0.9 sont effectivement corrects dans 90% des cas. Des scores de confiance non calibrés donnent une fausse impression d’exactitude.
Le coût d’une erreur varie selon le champ. Un nom de fournisseur incorrect sur une facture est gênant ; un montant total incorrect est une erreur financière. Définissez des seuils de confiance par champ pour orienter les résultats vers une revue humaine lorsqu’ils ne sont pas atteints :
Placez la confiance du modèle sur l’axe horizontal et l’exactitude réelle sur l’axe vertical. Un modèle parfaitement calibré suit la diagonale. Une confiance systématiquement trop élevée produit une courbe sous la diagonale ; une confiance systématiquement trop faible produit une courbe au-dessus. Les deux peuvent être corrigées en ajustant la température ou par une calibration a posteriori (calibration de Platt).
Calibrez sur au moins 200 exemples annotés par champ pour obtenir des tranches statistiquement significatives. En dessous de 100 exemples, les estimations d’exactitude par tranche sont trop bruitées pour guider une action.
2.12 Flux de données et confidentialité {#212-data-flow—privacy}
Important : Tout ce que vous partagez avec Claude Code est envoyé aux serveurs d’Anthropic. Comprendre ce flux de données permet de protéger les informations sensibles.
Ce qui est envoyé à Anthropic {#what-gets-sent-to-anthropic}
2. Ne connectez jamais les bases de données de production aux serveurs MCP. Utilisez les environnements de développement ou de staging avec des données anonymisées.
3. Utilisez des hooks de sécurité pour bloquer la lecture des fichiers sensibles (voir la Section 7.4).
Guide complet : Pour la documentation complète sur la confidentialité, y compris les risques connus, les incidents rapportés par la communauté et les considérations propres aux entreprises, consultez le Guide de confidentialité et de conservation des données.
Temps de lecture : 5 minutes
Objectif : Comprendre l’architecture de base de Claude Code
Cette section résume les mécanismes internes de Claude Code. Pour une analyse technique complète avec des diagrammes et des sources, consultez le Guide d’architecture et de fonctionnement interne.
Le schéma décrit la boucle de base entre modèle et outils, sans inventorier toutes les fonctions actuelles du produit : le mode Auto peut ajouter un classificateur de permissions et les workflows dynamiques coordonner d’autres agents. Le modèle choisit des actions parmi les outils, contrôles de politique et commandes d’exécution exposés par le runtime.
Exécution des outils : Claude Code peut commencer à exécuter les outils marqués comme compatibles avec une exécution concurrente (opérations en lecture seule comme Read, Grep, Glob) alors que le modèle génère encore sa réponse, ce qui réduit la durée totale du tour. Les outils non concurrents (écritures, commandes bash) attendent la fin de la réponse et s’exécutent en série. Lorsque plusieurs outils en lecture seule figurent dans une même réponse, ils s’exécutent en parallèle, avec une limite par défaut de 10 exécutions simultanées.
Système de gestion des tâches {#task-management-system}
TaskCreate : créer une tâche ; utiliser TaskUpdate pour les dépendances et les changements d’état
TaskUpdate : modifier l’état, les métadonnées et les dépendances des tâches
TaskGet : récupérer les détails d’une tâche
TaskList : lister toutes les tâches de la liste courante
TaskOutput a été supprimé dans v2.1.278. Utilisez Read sur le chemin de sortie renvoyé par la tâche en arrière-plan ; ne supposez pas un répertoire fixe.
Fonctionnalités principales :
Stockage persistant : tâches enregistrées dans ~/.claude/tasks/<task-list-id>/
Coordination multisession : partage de l’état entre plusieurs sessions Claude
Suivi des dépendances : les tâches peuvent en bloquer d’autres (la tâche A bloque la tâche B)
Cycle de vie des états : pending → in_progress → completed ; consigner les échecs dans les détails de la tâche sans inventer d’état failed
⚠️ Important : Utilisez des identifiants de listes de tâches propres à chaque dépôt pour éviter de mélanger les projets. Les tâches portant le même identifiant sont partagées entre toutes les sessions qui l’utilisent.
Enregistrement de tâche illustratif (ce n’est pas le schéma complet d’un appel d’outil) :
{
"id": "task-auth-login",
"subject": "Implement login endpoint",
"description": "POST /auth/login with JWT token generation",
Projets répartis sur plusieurs sessions de développement
Hiérarchies de tâches complexes avec dépendances
Scénarios de coordination multi-agent
Besoin de reprendre le travail après une compaction du contexte
⚠️ Limites de Tasks API à prendre en compte
Contrainte de visibilité des champs :
Outil
Champs visibles
Champs masqués
TaskList
id, subject, status, owner, blockedBy
description, activeForm, metadata
TaskGet
Tous les champs
-
Conséquences :
Surcoût des appels multiples : consulter 10 descriptions de tâches nécessite 1 appel TaskList + 10 appels TaskGet (11 fois plus d’appels)
Pas de parcours des métadonnées : impossible de filtrer ou trier par champs personnalisés (priorité, estimations, tags) sans récupérer chaque tâche individuellement
Reprise de session moins directe : impossible de parcourir d’un coup toutes les notes de tâches pour décider où reprendre
Principe de diagnostic : Lorsque la liste de tâches de Claude ne correspond pas à votre intention, le problème se situe dans vos instructions, pas dans Claude.
Les listes de tâches servent de miroir à la clarté des instructions. Si vous demandez à Claude de planifier une fonctionnalité et que les tâches produites vous surprennent, cet écart est une information de diagnostic :
Your instruction: "Refactor the auth system"
Claude's task list:
- [ ] Read all auth-related files
- [ ] Identify code duplication
- [ ] Extract shared utilities
- [ ] Update imports
- [ ] Run tests
Your reaction: "That's not what I meant—I wanted to switch from session to JWT"
Diagnosis: Your instruction was ambiguous. "Refactor" ≠ "replace".
Types d’écarts et ce qu’ils révèlent :
Type d’écart
Signification
Correction
Tâches trop larges
Les instructions manquent de précision
Ajouter QUOI, OÙ, COMMENT, VÉRIFIER
Tâches trop étroites
Les instructions sont trop détaillées, sans vue d’ensemble
Exprimer l’objectif, pas seulement les étapes
Mauvaises priorités
Il manque le contexte sur ce qui compte
Ajouter les contraintes et les priorités
Tâches manquantes
Des connaissances implicites n’ont pas été partagées
Expliciter les hypothèses dans le prompt
Tâches supplémentaires
Claude a déduit des exigences que vous ne souhaitiez pas
Définir explicitement les limites du périmètre
Utiliser les écarts entre les tâches et votre intention dans le workflow :
## Step 1: Seed with loose instruction
User: "Improve the checkout flow"
## Step 2: Review Claude's task list (don't execute yet)
Claude generates: [task list]
## Step 3: Compare against your mental model
- Missing: payment retry logic? → Add to instructions
User: "Actually, here's what I need: [refined instruction with specifics]"
Conseil pratique : Exécutez TaskList après la planification initiale comme contrôle de cohérence avant l’exécution. Si plus de 30% des tâches vous surprennent, votre prompt doit être retravaillé. Itérez sur le prompt, pas sur les tâches.
Le contexte dépend du modèle et du fournisseur : les modèles actuels Opus, Sonnet et Fable ont une fenêtre native de 1M sur l’API directe ; Haiku 4.5 dispose de 200K. Les variantes anciennes suivent leurs propres règles d’accès. Voir la comparaison 200K et 1M. Les tailles suivantes sont illustratives, pas des réservations fixes :
Composant
Taille approximative
Prompt système
5-15K tokens
Fichiers CLAUDE.md
1-10K tokens
Historique de conversation
Variable
Résultats des outils
Variable
Réserve pour la réponse
40-45K tokens
Les sessions natives 1M déclenchent normalement la compaction automatique vers 967K tokens. /autocompact permet une fenêtre plus petite. Une compaction peut perdre une information utile plus tard : enregistrez les décisions et commandes de vérification avant une passation. Utilisez /compact aux transitions logiques ; un pourcentage fixe n’est pas un seuil universel de qualité. Voir Passations de session et Recherche sur l’auto-compaction.
Les équipes d’agents associent un responsable, des coéquipiers travaillant indépendamment, des tâches partagées et une messagerie directe. Activez-les avec CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 et choisissez un modèle disponible pour chaque coéquipier.
L’état des tâches est stocké dans ~/.claude/tasks/<team-name>/, la configuration d’équipe et les boîtes de réception dans ~/.claude/teams/<team-name>/. Le verrouillage des fichiers empêche deux agents de réclamer simultanément une tâche. Il ne fusionne pas les modifications du code et n’empêche pas deux agents de modifier le même fichier.
Attribuez des fichiers distincts ou des worktrees pour les modifications. Demandez au responsable d’arrêter ou de réorienter les coéquipiers lorsque leur périmètre change. L’affichage peut utiliser le même processus ou des volets de terminal ; Shift+Down passe d’un coéquipier à l’autre dans le même processus.
Les anciennes ressources communautaires emploient TeammateTool et des opérations déduites comme spawnTeam. Ce sont des notes historiques d’implémentation, pas l’interface documentée actuelle. Voir Agent Teams et §9.20 pour le fonctionnement et les limites actuels.
Anti-patterns des agents : rôles et contrôle du contexte {#agent-anti-patterns-roles-vs-context-control}
« Les sous-agents ne servent pas à anthropomorphiser des rôles, ils servent à contrôler le contexte », Dex Horty
Erreur fréquente : Créer des agents comme si l’on constituait une équipe humaine avec des intitulés de poste.
❌ Mauvaise approche (anthropomorphisation) :
- Frontend Agent (role: UI developer)
- Backend Agent (role: API engineer)
- QA Agent (role: tester)
- Security Agent (role: security expert)
Pourquoi cela échoue : Les agents ne sont pas des humains dotés de domaines d’expertise. Ce sont des outils d’isolation du contexte destinés à utiliser efficacement les ressources de calcul.
Au-delà des sous-agents génériques, l’orchestration par périmètre attribue des frontières de contexte distinctes aux agents afin de croiser leurs analyses.
Principe : Au lieu de confier toute la revue à un seul agent, lancez des agents aux périmètres isolés, chacun analysant un aspect distinct avec un contexte neuf :
User: Review the new payment service using scope-focused analysis:
Une boucle simple entre modèle et outils constitue un point de départ utile pour comprendre le système. Des modèles plus capables et une orchestration supplémentaire exigent toujours des limites explicites sur les outils et des vérifications.
Utilisez ce modèle simplifié pour repérer les décisions, les résultats d’outils et les échecs. Il ne démontre pas qu’un nombre réduit de composants améliore toujours la fiabilité, ni qu’une action choisie par le modèle est correcte.
Raccourcis globaux → Ajouter dans ~/.claude/CLAUDE.md
Lire cette section si : Vous travaillez sur plusieurs projets ou en équipe
Passer si : Projet unique, développeur solo (peut être configuré au fil de l’eau)
Temps de lecture : 15 minutes
Niveau : Semaine 1
Objectif : Personnaliser Claude Code pour votre projet
Les fichiers CLAUDE.md sont des instructions persistantes lues à chaque démarrage de session. Trois niveaux : ~/.claude/CLAUDE.md (global) → /project/CLAUDE.md (projet) → /project/CLAUDE.local.md (personnel ; ajouter à .gitignore). Les instructions sont combinées ; elles ne disposent pas d’un ordre de priorité garanti comme les paramètres. .claude/CLAUDE.md est un autre emplacement d’instructions de projet partagées.
Minimum viable : nom du projet, description en une phrase, et bloc ## Commands. Claude détecte automatiquement la stack, la structure des répertoires et les conventions. N’ajoutez une ligne que lorsque Claude fait deux fois la même erreur, pas de manière préventive.
Le risque d’ancrage : les entrées CLAUDE.md obsolètes biaisent chaque session vers des patterns dépassés. Traitez la suppression d’entrées comme une tâche de maintenance. Structurez autour du QUOI/POURQUOI/COMMENT pour les projets plus importants.
Couverture complète : Voir Memory Systems: CLAUDE.md pour le diagramme de hiérarchie à trois niveaux, le filtre de découvrabilité, les recherches sur les fichiers de contexte et les pratiques de partage en équipe. Pour les limites expérimentales, voir l’évaluation corrigée de la source.
« Vous ne devriez jamais avoir à corriger Claude deux fois pour la même erreur. »
— Boris Cherny, créateur de Claude Code
Le modèle mental : CLAUDE.md dépasse le simple fichier de configuration, c’est un système d’apprentissage organisationnel où chaque erreur se capitalise en connaissance d’équipe permanente.
Comment ça fonctionne :
Claude fait une erreur (ex. : utilise npm au lieu de pnpm)
Vous ajoutez une règle dans CLAUDE.md : "Always use pnpm, never npm"
Claude lit CLAUDE.md au démarrage de session → ne répète plus l’erreur
La connaissance se capitalise au fil du temps à mesure que l’équipe identifie et documente les cas limites
L’effet de capitalisation :
Semaine 1 : 5 règles → 5 erreurs évitées
Semaine 4 : 20 règles → 20 erreurs évitées
Mois 3 : 50 règles → 50 erreurs évitées + onboarding plus rapide
Exemple concret (équipe de Boris Cherny) :
CLAUDE.md a atteint 2 500 tokens (≈ 500 mots) au fil des mois
Capture les conventions propres au projet, les décisions architecturales et les « pièges »
Les nouveaux membres d’équipe bénéficient instantanément de la connaissance tribale accumulée
Claude s’aligne de plus en plus avec les standards de l’équipe au fil du temps
Anti-pattern : Tout documenter de manière préventive. Traitez plutôt CLAUDE.md comme un document vivant qui évolue à partir des vraies erreurs identifiées pendant le développement.
Aller plus loin : capitaliser les solutions entre les PRs
CLAUDE.md capture des règles comportementales. Pour les problèmes techniques résolus, un pattern complémentaire issu du Compound Engineering d’Every.to : un répertoire docs/solutions/ qui transforme chaque problème non trivial en documentation consultable.
docs/solutions/
├── auth-token-refresh-race-condition.md
├── ios-storekit2-receipt-validation.md
└── kotlin-coroutine-timeout-pattern.md
Chaque fichier documente : le problème, la solution, pourquoi elle fonctionne, et les cas limites. Claude lit ces fichiers lorsque des patterns similaires apparaissent : la troisième fois qu’un problème connexe survient, le correctif est déjà là. La distinction avec CLAUDE.md est intentionnelle : CLAUDE.md contient des règles, docs/solutions/ contient des problèmes résolus avec leur contexte complet.
L’approche Compound Engineering dans son ensemble formalise cette intuition en une boucle en quatre étapes et une philosophie plus large pour les équipes natives à l’IA.
La boucle principale : Plan → Work → Review → Compound
La plupart des équipes sautent la quatrième étape, qui est là où les vrais gains s’accumulent.
Étape
Ce qui se passe
Allocation de temps
Plan
Comprendre le besoin, explorer la codebase et la documentation, concevoir la solution
~40%
Work
L’agent implémente dans une branche/worktree isolée, les validations s’exécutent automatiquement
~10%
Review
Plusieurs agents spécialisés relisent en parallèle (sécurité, performance, architecture, etc.), les résultats sont priorisés P1/P2/P3
~40%
Compound
Documenter ce qui a fonctionné, mettre à jour CLAUDE.md avec les nouveaux patterns, créer des agents pour les tâches de relecture récurrentes
~10%
L’insight critique : 80% du temps de l’ingénieur devrait être consacré à planifier et relire, 20% à implémenter et capitaliser. Livrer de la valeur est le travail, pas écrire du code.
La règle 50/50
Allouez 50% du temps d’ingénierie à la construction de fonctionnalités, 50% à l’amélioration du système (agents de relecture, patterns documentés, générateurs de tests). En ingénierie traditionnelle, les équipes investissent 90/10 sur les fonctionnalités et se retrouvent avec une codebase de plus en plus difficile à travailler chaque année. Le ratio 50/50 rend chaque itération plus rapide que la précédente.
L’échelle d’adoption
Votre position actuelle détermine ce sur quoi vous devriez vous concentrer ensuite, pas ce que quelqu’un d’autre fait à l’étape cinq.
Étape
Description
Déblocage clé
0
Développement manuel
—
1
Assistance par chat (ChatGPT, copier-coller)
Bons prompts, les réutiliser
2
Outils agentiques avec relecture ligne par ligne
CLAUDE.md, apprendre à quoi faire confiance
3
Plan d’abord, relecture uniquement sur PR
S’éloigner pendant l’implémentation, relire le diff
4
De l’idée à la PR (machine unique)
Délégation complète, points de contact minimaux
5
Exécution parallèle en cloud
Flotte d’agents, vous relisez les PRs à leur arrivée
La plupart des développeurs plafonnent à l’étape 2 (approuver chaque action) parce qu’ils ne font pas confiance au résultat. La réponse n’est pas plus de relecture, ce sont de meilleures filets de sécurité : tests, agents de relecture automatisés, git worktrees pour l’isolation.
Croyances clés à adopter
Chaque unité de travail devrait rendre le travail suivant plus facile, pas plus difficile
Le goût appartient aux systèmes (CLAUDE.md, agents, skills), pas à la relecture manuelle
Construisez des filets de sécurité, pas des processus de relecture, la confiance vient d’une infrastructure de vérification, pas du gardiennage
Les plans sont le nouveau code : un plan bien écrit est l’artefact le plus précieux que vous produisez
La parallélisation est le nouveau goulot d’étranglement : la contrainte est désormais la puissance de calcul, pas l’attention
Le plugin (optionnel)
Every a publié un plugin Claude Code qui regroupe l’ensemble de ce système : 26 agents de relecture spécialisés, 23 commandes de workflow, et 13 skills de domaine.
Cela dépose la structure complète docs/brainstorms/, docs/solutions/, docs/plans/, et todos/ dans votre projet, accompagnée de commandes comme /workflows:plan, /workflows:work, /workflows:review, et /workflows:compound.
L’installation du plugin n’est pas requise pour appliquer la philosophie. Le pattern docs/solutions/ et la boucle fonctionnent avec votre configuration Claude Code existante.
Un pattern spécifique du compound-engineering qui fonctionne indépendamment : avant de créer un plan, vérifiez si une réflexion pertinente existe déjà.
L’instruction à ajouter dans CLAUDE.md ou un agent :
Before creating a plan for any feature or problem, check docs/brainstorms/ for existing
thinking on this topic. If a brainstorm exists, use it as input. If not, create a new
brainstorm file before writing the plan.
Le document de brainstorm n’est pas un plan. Il explore l’espace du problème : ce que nous savons, ce que nous ne savons pas, ce que nous avons déjà essayé, quelles contraintes existent. Le plan vient après. La plupart des équipes sautent cette étape et écrivent des plans qui répètent un raisonnement déjà effectué lors d’une session précédente.
La hiérarchie de documentation comme mémoire de projet
La structure de répertoires complète que le plugin établit sépare quatre types distincts de documents que la plupart des projets mélangent :
Répertoire
Contenu
Cycle de vie
CLAUDE.md
Règles et contraintes pour l’IA
Mis à jour rarement, signal fort
docs/brainstorms/
Exploration du problème, questions ouvertes
Créé avant la planification, conservé comme référence
docs/plans/
Plans d’implémentation actifs
Créé à partir des brainstorms, archivé après achèvement
docs/solutions/
Problèmes résolus avec contexte complet
Créé après achèvement, référencé quand des problèmes similaires apparaissent
todos/
Suivi des tâches
Éphémère, remplacé à chaque sprint
CLAUDE.md contient des règles. docs/solutions/ contient des problèmes résolus. docs/brainstorms/ contient de la réflexion. La séparation importe car une IA lisant CLAUDE.md s’attend à des contraintes, pas à un journal de décisions passées. Quand ces éléments se mélangent, l’IA traite les anciennes décisions comme des règles actuelles.
Vous pouvez adopter cette structure de manière incrémentale : commencez par docs/solutions/ (ROI le plus élevé), ajoutez docs/brainstorms/ quand les plans commencent à répéter un raisonnement antérieur, ajoutez le reste quand vous avez un workflow récurrent.
« Ne concevez pas vos workflows autour des limitations du modèle actuel. Construisez pour là où sera la technologie dans six mois. »
— Boris Cherny, Head of Claude Code, Lenny’s Newsletter (19 février 2026)
Le corollaire : chaque investissement que vous faites aujourd’hui dans CLAUDE.md, les skills, les hooks et les workflows se capitalise davantage à mesure que les modèles s’améliorent. Si vous optimisez purement pour les limitations actuelles, vous réécrirez constamment votre configuration. Si vous construisez pour un modèle légèrement plus capable, vos workflows s’exécuteront automatiquement lors de la sortie de la prochaine version.
Implications pratiques :
Écrivez les règles CLAUDE.md comme si Claude comprendrait mieux les nuances, ne sur-spécifiez pas des contraintes qui seront inutiles avec le prochain modèle
Construisez des agents pour des objectifs, pas pour des procédures étape par étape (les modèles s’améliorent en navigation, pas seulement en exécution)
Investissez maintenant dans vos patterns de prompts et vos slash commands, ils vieillissent bien
Au-delà de la capture réactive des erreurs, documentez proactivement les découvertes au cours des sessions de développement. Chaque insight que Claude fait remonter sur votre codebase est une entrée CLAUDE.md potentielle.
Le workflow :
Pendant une session de développement :
Claude découvre : "Ce service utilise une stratégie de retry personnalisée"
→ Immédiatement : Ajouter dans CLAUDE.md sous ## Architecture Decisions
Claude rencontre : "Les tests échouent s'ils sont exécutés dans le mauvais ordre à cause d'un état DB partagé"
→ Immédiatement : Ajouter dans CLAUDE.md sous ## Gotchas
Claude suggère : "Ce pattern est dupliqué dans 3 services"
→ Immédiatement : Ajouter dans CLAUDE.md sous ## Known Technical Debt
Prompt pratique :
User: Before we finish this session, review what we discovered today.
Add any architectural insights, gotchas, or conventions to CLAUDE.md
that would help future sessions (including sessions by other team members).
Ce qu’il faut capturer en session :
Type de découverte
Section CLAUDE.md
Exemple
Convention implicite
## Conventions
« Les services retournent des objets de domaine, jamais des réponses HTTP »
Dépendance non évidente
## Architecture
« UserService dépend de EmailService pour le flux d’inscription »
Piège dans les tests
## Gotchas
« Les tests E2E nécessitent Redis sur le port 6380 (pas le port par défaut) »
Contrainte de performance
## Constraints
« Regrouper les appels API par 50 maximum (limite de l’API externe) »
Raisonnement d’une décision de conception
## Decisions
« Choix de Zod plutôt que Joi pour la validation à l’exécution (tree-shakeable) »
Fréquence : Mettez à jour CLAUDE.md au moins une fois par session où vous apprenez quelque chose de non évident. Au fil du temps, cela construit une base de connaissance qui rivalise avec la documentation d’onboarding.
Recommandation de taille : Maintenez les fichiers CLAUDE.md entre 4 et 8 Ko au total (tous niveaux combinés). Des études de praticiens montrent que les fichiers de contexte dépassant 16 000 tokens dégradent la cohérence du modèle. Incluez les aperçus d’architecture, les conventions clés et les contraintes critiques. Excluez les références API complètes ou les exemples de code extensifs (liez-y à la place). L’équipe Next.js de Vercel a compressé environ 40 Ko de documentation de framework en un index de 8 Ko sans perte de performance dans les évaluations d’agents (Gao, 2026), confirmant la cible de 4-8 Ko.
Imports de fichiers : CLAUDE.md peut importer des fichiers supplémentaires avec la syntaxe @path/to/file (ex. : @README.md, @docs/conventions.md, @~/.claude/my-overrides.md). Les imports sont chargés avec le fichier CLAUDE.md qui les référence ; leur contenu contribue donc à son coût en contexte.
📊 Données empiriques : Anthropic AI Fluency Index (fév. 2026)
Seulement 30 % des utilisateurs de Claude définissent explicitement les termes de collaboration avant de démarrer une session. Ces 30 % produisent des interactions mesurément plus ciblées et efficaces. Un CLAUDE.md bien configuré est l’équivalent structurel de ces 30 % : il définit les attentes, le périmètre et les contraintes une seule fois, afin que chaque session démarre avec le bon contexte déjà chargé.
Les 70 % qui sautent cette étape négocient le périmètre implicitement, requête par requête, un schéma moins efficace et moins fiable.
Claude Code sauvegarde automatiquement le contexte utile entre les sessions sans édition manuelle de CLAUDE.md (v2.1.59+, partagé entre les git worktrees depuis v2.1.63).
Aspect
Détail
Stockage
.claude/memory/MEMORY.md (projet) ou ~/.claude/projects/<path>/memory/MEMORY.md
Limites
200 lignes / 25 Ko (tronqué à la lecture avec avertissement)
Gestion
Commande /memory : voir, éditer, supprimer des entrées
vs CLAUDE.md
CLAUDE.md : conventions d’équipe, versionné. Mémoire auto : contexte personnel, ignoré par git
Couverture complète : Voir Systèmes de mémoire : Mémoire automatique pour le détail des limites, la comparaison CLAUDE.md vs mémoire automatique, et le workflow recommandé.
Auto Dream : consolidation de la mémoire (découverte communautaire)
Sous-agent en arrière-plan qui consolide MEMORY.md entre les sessions : le prompt système indique littéralement « You are performing a dream. » Se déclenche lorsque les deux conditions sont remplies : ≥ 24 heures depuis la dernière exécution ET ≥ 5 sessions écoulées.
Phase
Action
Orienter
Lit le répertoire mémoire et les fichiers de sujets existants
Collecter les signaux
grep ciblé des transcripts de session
Consolider
Fusionne les signaux, convertit les dates relatives, supprime les faits contredits
Élaguer et indexer
Reconstruit MEMORY.md sous la limite de 200 lignes
Déclencher via /memory ou en langage naturel : « consolidate my memory files ». La commande /dream existe dans l’interface mais retourne « Unknown skill » sur la plupart des installations, utilisez plutôt le langage naturel.
Couverture complète : Voir Systèmes de mémoire : Auto Dream pour les conditions de déclenchement, le déroulement en 4 phases, les lacunes de qualité et les implémentations communautaires.
Lorsque vous utilisez plusieurs outils d’IA (Claude Code, CodeRabbit, SonarQube, Copilot…), ils peuvent entrer en conflit si chacun dispose de conventions différentes. La solution : une seule source de vérité pour tous les outils.
Structure recommandée :
/docs/conventions/
├── coding-standards.md # Style, naming, patterns
├── architecture.md # System design decisions
├── testing.md # Test conventions
└── anti-patterns.md # What to avoid
Puis référencer depuis partout :
# In CLAUDE.md
@docs/conventions/coding-standards.md
@docs/conventions/architecture.md
# In .coderabbit.yml
knowledge_base:
code_guidelines:
filePatterns:
- "docs/conventions/*.md"
Pourquoi c’est important : Sans source unique, votre agent local pourrait approuver du code que CodeRabbit signale ensuite, une perte de cycles inutile. Avec des conventions alignées, tous les outils appliquent les mêmes standards.
Claude Code découvre et fusionne automatiquement les fichiers CLAUDE.md dans les hiérarchies de monorepo :
monorepo/
├── CLAUDE.md # Root: org-wide standards
├── packages/
│ ├── api/
│ │ ├── CLAUDE.md # API-specific conventions
│ │ └── src/
│ ├── web/
│ │ ├── CLAUDE.md # Frontend conventions
│ │ └── src/
│ └── shared/
│ └── src/
└── tools/
└── cli/
├── CLAUDE.md # CLI tool specifics
└── src/
Comment ça fonctionne :
Claude lit d’abord le CLAUDE.md racine
Lorsque vous travaillez dans packages/api/, il fusionne le CLAUDE.md racine et celui de l’API
Les fichiers plus spécifiques s’ajoutent au contexte parent (sans le remplacer)
Résolution des conflits : Si la même instruction apparaît dans les deux fichiers, le fichier le plus spécifique (enfant) a la priorité. Les instructions sont fusionnées de manière additive : les règles enfant ne suppriment pas les règles parent, elles remplacent celles qui sont en conflit.
Stack spécifique au package, commandes locales, conventions propres
Exemple de CLAUDE.md racine pour monorepo :
# Acme Monorepo
pnpm workspace. Turborepo for builds.
## Commandes
-`pnpm install` - Installer toutes les dépendances
-`pnpm build` - Compiler tous les paquets
-`pnpm -F @acme/api dev` - Lancer le serveur de développement API
-`pnpm -F @acme/web dev` - Lancer le serveur de développement web
## Règles inter-paquets
- Types partagés dans @acme/shared
- Tous les paquets utilisent ESM
Exemple de CLAUDE.md pour un paquet :
# @acme/api
Backend Express + Prisma.
## Commandes
-`pnpm dev` - Démarrer avec rechargement à chaud
-`pnpm db:migrate` - Lancer les migrations
-`pnpm db:seed` - Insérer des données de test
## Conventions
- Contrôleurs dans /routes
- Logique métier dans /services
- Requêtes Prisma dans /repositories
Sécurité en production : Pour les équipes déployant Claude Code en production, consultez Production Safety Rules pour la stabilité des ports, la sécurité des bases de données et les schémas de verrouillage d’infrastructure.
À mesure que les projets grandissent, tout regrouper dans un seul fichier CLAUDE.md devient ingérable. La communauté a convergé vers une approche modulaire qui sépare l’index du détail, en utilisant les mécanismes natifs de chargement de fichiers de Claude.
Le schéma : CLAUDE.md reste sous 100 lignes et joue le rôle d’index de routage. Les règles spécifiques à chaque domaine résident dans des fichiers .claude/rules/*.md, chargés automatiquement au démarrage de la session. Les skills et workflows résident dans .claude/skills/.
.claude/
├── CLAUDE.md # Index uniquement — moins de 100 lignes
├── rules/
│ ├── testing.md # Conventions de test, seuils de couverture
│ ├── security.md # Invariants de sécurité
│ ├── architecture.md # Décisions de conception, références ADR
│ └── api-conventions.md # Standards API, règles de nommage
└── skills/
├── deploy.md # Workflow de déploiement
└── review.md # Processus de revue de code
Pourquoi ça fonctionne : Claude charge TOUS les fichiers dans .claude/rules/ automatiquement au démarrage de la session (section 3.2). L’index CLAUDE.md reste lisible d’un coup d’œil tandis que l’ensemble complet des règles est toujours actif.
Chargement conditionnel basé sur le chemin : Claude prend en charge le frontmatter dans les fichiers de règles pour restreindre les règles à des répertoires spécifiques. Une règle qui ne s’applique qu’au code de notebooks n’a pas besoin d’être chargée à chaque session :
---
globs: notebooks/**, experiments/**
---
# Conventions Jupyter
Toujours inclure une cellule markdown expliquant l'objectif de l'expérience avant tout code.
Ne jamais utiliser d'état global entre les cellules d'un notebook.
Avertissement : la syntaxe de tableau paths: échoue silencieusement. Le champ paths: documenté avec un tableau YAML (paths:\n - "**/*.ts") ne fonctionne pas en raison d’un bug dans le parseur CSV interne (confirmé dans le ticket GitHub #17204 et 8 signalements en double). Les chaînes entre guillemets sous paths: échouent également silencieusement, conservant les guillemets littéraux dans le glob. Utilisez globs: avec des motifs non quotés séparés par des virgules. Pas de guillemets, pas de syntaxe de tableau.
Les règles sans clé globs: se chargent inconditionnellement. Les règles avec globs: ne se chargent que lorsque Claude travaille avec des fichiers correspondant à ces motifs.
La hiérarchie à 3 niveaux (schéma validé par la communauté) :
-`pnpm dev` — démarrer le serveur de développement
-`pnpm test` — lancer les tests
-`pnpm build` — build de production
## Règles chargées automatiquement
Voir .claude/rules/ pour les conventions spécifiques à chaque domaine :
- testing.md — minimums de couverture, schémas de test
- security.md — règles d'authentification, validation des entrées
- api-conventions.md — nommage REST, format d'erreur
## Contraintes critiques
- Ne jamais modifier les fichiers dans src/generated/ (auto-générés par Prisma)
- Toujours utiliser pnpm, jamais npm ou yarn
Cette séparation maintient l’index d’usage quotidien lisible tout en permettant aux experts de domaine d’enrichir leur périmètre sans encombrer l’index partagé.
Source : Schéma documenté par la communauté Claude Code (joseparreogarcia.substack.com, 2026) ; 78 % des développeurs créent un CLAUDE.md dans les 48h suivant le démarrage avec Claude Code (enquête SFEIR Institute). Le chargement conditionnel basé sur le chemin est une fonctionnalité officielle documentée dans la référence des paramètres Claude Code.
Problème : Sans gestion de versions, perdre votre configuration Claude Code signifie des heures de reconfiguration manuelle pour les agents, skills, hooks et serveurs MCP.
Solution : Versionnez votre configuration avec Git et des schémas .gitignore stratégiques pour les secrets.
.claude/settings.json (paramètres projet, partagés en équipe)
↓ surchargé par
.claude/settings.local.json (spécifique à la machine, personnel)
Règles de précédence :
Global (~/.claude/settings.json) : Appliqué à tous les projets sauf surcharge
Projet (.claude/settings.json) : Configuration d’équipe partagée, committée dans Git
Local (.claude/settings.local.json) : Surcharges spécifiques à la machine, gitignored
Cette hiérarchie permet :
Coordination d’équipe : Partager les hooks/règles dans .claude/settings.json
Flexibilité personnelle : Surcharger les paramètres dans .local.json sans conflits Git
Cohérence multi-machine : Paramètres globaux dans ~/.claude/ synchronisés séparément
Note de compatibilité : Claude Code prend toujours en charge ~/.claude.json pour la rétrocompatibilité, mais ~/.claude/settings.json est l’emplacement recommandé. Les flags CLI (ex. --teammate-mode in-process) ont priorité sur tous les paramètres fichiers.
Votre répertoire ~/.claude/ contient la configuration globale (paramètres, serveurs MCP, historique de session) qui doit être sauvegardée mais contient des secrets.
Approche recommandée (inspirée de Martin Ratinaud, 504 sessions) :
Terminal window
# 1. Créer un dépôt Git pour la config globale
mkdir~/claude-config-backup
cd~/claude-config-backup
gitinit
# 2. Créer des liens symboliques vers les répertoires (pas les fichiers avec secrets)
ln-s~/.claude/agents./agents
ln-s~/.claude/commands./commands
ln-s~/.claude/hooks./hooks
ln-s~/.claude/skills./skills
# 3. Copier le modèle de paramètres (sans secrets)
cp~/.claude/settings.json./settings.template.json
# Remplacer manuellement les secrets par des espaces réservés ${VAR_NAME}
# 4. .gitignore pour les secrets
cat>.gitignore<<EOF
# Ne jamais committer ces fichiers
.env
settings.json # Contient les secrets résolus
mcp.json # Contient les clés API
*.local.json
# Historique de session (volumineux, personnel)
projects/
EOF
# 5. Committer et pousser vers un dépôt privé
gitadd.
gitcommit-m"Initial Claude Code global config backup"
Ce fichier configure les hooks, les permissions, les variables d’environnement, et bien plus. Le fichier .claude/settings.json au niveau du projet est commité dans le dépôt (partagé avec l’équipe). Les clés disponibles incluent : hooks, env, allowedTools, autoApproveTools, dangerouslyAllowedPatterns, teammates, teammateMode, apiKeyHelper, spinnerVerbs, spinnerTipsOverride, plansDirectory, enableAllProjectMcpServers.
Exemple de hooks (usage le plus courant dans .claude/settings.json) :
Deux paramètres permettent de personnaliser le texte qui défile dans le terminal pendant que l’agent travaille (« Analyzing… », « Prestidigitating… », etc.).
spinnerVerbs : remplace ou étend les verbes d’action affichés dans le spinner :
Utilisez "mode": "add" pour étendre la liste par défaut au lieu de la remplacer.
spinnerTipsOverride : personnalise les conseils affichés dans le spinner. Utilisez excludeDefault: true pour supprimer tous les conseils intégrés :
{
"spinnerTipsOverride": {
"tips": ["Try /compact when context is full", "Use --print for CI pipelines"],
"excludeDefault": true
}
}
Ces paramètres se placent dans ~/.claude/settings.json (personnel, non commité) ou .claude/settings.json (partagé avec l’équipe). Aucune valeur fonctionnelle, pure personnalisation de l’expérience utilisateur.
Lecture des chemins de fichiers correspondants (format qualifié par outil)
Edit(*.pem)
Modification des chemins de fichiers correspondants (format qualifié par outil)
Write(*.key)
Écriture des chemins de fichiers correspondants (format qualifié par outil)
Format de refus qualifié par outil : restreindre l’accès aux fichiers par modèle de chemin, pas seulement par nom d’outil :
{
"permissions": {
"deny": [
"Bash(rm -rf *)",
"Bash(terraform destroy *)",
"Read(*.env*)",
"Read(*.pem)",
"Read(*credentials*)",
"Edit(*.env*)",
"Edit(*.key)",
"Write(*.env*)",
"Write(*.key)"
]
}
}
Utilisez directement un motif de chemin pour Read/Edit/Write et un motif de commande pour Bash. Les qualificatifs file_path: et command: sont invalides pour ces champs principaux et sont ignorés avec un avertissement. Voir la syntaxe des règles de permission.
Défense en profondeur : permissions.deny présente une limite connue : l’indexation en arrière-plan peut exposer le contenu de fichiers via les rappels système avant l’application des permissions (GitHub #4160). Conserver les secrets hors du projet réduit leur découverte accidentelle, mais n’empêche pas un shell ou processus MCP autorisé de les lire. Utilisez l’isolation du système d’exploitation et des identifiants aux droits restreints lorsque l’accès doit être empêché.
Pour un contrôle granulaire dans ~/.claude/settings.json ou .claude/settings.json, deux formats sont disponibles.
autoApproveTools (format tableau, plus simple) approuve automatiquement les outils listés sans demande de confirmation.
allowedTools (format objet avec les valeurs true/false) offre un contrôle fin incluant les refus explicites.
Exemple utilisant autoApproveTools dans ~/.claude/settings.json :
{
"allowedTools": [
"Read",
"Grep",
"Glob",
"WebFetch",
"TodoRead",
"TodoWrite",
"Task",
"Bash(git status *)",
"Bash(git diff *)",
"Bash(git log *)",
"Bash(pnpm typecheck *)",
"Bash(pnpm lint *)",
"Bash(pnpm test *)"
]
}
Logique des modèles :
Modèle
Signification
Exemple
Read
Toutes les lectures
Tout fichier
Bash(git status *)
Commande spécifique
git status autorisé
Bash(pnpm *)
Préfixe de commande
pnpm test, pnpm build
Edit
Toutes les modifications
⚠️ Dangereux
Niveaux de permissions progressifs :
Niveau 1 - Débutant (très restrictif) :
{
"autoApproveTools": ["Read", "Grep", "Glob"]
}
Niveau 2 - Intermédiaire :
{
"autoApproveTools": [
"Read", "Grep", "Glob",
"Bash(git *)", "Bash(pnpm *)"
]
}
Niveau 3 - Avancé :
{
"autoApproveTools": [
"Read", "Grep", "Glob", "WebFetch",
"Edit", "Write",
"Bash(git *)", "Bash(pnpm *)", "Bash(npm *)"
]
}
⚠️ N’utilisez jamais --dangerously-skip-permissions
Des témoignages horrifiants issus de r/ClaudeAI incluent :
rm -rf node_modules suivi de rm -rf . (erreur de chemin)
git push --force vers main sans le vouloir
DROP TABLE users dans une migration mal générée
Suppression de fichiers .env contenant des identifiants
Préférez toujours allowedTools granulaire plutôt que de désactiver les permissions entièrement.
Alternative sûre : Pour une exécution autonome, lancez Claude Code dans des sandboxes Docker ou un environnement isolé similaire. Le sandbox devient la frontière de sécurité, rendant --dangerously-skip-permissions sûr à utiliser. Consultez le Guide d’isolation par sandbox pour les instructions de configuration et les alternatives.
Les paramètres et les fichiers d’instructions fonctionnent différemment. Les paramètres gérés et ceux de la ligne de commande priment sur les niveaux local, projet et utilisateur ci-dessous ; les listes de permissions et hooks applicables fusionnent entre portées.
Claude combine les instructions utilisateur et projet applicables. CLAUDE.md ou .claude/CLAUDE.md contient les instructions partagées du projet ; CLAUDE.local.md contient les instructions personnelles du projet. Les fichiers imbriqués deviennent pertinents lorsque Claude travaille dans leur sous-arborescence. Évitez les contradictions plutôt que de compter sur un remplacement déterministe comparable à celui des paramètres.
Les règles sans frontmatter paths se chargent de façon générale. Celles avec paths s’appliquent lorsque les fichiers correspondants sont pertinents. L’exemple ci-dessous suppose des règles sans restriction de chemin :
.claude/rules/
├── code-conventions.md ──┐
├── git-workflow.md ──┼──→ Tous chargés au démarrage de la session
Comprendre à quel moment chaque méthode de mémoire se charge est essentiel pour l’optimisation des tokens :
Méthode
Moment du chargement
Coût en tokens
Cas d’usage
CLAUDE.md
Démarrage de session
Toujours
Contexte principal du projet
.claude/rules/*.md
Au démarrage sans restriction ; fichiers correspondants pour les règles paths
Selon la portée
Conventions générales ou propres aux fichiers
@path/to/file.md dans CLAUDE.md
Au chargement des instructions qui importent
Chargé avec les instructions
Découpage des fichiers d’instructions
.claude/skills/<name>/SKILL.md
Corps complet à l’invocation
Description potentiellement disponible avant
Modèles de workflow et connaissances
Point clé : Limitez les conventions propres aux fichiers avec paths. Gardez les règles générales centrées sur les instructions qui s’appliquent largement. Les skills ne sont déclenchés qu’à l’invocation et peuvent ne pas l’être de manière fiable, une évaluation a montré que les agents n’invoquaient les skills que dans 56 % des cas (Gao, 2026). Ne comptez jamais sur les skills pour des instructions critiques ; utilisez CLAUDE.md ou rules à la place.
Depuis décembre 2025, les règles peuvent cibler des chemins de fichiers spécifiques à l’aide du frontmatter YAML :
---
paths:
- "src/api/**/*.ts"
- "lib/handlers/**/*.ts"
---
# API Endpoint Conventions
These rules only apply when working with API files:
- All endpoints must have OpenAPI documentation
- Use zod for request/response validation
- Include rate limiting middleware
Avertissement : la syntaxe de tableau paths: échoue silencieusement. Le champ paths: documenté avec un tableau YAML est défaillant en raison d’un bug du parseur CSV interne (_9A() reçoit un tableau JS et itère sur les caractères de la valeur stringifiée plutôt que sur les patterns réels). Les chaînes entre guillemets sous paths: présentent le même problème, conservant les guillemets littéraux dans le glob. Ce comportement est confirmé par l’issue GitHub #17204 et 8 rapports en doublon. La solution de contournement consiste à utiliser globs: avec des patterns non mis entre guillemets, séparés par des virgules. Pas de guillemets, pas de tableaux YAML.
Cela permet un chargement progressif du contexte : les règles n’apparaissent que lorsque Claude travaille avec des fichiers correspondants. Exemple concret : Avo a migré un CLAUDE.md de 600 lignes vers ~15 fichiers avec portée par chemin, rapportant des réponses plus précises et une maintenance plus facile entre les domaines. (Björn Jóhannsson)
Fonctionnement du matching :
Les patterns utilisent la syntaxe glob (identique à .gitignore)
Plusieurs règles peuvent correspondre au même fichier (toutes sont chargées)
Les règles sans frontmatter globs: se chargent toujours
Problème : Les fichiers d’instructions pour l’IA (CLAUDE.md, .cursorrules, AGENTS.md) se fragmentent entre développeurs, outils et systèmes d’exploitation, chaque développeur finit par avoir une version légèrement différente, et personne ne sait laquelle est la « bonne ».
Solution : Assemblage de modules basé sur des profils, extraire des modules réutilisables, définir des profils par développeur en YAML, assembler automatiquement le fichier d’instructions final.
Gain mesuré : Réduction de 59 % du contexte en tokens (de ~8 400 à ~3 450 tokens par fichier assemblé). Mesuré sur une équipe de 5 développeurs, stack TypeScript/Node.js.
À utiliser quand : Équipes de 3 développeurs ou plus utilisant plusieurs outils IA (Claude Code, Cursor, Windsurf, etc.)
À ignorer si : Développeur solo ou équipe homogène (même outil, même OS, mêmes règles pour tous).
# DO NOT EDIT - Auto-generated from profile. Edit profile + modules instead.
## Contexte du projet
{{MODULE:core-standards}}
## Workflow Git
{{MODULE:git-workflow}}
{{#if typescript}}
## Règles TypeScript
{{MODULE:typescript-rules}}
{{/if}}
## Environnement
{{MODULE:{{OS}}-paths}}
L’en-tête DO NOT EDIT est important : il empêche les développeurs d’apporter des modifications locales qui seraient écrasées lors de la prochaine assembly.
if (module.endsWith('-paths')) returnmodule.startsWith(profile.os)
if (module==='cursor-rules') return profile.tools.includes('cursor')
returntrue
}
// Run for all profiles
const profiles = ['alice', 'bob', 'carol']
for (const devof profiles) {
const result = assembleInstructions(`profiles/${dev}.yaml`, 'skeleton/claude.md')
writeFileSync(`output/${dev}/CLAUDE.md`, result)
console.log(`Generated CLAUDE.md for ${dev}`)
}
Vous pouvez écrire ceci en Python ou en bash également, la logique est la même : lire le profil, charger les modules, remplacer les placeholders, écrire la sortie.
Testé sur une équipe de 5 développeurs, stack TypeScript/Node.js (Méthode Aristote) :
Métrique
Monolithique
Basé sur profils
Évolution
Taille moyenne de CLAUDE.md
380 lignes
185 lignes
-51%
Coût estimé en tokens
~8 400 tok
~3 450 tok
-59%
Fichiers à maintenir
1 fichier partagé
12 modules + 5 profils
+16 fichiers
Propagation des mises à jour
Copier-coller manuel
Automatique (1 module → tous)
Automatisé
Détection de dérive
Aucune
Vérification CI quotidienne
Automatisé
Estimations de tokens basées sur ~22 tokens/ligne en moyenne. La réduction de 59% provient du fait que chaque développeur ne charge que les modules dont il a réellement besoin, au lieu du fichier monolithique complet avec des sections sans rapport avec sa configuration.
Audit : Listez tout ce qui figure dans votre CLAUDE.md actuel. Étiquetez chaque ligne comme universal (s’applique à tout le monde), conditional (dépend de l’outil/OS/rôle) ou personal (un seul développeur).
Extraction : Déplacez chaque catégorie dans un fichier séparé sous modules/. Un fichier par sujet (ex. : git-workflow.md, typescript-rules.md, macos-paths.md).
Profil : Créez un YAML par développeur, listant les modules dont il a besoin en fonction de ses outils, OS et rôle.
Script : Écrivez un assembler qui lit les profils, injecte les modules dans le squelette et écrit la sortie. Commencez simple, l’exemple ci-dessus est prêt pour la production sur les petites équipes.
CI : Ajoutez un job GitHub Actions quotidien qui régénère toutes les sorties et exécute git diff --exit-code pour détecter les dérives.
Ce pattern a un coût réel. Soyez honnête sur la question de savoir si vous en avez besoin :
Situation
Recommandation
Développeur solo
Pas utile. Un seul CLAUDE.md suffit.
Équipe de 2-3 personnes, mêmes outils
Limite. Utilisez plutôt les règles de priorité de CLAUDE.md (Section 3.4).
Équipe 5+, multi-outils
Ce pattern est rentable.
Instructions qui changent rapidement
Coût de maintenance élevé. Stabilisez vos règles d’abord, puis modularisez.
Projets simples (<3 mois)
Excessif. Utilisez un CLAUDE.md partagé.
Le point d’équilibre se situe approximativement à 3+ développeurs avec 2+ outils d’IA différents. En dessous, la charge de gestion des fichiers dépasse les bénéfices.
Lorsque plusieurs développeurs utilisent Claude Code sur la même base de code, la génération d’IA non déclarée crée un problème de qualité silencieux : du code est mergé sans que personne ne comprenne ce qu’il fait ni pourquoi.
Le pattern (issu d’équipes en production) : rendre la génération par IA visible sans la bloquer.
Seuil de divulgation : si Claude génère plus de ~10 lignes consécutives, l’auteur le déclare dans la PR.
Ajout au template de PR :
## AI Involvement
**What AI did**: [list affected files or sections]
**What I did**: [review, adapted, tested, understood]
**Reviewed**: [yes / no — explain if no]
Pourquoi ça fonctionne :
Force l’auteur à réellement lire et comprendre le code généré avant de merger
Rend la revue de code plus efficace (les reviewers savent ce qu’il faut scruter)
Empêche le « vibe coding » d’accumuler silencieusement de la dette technique
Crée une trace écrite des décisions architecturales
Application progressive : adaptez au niveau de maturité de votre équipe :
Niveau du développeur
Exigence de divulgation
Junior / en intégration
Obligatoire : chaque bloc généré par IA
Intermédiaire
Recommandé : fonctionnalités non triviales
Senior
Optionnel : à sa propre discrétion
Ce que ce n’est PAS :
Pas une interdiction de la génération par IA
Pas un exercice de comptage de lignes
Pas un mécanisme de mise en cause
Anti-pattern : Passer outre la divulgation pour aller plus vite. Le coût caché, c’est que les reviewers approuvent du code que personne ne comprend, s’accumulant sur des mois en zones opaques de la base de code pour toute l’équipe.
Les 3 principes de Boris Cherny pour les équipes IA
Ce sont les principes que Boris Cherny (Head of Claude Code chez Anthropic) partage avec chaque nouveau membre de l’équipe.
— Lenny’s Newsletter, 19 février 2026
1. Sous-doter les projets intentionnellement
Avoir un excellent ingénieur sur un grand problème (plutôt qu’une équipe complète) force une utilisation intensive de l’IA. La contrainte accélère la livraison, elle ne la ralentit pas. Le goulot d’étranglement passe des effectifs à la qualité des prompts et des workflows.
2. Donner aux ingénieurs des tokens illimités d’abord
N’optimisez pas les coûts de tokens tôt. Donnez aux ingénieurs la liberté d’expérimenter au maximum. Les patterns fous et innovants n’émergent que quand personne ne surveille le compteur. Optimisez les coûts après qu’une idée réussie a prouvé sa valeur et doit passer à l’échelle.
3. Encourager les gens à aller plus vite
Le réflexe par défaut avec les outils IA, c’est la prudence : examiner chaque sortie, remettre en question chaque suggestion. Le meilleur réflexe : livrer, valider, itérer. Claude Code est conçu pour des cycles à haute vélocité, pas pour une délibération minutieuse.
Quand appliquer : Équipes de 2+ utilisant Claude Code de façon professionnelle. Les développeurs solo devraient se concentrer sur les deux premiers principes (sous-doter = se traiter comme une équipe d’une personne avec le levier de l’IA ; tokens illimités = ne pas s’autocensurer dans ses expérimentations).
Pour aller plus loin : distribution des standards à l’échelle organisationnelle
La Profile-Based Module Assembly résout le problème de cohérence par développeur. Elle nécessite toujours que votre équipe maintienne les modules manuellement et exécute l’assembler. À partir de 50+ développeurs sur 30+ dépôts, même cela devient une friction.
Des outils comme Packmind poussent le même principe plus loin : définissez les standards une fois dans un playbook central, et distribuez-les automatiquement sous forme de fichiers CLAUDE.md, de slash commands et de skills, à travers les dépôts et les outils IA (Claude Code, Cursor, Copilot, Windsurf). Le playbook peut également ingérer des connaissances à partir des commentaires de revue de PR, des discussions Slack et des rapports d’incidents pour maintenir les standards à jour sans maintenance manuelle.
Quand envisager cela : Équipes de 10+ développeurs, 5+ dépôts, utilisant plus d’un agent de codage IA.
Ajoutez le frontmatter YAML (name, description, tools, model)
Rédigez les instructions
Utilisez : @mon-agent "description de la tâche"
Types d’agents populaires : Auditeur de sécurité, Générateur de tests, Réviseur de code, Concepteur d’API
Lisez cette section si : Vous avez des tâches récurrentes ou avez besoin d’une expertise métier
Ignorez-la si : Toutes vos tâches sont des explorations ponctuelles
Temps de lecture : 20 minutes
Niveau de compétence : Semaine 1-2
Objectif : Créer des assistants IA spécialisés
Tous les champs officiels pris en charge par Claude Code (source) :
Champ
Requis
Description
name
✅
Identifiant en kebab-case
description
✅
Quand activer cet agent (utilisez “PROACTIVELY” pour l’invocation automatique)
model
❌
inherit (par défaut), sonnet, opus, haiku, ou un identifiant de modèle complet disponible
tools
❌
Outils autorisés (séparés par des virgules). Supporte la syntaxe Task(agent_type) pour restreindre les sous-agents pouvant être créés
disallowedTools
❌
Outils à interdire, retirés de la liste héritée ou spécifiée
permissionMode
❌
default, acceptEdits, dontAsk, bypassPermissions, ou plan
maxTurns
❌
Nombre maximum de tours agentiques avant l’arrêt du sous-agent
skills
❌
Skills à précharger dans le contexte de l’agent au démarrage (contenu injecté intégralement, pas seulement disponible)
mcpServers
❌
Serveurs MCP pour ce sous-agent, chaînes de noms de serveurs ou configurations inline
hooks
❌
Hooks de cycle de vie limités à ce sous-agent (PreToolUse, PostToolUse, Stop)
memory
❌
Portée de la mémoire persistante : user, project, ou local
background
❌
true pour toujours exécuter en tâche de fond (par défaut : false)
isolation
❌
worktree pour exécuter dans un worktree git temporaire (nettoyé automatiquement si aucune modification)
color
❌
Couleur de sortie CLI pour une distinction visuelle (ex. : green, magenta)
Portées de la mémoire : choisissez selon l’étendue souhaitée des connaissances :
Portée
Stockage
À utiliser quand
user
~/.claude/agent-memory/<name>/
Apprentissage multi-projets
project
.claude/agent-memory/<name>/
Spécifique au projet, partageable via git
local
.claude/agent-memory-local/<name>/
Spécifique au projet, non commité
La couverture complète de la mémoire des agents (limite d’injection de 200 lignes, structure MEMORY.md, guide de sélection de portée) se trouve dans §4.5 Mémoire des Agents.
Les exemples illustrent les schémas d’utilisation courants
Compatibilité de version notée si dépendant d’un framework
💡 Règle des Trois : Si un agent ne fait pas gagner un temps significatif sur au moins 3 tâches récurrentes, c’est probablement une sur-ingénierie. Commencez par les skills, ne passez aux agents que lorsque la complexité l’exige.
Audit automatisé : Exécutez /audit-agents-skills pour un audit qualité complet de tous les agents, skills et commandes. Évalue chaque fichier sur 16 critères avec une notation pondérée (32 points pour les agents/skills, 20 pour les commandes). Consultez examples/skills/audit-agents-skills/ pour la méthodologie de notation complète.
Les sous-agents peuvent s’exécuter en arrière-plan sans bloquer la session principale. Cela est utile pour les tâches en mode « lancer et oublier » comme l’exécution de tests, le linting ou les notifications.
Mode
Comportement
À utiliser quand
Par défaut
Le parent attend la sortie de l’agent
Besoin du résultat avant de continuer
Arrière-plan
L’agent s’exécute en parallèle, le parent continue
Lancer et oublier (tests, linting, notifications)
Gérer les agents en arrière-plan :
Terminal window
# Lister les agents en cours + overlay de suppression
ctrl+f# Ouvre l'overlay du gestionnaire d'agents
# Annuler uniquement le fil principal (les agents en arrière-plan continuent)
Introduit dans Claude Code v2.1.33 (février 2026), le champ frontmatter memory donne aux sous-agents une connaissance persistante au format markdown qui survit entre les sessions. Avant cela, chaque invocation d’agent démarrait avec une ardoise vierge, indépendamment des exécutions précédentes.
Sans mémoire, un agent de révision de code qui découvre que votre équipe préfère les retours anticipés plutôt que les blocs if imbriqués n’a aucun moyen de conserver cette observation. L’invocation suivante repart de zéro. La mémoire des agents résout ce problème : l’agent écrit ses conclusions dans un fichier structuré, et les invocations futures reprennent là où la dernière s’était arrêtée.
Cela se distingue des autres systèmes de mémoire de Claude Code. Chacun sert un objectif différent :
Système
Écrit par
Lu par
Portée
Persiste
CLAUDE.md
Vous (manuellement)
Claude principal + tous les agents
Projet ou global
Suivi par Git
Mémoire automatique
Claude principal (automatique)
Claude principal uniquement
Par projet et par utilisateur
Ignoré par Git
Mémoire des agents
L’agent lui-même
Cet agent spécifique uniquement
Configurable
Selon la portée
Un agent lit à la fois CLAUDE.md (contexte de projet partagé) et sa propre mémoire (connaissances accumulées spécifiques à l’agent). Les deux couches sont complémentaires.
Choisissez une portée selon l’endroit où la connaissance est utile :
Portée
Emplacement de stockage
Contrôle de version
Idéal pour
user
~/.claude/agent-memory/<agent-name>/
Non
Apprentissage inter-projets : un réviseur de code qui accumule des connaissances sur les patterns dans tous les dépôts
project
.claude/agent-memory/<agent-name>/
Oui (commité)
Connaissances spécifiques au projet que toute l’équipe devrait partager, par ex. les conventions d’API découvertes par un agent de scaffolding
local
.claude/agent-memory-local/<agent-name>/
Non (ignoré par Git)
Connaissances spécifiques au projet qui sont personnelles et ne doivent pas être commitées
Ces portées reflètent la hiérarchie des paramètres (~/.claude/settings.json → .claude/settings.json → .claude/settings.local.json), rendant le modèle mental cohérent dans tout le système.
Activez la mémoire en ajoutant une ligne au frontmatter de l’agent :
---
name: code-reviewer
description: Reviews code for quality, security, and consistency
Au démarrage d’un agent, Claude Code lit les 200 premières lignes de MEMORY.md dans le répertoire mémoire de l’agent et les injecte directement dans le system prompt de l’agent. C’est automatique : aucun appel d’outil explicite n’est nécessaire.
~/.claude/agent-memory/code-reviewer/
├── MEMORY.md ← Les 200 premières lignes injectées au démarrage
├── react-patterns.md ← Fichier thématique, chargé à la demande
└── security-checklist.md ← Fichier thématique, chargé à la demande
Une fois que MEMORY.md dépasse 200 lignes, l’agent devrait déplacer le contenu détaillé dans des fichiers thématiques et conserver MEMORY.md comme un index concis avec des références. L’agent gère cela lui-même : Read, Write et Edit sont automatiquement disponibles pour tout agent avec memory défini.
Implication pratique : structurez MEMORY.md comme un résumé intelligent, pas un journal en ajout seul. Les entrées à fort signal en haut, les fichiers thématiques pour la profondeur.
La mémoire n’est utile que si l’agent la lit et l’écrit de manière cohérente. Un prompting explicite dans le corps de l’agent fait une grande différence :
---
name: api-developer
description: Implement API endpoints following team conventions
tools: Read, Write, Edit, Bash
memory: project
---
Before starting any task, review your memory for relevant conventions and
past decisions. After completing a task, update your memory with new patterns,
architectural decisions, or recurring issues you observed. Keep MEMORY.md
under 200 lines — move detailed notes to topic-specific files.
Ce pattern (skills pour les connaissances statiques de démarrage, mémoire pour les connaissances accumulées dynamiquement) donne aux agents le meilleur des deux mondes. Les skills injectent du matériel de référence soigneusement sélectionné dès la première exécution ; la mémoire transmet ce que l’agent découvre par lui-même.
Périmètre Code Défensif : Catches silencieux, exceptions avalées, fallbacks cachés (contexte : code de gestion des erreurs)
Patterns clés (au-delà du Split Role générique) :
Vérification préalable : git log --oneline -10 | grep "Co-Authored-By: Claude" pour détecter les passes de suivi et éviter de répéter des suggestions
Anti-hallucination : Utiliser Grep/Glob pour vérifier les patterns avant de les recommander (règle d’occurrence : >10 = établi, <3 = non établi)
Réconciliation : Prioriser les patterns existants du projet sur les patterns idéaux, ignorer les suggestions avec une justification documentée
Classification par sévérité : 🔴 À Corriger Impérativement (bloquants) / 🟡 À Corriger (améliorations) / 🟢 Facultatif (nice-to-haves)
Boucle de convergence : Revue → correction → re-revue → répétition (max 3 itérations) jusqu’à ce qu’il ne reste que des améliorations optionnelles
Garde-fous en production :
Lire le contexte complet du fichier (pas seulement les lignes du diff)
Chargement conditionnel du contexte selon le contenu du diff (requêtes DB → vérifier les index, routes API → vérifier le middleware d’auth)
Liste de fichiers protégés à ignorer (package.json, migrations, .env)
Portes qualité : validation tsc && lint avant chaque itération
Source : Final Review de Pat CullenImplémentation : Voir section avancée /review-pr, examples/agents/code-reviewer.md, guide/workflows/iterative-refinement.md (Boucle d’Auto-Correction de Revue)
Le guide liste « les personas d’expertise en jeu de rôle » comme mauvaise raison d’utiliser des agents (voir §3.x, Quand NE PAS utiliser d’agents). Les Agents à Perspective Nommée sont un pattern différent et ne doivent pas être confondus avec ça.
La distinction :
Pattern
Ce que c’est
Problème
Jeu de rôle persona (anti-pattern)
« Tu es un développeur backend senior avec 10 ans d’expérience »
Rôle générique, n’apporte rien de plus qu’un bon prompt
Perspective Nommée
« Revoir depuis la perspective de DHH »
Encode un ensemble spécifique et reconnaissable d’opinions d’ingénierie
Un Agent à Perspective Nommée utilise un nom d’ingénieur bien connu comme prompt compressé. Nommer un agent « DHH » regroupe sans le formuler explicitement : fat models, thin controllers, conventions REST sur la configuration, scepticisme envers l’abstraction prématurée, pragmatisme Rails. Le nom est un raccourci vers un style opinioné distinct, pas un déguisement.
Quand ça fonctionne : Uniquement pour les ingénieurs dont les vues ont été intégrées à l’entraînement de Claude et dont les opinions correspondent à un style stable et reconnaissable. DHH (Rails), Kent Beck (TDD, simplicité), Martin Fowler (refactoring, patterns) sont de bons candidats. Les noms aléatoires ne le sont pas.
Exemple (tiré du plugin compound-engineering de Every.to) :
---
name: dhh-reviewer
description: Review code from DHH's perspective. Prioritize Rails conventions, fat models, thin controllers, pragmatic REST, and skepticism of unnecessary abstraction.
allowed-tools: Read, Grep
---
La valeur de l’agent réside dans la mise en avant d’une perspective cohérente qui pourrait être en désaccord avec votre approche par défaut, et non dans la simulation d’une personne.
Mise en garde : Les Agents à Perspective Nommée peuvent dériver à mesure que l’entraînement de Claude évolue. Traitez le nom comme un raccourci pratique, pas comme une garantie que l’agent suivra les opinions actuelles d’une personne réelle.
Source : Plugin compound-engineering de Every.to (2026)
Un agent qui met à jour ses propres skills après chaque exécution. Au lieu de maintenir manuellement la documentation, l’agent lit l’état actuel de son domaine et réécrit les connaissances injectées en lui-même.
Quand l’utiliser : Agents à longue durée de vie dont le domaine évolue : éditeurs de présentation, clients API suivant les changements de schéma, agents gérant des documents vivants.
Mécanisme central (dans le system prompt de l’agent) :
### Étape N : Auto-Évolution (après chaque exécution)
Après avoir accompli votre tâche principale, mettez à jour vos skills préchargés pour rester synchronisé :
1. Lire l'état actuel de [le domaine que vous avez modifié]
2. Mettre à jour `.claude/skills/<your-skill>/SKILL.md` pour refléter la réalité
3. Consigner ce qui a changé et pourquoi dans une section "## Learnings" de ce fichier agent
Cela évite la dérive des connaissances entre ce que vous savez et ce qui est.
Exemple complet, un agent curateur de présentation qui maintient à jour ses propres connaissances de mise en page et de poids :
---
name: presentation-curator
description: PROACTIVELY use when updating slides, structure, or weights
tools: Read, Write, Edit, Grep, Glob
model: sonnet
color: magenta
skills:
- presentation/slide-structure
- presentation/styling
---
## Étape 5 : Auto-évolution (après chaque exécution)
Lire presentation/index.html et mettre à jour vos skills :
- skill slide-structure : mettre à jour les plages de sections, la table de pondération, le nombre de slides
- skill styling : mettre à jour les patterns CSS si de nouveaux ont été introduits
- Ajouter les nouvelles découvertes dans la section `## Learnings` ci-dessous
## Learnings
_Chaque exécution ajoute des découvertes ici. Les invocations futures démarrent informées._
- Les badges de slides sont injectés en JS : ne jamais les coder en dur dans le HTML.
Pourquoi ça fonctionne : Le frontmatter skills: injecte le contenu des skills au démarrage de l’agent. En réécrivant ces fichiers après chaque exécution, la prochaine invocation de l’agent démarre avec les connaissances à jour. Aucune maintenance humaine requise.
Contraintes clés :
Limiter les mises à jour au strict nécessaire : ne mettre à jour que ce qui a réellement changé
Maintenir un journal ## Learnings pour que l’agent accumule des connaissances au fil des sessions
Associer avec memory: project pour la persistance inter-sessions du contexte général
CC 2.1.3 (janvier 2026) : Les skills et les commandes sont désormais unifiés. .claude/commands/ est fusionné dans .claude/skills/. Les skills disposent de deux modes d’invocation : déclenchement par l’utilisateur (/skill-name, équivalent aux anciennes commandes) et déclenchement par le modèle (chargement automatique par correspondance de description). Pour restreindre un skill à l’invocation utilisateur uniquement, ajouter disable-model-invocation: true à son frontmatter. Les fichiers existants dans .claude/commands/ restent rétrocompatibles, mais tout nouveau développement doit être placé dans .claude/skills/.
Temps de lecture : 20 minutes
Niveau : Semaine 2
Objectif : Créer, tester et gérer des modules de connaissances réutilisables
Cette taxonomie est une aide à la conception, pas une classification officielle de la plateforme. Elle distingue les skills qui compensent une limite du modèle de ceux qui encodent un choix local durable. Cette distinction change la référence de comparaison et le test de retrait.
Tous les skills ne vieillissent pas de la même façon. Le type que vous construisez détermine comment vous l’écrivez, comment vous le testez, et quand le retirer.
Montée en capacité
Préférence encodée
Ce que ça fait
Comble un manque que le modèle de base ne peut pas gérer de façon cohérente
Séquence les capacités existantes selon la méthode spécifique de votre équipe
Exemples
Placement précis de texte PDF, patterns de code personnalisés
Liste de vérification NDA, workflow de mise à jour hebdomadaire
Durabilité
Diminue à mesure que le modèle s’améliore
Reste durable tant que le workflow est pertinent
Signal de retrait
Le modèle réussit l’évaluation sans le skill
Le workflow change ou devient non pertinent
Approche d’évaluation
Test A/B : avec vs. sans le skill
Vérification de fidélité : suit-il correctement la séquence ?
La montée en capacité enseigne à Claude quelque chose qu’il ne sait genuinement pas bien faire seul, pour l’instant. Valeur élevée aujourd’hui, mais génère une dette de maintenance : à mesure que Claude s’améliore, ces skills peuvent devenir redondants. Les évaluations vous le signalent avant qu’un utilisateur ne s’en aperçoive.
La préférence encodée encode la façon spécifique de votre équipe de faire quelque chose que Claude sait déjà faire. Une révision NDA suit les critères de votre équipe juridique, pas une liste générique. Ces skills n’entrent pas en concurrence avec les améliorations du modèle : ils capturent des décisions de workflow qui vous appartiennent, et restent pertinents tant que votre processus le reste.
Implication pratique : Lors de la construction d’un skill de montée en capacité, prévoir du temps pour les évaluations. Lors de la construction d’un skill de préférence encodée, prévoir du temps pour maintenir la description du workflow à jour à mesure que votre processus évolue.
Les commandes personnalisées ont fusionné avec les skills, mais les fichiers existants restent utilisables. Un fichier .claude/commands/deploy.md et un skill .claude/skills/deploy/SKILL.md créent tous deux /deploy. Utilisez le format répertoire de skill pour le nouveau contenu réutilisable : il permet les fichiers complémentaires et les contrôles d’invocation. Réservez disable-model-invocation: true aux workflows manuels ayant des effets de bord.
Concept
Rôle
Invocation
Agent
Outil d’isolation du contexte
Délégation via l’outil Task
Skill
Module de connaissances ou modèle de workflow
/skill-name (utilisateur) ou chargement automatique (modèle)
La correction exige-t-elle un ordre garanti, des tentatives, un artefact obligatoire ou un arrêt strict ?
├─ Oui → Utiliser un HOOK, SCRIPT, JOB CI ou WORKFLOW DYNAMIQUE
│ Garder le jugement dans un skill seulement si le modèle doit interpréter un cas.
│
└─ Non → S'agit-il de connaissances réutilisables ou d'une procédure adaptable ?
├─ Oui → Utiliser un SKILL
│ Invocation manuelle si le moment ou les effets de bord doivent rester sous contrôle utilisateur.
│
└─ Non → Faut-il un contexte isolé ou un travail parallèle ?
├─ Oui → Utiliser un AGENT
│ Exemple : code-reviewer, performance-auditor
│
└─ Non → L'écrire directement dans CLAUDE.md comme instructions
Heuristique de départ, pas règle de la plateforme : placez dans CLAUDE.md le contenu pertinent pour la plupart des sessions, et dans des skills les procédures et références occasionnelles. Mesurez vos propres usages avant de fixer un seuil numérique. Les descriptions visibles des skills consomment déjà du contexte ; leur contenu complet entre dans la conversation lors de l’invocation.
Voir aussi : Comparaison du chargement en mémoire pour les sept mécanismes, dont Hooks, MCP et CLAUDE.md face aux règles. cc-sessions discover applique le seuil de 20 % à votre historique pour aider à identifier les candidats.
Les subagents n’héritent pas des skills automatiquement : c’est une source de confusion fréquente.
Règle
Détails
Les agents intégrés ne peuvent pas utiliser les skills
Les agents Explorer, Plan et Verify n’ont pas accès aux skills
Les subagents personnalisés nécessitent un câblage explicite
Les skills doivent être listés dans le champ skills: du frontmatter de l’agent
Les skills se chargent au démarrage de l’agent
Pas à la demande comme dans la conversation principale : tous les skills listés sont chargés au démarrage
Ne lister que les skills toujours pertinents
Ne pas ajouter un skill à moins qu’il ne s’applique à chaque tâche que le subagent effectue
Frontmatter d’un subagent personnalisé avec des skills (.claude/agents/my-agent.md) :
---
name: frontend-reviewer
description: "Use this agent when reviewing frontend code for accessibility and security"
tools: Bash, Glob, Grep, Read, WebFetch
model: sonnet
skills: accessibility-audit, security-guardian
---
Les skills listés dans skills: doivent exister dans .claude/skills/ (projet) ou ~/.claude/skills/ (personnel). Créer des agents avec des skills via /agents dans Claude Code ou ajouter le champ skills: à un fichier d’agent existant.
Agent A : possède les connaissances sécurité (dupliquées)
Agent B : possède les connaissances sécurité (dupliquées)
Agent C : possède les connaissances sécurité (dupliquées)
Avec un skill maintenu par le projet :
skill security-guardian : source partagée dans le périmètre de ce dépôt et de cette équipe
Agent A : hérite de security-guardian
Agent B : hérite de security-guardian
Agent C : hérite de security-guardian
La duplication diminue seulement dans un périmètre de responsabilité doté d’un mainteneur, d’un circuit de revue et d’hypothèses communes. Un skill public ne crée pas automatiquement ce contrat.
Gouvernance de la responsabilité et de la réutilisation
Dans Un Skill n’est pas une librairie, Frédéric Camblor distingue le partage d’une idée ou d’une implémentation de l’engagement à maintenir ensemble un artefact générique. Les skills encodent souvent un contexte coûteux à reconstruire et peuvent régresser sans échec de compilation.
Choisissez le périmètre avant le canal de distribution :
Sphère
Canal habituel
Attente par défaut
Personnelle
~/.claude/skills/
Adaptation aux habitudes d’une personne, sans promesse de compatibilité
Projet ou équipe
.claude/skills/ commité dans le projet
Contrat local commun avec un responsable nommé et un circuit de revue
Outil ou fournisseur
Plugin ou dépôt maintenu
Support versionné pour les utilisateurs de cet outil
Marketplace ou globale
Registre ou dépôt public
Découverte et inspiration ; l’adoption exige une revue et une évaluation locales
Le partage public peut aboutir à plusieurs décisions valables : utiliser tel quel, forker et spécialiser, extraire un pattern ou rejeter. Une duplication n’est pas forcément du gaspillage si l’alternative est un skill générique rempli de branches pour des contextes incompatibles.
Deux règles s’appliquent simultanément :
Frontière de sécurité : traitez un skill téléchargé comme du code exécutable. Examinez ses instructions, scripts, dépendances et autorisations d’outils avant son invocation.
Frontière de responsabilité : traitez un skill comme un contexte situé. Consignez son périmètre, son responsable, ses hypothèses, sa référence de comparaison et son signal de retrait.
Un catalogue reste donc utile même sans installation : il expose des workflows, garde-fous et patterns de conception qui peuvent inspirer un skill local plus ciblé.
low|medium|high : remplace le niveau d’effort de la session lorsque ce skill est invoqué. Définir low pour les tâches mécaniques (commit, format, scaffold), high pour l’analyse ou le raisonnement architectural.
model
CC uniquement
Modèle à utiliser lors de l’exécution de ce skill : haiku, sonnet, opus, ou un identifiant de modèle complet. Remplace le modèle de la session pour l’exécution de ce skill. Utile pour les skills mécaniques rapides (haiku) ou les skills d’analyse approfondie (opus).
argument-hint
CC uniquement
Placeholder affiché dans le menu des slash commands lorsque le skill accepte $ARGUMENTS. Format : "[--flag] [positional_arg]". Exemple : "[--verbose] [--max N] <branch>".
disable-model-invocation
CC uniquement
true pour rendre le skill uniquement manuel (workflow avec effets de bord). C’est ce qui a remplacé .claude/commands/ : les workflows invocables par l’utilisateur résident désormais dans .claude/skills/ avec ce flag.
context
CC uniquement
fork exécute le skill dans un subagent isolé. Le subagent ne reçoit que les entrées qui lui sont transmises ; seule sa réponse finale retourne dans la conversation principale. Les lectures de fichiers, appels d’outils et raisonnements intermédiaires à l’intérieur du contexte forké n’apparaissent pas dans la fenêtre de contexte parente. Limitation connue : context: fork est ignoré lorsque le skill est invoqué via l’outil Skill dans le code d’un agent. Le comportement fork ne s’active que lorsque le skill est appelé en tant que slash command (ex. /my-skill).
hooks
CC uniquement
Hooks d’événements limités à la durée de vie de ce skill. Même format que les hooks de settings.json. Les hooks sont enregistrés à l’invocation du skill et supprimés en fin de session. Les hooks Stop dans les skills sont automatiquement convertis en SubagentStop. Le champ once: true sur un handler de hook est respecté ici (se déclenche une fois par session puis se supprime) ; il est ignoré dans les fichiers settings.
model par skill : remplace le modèle pour l’exécution de ce skill. Le modèle de session est restauré à la fin du skill.
---
name: quick-format
description: Run Prettier on the current file
model: haiku# Rapide et économique pour les tâches mécaniques
effort: low
allowed-tools: Bash
disable-model-invocation: true
---
hooks dans le frontmatter d’un skill : enregistre des hooks d’événements actifs uniquement pendant l’exécution de ce skill. Les hooks sont nettoyés à la fin de la session.
---
name: secure-ops
description: Perform operations with pre-execution security checks
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "./scripts/security-check.sh"
once: true# Se déclenche une fois par session puis se supprime
---
effort par skill (v2.1.80+) : remplace le niveau d’effort de la session pour une invocation de skill spécifique. Indépendant de effortLevel dans settings.json : la valeur du skill prend la priorité uniquement pendant l’exécution de ce skill, puis revient à la valeur précédente.
---
name: security-audit
description: Deep security analysis with threat modeling
effort: high# Toujours en effort élevé, quel que soit le paramètre de session
allowed-tools: Read Grep Glob Bash
---
---
name: commit
description: Stage and commit changes with conventional format
effort: low# Mécanique — aucun budget de raisonnement nécessaire
allowed-tools: Bash
---
Pourquoi c’est important : L’effort contrôle la profondeur de réflexion, la verbosité des appels d’outils et la profondeur d’analyse, pas seulement les tokens. Un skill low s’exécute plus vite et à moindre coût. Un skill high raisonne plus profondément sans que l’utilisateur ait à ajuster manuellement le paramètre de session. Cela permet une allocation automatique du budget cognitif par type de tâche : ne payer pour le raisonnement que là où il apporte de la valeur.
${CLAUDE_EFFORT} dans le contenu d’un skill (v2.1.120) : le corps d’un skill peut référencer ${CLAUDE_EFFORT} comme variable. Claude le substitue par la chaîne du niveau d’effort courant (low, medium, high, xhigh, max) avant de traiter le skill. Utiliser ceci pour brancher les instructions en fonction de l’effort :
---
name: review-code
effort: medium
---
Review the changed files for correctness.
${if CLAUDE_EFFORT == "high" or CLAUDE_EFFORT == "xhigh"}
Also run a full security audit and check all edge cases.
${end}
Cela permet à un seul skill de servir à la fois les cas d’analyse rapide (low/medium) et approfondie (high/xhigh) sans maintenir deux skills distincts.
Les wildcards dans allowed-tools préapprouvent les commandes correspondantes pour le tour qui invoque le skill :
# Préapprouver un espace de noms de commandes CLI pour cette invocation
allowed-tools: Bash(agent-browser:*)
# Préapprouver les scripts npm
allowed-tools: Bash(npm run *)
# Préapprouver les lectures et les modifications sous docs
allowed-tools: Read Grep Glob Edit(/docs/**)
Cette préapprobation est plus ciblée qu’un accès Bash large, mais ne constitue ni une sandbox ni une liste exclusive d’outils. Les autres outils restent appelables selon les permissions de la session. Utilisez disallowed-tools pour retirer des outils pendant le tour, et les règles de refus du projet pour une restriction persistante. Examinez les autorisations des skills du projet avant d’ouvrir Claude Code dans un dépôt non fiable.
Standard ouvert : Les Agent Skills suivent la spécification agentskills.io, créée par Anthropic et supportée par plus de 35 plateformes (Cursor, VS Code, GitHub Copilot, Codex, Gemini CLI, Goose, Roo Code, OpenHands, Amp, Letta, Junie, etc.). Les skills que vous créez pour Claude Code sont portables. Le champ disable-model-invocation est une extension Claude Code.
Utiliser le CLI officiel skills-ref pour valider votre skill avant publication :
Terminal window
skills-refvalidate./my-skill# Vérifier le frontmatter + les conventions de nommage
skills-refto-prompt./my-skill# Générer le XML <available_skills> pour les prompts d'agents
Au-delà de la validation de spec : Trois outils d’audit complémentaires :
/audit-agents-skills : audit qualité large couvrant agents, skills ET commandes (16 critères, notation pondérée sur 32 points). À utiliser pour la mise en production générale.
/eval-skills : audit ciblé sur les skills avec un moteur d’inférence de niveau d’effort. Découvre tous les skills, infère le niveau effort approprié à partir de l’analyse du contenu, signale les incohérences, et affiche des correctifs de frontmatter prêts à copier-coller. À utiliser lors de l’ajout de champs effort à une bibliothèque existante ou lors de l’audit d’un nouveau projet. Voir examples/skills/eval-skills/.
/eval-rules : audit centré sur les règles avec révision interactive de l’utilité. Résout chaque pattern glob paths: par rapport aux fichiers réels du projet, signale les patterns morts ou trop larges, puis vous demande règle par règle si chaque règle se déclenche encore dans le bon contexte et si son contenu est toujours exact. Peut appliquer des modifications en place selon vos réponses. À utiliser pour l’hygiène périodique des règles ou lorsqu’une règle se déclenche trop souvent ou jamais. Voir examples/skills/eval-rules/.
Avant de publier ou de committer un skill, parcourir cette liste de vérification du contenu. /audit-agents-skills évalue le frontmatter et la structure ; cette liste couvre la couche de contenu que les outils automatisés ne détectent pas.
Liste de vérification (critères d’ingénierie composée de Every.to, adaptés) :
Frontmatter complet : name, description, allowed-tools tous présents et exacts
Section « Quand appliquer » : énonce explicitement les déclencheurs et les anti-déclencheurs (quand NE PAS utiliser)
Méthodologie structurée : étapes numérotées ou séquence de décision claire, pas de paragraphes libres
Aucun TODO ni placeholder : chaque section est complète et actionnable
allowed-tools limité au minimum : si le skill ne lit que des fichiers, ne pas accorder Bash ; s’il effectue des recherches, ne pas accorder Edit
Format de sortie documenté : que produit Claude ? Un exemple ou un modèle est inclus
Pas de AskUserQuestion pour les skills multi-plateformes : les skills invoqués par d’autres agents ne doivent pas bloquer sur des prompts interactifs
Responsabilité unique : un skill, un domaine, pas un fourre-tout qui délègue à des sous-skills
La description est une phrase déclencheur : le champ description doit indiquer à Claude quand activer ce skill, pas ce qu’il fait en interne
Ces neuf critères établissent seulement la préparation structurelle et éditoriale. Avant une utilisation en production ou un partage, testez le déclenchement et la qualité des sorties sur des prompts représentatifs, dans de nouvelles sessions, avec une référence sans skill. Consignez le modèle, la version de Claude Code, les prompts, assertions, nombres d’exécutions et de réussites, coût en tokens et variabilité observée.
Les skills ont un cycle de vie. Les traiter comme des artefacts permanents les laisse vieillir : chaque nom et description visible consomme du contexte, tandis qu’un contenu obsolète invoqué peut orienter le travail dans la mauvaise direction.
Deux modèles définissent quand agir :
DÉTECTER LES RÉGRESSIONS DÉTECTER L'OBSOLESCENCE
───────────────────── ────────────────────────
Le modèle évolue Le modèle s'améliore
↓ ↓
Le skill dérive Le skill passe seul
↓ (sans assistance)
L'eval alerte ↓
(signal précoce) Skill retiré
↓ (plus nécessaire)
Corriger ou retirer
Détecter les régressions : votre skill fonctionnait le mois dernier. Le modèle a été mis à jour. Son comportement a changé. Sans evals, vous le découvrez quand un utilisateur signale un problème. Avec des evals, vous le détectez avant que l’échec n’atteigne qui que ce soit.
Détecter l’obsolescence : vous avez créé un skill d’Augmentation de Capacité pour combler une lacune. Six mois plus tard, Claude gère cette lacune nativement. Lancez l’eval sans le skill : s’il passe, le skill n’est plus nécessaire. Supprimez-le pour réduire la charge de contexte et la maintenance.
Lancer l’eval sans le skill : Claude réussit-il seul ?
Vérifier la date de dernière activation : quand ce skill a-t-il été déclenché pour la dernière fois en pratique ?
Vérifier la précision du workflow : pour les skills de Préférence Encodée, le processus sous-jacent a-t-il changé ?
Examiner l’usage et le coût de contexte : lancer /skill-doctor dans le terminal ; son signal d’inutilisation invite à une revue, pas à une suppression automatique
Désactiver avant de supprimer : désactiver un candidat avec /skills ou skillOverrides, puis comparer des sessions représentatives
Archiver hors des chemins de découverte : conserver le skill dans l’historique Git ou le déplacer hors de .claude/skills/ ; la découverte récursive peut garder une archive interne visible
/skill-doctor signale les skills visibles jamais invoqués et leur coût de contexte. La documentation officielle actuelle exige Claude Code v2.1.252 ou ultérieur. Le rapport exclut les skills intégrés et d’entreprise, dépend de la récupération des feature flags et n’est pas disponible via Remote Control.
Voir aussi : §5.Y Skill Evals, comment lancer des evals pour éclairer les décisions de retrait.
Les évaluations remplacent une impression non étayée par des preuves reproductibles. Elles ne démontrent ni une correction universelle ni l’absence de variabilité du modèle, et ne suffisent pas à rendre un skill prêt pour la production.
Sortie attendue (à quoi ressemble un bon résultat)
↓
Lancer les evals
↓
Réussite ✓ / Échec ✗
↓
Améliorer le skill → Relancer
Définissez des prompts réalistes, des fichiers d’entrée facultatifs et des assertions explicites. Exécutez chaque cas dans un contexte isolé, avec puis sans le skill. La référence sans skill révèle sa valeur ajoutée, au-delà d’une réponse simplement acceptable.
Les résultats indiquent : taux de réussite, temps écoulé, utilisation des tokens par cas de test.
Mode Benchmark : suit les taux de réussite, le temps écoulé et l’utilisation des tokens au fil des mises à jour du modèle. Exécute les tests en parallèle avec des contextes propres et isolés (pas de contamination croisée entre les cas). Utilisez-le pour détecter automatiquement les régressions lors des mises à jour de Claude.
Tests A/B (Agents Comparateurs) : comparaison en aveugle entre deux versions d’un skill, sans révéler laquelle est laquelle. Cela réduit le biais de confirmation, sans transformer un juge LLM en preuve indépendante.
Optimisation du déclenchement (Description Optimizer) : analyse le champ description et propose des améliorations pour réduire les faux positifs (déclenchement injustifié) et les faux négatifs (absence de déclenchement attendu).
└── evals.json # Prompts, fichiers d'entrée et assertions
Le plugin écrit les preuves d’évaluation de chaque exécution dans grading.json et agrège les résultats avec et sans skill dans benchmark.json. Ces rapports sont des artefacts de preuve, pas des éléments de la spécification portable Agent Skills.
Un comportement par test : ne combinez pas plusieurs assertions, les échecs deviennent ambigus
Incluez les cas limites : testez les entrées qui ont rendu le skill nécessaire au départ
Définissez « bon » avec précision : des sorties attendues vagues rendent les jugements d’eval peu fiables
Définissez une règle d’acceptation selon le risque : indiquez le dénominateur, la variabilité et la gravité de chaque assertion en échec, plutôt qu’un pourcentage universel
Séparez déclenchement et sortie : un skill correctement invoqué peut produire un résultat erroné
Utilisez des vérifications indépendantes si possible : des validateurs déterministes et une revue humaine qualifiée renforcent l’évaluation LLM
Objectif : Détecter, analyser et suggérer des design patterns Gang of Four dans des bases de code TypeScript/JavaScript, avec des recommandations adaptées à la stack.
Emplacement : examples/skills/design-patterns/
Fonctionnalités principales :
Détection de 23 design patterns GoF (Créationnels, Structurels, Comportementaux)
Détection adaptée à la stack (React, Angular, NestJS, Vue, Express, RxJS, Redux, ORMs)
Détection de code smells avec suggestions de patterns
Évaluation de la qualité (5 critères : Correction, Testabilité, SRP, Ouvert/Fermé, Documentation)
Préférence pour les alternatives natives à la stack (ex. : React Context plutôt que Singleton)
Structure :
design-patterns/
├── SKILL.md # Instructions principales du skill
├── reference/
│ ├── patterns-index.yaml # Métadonnées des 23 patterns
│ ├── creational.md # 5 patterns créationnels
│ ├── structural.md # 7 patterns structurels
│ └── behavioral.md # 11 patterns comportementaux
├── signatures/
│ ├── stack-patterns.yaml # Détection de stack + alternatives natives
│ ├── detection-rules.yaml # Patterns grep pour la détection
Ce que ce pattern illustre : L’encapsulation MCP avec chargement différé des outils. Les outils MCP de Tally ne sont pas disponibles par défaut : leurs schémas doivent être récupérés via ToolSearch avant tout appel. Ce skill gère cela automatiquement et documente tous les pièges qui provoquent des échecs lors d’appels API à l’aveugle.
Fonctionnalités principales :
Gestion du flux OAuth (authentification → navigateur → URL de callback → finalisation)
Chaînage de blocs avec insertAfterBlockUuid pour préserver l’ordre
Prise en charge du HTML (blocs TEXT oui, labels d’options non)
Mises à jour de texte en lot en un seul appel
Fichier de référence des problèmes connus avec 7 limitations documentées et leurs contournements
Structure :
tally-form-builder/
├── SKILL.md # Workflow complet + règles + anti-patterns
└── references/
├── block-types.md # Tous les types de blocs avec payloads et exemples
└── known-issues.md # 7 limitations avec contournements
Concept central : Outils différés
Les outils MCP de Tally sont différés : les appeler sans ToolSearch au préalable renvoie InputValidationError. Le skill impose une étape ToolSearch obligatoire avant tout appel MCP. Ce pattern s’applique à tout serveur MCP avec des outils différés.
Avant d’explorer des dépôts spécifiques, Context7 propose un outil CLI compagnon (ctx7) qui automatise la découverte et l’installation de skills. Au lieu de cloner manuellement des dépôts, ctx7 skills suggest analyse les dépendances de votre projet et recommande les skills correspondants depuis le registre context7.com/skills, avec des scores de confiance pour évaluer la qualité.
Installation :
Terminal window
npxctx7--help# No install required (npx)
npminstall-gctx7# Global install
Workflow de découverte :
Terminal window
# Auto-detect project deps and suggest matching skills
npxctx7skillssuggest
# Search by keyword
npxctx7skillssearchterraform
# Install from any GitHub repository
npxctx7skillsinstallantonbabenko/terraform-skill
npxctx7skillsinstallowner/repo
# List / remove installed skills
npxctx7skillslist
npxctx7skillsremoveskill-name
Assistant de configuration (remplace la commande manuelle claude mcp add) :
Terminal window
# Configure Context7 for Claude Code — detects editor, picks MCP or CLI+Skills mode
npxctx7setup--claude
ctx7 setup lance un assistant qui configure Context7 dans le bon mode pour votre éditeur. Utilisez-le lors de la première configuration de Context7 plutôt que d’écrire manuellement claude mcp add. Le flag --claude cible Claude Code spécifiquement ; --cursor et --universal sont disponibles pour d’autres éditeurs.
Registre vs. agentskills.io : La spécification agentskills.io est le standard ouvert définissant le format des skills (supporté par 30+ plateformes, voir §5.1). Le registre context7.com/skills est un répertoire hébergé de skills conformes à ce standard. Les deux sont complémentaires : agentskills.io définit le format, context7.com/skills est un endroit pour découvrir et partager des skills conformes. Les skills installés via ctx7 se trouvent dans ~/.claude/skills/ et fonctionnent de façon identique aux skills installés manuellement.
Génération de skills (authentifiée, soumise à des limites de débit) :
10/week
npxctx7skillsgenerate# AI-generated custom skill
La génération est à réserver de préférence aux skills sans équivalent dans le registre. Pour l’intégration d’équipes à grande échelle, le workflow suggest + install est plus pratique que la génération.
Consultation de documentation CLI (alternative au MCP) :
Terminal window
# Search available libraries
npxctx7libraryreact
# Fetch docs for a specific library + query
npxctx7docs/facebook/react"useEffect cleanup"
Il s’agit de l’équivalent en terminal de ce que fait le serveur MCP Context7. Utile quand vous souhaitez consulter quelque chose vous-même sans invoquer Claude, ou dans des environnements où MCP n’est pas configuré. Les utilisateurs de Claude Code qui ont déjà le serveur MCP actif n’en ont pas besoin : Claude s’en charge automatiquement.
La communauté Claude Code a créé des collections de skills spécialisées pour des domaines spécifiques. Une collection notable se concentre sur la cybersécurité et les tests d’intrusion.
Les garde-fous du modèle passent en premier (vérifié le 17 octobre 2026) : le Cyber Verification Program d’Anthropic indique que les modèles en accès général « have conservative cyber safeguards that block most cyber work ». Ils restent utilisables pour la revue de code, la correction de failles connues, la recherche de vulnérabilités dans un code source qui vous appartient et le tri d’alertes de sécurité. Les tests d’intrusion et le red teaming autorisés exigent le niveau Red Team Access, réservé aux organisations. Installer un skill ne modifie pas ces garde-fous. L’éligibilité et le formulaire de candidature figurent sur la même page.
description: Security testing specialist for penetration testing
tools: Read, Grep, Bash
skills:
- sql-injection-testing
---
Le champ skills précharge le contenu complet du skill dans le subagent au démarrage. Il contrôle le préchargement, pas l’accès : le subagent peut toujours invoquer d’autres skills via l’outil Skill, sauf si Skill est retiré de ses outils (référence des subagents).
Remarque : Ces skills en cybersécurité n’ont pas été entièrement testés par les mainteneurs de ce guide. Bien qu’ils semblent bien structurés et complets d’après leur documentation, vous devriez :
Tester rigoureusement avant toute utilisation dans des évaluations de sécurité en production
Vous assurer d’avoir les autorisations appropriées avant de conduire tout test d’intrusion
Examiner et valider les techniques au regard des politiques de sécurité de votre organisation
N’utiliser que dans des contextes légaux avec la permission écrite des propriétaires des systèmes
Contribuer en retour si vous trouvez des problèmes ou des améliorations
Les skills semblent respecter les bonnes pratiques du hacking éthique et incluent les prérequis légaux appropriés, mais comme pour tout outil de sécurité, la vérification est indispensable.
claude-red : Bibliothèque de Skills en Sécurité Offensive
Une alternative plus complète à la collection zebbern ci-dessus. claude-red est une bibliothèque organisée de 58 skills en sécurité offensive couvrant 13 catégories de surfaces d’attaque, conçue pour des engagements red team autorisés, la chasse aux bugs bounty et les audits de sécurité sur vos propres systèmes.
Dépôt : SnailSploit/Claude-Red, 2 786 étoiles au 27/07/2026 (1 200+ auparavant), licence MIT, maintenance active (mise à jour mai 2026).
Catégories : Applications web (16 skills : SQLi, XSS, SSRF, SSTI, XXE, IDOR, RCE, désérialisation, conditions de course, request smuggling, contournement WAF, GraphQL…), Auth & Identité (manipulation JWT, exploitation OAuth), Active Directory, Sans fil (13 skills), Cloud (AWS/Azure/GCP), Mobile (Android/iOS), IoT et embarqué, Infrastructure & Red Team, Développement d’exploits (6 skills), Fuzzing & Recherche de vulnérabilités, OSINT/Reconnaissance, Sécurité IA, et Utilitaires (checklist de triage rapide, reporting).
Chaque skill est un SKILL.md structuré avec frontmatter (nom, description, phrases déclencheuses), méthodologie détaillée, énumération des outils et chemins d’escalade : des orientations opérationnelles de niveau expert, pas des exploits prêts à copier.
Le schéma le plus important avec claude-red est de charger les skills sans les installer de façon permanente. Cela maintient votre répertoire global ~/.claude/skills/ propre.
Option 1, lecture directe en session : Demandez à Claude de lire un fichier skill et d’appliquer sa méthodologie. Le contexte disparaît à la fermeture de la session.
Option 2, --append-system-prompt-file au lancement : ajoutez un ou plusieurs skills au prompt système par défaut, le temps d’une session. Claude Code n’a pas de flag --system-file. Préférez la forme qui ajoute : --system-prompt-file remplace le prompt par défaut, y compris ses consignes d’outils et de sécurité (référence CLI).
Les deux formes ont été vérifiées avec des consignes témoins sur Claude Code 2.1.302 en mode non interactif (-p). Le lancement interactif n’a pas été testé.
Option 3, .claude/skills/ au niveau du projet : Créez des liens symboliques uniquement vers les skills pertinents dans le répertoire .claude/skills/ du dépôt cible, effectuez l’audit, puis supprimez le répertoire. Aucune pollution au-delà des limites du dépôt.
Plutôt que de charger les 58 skills, rédigez un prompt qui associe les skills à votre stack. C’est le schéma le plus efficace : Claude ne lit que les skills pertinents pour votre surface d’attaque et les applique avec votre base de code comme contexte.
Exemple pour une application Next.js + Prisma + Clerk :
You are doing a security audit on this Next.js/tRPC/Prisma/Clerk codebase.
5. Skills/ai/offensive-ai-security/SKILL.md — prompt injection on AI endpoints
Priority vectors: IDOR between user roles, JWT algorithm confusion,
Prisma raw query injection, SSRF via external API integrations.
Codebase: [path to project root]
Start with the fast-checking triage, then dig into IDOR and auth.
Adaptez la liste des skills à votre stack réelle : un projet CLI en Rust chargerait des skills de fuzzing et de développement d’exploits plutôt que des skills web ; une application cartographique avec chargement de tuiles externes prioriserait SSRF et XSS plutôt que SQLi.
À utiliser uniquement sur des systèmes que vous possédez ou pour lesquels vous disposez d’une autorisation écrite explicite pour tester. Le fichier SECURITY.md du dépôt détaille le périmètre : engagements autorisés, programmes de bug bounty, compétitions CTF et recherche interne en sécurité uniquement. Un usage abusif peut violer les législations sur la cybercriminalité (CFAA, Computer Misuse Act).
Une autorisation écrite répond à l’exception de la politique d’usage pour la recherche en sécurité. Elle ne lève pas les garde-fous cyber du modèle, qui dépendent de votre niveau d’accès.
Si vous créez des skills spécialisés pour d’autres domaines (DevOps, data science, ML/IA, etc.), envisagez de les partager avec la communauté via des dépôts similaires ou des pull requests vers des collections existantes.
Dépôt : blader/ClaudeceptionAuteur : Siqi Chen (@blader) | Étoiles : 2 381 (27/07/2026, contre 1k+ auparavant) | Licence : MIT
Contrairement aux dépôts de skills traditionnels, Claudeception est un méta-skill qui génère de nouveaux skills pendant les sessions Claude Code. Il répond à une limitation fondamentale : « Chaque fois que vous utilisez un agent de codage IA, il repart de zéro. »
Un utilisateur a rapporté que Claudeception a auto-généré un skill pre-merge-code-review depuis son workflow réel, transformant une session de débogage ad hoc en un skill réutilisable et déclenché automatiquement.
Ce skill illustre le schéma du skill qui crée des skills, une méta-approche où Claude Code s’améliore lui-même par apprentissage au fil des sessions. Inspiré par des travaux académiques sur les bibliothèques de skills réutilisables (Voyager, CASCADE, SEAgent, Reflexion).
Amélioration automatique de skills : Claude Reflect System
Dépôt : claude-reflect-systemAuteur : Haddock Development | Statut : Projet tiers ; le comportement et la maintenance actuels restent à vérifier
Marketplace : Agent Skills Index
Là où Claudeception crée de nouveaux skills à partir de patterns découverts, Claude Reflect System vise à proposer des modifications de skills existants à partir des retours et corrections observés dans les sessions.
Limite des preuves : la réflexion sur les sessions peut produire des candidats utiles, mais ne valide pas ses propres modifications. Avant installation, examinez une révision précise du dépôt et vérifiez le contrat des hooks, les commandes, les écritures et le retour arrière. Avant d’accepter une modification, relancez des évaluations indépendantes ou des contrôles déterministes contre la version précédente.
Problème : Vous utilisez un skill terraform-validation qui ne détecte pas une mauvaise configuration de sécurité spécifique. Pendant la session, Claude détecte et corrige manuellement le problème.
Exemple de proposition :
Claude a corrigé un schéma non couvert par le skill
Une correction est apparue avec des tests réussis
Le système attribue au candidat un niveau de confiance élevé
+ - Reject: Encryption not set or using AES256 instead of aws:kms
L’utilisateur examine → évalue contre la version précédente → accepte ou rejette le candidat. Une modification réussie ne prouve pas que les sessions futures détecteront toujours ce problème.
Les systèmes auto-améliorants introduisent des risques de sécurité spécifiques. Claude Reflect System inclut des mesures d’atténuation, mais les utilisateurs doivent rester vigilants :
Risque
Description
Atténuation
Responsabilité de l’utilisateur
Empoisonnement des retours
Des entrées adversariales manipulent les propositions d’amélioration
Validation par l’utilisateur, scoring de confiance
Examinez toutes les propositions HIGH confidence, rejetez les modifications suspectes
Empoisonnement de mémoire
Des modifications malveillantes des schémas appris s’accumulent
Sauvegardes Git, validation syntaxique
Auditez périodiquement l’historique des skills via Git log
Injection de prompt
Instructions intégrées dans les transcriptions de session
Assainissement des entrées, isolation des propositions
N’approuvez jamais des propositions contenant des commandes exécutables
Gonflement des skills
Croissance non contrôlée sans curation
Mode /reflect [skill] manuel, curation régulière
Archivez ou fusionnez les améliorations redondantes trimestriellement
UI UX Pro Max est le skill de design le plus populaire dans l’écosystème des assistants de codage IA. Il ajoute un moteur de raisonnement design à Claude Code (et 14 autres assistants), remplaçant l’UI générique générée par IA par des systèmes de design professionnels et adaptés au secteur.
Le moteur fonctionne hors ligne : il effectue une recherche BM25 sur environ 400 règles JSON locales pour recommander des styles, palettes et typographies. Aucun appel LLM externe, aucune dépendance réseau à l’exécution.
Multiplateforme : prend en charge Cursor, Windsurf, Copilot, Gemini CLI et dix autres clients en plus de Claude Code
Signal de qualité
110,8K étoiles et 11,8K forks au 27/07/2026, contre 33,7k et 3,3k dans les trois premiers mois ; la plus forte traction communautaire des skills de design
Maintenance
Active : v2.0→v2.2.1 en dix jours en janvier 2026, mises à jour régulières
Communauté chinoise
Forte adoption : présence sur jimmysong.io et dans les dépôts de benchmark de cet écosystème
Note de sécurité : npm install -g uipro-cli installe globalement un paquet d’une organisation anonyme, « nextlevelbuilder ». Un audit de source en février 2026 a confirmé :
Aucun script preinstall/postinstall dans le paquet npm
Aucun appel réseau dans le moteur Python (search.py, core.py, design_system.py ; bibliothèque standard et CSV/JSON locaux uniquement)
L’option 3, clonage Git manuel, reste le parcours le plus sûr pour examiner les sources avant installation. Le paquet n’a pas fait l’objet d’un audit formel par Anthropic ou les mainteneurs de ce guide.
Skills.sh (Vercel Labs) propose un marketplace centralisé pour découvrir et installer des skills d’agents avec une installation en une seule commande :
Installation : le CLI copie les skills sélectionnés vers l’agent et le périmètre choisis. Confirmez la destination et examinez les fichiers copiés avant invocation.
Agents pris en charge : le catalogue actuel comprend Claude Code, Cursor, Codex, GitHub Copilot, Windsurf, Gemini, Cline et d’autres clients.
Format : SKILL.md standard avec frontmatter YAML. Les champs propres à Claude Code ne se comportent pas nécessairement de la même façon dans un autre client.
Le classement et les nombres d’installations changent continuellement et ne prouvent ni qualité, ni compatibilité, ni maintenance. Consultez le catalogue skills.sh actuel pour découvrir des ressources, puis examinez le dépôt retenu et évaluez le skill dans votre périmètre avant adoption.
Vercel a lancé une analyse de sécurité automatisée sur chaque skill de skills.sh (annonce, 17 fév. 2026), en partenariat avec trois cabinets de sécurité indépendants couvrant plus de 60 000 skills :
Partenaire
Méthode
Performance
Socket
Analyse statique multi-écosystèmes + réduction du bruit par LLM (curl|sh, obfuscation, exfiltration, dépendances suspectes)
95% de précision, 97% de F1
Snyk
Moteur mcp-scan : juges LLM + règles déterministes, détecte les « flux toxiques » entre langage naturel et code exécutable
90-100% de rappel, 0% de faux positifs sur les skills légitimes
Gen (Agent Trust Hub)
Surveillance en temps réel des connexions entrantes/sortantes des agents pour prévenir l’exfiltration de données et l’injection de prompts
Continu
Niveaux de risque affichés sur chaque page de skill et présentés avant l’installation via skills@1.4.0+ :
Niveau
Signification
✅ Sûr
Vérifié selon les meilleures pratiques de sécurité
🟡 Faible risque
Indicateurs de risques mineurs détectés
🔴 Risque élevé
Préoccupations de sécurité significatives
☠️ Critique
Comportement grave ou malveillant, masqué de la recherche
Surveillance continue : les skills sont réévalués à mesure que la détection s’améliore. Si un dépôt devient malveillant après l’installation, sa note se met à jour automatiquement.
Modèle de sécurité : traitez un skill téléchargé comme du code exécutable : il peut contenir des autorisations d’outils, scripts, dépendances et instructions. La note d’une marketplace est un élément de décision, pas un substitut à la revue de la version installée.
Modèle de responsabilité : l’installation ne crée pas de contrat de maintenance partagé. Utilisez tel quel, forkez, extrayez un pattern ou rejetez selon votre contexte et vos preuves d’évaluation.
Statut : Lancé le 21 jan. 2026, audité en sécurité depuis le 17 fév. 2026 (Socket + Snyk + Gen)
Gouvernance : Projet communautaire de Vercel Labs (non officiel Anthropic). Skills contribués par Vercel, Anthropic, Supabase et des membres de la communauté.
Compromis :
✅ Découverte centralisée et classement actualisé
✅ Installation en une commande (vs clonage GitHub manuel)
✅ Utilise le format répertoire Agent Skills
✅ Audit de sécurité automatisé en 3 couches avant installation
✅ Surveillance continue après installation
⚠️ Orienté multi-agents (pas spécifique à Claude Code)
⚠️ Les skills nécessitent une invocation explicite ; les agents ne les invoquent automatiquement qu’environ 56% du temps (Gao, 2026). Pour les instructions critiques, préférez le CLAUDE.md toujours chargé
CC 2.1.3 (janvier 2026) : Les skills et les commandes sont désormais unifiés. .claude/commands/ est fusionné dans .claude/skills/. Les skills ont deux modes d’invocation : déclenché par l’utilisateur (/skill-name, équivalent aux anciennes commandes) et déclenché par le modèle (chargé automatiquement par correspondance de description). Pour restreindre un skill à l’invocation par l’utilisateur uniquement, ajoutez disable-model-invocation: true à son frontmatter. Les fichiers existants dans .claude/commands/ restent rétrocompatibles, mais tout nouveau développement doit se faire dans .claude/skills/.
Temps de lecture : 10 minutes
Niveau : Semaine 1-2
Objectif : Créer des slash commands personnalisées
Les slash commands sont des skills invocables par l’utilisateur. Depuis CC 2.1.3, elles se trouvent dans .claude/skills/ (et non .claude/commands/). La syntaxe d’invocation /nom reste inchangée. Ajoutez disable-model-invocation: true dans le frontmatter d’un skill pour le restreindre à l’usage utilisateur uniquement.
Claude Code fournit environ 100 commandes intégrées. La liste complète par catégorie figure dans le tableau §10.1, et la référence officielle de la version courante se trouve dans la documentation des commandes. Voici celles qui reviennent dans la plupart des sessions.
Commande
Action
/help
Afficher toutes les commandes
/clear
Effacer la conversation
/compact
Résumer le contexte
/status
Afficher les informations de session
/context
Détail du contexte/décompte des tokens avec suggestions d’action
/usage (/cost, /stats)
Coût de session, limites de l’offre et détail par modèle (fusion de /cost et /stats en v2.1.118)
/plan
Passer en mode Plan
/rewind (/checkpoint, /undo)
Revenir à un point de contrôle de la conversation et/ou du code
/resume (/continue)
Reprendre une session avec un sélecteur interactif
/voice
Activer/désactiver la saisie vocale (maintenir Espace pour parler, relâcher pour envoyer)
/recap
Afficher un résumé du contexte lors du retour à une session après une pause
/config
Éditeur de configuration interactif, ou key=value pour définir directement une valeur
/model
Changer de modèle (sonnet/opus/opusplan)
/effort [level]
Choisir la profondeur du thinking : low/medium/high/xhigh/max/ultracode ; sans argument, ouvrir le curseur interactif
/focus
Activer/désactiver la vue focalisée (interface minimaliste, masque les métadonnées)
/tui [fullscreen]
Passer au rendu TUI plein écran sans scintillement
/copy
Sélecteur interactif : copier un bloc de code ou une réponse complète
/loop [interval] [prompt] (/proactive)
Exécuter un prompt à intervalle récurrent
/code-review [level]
Relire le diff pour trouver bugs et améliorations. --fix les applique, ultra lance la revue cloud
/simplify
Relire le code modifié et corriger la sur-ingénierie (ne recherche plus les bugs depuis v2.1.154)
/batch
Modifications à grande échelle via des agents worktree parallèles
/subtask <task>
Confier une tâche annexe à un sous-agent issu d’un fork qui rend compte ici (v2.1.212+)
/insights
Générer un rapport d’analyse d’utilisation
/btw [question]
Question rapide via une superposition éphémère : lecture seule, sans outils, réponse unique, ne pollue pas l’historique principal
/doctor (/checkup)
Vérifier installation, paramètres, hooks, volume de CLAUDE.md, skills inutilisés et serveurs MCP
/skill-doctor
Rapport de skills dans le terminal : coût de contexte visible et skills jamais invoqués ; exclut les skills embarqués et d’entreprise, indisponible via Remote Control (v2.1.252+)
/release-notes
Parcourir le changelog de Claude Code de façon interactive
/fewer-permission-prompts
Analyser les transcriptions et proposer une liste d’outils en lecture seule autorisés (livrée sous le nom /less-permission-prompts en v2.1.111)
/team-onboarding
Générer un guide d’intégration à partir de 30 jours d’historique de sessions
/terminal-setup
Configurer Shift+Enter dans le terminal (VS Code, Cursor, Zed, Alacritty)
/reload-plugins
Recharger les plugins actifs sans redémarrer
/mcp
Afficher le statut des serveurs MCP
/memory
Afficher/modifier les fichiers mémoire
/plugin
Gérer les plugins (installer, lister, mettre à jour)
/keybindings
Modifier les raccourcis clavier (ouvre ~/.claude/keybindings.json)
/setup-bedrock
Assistant de configuration Bedrock interactif
/setup-vertex
Assistant de configuration Vertex AI interactif
/ultrareview
Revue de code parallèle dans le cloud ; alias de /code-review ultra (Pro/Max)
/goal [condition]
Définir une condition d’achèvement. Claude travaille de façon autonome sur plusieurs tours jusqu’à ce que la condition soit remplie, affichant une superposition en direct avec le temps écoulé, le nombre de tours et l’utilisation des tokens. Exemple : /goal all tests pass and build is green (v2.1.139)
/scroll-speed
Curseur interactif pour régler la vitesse de défilement à la molette. Les modifications prennent effet immédiatement avec un aperçu en direct. (v2.1.139)
/btw vous permet de poser une question rapide en marge pendant que Claude travaille, sans interrompre votre flux. Tapez /btw what does this function return? et obtenez une réponse instantanée dans une superposition, la tâche principale continue de s’exécuter sans interruption.
Fonctionnement : Claude génère un agent éphémère temporaire SANS outils disponibles. Il ne peut pas lire de fichiers, exécuter des commandes, ni effectuer d’actions. Il répond une seule fois sur la base du contexte de conversation actuel, puis la superposition se ferme. L’échange n’entre jamais dans l’historique de votre conversation principale.
Contraintes clés :
Lecture seule : pas d’accès aux fichiers, pas de commandes shell
Réponse unique : pas de suivi dans la superposition
Contexte uniquement : répond à partir de ce qui est déjà dans la conversation, pas depuis le disque
« Pleinement conscient du contexte » signifie le contexte de conversation, pas les fichiers du projet
Quand l’utiliser :
Clarification rapide en cours de tâche (« btw what’s the default port for Postgres? »)
Vérification de terminologie sans arrêter le travail
Vérification rapide sur quelque chose que Claude vient de mentionner
Syntaxe : Commencez votre message par btw (minuscules, sans slash) suivi de votre question. Claude Code détecte le préfixe btw et le redirige vers l’agent de superposition éphémère.
Remarque : Cette fonctionnalité (btw-side-question) a été introduite vers la v2.0.73 et stabilisée à la v2.1.23. Si vous rencontrez des problèmes, vérifiez que vous utilisez une version récente.
La bifurcation de session crée une nouvelle session indépendante qui démarre à partir d’un point existant de l’historique. Utilisez-la lorsque vous atteignez un point de décision et souhaitez explorer deux directions sans repartir de zéro.
Deux façons de bifurquer :
Terminal window
# From inside an active session
/branch
# From the CLI when resuming
claude--resume<session-id>--fork-session
/branch a été ajouté en v2.1.77, succédant à /fork. Les deux ont ensuite divergé : depuis v2.1.212, /branch vous place dans la copie, /fork copie la conversation dans une session distincte en arrière-plan qui fonctionne indépendamment, et /subtask confie une tâche annexe à un sous-agent issu d’un fork qui rapporte son résultat dans cette conversation.
Quand bifurquer plutôt que redémarrer :
Vous êtes dans un état fonctionnel et souhaitez explorer un refactoring risqué sans le perdre
Vous souhaitez essayer deux approches différentes du même problème en parallèle
Vous avez trouvé un bon point de contrôle en cours de session et souhaitez en partir pour tester une hypothèse
Après la bifurcation, les deux branches sont indépendantes : les modifications dans l’une n’affectent pas l’autre. Reprenez l’une ou l’autre ultérieurement avec claude --resume et le sélecteur de session interactif.
Conseil : exécutez /rename avant de bifurquer pour pouvoir distinguer les deux branches dans le sélecteur.
/recap fournit un résumé du contexte lorsque vous revenez à une session après une pause. Claude détecte automatiquement l’absence et génère un bref récapitulatif de ce sur quoi on travaillait, des dernières actions effectuées, et de ce qui vient ensuite. Cela rend le retour à une longue session bien moins désorientant, notamment après une nuit ou une compaction de contexte.
Comportement : Le récapitulatif se déclenche automatiquement à la reprise d’une session. Il ne se déclenche pas à la fin d’une session ; le déclencheur est le retour à une session qui était inactive.
Options de configuration :
Méthode
Effet
/config puis rechercher “recap”
Activer/désactiver la fonctionnalité dans l’interface
CLAUDE_CODE_ENABLE_AWAY_SUMMARY=1
Forcer l’activation (utile si la télémétrie est désactivée)
CLAUDE_CODE_ENABLE_AWAY_SUMMARY=0
Désactiver complètement
La fonctionnalité fonctionne même avec la télémétrie désactivée (Bedrock, Vertex, Foundry, DISABLE_TELEMETRY). Vous pouvez également la basculer depuis /config sans toucher aux variables d’environnement.
Historique des versions : Introduite dans la v2.1.108. Étendue aux environnements sans télémétrie dans la v2.1.110. Une régression qui provoquait un déclenchement automatique pendant que l’utilisateur rédigeait encore un message a été corrigée dans la v2.1.113.
/insights analyse votre historique d’utilisation de Claude Code pour générer un rapport complet identifiant les patterns, points de friction et opportunités d’optimisation.
La commande traite vos données de session pour détecter :
Domaines de projet : Regroupe automatiquement votre travail en thématiques (ex. « Développement Frontend », « Outillage CLI », « Documentation ») avec le nombre de sessions
Style d’interaction : Identifie vos patterns de workflow (orienté plan, exploratoire, itératif, supervisory)
Patterns de succès : Met en évidence ce qui fonctionne bien dans votre utilisation (coordination multi-fichiers, approches de débogage, sélection d’outils)
Catégories de friction : Identifie les problèmes récurrents (code bogué, mauvais répertoires, perte de contexte, requêtes mal comprises)
Utilisation des outils : Suit les outils que vous utilisez le plus (Bash, Read, Edit, Grep, etc.) et identifie les opportunités d’optimisation
Comportement multi-claude : Détecte les patterns de sessions parallèles (exécution simultanée de plusieurs instances Claude)
Patterns temporels : Identifie vos plages horaires les plus productives et la distribution des temps de réponse
L’exécution de /insights génère un rapport HTML interactif dans ~/.claude/usage-data/report.html contenant :
Résumé en un coup d’œil :
Ce qui fonctionne : 2-3 phrases sur les patterns réussis
Ce qui fait obstacle : 2-3 phrases sur les principaux points de friction
Gains rapides : 1-2 suggestions d’action (temps de mise en place < 5 minutes)
Workflows ambitieux : 1-2 patterns avancés pour une exploration future
Sections détaillées :
Ce sur quoi vous travaillez : 3-5 domaines de projet auto-détectés avec descriptions
Comment vous utilisez Claude Code : Analyse narrative (2-3 paragraphes) de votre style d’interaction + résumé des patterns clés
Choses impressionnantes que vous avez faites : 3 « grandes réussites », workflows sophistiqués détectés par le système (ex. révisions multi-agents, couches d’automatisation personnalisées)
Là où les choses tournent mal : 3 catégories de friction avec exemples et stratégies d’atténuation
Fonctionnalités CC existantes à essayer :
6+ ajouts CLAUDE.md (pré-formatés, prêts à copier)
3 fonctionnalités avec code de configuration (skills personnalisés, hooks, agents de tâches)
Nouvelles façons d’utiliser Claude Code : 3 patterns d’utilisation avec prompts copiables
À l’horizon : 3 workflows ambitieux avec prompts d’implémentation détaillés (300+ tokens chacun)
Fin amusante : Une anecdote tirée de vos sessions (ex. une intervention mémorable de l’utilisateur ou un pattern remarquable)
Éléments interactifs :
Boutons de copie pour tous les extraits de code et prompts
Cases à cocher pour les ajouts CLAUDE.md (copie en masse)
Graphiques et visualisations (utilisation des outils, types de friction, résultats, distribution par heure de la journée)
« Code bogué nécessitant plusieurs cycles de correction » (22 occurrences) → Suggère des boucles build-check-fix après chaque modification
« Mauvais répertoire avant de commencer le travail » (12 occurrences) → Recommande une confirmation explicite du répertoire de travail dans CLAUDE.md
« Tests insuffisants en conditions réelles » → Propose des protocoles de tests manuels au-delà des vérifications automatisées
« Perte de contexte » → Signale les sessions où la conversation s’est déconnectée de l’objectif initial
Schémas de succès :
« Exécution pilotée par un plan à grande échelle » → Détecte les utilisateurs qui fournissent des plans numérotés et atteignent des taux de complétion de 80 %+
« Boucles de révision et de challenge multi-agents » → Identifie les utilisateurs expérimentés qui lancent des sous-agents pour une révision contradictoire
« Slash commands personnalisées pour les flux de travail récurrents » → Met en évidence les schémas de couche d’automatisation
Suggestions pour CLAUDE.md (exemple) :
## Project directories
Always confirm the correct working directory before starting work:
- Frontend: /path/to/web-app
- Backend: /path/to/api
- Docs: /path/to/documentation
Never assume which project to work in — ask if ambiguous.
Recommandations de fonctionnalités (exemple) :
« Votre friction n°1 est le code bogué (22 occurrences). Un hook pre-commit exécutant des vérifications de build les détecterait avant qu’ils ne s’accumulent. »
« Vous exécutez 73 % de vos messages dans des sessions parallèles (multi-clauding). Envisagez un protocole de coordination de sessions dans CLAUDE.md. »
Flux de travail horizon (exemple) :
Self-Healing Builds With Test-Driven Agents
Implement the following plan step by step. After EVERY file edit,
run the full build command. If the build fails, immediately diagnose
the error, fix it, and rebuild before moving to the next step.
Moteur d’analyse : Utilise Claude Haiku (rapide, économique)
Limite de sessions : Analyse jusqu’à 50 sessions récentes par exécution
Budget de tokens : Maximum 8 192 tokens par passe d’analyse
Emplacement des données : ~/.claude/usage-data/ (sessions stockées en JSONL)
Confidentialité : Toutes les analyses s’exécutent localement ; aucune donnée n’est envoyée à des services externes au-delà de l’utilisation standard de l’API Claude Code
Fonctionnement de /insights (aperçu de l’architecture)
Le pipeline d’analyse traite les données de session en 7 étapes :
Filtrage des sessions : Chargement depuis ~/.claude/projects/, exclusion des sous-sessions d’agents, des sessions avec moins de 2 messages utilisateur, ou d’une durée inférieure à 1 minute
Résumé des transcripts : Découpage des sessions dépassant 30 000 caractères en segments de 25 000 caractères
Extraction de facettes : Utilise Claude Haiku pour classifier les sessions en catégories structurées
Analyse agrégée : Détecte les schémas inter-sessions et les flux de travail récurrents
Résumé exécutif : Génère la synthèse « En un coup d’œil » selon quatre dimensions
Génération du rapport : Produit un HTML interactif avec visualisations et sections narratives
Mise en cache des facettes : Sauvegarde les classifications dans ~/.claude/usage-data/facets/<session-id>.json pour des exécutions ultérieures rapides
Système de classification par facettes :
Le système catégorise les sessions selon ces dimensions :
Objectifs (13 types) :
Débogage/Investigation, Implémentation de fonctionnalité, Correction de bug, Écriture de script/outil, Refactorisation de code, Configuration système, Création de PR/Commit, Analyse de données, Compréhension de codebase, Écriture de tests, Rédaction de documentation, Déploiement/Infrastructure, Cache Warmup
Types de friction (12 catégories) :
Requêtes mal comprises, Mauvaise approche, Code bogué, Actions rejetées par l’utilisateur, Claude bloqué, Arrêt prématuré par l’utilisateur, Mauvais emplacements de fichiers, Sur-ingénierie, Lenteur/verbosité, Échecs d’outils, Requêtes peu claires, Problèmes externes
Niveaux de satisfaction (6) :
Frustré → Insatisfait → Probablement satisfait → Satisfait → Très satisfait → Incertain
Catégories de succès (7) :
Recherche rapide et précise, Modifications de code correctes, Bonnes explications, Aide proactive, Modifications multi-fichiers, Bon débogage, Aucun
Types de sessions (5) :
Tâche unique, Multi-tâches, Raffinement itératif, Exploration, Question rapide
Comprendre ces catégories aide à interpréter votre rapport :
Forte friction « Code bogué » → Envisagez d’implémenter des hooks pre-commit (voir la fonctionnalité Hooks)
Faible satisfaction sur les objectifs « Implémentation de fonctionnalité » → Améliorez la précision de la phase de planification
Schéma « Arrêt prématuré par l’utilisateur » → Peut indiquer que les requêtes manquent de contexte suffisant
Optimisation des performances : Le système de mise en cache garantit que les exécutions suivantes n’analysent que les nouvelles sessions (pas celles déjà classifiées), rendant les exécutions mensuelles régulières rapides même avec un grand historique de sessions.
Ajoutée dans la v2.1.63, /simplify est une slash command intégrée qui examine votre code récemment modifié à la recherche de sur-ingénierie et d’abstractions redondantes, puis corrige les problèmes détectés.
/simplify analyse le code modifié à la recherche de :
Réutilisation : logique dupliquée qui pourrait être extraite
Qualité : schémas qui réduisent la lisibilité ou la maintenabilité
Efficacité : améliorations algorithmiques et structurelles
Elle opère au niveau de l’architecture et de la structure, pas au niveau du formateur ou du linter. /simplify complète des outils comme ESLint ou Prettier sans les remplacer.
Ajoutée dans la v2.1.63, /batch orchestre des modifications à grande échelle d’une codebase en distribuant le travail sur 5 à 30 agents parallèles dans des git worktrees isolés, chacun ouvrant sa propre pull request.
/batch est l’équivalent natif du schéma multi-agents en worktrees parallèles (voir §15). Utilisez-le pour des modifications grandes, répétitives, au niveau des fichiers, qui peuvent être divisées en unités indépendantes : migrations, refactorisations, annotations de types en masse, remplacement de dépendances.
Note : /simplify et /batch sont des slash commands intégrées fournies avec Claude Code v2.1.63+. Aucune configuration requise.
Claude Code propose trois mécanismes distincts pour exécuter des tâches récurrentes. Ils diffèrent par l’endroit où l’exécution se produit, la façon dont la tâche est déclenchée, et si une machine locale doit être allumée.
Les routines s’exécutent sur une infrastructure cloud gérée par Anthropic ou dans un environnement autohébergé par l’organisation ; votre machine peut être éteinte. Chaque exécution clone une nouvelle copie de votre dépôt GitHub. Trois types de déclencheurs peuvent être combinés sur une seule routine.
Limite des événements : Les routines sont des sessions persistantes distinctes. Ce ne sont pas des Monitors locaux ; pour un relais d’événement GitHub, un Monitor WebSocket, les Channels et une passation contrôlée à Codex, voir Ingestion d’événements et délégation sûre.
Aperçu de recherche : le comportement, les limites et la surface d’API peuvent changer.
Accès : Plans Pro, Max, Team et Enterprise.
Limites d’exécutions quotidiennes :
Plan
Exécutions/jour
Pro
5
Max
15
Team / Enterprise
25
Des exécutions supplémentaires sont disponibles avec la facturation activée au-delà du plafond quotidien.
Créer une routine via :
claude.ai/code/routines : interface web
Application Desktop : Nouvelle tâche → Nouvelle tâche distante
/schedule dans le CLI (déclencheur planifié uniquement ; les déclencheurs API et GitHub nécessitent l’interface web)
Fonctionnement de chaque exécution : Anthropic clone votre dépôt, démarre une session Claude avec l’environnement et les connecteurs MCP configurés, exécute la tâche, puis pousse les commits vers une branche préfixée claude/ par défaut.
Contraintes principales :
Pas d’accès aux fichiers locaux (uniquement les fichiers suivis dans le dépôt GitHub)
L’intervalle minimum est de 1 heure pour le déclencheur planifié
Prend en charge les connecteurs MCP : Slack, Linear, Google Drive, et d’autres configurés par routine
Les exécutions apparaissent comme des sessions complètes que vous pouvez inspecter, continuer ou transformer en PR
S’exécute sur une cadence cron récurrente. Quatre préréglages (toutes les heures / quotidiennement / jours de semaine / hebdomadairement), plus des expressions personnalisées définies via /schedule update dans le CLI.
Terminal window
/schedule"every Monday at 9am, open a PR summarizing last week's merged PRs"
/schedule"every night at 2am, pull the top bug from Linear and open a draft fix PR"
/schedule"every Friday, scan merged PRs for docs drift and open update PRs"
Chaque routine obtient un point de terminaison HTTP dédié. Envoyez-y une requête POST depuis n’importe quel système externe (outils d’alerte, pipelines de déploiement, scripts CI) et Claude ouvre une nouvelle session autonome.
-d'{"text": "Sentry alert SEN-4521 fired in prod. Stack trace attached."}'
Le champ text optionnel transmet un contexte spécifique à l’exécution (corps d’alerte, ID de déploiement, extrait de log) au prompt de la routine. La réponse retourne une session_url pour observer l’exécution en direct.
Configuration : ajoutez un déclencheur API depuis la page d’édition de la routine dans l’interface web, cliquez sur Générer un token (affiché une seule fois, conservez-le immédiatement), copiez l’URL du point de terminaison. Les tokens sont par routine et peuvent être régénérés ou révoqués depuis le même panneau.
Cas d’usage : Une alerte Datadog se déclenche → Claude corrèle la trace avec les commits récents, ouvre un PR de correction en brouillon ; le pipeline CD appelle le point de terminaison après un déploiement → vérifications de fumée + go/no-go vers le canal Slack.
Déclenche une nouvelle session automatiquement sur les événements de dépôt GitHub correspondants. Nécessite d’installer l’application GitHub Claude sur le dépôt cible (distincte de /web-setup).
17 types d’événements pris en charge : pull request, push, issues, releases, check run, check suite, workflow run, workflow job, workflow dispatch, repository dispatch, pull request review, commentaire de révision de PR, commentaire d’issue, discussion, commentaire de discussion, commentaire de commit, entrée de file de fusion.
Filtres PR : affiner par auteur, titre, corps, branche base/head, labels, état brouillon, état de fusion ou origine fork. Toutes les conditions doivent correspondre.
# Exemples de combinaisons de filtres
PR ouverte depuis un fork → routine de révision de sécurité
Toute PR fusionnée modifiant /sdk/python/ → routine auto-portage vers le SDK Go
PR ouverte, pas en brouillon → routine liste de contrôle de révision d'équipe
Important : chaque événement correspondant ouvre sa propre session indépendante. Deux PR ouvertes = deux sessions. Il n’y a pas de réutilisation de session entre les événements.
Un bon candidat pour une Routine possède trois propriétés : il exécute la même logique à chaque fois (ou réagit à un événement bien défini), la sortie est concrète (PR ouverte, message posté, fichier mis à jour), et aucun humain n’a besoin d’être dans la boucle pendant l’exécution.
Cinq angles pour auditer n’importe quel projet :
Angle
Questions à poser
Maintenance planifiée
Que faites-vous manuellement selon un calendrier et oubliez parfois ? Audits de dépendances, triage des PR obsolètes, dérive de couverture, rapports de code mort
Réactions aux événements
Que devrait-il se passer à chaque ouverture ou fusion de PR mais ne se passe pas parce que personne n’y arrive ? Listes de contrôle de révision, mises à jour du changelog, synchronisation inter-dépôts
Réponse aux alertes
Quand la surveillance se déclenche, quelle est la première chose qu’un développeur fait ? Cette étape pourrait-elle s’exécuter automatiquement avant que l’humain ne regarde ?
Synchronisation inter-systèmes
Qu’est-ce qui dérive parce que la synchronisation est manuelle ? Deux SDK, un site de documentation et une API, des issues GitHub et Linear
Automatisation des releases
Que faites-vous à la main avant ou après un déploiement ? Tests de fumée, notes de version, notifications aux parties prenantes
Utilisez la commande /routines-discover pour exécuter cette analyse sur n’importe quelle codebase, elle lit le dépôt, identifie des candidats concrets selon les cinq angles et les classe par ratio valeur/effort.
Les tâches Desktop s’exécutent sur votre machine locale via l’application Claude Code Desktop. Votre machine doit être allumée, mais vous n’avez pas besoin d’une session terminal active.
Contrairement aux tâches cloud, les tâches Desktop ont un accès complet aux fichiers locaux et à votre configuration MCP existante. L’intervalle minimum est de 1 minute.
Créer une tâche : ouvrez l’application Desktop, allez dans la page Planification, cliquez sur Nouvelle tâche. Vous pouvez également créer une tâche distante (cloud) depuis la même page en sélectionnant Nouvelle tâche distante.
Fonctionnement de chaque exécution : Une nouvelle instance Claude démarre, lit vos fichiers de projet, exécute le prompt de la tâche, puis s’arrête. Les exécutions manquées (machine éteinte) sont mises en file d’attente et exécutées à la réouverture de l’application.
Pour un contrôle total sans l’application Desktop, connectez le cron système directement avec le flag headless de Claude :
Terminal window
# crontab -e
08**1-5bash-c'source /home/user/.env && cd /your/repo && claude --print "summarize git changes since yesterday" >> /var/log/claude-daily.log 2>&1'
Cette approche s’exécute entièrement sans aucune infrastructure Anthropic et n’a pas d’intervalle minimum. Trois points à respecter : utilisez le chemin complet vers claude (vérifiez avec which claude), chargez votre ANTHROPIC_API_KEY depuis un fichier plutôt que de la coder en dur, et redirigez stdout et stderr vers un fichier log pour garder un enregistrement de chaque exécution.
/loop [intervalle] [prompt] planifie un travail récurrent dans la session courante. Avec un intervalle, la cadence est fixe. Sans intervalle, Claude choisit le délai entre les itérations. L’intervalle déclenche une exécution ; il ne constitue pas une condition de fin.
Terminal window
/loop5mcheckthedeploy
/loop30m/slack-feedback
/loop1h/pr-pruner
Fonctionnement : Les prompts planifiés s’exécutent entre les tours, lorsque Claude est disponible. Un intervalle fixe devient une planification cron à la minute, avec un décalage possible. Sans intervalle, Claude choisit un délai entre une minute et une heure selon le travail observé. /loop seul utilise le prompt de maintenance intégré, ou .claude/loop.md s’il existe, puis ~/.claude/loop.md comme défaut utilisateur. Sur les fournisseurs tiers ou lorsque la récupération des feature flags est désactivée, les intervalles dynamiques et le prompt par défaut nécessitent la v2.1.248 ou ultérieure ; les anciennes versions dans ces configurations utilisent dix minutes lorsqu’un prompt n’a pas d’intervalle.
Frontière d’invocation : Un prompt planifié peut appeler un skill que Claude est autorisé à invoquer, par exemple un skill /review-pr configuré. Les commandes intégrées et les skills avec disable-model-invocation: true sont transmis comme texte sans être exécutés. Ne supposez pas qu’imbriquer /goal dans un prompt /loop active un objectif. La conception du triage borné distingue le workflow proposé d’une composition de commandes testée.
Arrêt et reprise : Demandez à Claude de lister ou d’annuler les tâches ; les outils sous-jacents sont CronList et CronDelete. Pour une boucle à cadence dynamique en attente, Esc annule le prochain réveil ; Claude peut aussi arrêter cette boucle lorsque la tâche est terminée. Les tâches à intervalle fixe continuent jusqu’à annulation ou expiration. Une nouvelle conversation arrête les tâches de la précédente ; --resume ou --continue restaure les tâches non expirées. Fermer le processus empêche les exécutions jusqu’à sa reprise.
Cas d’usage de Boris Cherny (créateur de Claude Code) :
Boucle
Ce qu’elle fait
/loop 5m /babysit
Gère automatiquement la révision de code, le rebase, et fait avancer les PR
/loop 30m /slack-feedback
Poste des PR pour les retours de l’équipe toutes les 30 min
/loop 1h /pr-pruner
Nettoie les PR obsolètes selon un calendrier
Contraintes : Les tâches récurrentes expirent sept jours après leur création, y compris le temps passé hors de la session. Une session peut contenir jusqu’à 50 tâches planifiées. Utilisez les Routines ou les tâches Desktop pour une planification indépendante d’une conversation. Source : Run prompts on a schedule, vérifiée le 10 septembre 2026.
/loop ajouté dans la v2.1.71. Marqueurs d’horodatage dans les transcripts de boucle ajoutés dans la v2.1.86. Les tâches planifiées Cloud et Desktop ont été lancées le 9 mars 2026. Source : code.claude.com/docs/en/whats-new
Skills invocables par l’utilisateur (anciennement « Commandes personnalisées »)
Ajoutez disable-model-invocation: true au frontmatter pour empêcher le modèle de charger automatiquement le skill quand il n’est pas explicitement invoqué.
Vous avez reçu les arguments suivants : $ARGUMENTS[0] $ARGUMENTS[1] $ARGUMENTS[2]
(Ou utilisez la forme abrégée : $0 $1 $2)
Traitez-les en conséquence.
Utilisation :
/tech:deploy production
$ARGUMENTS[0] (ou $0) devient production.
⚠️ Changement Incompatible (v2.1.19) : La syntaxe des arguments a changé de la notation pointée ($ARGUMENTS.0) vers la notation entre crochets ($ARGUMENTS[0]). Si vous avez des commandes personnalisées existantes utilisant l’ancienne syntaxe, mettez-les à jour :
Terminal window
# Ancienne syntaxe (< v2.1.19) :
$ARGUMENTS.0 $ARGUMENTS.1
# Nouvelle syntaxe (v2.1.19+) :
$ARGUMENTS[0] $ARGUMENTS[1]
# Ou utilisez la forme abrégée :
$0$1
Associez $ARGUMENTS à argument-hint pour que les utilisateurs voient les options disponibles dans le sélecteur de commandes. L’indication apparaît comme texte de substitution lors de la saisie de la commande :
---
description: Déployer vers un environnement cible
argument-hint: "<env> [--skip-tests] [--dry-run]"
---
Déployer vers l'environnement $ARGUMENTS[0].
Quand l’utilisateur tape /deploy, le menu affiche : /deploy <env> [--skip-tests] [--dry-run]
Le modèle standard ci-dessus fonctionne bien pour les commandes de workflow. Pour les commandes présentant un risque procédural (flux de déploiement, migrations de données, opérations irréversibles), ajoutez une section « Points de Contrôle de Validation du Contexte » avant les étapes :
## Points de Contrôle de Validation du Contexte
Avant d'exécuter toute étape, vérifiez que tous ces éléments sont vrais.
Si un point de contrôle échoue, arrêtez-vous et expliquez pourquoi.
* [ ] La branche cible existe et est à jour avec main
* [ ] Aucune modification non validée dans les fichiers concernés
* [ ] Le fichier de configuration requis existe au chemin X
* [ ] Les identifiants ou permissions sont disponibles
La liste de contrôle impose une vérification explicite des préconditions plutôt que de laisser Claude découvrir les échecs en cours d’exécution. Un point de contrôle échoué produit une erreur claire avec une raison corrigeable ; un échec en milieu d’étape produit un état partiel plus difficile à récupérer.
Modèle prêt à l’emploi disponible dans examples/commands/recipe-template.md de ce dépôt.
Ce que sont les hooks : Des scripts qui s’exécutent automatiquement lors d’événements (comme les git hooks)
Types d’événements :
PreToolUse → Avant que Claude n’exécute un outil (ex. : bloquer des commandes dangereuses)
PostToolUse → Après qu’un outil s’est exécuté (ex. : formater automatiquement le code)
UserPromptSubmit → Quand vous envoyez un message (ex. : injecter du contexte)
Cas d’usage courants :
🛡️ Sécurité : Bloquer les suppressions de fichiers, empêcher les secrets dans les commits
🎨 Qualité : Formatage automatique, lint, exécution de tests
📊 Journalisation : Suivre les commandes, auditer les modifications
Démarrage rapide : Consultez 7.3 Modèles de hooks pour des exemples prêts à l’emploi
Lisez cette section si : Vous souhaitez de l’automatisation ou avez besoin de garde-fous de sécurité
Ignorez-la si : Le contrôle manuel suffit pour votre flux de travail
Temps de lecture : 20 minutes
Niveau de compétence : Semaine 2-3
Objectif : Automatiser Claude Code avec des scripts pilotés par événements
Cycle de vie (événements au niveau de la session) :
Événement
Quand il se déclenche
Peut bloquer ?
Cas d’usage
SessionStart
La session commence ou reprend
Non
Initialisation, chargement du contexte de développement
Setup
Se déclenche uniquement avec --init-only, --init, ou --maintenance en mode -p (pas au démarrage normal)
Non
Installation unique de dépendances, nettoyage CI planifié
SessionEnd
La session se termine
Non
Nettoyage, journalisation
Actions d’agent (pipeline d’exécution d’outils) :
Événement
Quand il se déclenche
Peut bloquer ?
Cas d’usage
Stop
Claude termine sa réponse
Oui
Actions post-réponse, boucles de continuation
StopFailure
Le tour se termine à cause d’une erreur API (limite de débit, échec d’authentification)
Non
Alerte sur l’épuisement du quota, observabilité
PreToolUse
Avant l’exécution d’un appel d’outil
Oui
Validation de sécurité, modification des entrées
PostToolUse
Après qu’un outil s’est exécuté avec succès
Non
Formatage, journalisation
PostToolUseFailure
Après l’échec d’un appel d’outil
Non
Journalisation des erreurs, actions de récupération
PostToolBatch
Après qu’un lot complet d’appels d’outils parallèles est résolu, avant le prochain appel au modèle
Oui
Injecter du contexte au niveau du lot, appliquer des politiques de lot
Permissions (flux d’approbation) :
Événement
Quand il se déclenche
Peut bloquer ?
Cas d’usage
PermissionRequest
La boîte de dialogue de permission apparaît
Oui
Logique d’approbation personnalisée
PermissionDenied
Un appel d’outil est refusé par le classificateur en mode automatique (se déclenche uniquement en mode automatique, pas lors des refus manuels de l’utilisateur)
Non
Auditer les refus du classificateur, retourner retry: true pour laisser le modèle réessayer
Compaction (gestion du contexte) :
Événement
Quand il se déclenche
Peut bloquer ?
Cas d’usage
PreCompact
Avant la compaction du contexte
Oui
Bloquer la compaction automatique non souhaitée, sauvegarder l’état
PostCompact
Après la compaction du contexte
Non
Restaurer l’état, journaliser la compaction
Multi-agent (orchestration) :
Événement
Quand il se déclenche
Peut bloquer ?
Cas d’usage
SubagentStart
Un sous-agent est instancié
Non
Initialisation du sous-agent
SubagentStop
Un sous-agent se termine
Oui
Nettoyage du sous-agent
TeammateIdle
Un membre de l’équipe d’agents est sur le point de passer en veille
Oui
Coordination d’équipe, portes de qualité
TaskCreated
Une tâche est créée via TaskCreate
Oui
Imposer un nommage, bloquer les tâches non autorisées
TaskCompleted
Une tâche est marquée comme terminée
Oui
Imposer des critères de complétion
Configuration (paramètres et instructions) :
Événement
Quand il se déclenche
Peut bloquer ?
Cas d’usage
ConfigChange
Un fichier de configuration change pendant la session
Oui (sauf politique)
Audit d’entreprise, bloquer les modifications non autorisées
InstructionsLoaded
Un fichier CLAUDE.md ou .claude/rules/*.md est chargé dans le contexte (au démarrage de la session et lors d’un chargement paresseux en milieu de session)
Non
Auditer les fichiers d’instructions actifs, suivi de conformité
Système de fichiers (modifications de l’espace de travail) :
Événement
Quand il se déclenche
Peut bloquer ?
Cas d’usage
CwdChanged
Le répertoire de travail change (ex. quand Claude exécute cd). Utile avec direnv
Non
Recharger les variables d’environnement, activer les chaînes d’outils
FileChanged
Un fichier surveillé change sur le disque ; matcher précise les noms de fichiers à surveiller
Non
Recharger la configuration, déclencher des observateurs
WorktreeCreate
Un worktree est en cours de création via --worktree ou isolation: "worktree". Remplace le comportement git par défaut
Oui (code de sortie non nul)
Configuration VCS personnalisée (SVN, Perforce)
WorktreeRemove
Un worktree est en cours de suppression (à la fin de la session ou quand un sous-agent se termine)
Non
Nettoyer l’état VCS
Interaction utilisateur (invites et notifications) :
Événement
Quand il se déclenche
Peut bloquer ?
Cas d’usage
UserPromptSubmit
L’utilisateur soumet une invite, avant que Claude ne la traite
Oui
Enrichissement du contexte, validation de l’invite
UserPromptExpansion
Une commande slash se développe en invite, avant d’atteindre Claude
Oui
Bloquer l’exécution d’une commande, injecter du contexte de skill
Notification
Claude envoie une notification
Non
Alertes sonores, notifications personnalisées
MessageDisplay
Pendant l’affichage du texte d’un message assistant (affichage uniquement)
Non
Supprimer le markdown à l’écran, masquer les secrets avant le rendu
Elicitation
Un serveur MCP demande une saisie utilisateur pendant un appel d’outil
Oui
Répondre par programmation, ignorer le dialogue interactif
ElicitationResult
L’utilisateur répond à une elicitation MCP, avant que la réponse ne soit renvoyée au serveur
Oui
Auditer ou remplacer les réponses avant qu’elles n’atteignent le serveur MCP
Stop et SubagentStop : champ last_assistant_message (v2.1.47+) : Ces événements incluent un champ last_assistant_message dans leur entrée JSON, donnant un accès direct à la dernière réponse de Claude sans avoir à analyser les fichiers de transcription. Utile pour les pipelines d’orchestration qui doivent inspecter ou journaliser la dernière sortie.
Bloquer Claude sur des erreurs (le code de sortie 2 est ignoré pour les décisions de blocage)
Fournir un retour en temps réel via stdout ou systemMessage
Garantir l’ordre d’exécution avec d’autres hooks
Les hooks async PEUVENT retourner additionalContext via une sortie JSON. Si le hook produit hookSpecificOutput.additionalContext, ce contenu est transmis à Claude comme contexte lors du prochain tour de conversation (après la fin du processus en arrière-plan). Ce n’est pas en temps réel, mais cela atteint bien Claude.
N’utilisez async que lorsque la complétion du hook est véritablement indépendante du flux de travail de Claude.
Pour les hooks qui effectuent un long travail en arrière-plan et doivent signaler un échec à Claude, utilisez asyncRewake: true plutôt que async: true. Comme async, le hook s’exécute en arrière-plan sans bloquer. Contrairement à async, si le hook se termine avec le code 2, Claude Code réveille immédiatement la session et affiche le stderr du hook comme rappel système afin que Claude puisse réagir à l’échec même si la session était autrement inactive.
{
"type": "command",
"command": ".claude/hooks/deploy-watcher.sh",
"asyncRewake": true
}
Utilisez ceci pour les tâches de surveillance en arrière-plan (pipelines de déploiement, statut CI) où un échec devrait interrompre Claude plutôt que de disparaître silencieusement dans les journaux.
Tout ne nécessite pas de l’IA. Choisissez le bon outil :
Type de tâche
Meilleur outil
Pourquoi
Exemple
Déterministe
Script Bash
Rapide, prévisible, sans tokens
Créer une branche, récupérer les commentaires de PR
Basé sur des patterns
Bash + regex
Fiable pour les patterns connus
Vérifier les secrets, valider le format
Nécessite une interprétation
Agent IA
Jugement requis
Revue de code, décisions d’architecture
Dépendant du contexte
Agent IA
Nécessite de la compréhension
”Est-ce que cela correspond aux exigences ?”
Règle empirique : Si vous pouvez écrire une regex ou un simple conditionnel, utilisez un script bash. Si cela nécessite de la “compréhension” ou du “jugement”, utilisez un agent.
Exemple, flux de travail PR :
Terminal window
# Déterministe (bash) : créer une branche, pousser, ouvrir une PR
gitcheckout-bfeature/xyz
gitpush-uoriginfeature/xyz
ghprcreate--title"..."--body"..."
# Interprétation (agent) : revoir la qualité du code
# → Utiliser un sous-agent de revue de code
Pourquoi c’est important : Les scripts bash sont instantanés, gratuits (pas de tokens), et 100 % prévisibles. Réservez l’IA aux tâches qui nécessitent genuinement de l’intelligence.
Motif regex filtrant le déclenchement des hooks (nom d’outil, raison de démarrage de session, etc.)
if
Filtre par règle de permission contrôlant le déclenchement du hook (ex. Bash(git *)), v2.1.85+
type
Type de hook : "command", "http", "mcp_tool", "prompt" ou "agent"
command
Commande shell à exécuter (pour le type command)
args
string[], forme exec : tableau de chaînes lancé directement sans shell. Les chemins n’ont pas besoin d’être entre guillemets. Quand ce champ est présent, command est ignoré. Permet d’éviter les risques d’injection shell. (v2.1.139)
prompt
Texte du prompt pour l’évaluation par LLM (pour les types prompt/agent). Utiliser $ARGUMENTS comme emplacement réservé pour le JSON d’entrée du hook
Modèle à utiliser pour l’évaluation (pour les types prompt/agent). Par défaut, un modèle rapide
async
Si true, s’exécute en arrière-plan sans bloquer (pour le type command uniquement)
asyncRewake
Si true, s’exécute en arrière-plan mais réveille Claude au code de sortie 2 (implique async). À utiliser pour les tâches de surveillance en arrière-plan devant interrompre Claude en cas d’échec
statusMessage
Message de spinner personnalisé affiché pendant l’exécution du hook
once
Si true, ne s’exécute qu’une seule fois par session puis est supprimé (skills uniquement)
Forme exec (args) : Utiliser args: ["program", "arg1", "arg2"] pour lancer la commande sans interpréteur shell. Utile quand les chemins contiennent des espaces ou des caractères spéciaux qui nécessiteraient des guillemets dans command. La forme exec évite également les risques d’injection shell dans les contextes automatisés.
Les hooks n’ont pas besoin d’être persistés dans settings.json. Claude Code prend en charge les hooks à portée de session éphémères, enregistrés à l’exécution et ne durant que le temps de la session en cours. Ils ne sont jamais écrits dans un fichier de configuration et disparaissent à la fin de la session.
C’est le mécanisme qu’utilisent les skills en interne : quand vous invoquez un skill, il peut enregistrer un ou plusieurs hooks pour cette invocation sans modifier durablement votre configuration. Une fois le skill terminé (ou la session close), ces hooks disparaissent.
Quand utiliser les hooks à portée de session :
Skills nécessitant des callbacks d’événements uniquement pendant leur activité
Automatisation temporaire (ex. : « auditer chaque fichier que j’édite durant cette session uniquement »)
Pipelines CI ou scripts d’orchestration injectant des hooks via l’API de manière programmatique
Les hooks à portée de session suivent le même schéma JSON que les hooks settings.json (mêmes noms d’événements, matchers, types et format de sortie) et peuvent être enregistrés via l’API programmatique ou par les skills au moment de l’invocation.
Tapez /hooks dans Claude Code pour ouvrir un navigateur en lecture seule de tous les hooks configurés. Le menu regroupe les hooks par événement, affiche le matcher et les détails du gestionnaire pour chacun, et indique la source de chaque hook : [User] (~/.claude/settings.json), [Project] (.claude/settings.json), [Local] (.claude/settings.local.json), [Plugin] ou [Session] (enregistré à l’exécution). Utilisez-le pour vérifier qu’un hook est bien enregistré, savoir de quel fichier de configuration il provient, ou inspecter la commande ou l’URL complète sans fouiller dans le JSON. Le menu est en lecture seule : modifiez directement le JSON de configuration (ou demandez à Claude) pour effectuer des changements.
Types de hooks :
command : Exécute une commande shell. Reçoit du JSON sur stdin, retourne du JSON sur stdout. Type le plus courant.
http(v2.1.63+) : Envoie du JSON par POST à une URL et lit la réponse JSON. Utile pour les webhooks CI/CD et les intégrations backend sans état ne nécessitant pas de dépendances shell. Configurer avec url et optionnellement allowedEnvVars pour l’interpolation d’en-têtes.
mcp_tool : Appelle un outil sur un serveur MCP déjà connecté. Configurer avec server (nom du serveur) et tool (nom de l’outil) ; la sortie texte de l’outil est traitée comme stdout d’une commande. Le serveur doit être connecté avant le déclenchement du hook.
prompt : Envoie le prompt et l’entrée du hook à un modèle Claude (Haiku par défaut) pour une évaluation en un tour. Retourne {ok: true/false, reason: "..."}. Configurer le modèle via le champ model.
agent : Lance un sous-agent avec accès aux outils (Read, Grep, Glob, etc.) pour une vérification multi-tour. Retourne le même format {ok: true/false}. Jusqu’à 50 tours d’utilisation d’outils.
Les hooks HTTP reçoivent le même payload JSON que les hooks command et doivent retourner du JSON valide. Le champ allowedEnvVars liste les variables d’environnement pouvant être référencées dans les en-têtes (ex. : pour l’authentification par token Bearer).
Le champ if filtre le déclenchement d’un hook en utilisant la même syntaxe de règles de permission que allowedTools. Cela évite de lancer des sous-processus à chaque événement et élimine le besoin d’instructions case côté shell.
// Avant : le hook se déclenche à chaque PostToolUse — logique de garde dans le script
{
"event": "PostToolUse",
"command": "./scripts/log-tool-usage.sh"
}
// Après : le hook se déclenche uniquement quand Bash exécute une commande git
{
"event": "PostToolUse",
"if": "Bash(git *)",
"command": "./scripts/log-git-usage.sh"
}
Les motifs if supportés suivent la même syntaxe que les règles de permission des outils :
Motif
Se déclenche quand
Bash(git *)
Tout appel Bash commençant par git
Edit
Tout appel à l’outil Edit
Write(/tmp/*)
Écriture dans des chemins sous /tmp/
Bash(npm * | yarn *)
Commandes npm ou yarn
Performance : Chaque déclenchement de hook est un sous-processus. Le filtrage conditionnel avec if réduit la charge dans les grands dépôts où PostToolUse se déclenche des centaines de fois par session.
Champs communs (tous les événements) : session_id, transcript_path, cwd, permission_mode, hook_event_name. Les champs spécifiques à l’événement (comme tool_name et tool_input pour PreToolUse) sont ajoutés en plus.
Champ
Type
Description
session_id
string
Identifiant unique de session
transcript_path
string
Chemin vers le fichier de transcription de session
cwd
string
Répertoire de travail courant
permission_mode
string
Mode de permission actif
hook_event_name
string
Événement ayant déclenché le hook
effort.level
string
Niveau d’effort actif : low, medium, high, xhigh, max. Les hooks de type Bash reçoivent également cette valeur via la variable d’environnement $CLAUDE_EFFORT. (v2.1.133)
agent_id
string
Identifiant unique du sous-agent. Présent uniquement quand le hook se déclenche à l’intérieur d’un appel de sous-agent.
agent_type
string
Nom de l’agent ("Explore", "security-reviewer", etc.). Présent quand le hook se déclenche dans un sous-agent ou quand la session utilise --agent.
Les hooks communiquent leurs résultats via les codes de sortie et optionnellement du JSON sur stdout. Choisir une seule approche par hook : soit les codes de sortie seuls, soit une sortie à 0 avec du JSON pour un contrôle structuré. Claude Code ne traite le JSON qu’à la sortie 0 ; si votre hook sort avec un autre code, stdout et tout JSON qu’il contient sont silencieusement ignorés.
Champs JSON universels (tous les événements) :
Champ
Défaut
Description
continue
true
Si false, Claude cesse tout traitement
stopReason
aucun
Message affiché à l’utilisateur quand continue est false
suppressOutput
false
Si true, masque stdout du mode verbeux
systemMessage
aucun
Message d’avertissement affiché à l’utilisateur
terminalSequence
aucun
Chaîne d’échappement terminal autorisée à émettre (OSC 0/1/2/9/99/777 ou BEL). À utiliser pour les notifications bureau ou les titres de fenêtre plutôt qu’écrire dans /dev/tty, auquel les hooks n’ont pas accès. Requiert v2.1.141+.
Le contrôle de décision spécifique à l’événement varie selon le type d’événement :
PreToolUse : Utilise hookSpecificOutput avec permissionDecision (allow/deny/ask/defer), permissionDecisionReason, updatedInput, additionalContext. Quand plusieurs hooks PreToolUse retournent des décisions différentes, la priorité est : deny > defer > ask > allow (v2.1.89+).
PostToolUse, Stop, SubagentStop, UserPromptSubmit, ConfigChange : Utilise decision: "block" au niveau supérieur avec reason
TeammateIdle, TaskCompleted : Code de sortie 2 uniquement (pas de contrôle de décision JSON)
PermissionRequest : Utilise hookSpecificOutput avec decision.behavior (allow/deny)
continueOnBlock pour les hooks de prompt : Un hook type: "prompt" renvoie ok: true ou ok: false. Sur PostToolUse, continueOnBlock: true transmet la raison du refus à Claude afin qu’il puisse continuer et s’adapter. Les hooks de commande utilisent les champs de décision propres à l’événement.
{
"hooks": {
"PostToolUse": [{
"matcher": "Write|Edit",
"hooks": [{
"type": "prompt",
"prompt": "Check this result against project policy. Return JSON with ok and, if false, reason. $ARGUMENTS",
"continueOnBlock": true
}]
}]
}
}
Remplacement de sortie (PostToolUse) : hookSpecificOutput.updatedToolOutput doit correspondre à la structure réelle de la réponse de l’outil. Pour un résultat Bash :
{
"hookSpecificOutput": {
"hookEventName": "PostToolUse",
"updatedToolOutput": {
"stdout": "[redacted]",
"stderr": "",
"interrupted": false,
"isImage": false
}
}
}
Le remplacement modifie ce que Claude voit ; il n’annule pas les effets de l’outil et n’expurge pas la télémétrie capturée avant le hook. Voir la référence des hooks.
Exemple de blocage PreToolUse (préférable au code de sortie 2) :
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "Destructive command blocked by hook"
Satisfaction de AskUserQuestion par PreToolUse (v2.1.85+, intégrations headless) :
Quand Claude déclenche AskUserQuestion en cours de session, les invites interactives ne sont pas disponibles dans les environnements headless (pipelines CI, frontends web, orchestrateurs). Un hook PreToolUse peut intercepter la question, collecter la réponse via une interface externe, et la retourner avant l’exécution de l’outil :
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"updatedInput": { "answer": "yes, proceed with migration" },
"permissionDecision": "allow"
}
}
Le script du hook est responsable de la récupération de la réponse (ex. : interrogation d’un webhook ou lecture depuis une file). Retourner updatedInput avec la réponse et permissionDecision: "allow" pour satisfaire la question et continuer l’exécution sans invites interactives.
Décision defer dans PreToolUse (v2.1.89+, headless/non-interactif uniquement) :
defer est conçu pour les intégrations headless où Claude est orchestré par un processus externe. Quand un hook retourne permissionDecision: "defer", Claude se met en pause avec stop_reason: "tool_deferred" et attend. Le processus appelant peut alors collecter une entrée auprès d’un utilisateur ou d’un autre système et reprendre la session avec --resume <session-id>. Dans les sessions de terminal interactives, defer est ignoré avec un avertissement.
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "defer",
"permissionDecisionReason": "Awaiting human approval via external workflow"
Un principe clé pour garder le contexte de l’agent propre : les hooks doivent être silencieux en cas de succès et verbeux uniquement en cas d’échec.
#!/bin/bash
# .claude/hooks/build-check.sh — Modèle de Succès Silencieux
# En cas de succès : complètement silencieux (rien n'entre dans le contexte de l'agent)
# En cas d'échec : afficher les erreurs + exit 2 pour réengager l'agent
OUTPUT=$(bunrunbuild2>&1)
EXIT_CODE=$?
if [[ $EXIT_CODE-eq0 ]]; then
exit0# Silencieux — pas de sortie, pas de bruit dans le contexte
fi
# Échec : envoyer les erreurs à l'agent pour correction
echo"$OUTPUT">&2
exit2
Cette asymétrie (silence en cas de succès, signal en cas d’échec) empêche les logs de build réussis, les sorties de tests et les rapports de lint de s’accumuler comme « bruit de contexte » dans les longues sessions. L’agent ne voit que ce qui nécessite une action.
Source : Modèle formalisé par HumanLayer: Harness Engineering for Coding Agents (mars 2026). Également validé par la philosophie de conception de RTK : supprimer la sortie des commandes réussies, n’afficher que les erreurs.
Ces quatre événements de hook ont accès à une variable d’environnement CLAUDE_ENV_FILE, qui fournit un chemin vers un fichier où vous pouvez persister des variables d’environnement pour les commandes Bash ultérieures de la session. Écrivez des instructions export dedans (utilisez l’ajout >> pour préserver les variables définies par d’autres hooks) :
Les variables écrites ici sont disponibles pour tous les appels ultérieurs à l’outil Bash que Claude effectue dans cette session. C’est la méthode standard pour injecter de la configuration d’environnement (ex. : activation de nvm, chargement de direnv) sans modifier durablement l’environnement système.
sessionTitle (définit le titre de session), reloadSkills (bool, réanalyse les skills après le hook), watchPaths (tableau, enregistre des fichiers pour FileChanged), additionalContext, initialUserMessage
watchPaths (remplace la liste de surveillance de fichiers dynamique)
FileChanged
file_path, event (change/add/unlink)
watchPaths (met à jour la liste de surveillance de fichiers dynamique). Le champ matcher joue un double rôle : il enregistre les noms de fichiers dans la liste de surveillance ET filtre les groupes de gestionnaires à exécuter.
WorktreeCreate
name (identifiant slug)
stdout affiche le chemin absolu du worktree créé (ou HTTP : hookSpecificOutput.worktreePath). Une sortie non nulle fait échouer la création.
Aucun. Délai d’attente par défaut : 1,5s (augmenter avec timeout par hook ; la variable d’environnement CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS remplace le budget jusqu’à 60s).
hookSpecificOutput.action, content (remplace la réponse de l’utilisateur)
MessageDisplay
turn_id, message_id, index (base 0 par lot), final (bool, dernier lot), delta (nouvelles lignes)
hookSpecificOutput.displayContent (remplace le texte affiché à l’écran, la transcription est inchangée). Délai d’attente par défaut : 10s.
Notification
message, title, notification_type
Aucun (effets de bord uniquement)
background_tasks et session_crons sont disponibles dans Stop/SubagentStop depuis v2.1.145. Chaque entrée dans background_tasks possède id, type (shell/subagent/monitor/workflow/teammate/cloud session/MCP task), status, description, et des champs spécifiques au type. Chaque entrée dans session_crons possède id, schedule, recurring (bool), prompt. Utilisez-les pour distinguer « session terminée » de « session en attente de tâches en arrière-plan ».
additionalContext est injecté dans la fenêtre de contexte de Claude comme rappel système au point où le hook s’est déclenché. Pour PostToolUse et PostToolBatch, il apparaît à côté du résultat de l’outil. Pour UserPromptSubmit, il apparaît à côté du prompt soumis. Plusieurs hooks retournant additionalContext pour le même événement sont tous transmis. Les valeurs sont limitées à 10 000 caractères.
Sous Windows, Claude Code peut utiliser PowerShell comme outil de première classe aux côtés de Bash, permettant l’exécution de scripts .ps1, de modules PowerShell et de commandes natives Windows sans nécessiter WSL ni Git Bash.
À activer dans ~/.claude/settings.json :
{
"tools": {
"powershell": {
"enabled": true
}
}
}
Une fois activé, Claude peut exécuter des commandes PowerShell directement (par ex. Get-ChildItem, Invoke-WebRequest, CLI dotnet). Utile pour les équipes travaillant dans des environnements Windows où les scripts .ps1 constituent la couche d’automatisation standard.
Aperçu : Il s’agit d’un aperçu opt-in à partir de la v2.1.84. L’outil Bash reste disponible sous Windows via Git Bash ou WSL et est toujours préféré pour les scripts multiplateformes.
Les utilisateurs Windows peuvent créer des hooks à l’aide de PowerShell (.ps1) ou de fichiers batch (.cmd).
Remarque : Les hooks Windows doivent utiliser l’invocation PowerShell complète avec -ExecutionPolicy Bypass afin d’éviter les restrictions de politique d’exécution.
Modèle W1 : Vérification de sécurité PreToolUse (PowerShell)
Les hooks de sécurité sont essentiels pour protéger votre système.
Configurations avancées : Pour une sécurité complète incluant la détection d’injection Unicode, la vérification d’intégrité des configurations MCP et les mitigations spécifiques aux CVE, consultez le Guide de renforcement de la sécurité.
Plugin Claude Security : le scanner de vulnérabilités multi-agents d’Anthropic s’installe avec /plugin install claude-security@claude-plugins-official sur les plans payants et l’accès API. Il cartographie l’architecture, construit un modèle de menaces, soumet chaque résultat à des vérificateurs indépendants et écrit des correctifs que vous appliquez vous-même. Un service Claude Security managé est disponible sur le plan Enterprise. Voir Guide de renforcement de la sécurité → Claude Code en tant que scanner de sécurité.
Validé à grande échelle : Dans le cadre d’un partenariat avec Mozilla en mars 2026, Claude Opus 4.6 a analysé ~6 000 fichiers C++ du moteur JS de Firefox en deux semaines, révélant 22 vulnérabilités confirmées (14 de sévérité élevée), soit environ un cinquième de tous les CVE Firefox de haute sévérité corrigés en 2025. Cela démontre la profondeur pratique du modèle pour les travaux de sécurité en production, bien au-delà d’un simple lint de surface.
L’équipe Claude Code utilise une configuration dans laquelle les demandes d’autorisation sont acheminées vers un modèle plus capable jouant le rôle de gardien de sécurité, plutôt que de s’appuyer uniquement sur la correspondance de règles statiques.
Concept : Un hook PreToolUse intercepte les demandes d’autorisation et les transmet à Opus 4.7 (ou un autre modèle capable) via l’API. Le modèle gardien analyse les tentatives d’injection de prompt, les schémas dangereux et les usages inattendus des outils, puis approuve automatiquement les requêtes sûres ou bloque les suspectes.
"Analyze this tool call for security risks. Is it safe? Reply SAFE or BLOCKED:reason")
[[ "$VERDICT"== SAFE* ]] && exit0
echo"BLOCKED by security gate: $VERDICT">&2
exit2
Pourquoi utiliser un modèle comme gardien : Les règles statiques détectent les schémas connus mais passent à côté des attaques inédites. Un modèle capable comprend l’intention et le contexte : il peut distinguer rm -rf node_modules (nettoyage) de rm -rf / (destruction) en se basant sur la conversation environnante, et pas uniquement sur la correspondance de schémas.
Compromis : Chaque appel filtré ajoute de la latence et un coût. Utilisez des exemptions de chemin rapide pour les outils en lecture seule et ne filtrez que les opérations d’écriture et d’exécution.
# Devrait quitter avec 1 et afficher "Variable expansion detected"
Référence croisée : Pour un renforcement complet de la sécurité incluant les mitigations spécifiques aux CVE et l’intégrité des configurations MCP, consultez le Guide de renforcement de la sécurité.
Au lieu de configurer des dizaines de hooks individuels, utilisez un dispatcher unique qui achemine les événements de manière intelligente selon le type de fichier, l’outil et le contexte.
Le problème : à mesure que votre collection de hooks grossit, settings.json devient difficile à gérer avec des matchers répétés et des configurations qui se chevauchent.
La solution : un point d’entrée unique qui distribue vers des gestionnaires spécialisés.
.claude/hooks/dispatch.sh
#!/bin/bash
# Single entry point for all PostToolUse hooks
# Routes to specialized handlers based on file type and tool
Enchaînez plusieurs hooks de validation pour détecter les problèmes immédiatement après les modifications du code. Ce modèle garantit la qualité du code sans intervention manuelle.
Les hooks sont automatiquement configurés pour SessionStart (référence RTK) et SessionEnd (affichage du résumé). Aucune configuration manuelle n’est nécessaire.
Le problème : Quand Claude compacte le contexte lors d’une longue session, les agents configurés avec un rôle spécifique (responsable d’équipe, développeur, réviseur) peuvent « oublier » leur identité. La transcription compactée ne contient plus les instructions système d’origine, donc la réponse suivante abandonne complètement le rôle et commence à se comporter de façon générique.
Ce phénomène est particulièrement visible dans les équipes d’agents avec des préfixes d’identité explicites. Un agent développeur qui marquait systématiquement ses messages avec 🔨 DEVELOPER: s’arrête soudainement après la compaction et commence à répondre comme un assistant générique.
Le pattern : Stocker l’identité de l’agent dans un fichier (.claude/agent-identity.txt). Après chaque message utilisateur, un hook UserPromptSubmit vérifie si la dernière réponse de l’assistant contient le marqueur d’identité attendu. Si ce n’est pas le cas (ce qui arrive après la compaction), il injecte le contenu du fichier d’identité comme additionalContext. La réponse suivante rétablit le rôle sans intervention humaine.
.claude/agent-identity.txt
# Instructions d'identité de votre agent — tout ce qui doit survivre à la compaction
Zéro surcharge lorsque le marqueur d’identité est présent (sort immédiatement à la correspondance)
No-op silencieux quand aucun fichier .claude/agent-identity.txt n’existe
Se déclenche automatiquement après la compaction : aucune intervention manuelle nécessaire
Fonctionne aussi bien en sessions solo (agents de longue durée) que dans les configurations d’équipes d’agents
Personnalisation : Définissez CLAUDE_IDENTITY_MARKER dans votre environnement avec une chaîne courte et distinctive tirée de la sortie standard de l’agent (ex. "LEAD:", "DEVELOPER:", "🔨"). Si non défini, le hook utilise les 40 premiers caractères du fichier d’identité comme marqueur.
Temps de lecture : 5 minutes
Niveau de compétence : Configuration d’équipe
À mesure que votre collection de hooks grandit, une tension émerge : certains développeurs veulent une surcharge minimale (démarrage rapide, pas de vérifications bloquantes), tandis que les membres soucieux de la sécurité ou les pipelines CI veulent une application stricte. Un seul settings.json ne peut pas bien servir les deux.
Le pattern : conditionner chaque hook à une variable d’environnement qui déclare le niveau d’application souhaité. Trois niveaux couvrent la plupart des équipes :
minimal — uniquement les hooks de sécurité critiques (détection de secrets, blocages de permissions)
standard — hooks de workflow de développement (formatage, vérification de types, lint)
Objectif : Compréhension approfondie du code par analyse sémantique, indexation et mémoire persistante.
Pourquoi Serena est important : Claude Code ne dispose pas d’indexation intégrée (contrairement à Cursor). Serena comble ce manque en indexant votre base de code pour des recherches plus rapides et plus intelligentes. Il fournit également une mémoire de session, un contexte qui persiste d’une conversation à l’autre.
Fonctionnalités clés :
Fonctionnalité
Description
Indexation
Pré-indexe votre base de code pour une recherche efficace de symboles
Mémoire de projet
Stocke le contexte dans .serena/memories/ entre les sessions
Initialisation
Analyse automatiquement la structure du projet à la première exécution
Outils :
Outil
Description
find_symbol
Trouver des fonctions, classes, méthodes par nom
get_symbols_overview
Obtenir un aperçu de la structure d’un fichier
search_for_pattern
Recherche par expression régulière dans la base de code
find_referencing_symbols
Trouver toutes les utilisations d’un symbole
replace_symbol_body
Remplacer le corps d’une fonction ou d’une classe
write_memory
Sauvegarder le contexte pour les sessions futures
read_memory
Récupérer le contexte sauvegardé
list_memories
Lister toutes les mémoires stockées
Workflow de mémoire de session :
# Début de session
list_memories() → Voir quel contexte existe
read_memory("auth_architecture") → Charger le contexte pertinent
# Pendant le travail
write_memory("api_refactor_plan", "...") → Sauvegarder les décisions pour plus tard
# Fin de session
write_memory("session_summary", "...") → Persister la progression
Objectif : Recherche sémantique de code axée sur la confidentialité, avec analyse du graphe d’appels.
Pourquoi grepai est recommandé : Il est entièrement open-source, s’exécute entièrement en local grâce aux embeddings Ollama (pas de cloud, pas de problème de confidentialité), et propose une analyse du graphe d’appels : tracez qui appelle quelle fonction et visualisez les dépendances. Cette combinaison en fait le meilleur choix pour la plupart des besoins de recherche sémantique.
Fonctionnalités clés :
Fonctionnalité
Description
Recherche sémantique
Trouver du code par description en langage naturel
Graphe d’appels
Tracer les appelants, les appelés et les graphes de dépendances complets
Confidentialité d’abord
Utilise Ollama en local (pas de cloud)
Indexation en arrière-plan
Le démon grepai watch maintient l’index à jour
Exemple :
Terminal window
# Recherche sémantique (trouve du code par sens, pas par texte exact)
grepaisearch"user authentication flow"
# Qui appelle cette fonction ?
grepaitracecallers"createSession"
# → Liste les 23 fichiers qui appellent createSession avec contexte
# Que appelle cette fonction ?
grepaitracecallees"SessionProvider"
# Graphe de dépendances complet
grepaitracegraph"createSession"--depth3
Outils MCP disponibles :
Outil
Description
grepai_search
Recherche sémantique en langage naturel
grepai_trace_callers
Trouver tous les appelants d’une fonction
grepai_trace_callees
Trouver toutes les fonctions appelées par une fonction
Exploration de bases de code inconnues par intention
Compréhension des dépendances d’appels avant refactorisation
La confidentialité est requise (pas de cloud, tout en local)
Besoin de tracer “qui appelle quoi” dans la base de code
Performance vs outils traditionnels :
Type de recherche
Outil
Temps
Résultats
Correspondance exacte
rg (ripgrep)
~20ms
Correspondances exactes uniquement
Correspondance exacte
grep
~45ms
Correspondances exactes uniquement
Sémantique
grepai
~500ms
Correspondances basées sur l’intention
Point clé : grepai est ~25x plus lent que rg pour les correspondances exactes, mais trouve des résultats que les outils basés sur les motifs ne peuvent pas découvrir.
Terminal window
# Motif exact connu → utiliser rg (rapide)
rg"createSession"--typets
# Nom exact inconnu → utiliser grepai (sémantique)
Avant de modifier une fonction très utilisée, lancez une requête de dépendances pour énumérer tous les sites d’appel affectés, puis décidez si vous continuez. Ce workflow nommé prévient les ruptures en cascade dans les grandes bases de code.
Terminal window
# Étape 1 : Cartographier tous les appelants avant de toucher à une fonction
grepaitracecallers"processPayment"
# → Retourne : 14 sites d'appel dans 7 fichiers
# Étape 2 : Vérifier les appelés (de quoi dépend-elle)
grepaitracecallees"processPayment"
# → Retourne : 3 dépendances en aval
# Étape 3 : Décider de la portée avant d'écrire une seule ligne
# 14 appelants + 3 dépendances = rayon d'impact significatif → planifier la refactorisation d'abord
Exécuter ceci avant de démarrer toute refactorisation touchant une fonction utilisée à 3+ endroits, pas après avoir rencontré des erreurs de compilation.
Objectif : Mémoire persistante automatique entre les sessions Claude Code via une capture compressée par IA des usages d’outils et des observations. Résout la perte de contexte sans appels manuels à write_memory().
Fonctionnalité
Valeur
Capture
Hooks dans SessionStart, PostToolUse, Stop, SessionEnd
Stockage
SQLite + Chroma optionnel (fallback port 8000 : SQLite FTS)
Worker
Processus Bun, port 37777, fail-open (un worker mort ne bloque jamais le travail)
AGPL-3.0 + PolyForm Noncommercial (vérifier pour usage commercial)
Étoiles
88,7K au 27/07/2026 (contre 26,5K au 2026-03-30, v10.6.3)
Avertissement de sécurité : GET /api/settings expose les clés API en texte clair : définir host: "127.0.0.1", jamais "0.0.0.0".
Piège de coexistence des hooks : L’installation de claude-mem écrase les tableaux hooks existants dans settings.json. Sauvegarder avant l’installation, puis fusionner manuellement.
Coût : ~5-15 $/mois (utilisateurs intensifs). Passer du modèle de compression Claude Haiku à Gemini 2.5 Flash économise ~86%.
Couverture complète : Voir Memory Systems: claude-mem pour l’analyse complète de l’architecture, les types d’observations, le workflow de divulgation progressive, les contrôles de confidentialité et le tableau comparatif des coûts.
GitHub : safishamsi/graphify, renommé Graphify-Labs/graphify | PyPI : graphifyy | Étoiles : 97,1K (27/07/2026, contre 42K) | Licence : MIT
Graphify convertit un répertoire de projet en graphe de connaissance persistant et injecte un rapport structurel compact (GRAPH_REPORT.md) dans Claude Code. L’assistant répond aux questions d’architecture en lisant le graphe pré-construit plutôt qu’en re-scannant les fichiers bruts à chaque prompt. L’extraction initiale s’exécute une seule fois ; les sessions suivantes interrogent le graphe à un coût en tokens quasi nul.
Transcription locale optionnelle : faster-whisper transcrit audio/vidéo en local.
Extraction sémantique parallèle : Des sous-agents Claude traitent docs, PDFs et images en utilisant votre clé API existante.
Les résultats fusionnent dans un graphe NetworkX clusterisé avec l’algorithme de Leiden (basé sur la topologie, pas d’embeddings vectoriels). Chaque relation est étiquetée EXTRACTED, INFERRED ou AMBIGUOUS. Trois fichiers de sortie atterrissent dans graphify-out/ :
graph.html : visualisation interactive dans le navigateur
Graphify vs GrepAI : Des couches différentes, complémentaires. GrepAI (Ollama, local, gratuit) gère les recherches sémantiques en temps réel pendant le codage actif : rapide, ciblé, précis. Graphify pré-calcule les relations structurelles dans toute la base de code (chaînes d’appels, dépendances inter-fichiers, clusters de communautés) et remplace les lectures répétées de fichiers par un seul rapport compact par session. GrepAI pour la découverte ; Graphify pour le raisonnement architectural et les questions multi-sauts.
Graphify vs claude-mem : Des préoccupations distinctes. claude-mem stocke ce que vous avez discuté entre les sessions (décisions, appels d’outils, observations). Graphify cartographie ce que la base de code contient (structure, dépendances, clusters de concepts). Aucun chevauchement : ils adressent différentes couches de perte de contexte.
Workflow en équipe : Committer graphify-out/ (en excluant manifest.json et cache/) dans git afin que les coéquipiers héritent du graphe pré-construit sans avoir à exécuter l’extraction eux-mêmes.
Mises en garde :
Les fichiers non-code (docs, PDFs, images) sont envoyés à l’API de votre assistant IA lors de la première exécution, les coûts s’accumulent sur les dépôts mixtes volumineux.
Sans le hook post-commit, le graphe diverge de la base de code.
Les affirmations d’efficacité en tokens de l’auteur (71,5x–120x moins de tokens vs exploration par grep) sont des benchmarks auto-rapportés sans reproduction indépendante. À traiter comme indicatif.
Pas de langage de requête natif : les requêtes de graphe passent par l’assistant IA, pas par Cypher/SQL.
Stats : 97,1K étoiles GitHub au 27/07/2026 (contre 42K) | v0.7.4 (2026-05-04) | Python ≥3.10 | MIT
Objectif : Recherche sémantique en langage naturel dans du code, des documents, des PDFs et des images.
Pourquoi envisager mgrep : Si vous avez besoin d’une recherche multi-format (code + PDFs + images) ou préférez une solution cloud, mgrep est une alternative à grepai. Leurs benchmarks indiquent ~2x moins de tokens utilisés par rapport aux workflows basés sur grep.
Fonctionnalités clés :
Fonctionnalité
Description
Recherche sémantique
Trouver du code par description en langage naturel
Indexation en arrière-plan
mgrep watch indexe en respectant .gitignore
Multi-format
Recherche dans du code, des PDFs, des images, du texte
Objectif : Correspondance de motifs basée sur l’AST pour des recherches de code structurelles précises.
Type : Plugin communautaire optionnel (pas intégré au cœur de Claude Code)
Installation :
Terminal window
# Installer le skill ast-grep pour Claude Code
npxskillsaddast-grep/agent-skill
# Ou manuellement via le marketplace de plugins
/pluginmarketplaceadd
Qu’est-ce qu’ast-grep ?
ast-grep recherche du code en se basant sur la structure syntaxique (Arbre Syntaxique Abstrait) plutôt que sur du texte brut. Cela permet de trouver des motifs comme « les fonctions async sans gestion des erreurs » ou « les composants React utilisant des hooks spécifiques » que les expressions régulières ne peuvent pas détecter de manière fiable.
Caractéristiques clés :
Aspect
Comportement
Invocation
Explicite : Claude ne peut pas automatiquement détecter quand l’utiliser
Intégration
Plugin qui apprend à Claude comment écrire des règles ast-grep
Langages
JavaScript, Python, Rust, Go, Java, C/C++, Ruby, PHP + plus
Les premières versions de Claude Code utilisaient le RAG avec des embeddings Voyage pour la recherche sémantique. Anthropic est passé à une recherche agentique basée sur grep (ripgrep) après que des benchmarks ont montré des performances supérieures avec une complexité opérationnelle moindre (pas de synchronisation d’index, pas de risques de sécurité). Cette philosophie « Chercher, ne pas indexer » privilégie la simplicité.
ast-grep est une extension communautaire pour des recherches structurelles spécialisées où l’approche regex de grep ne suffit pas : un outil chirurgical pour des cas d’usage spécifiques, pas un remplacement de grep.
Statut : Développement actif, v0.15.0 (fév. 2026). 39,3K étoiles au 27/07/2026 (plus de 12 100 auparavant). Cycle de publication rapide.
Objectif : CLI de navigateur headless conçu pour les agents IA. Utilise Playwright/CDP en arrière-plan mais optimise toutes les sorties pour la consommation par les LLM. Écrit en Rust pour un démarrage en sous-milliseconde.
Pourquoi c’est important pour les workflows agentiques : Playwright MCP est verbeux, chaque snapshot DOM ajoute des tokens. agent-browser ne retourne que les éléments exploitables via des références courtes stables (@e1, @e2), réduisant l’utilisation des tokens de ~82,5% sur des scénarios identiques (benchmark Pulumi, 2026-03-03).
Installation :
Terminal window
# Homebrew
brewinstallvercel-labs/tap/agent-browser
# Ou npm
npminstall-g@vercel-labs/agent-browser
Capacités :
Fonctionnalité
Détails
Navigation + interaction
Clic, frappe, défilement, remplissage de formulaires
Arbre d’accessibilité
Snapshots optimisés pour les LLM (éléments exploitables uniquement)
Diffs visuels
Comparaison pixel par pixel avec des références
Persistance de session
Sauvegarde/restauration de l’état d’authentification (AES-256-GCM)
Multi-session
Instances isolées, cookies/stockage séparés
Sécurité (v0.15.0)
Coffres d’authentification, listes d’autorisation de domaines, politiques d’action
Streaming de navigateur
Aperçu WebSocket en direct pour la navigation « en binôme » humain+agent
agent-browser vs Playwright MCP :
Dimension
Playwright MCP
agent-browser
Public cible
Développeurs (suites de tests)
Agents IA
Utilisation des tokens
Référence
-82,5%
Références d’éléments
Sélecteurs XPath/CSS
@e1, @e2 (stables, compacts)
Implémentation
Node.js
Rust (démarrage en sous-ms)
Persistance de session
Non
Oui
Contrôles de sécurité
Aucun
Coffres d’authentification, listes d’autorisation de domaines
Agents auto-vérifiants
Maladroit
Motif natif
La boucle Ralph Wiggum, motif d’agent auto-vérifiant :
1. L'agent code la fonctionnalité
2. Déploie (Vercel, toute cible)
3. agent-browser navigue vers l'URL déployée de manière autonome
4. Teste les scénarios, lit les snapshots d'accessibilité
5. En cas d'échec : l'agent lit la sortie, corrige le code, redéploie
6. Boucle jusqu'à ce que tous les scénarios passent — sans intervention humaine
Documenté en production chez Pulumi (2026-03-03) sur 6 scénarios de test dans une application réelle.
Utiliser quand :
L’agent doit vérifier sa propre sortie déployée (boucles auto-vérifiantes)
Le coût en tokens du contexte du navigateur est une contrainte
Tests multi-sessions (instances de navigateur parallèles isolées)
Régression visuelle dans des pipelines CI/CD agentiques
Ne pas utiliser quand :
Vous avez des suites de tests Playwright existantes : pas un remplacement direct des exécuteurs de tests
Scraping de sites anti-bot protégés : la détection IP/comportementale reste inchangée (les services de type Browserbase sont toujours nécessaires)
⚠️ Statut : En cours de test. Évalué début 2026. Licence MIT, Python.
Objectif : Mémoire sémantique persistante avec recherche inter-sessions et support multi-clients. Complète Serena (clé-valeur) avec une récupération basée sur la signification : retrieve_memory("what did we decide about auth?").
Problèmes connus : La valeur par défaut busy_timeout=5000ms provoque des erreurs intermittentes sous accès concurrent ; corriger avec MCP_MEMORY_SQLITE_PRAGMAS=busy_timeout=15000,cache_size=20000.
Couverture complète : Voir Memory Systems: doobidoo pour l’installation, la configuration, les backends de stockage, les problèmes connus et la comparaison avec Kairn/ICM.
Source : doobidoo/mcp-memory-service GitHub ([NON VÉRIFIÉ, le compte GitHub doobidoo ne résout plus au contrôle du 27/07/2026, l’API renvoie 404. Dernier chiffre confirmé : ~1,6K étoiles], v10.0.2)
Kairn : Mémoire en graphe de connaissances avec décroissance biologique
⚠️ Statut : En cours de test. Évalué fév. 2026. Licence MIT, Python.
Objectif : Mémoire de projet à long terme sous forme de graphe de connaissances avec décroissance biologique automatique : les informations obsolètes expirent sans nettoyage manuel.
Fonctionnalité
Valeur
Relations typées
depends-on, resolves, causes
Modèle de décroissance
Solutions ~200 jours, contournements ~50 jours
Outils
18 outils MCP (opérations de graphe, recherche, motifs inter-espaces de travail)
Installation
pip install kairn
Utilisez Kairn quand la causalité est importante (« ceci se casse à cause de cela ») ou quand des projets de longue durée accumulent des contournements obsolètes qui nécessitent un élagage automatique.
Couverture complète : Voir Memory Systems: Kairn pour la décomposition complète des fonctionnalités, les détails du modèle de décroissance et la comparaison avec doobidoo/ICM.
⚠️ Statut : En cours de test. Évalué mars 2026. Licence Source-Available (gratuite pour les individus et les équipes ≤20). Les benchmarks sont fournis par le fournisseur, non vérifiés indépendamment.
Objectif : Mémoire persistante combinant la décroissance épisodique (Memories) et un graphe de connaissances permanent (Memoirs) dans un seul binaire Rust sans dépendance.
Couverture complète : Voir Memory Systems: ICM pour la décomposition complète de l’architecture, les types de relations Memoir, les benchmarks et la comparaison avec Kairn/doobidoo.
Source : rtk-ai/icm GitHub (508 étoiles au 27/07/2026, contre 52 auparavant, Source-Available)
Objectif : Accès Git programmatique via 12 outils structurés pour la gestion des commits, diffs, logs et branches.
Pourquoi Git MCP vs Bash git : L’outil Bash peut exécuter des commandes git mais retourne une sortie terminal brute qui nécessite une analyse syntaxique et consomme des tokens. Git MCP retourne des données structurées directement utilisables par Claude, avec des filtres intégrés (date, auteur, branche) et des diffs économes en tokens via le paramètre context_lines.
⚠️ Statut : Développement précoce, API susceptible de changer. Adapté aux workflows locaux ; tester avant d’adopter dans des pipelines de production.
Outils (12) :
Outil
Description
git_status
État de l’arbre de travail (indexé, non indexé, non suivi)
git_diff_unstaged
Modifications non indexées
git_diff_staged
Modifications indexées prêtes à être commitées
git_diff
Comparer deux branches, commits ou refs quelconques
git_commit
Créer un commit avec un message
git_add
Indexer un ou plusieurs fichiers
git_reset
Désindexer des fichiers
git_log
Historique des commits avec filtres de date, auteur et branche
git_create_branch
Créer une nouvelle branche
git_checkout
Changer de branche
git_show
Afficher les détails d’un commit ou d’un tag
git_branch
Lister toutes les branches locales
Configuration :
Terminal window
# Aucune installation requise — uvx le télécharge au premier lancement
Objectif : Accès complet à la plateforme GitHub : Issues, Pull Requests, Projects, recherche de code, gestion de dépôts et GitHub Enterprise.
Git MCP vs GitHub MCP (deux couches distinctes) :
Couche
Outil
Périmètre
Opérations Git locales
Git MCP Server
Commits, diffs, branches, staging
Plateforme cloud GitHub
GitHub MCP Server
Issues, PRs, Projects, Reviews, Search
Les deux peuvent être actifs simultanément. Ils se complètent : Git MCP gère le travail local, GitHub MCP gère la collaboration et l’état cloud.
Deux modes de configuration :
Mode
Prérequis
Quand l’utiliser
Distant (api.githubcopilot.com)
Abonnement GitHub Copilot
Déjà abonné à Copilot
Binaire auto-hébergé
GitHub PAT uniquement
Sans Copilot, code propriétaire ou exigences de confidentialité
MCP distant (nécessite un abonnement GitHub Copilot) :
⚠️ Problème connu : claude mcp add --transport http tente par défaut un enregistrement dynamique de client OAuth, que l’endpoint Copilot ne prend pas en charge. Vous obtiendrez : Incompatible auth server: does not support dynamic client registration. La solution est d’injecter le token manuellement (voir ci-dessous).
Étape 3, modifier ~/.claude.json pour ajouter l’en-tête Authorization :
{
"mcpServers": {
"github": {
"type": "http",
"url": "https://api.githubcopilot.com/mcp/",
"headers": {
"Authorization": "Bearer gho_xxxxxxxxxxxx"
}
}
}
}
Si le token expire : gh auth refresh puis mettre à jour la valeur dans ~/.claude.json.
Configuration auto-hébergée (GitHub PAT uniquement, Copilot non requis) :
Terminal window
# Télécharger le binaire depuis github.com/github/github-mcp-server/releases
exportGITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx
./github-mcp-serverstdio
{
"mcpServers": {
"github": {
"command": "/path/to/github-mcp-server",
"args": ["stdio"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx"
}
}
}
}
Fonctionnalités principales :
Issues : créer, lister, filtrer, assigner, fermer
Pull Requests : créer, réviser, fusionner, lister par assigné/label
Projects : lire et mettre à jour GitHub Projects v2
Recherche de code : rechercher dans tous les dépôts d’une organisation
GitHub Enterprise : même API, URL de base différente
Workflows typiques avec Claude Code :
« Lister toutes les PRs ouvertes qui me sont assignées sur org/repo, triées par dernière activité »
« Pour la PR #456, résumer les changements, signaler les ruptures de compatibilité et rédiger un commentaire de révision »
« Créer une issue pour le bug X avec une checklist, puis ouvrir une branche et pousser un commit de correction »
« Rechercher dans tous les dépôts de l’organisation les usages de fetchUser() déprécié et lister les fichiers à migrer »
Différence avec @modelcontextprotocol/server-github : Le serveur GitHub MCP officiel ajoute la prise en charge de Projects, l’authentification OAuth 2.1, GitHub Enterprise et l’endpoint hébergé à distance. Le serveur de référence npm est plus léger mais couvre moins de fonctionnalités.
Source : github/github-mcp-server, Go, licence MIT, 31,8K étoiles au 27/07/2026 (contre 20 000+ auparavant), activement maintenu avec des releases régulières.
Le Claude Code Ultimate Guide fournit un serveur MCP stdio : les clients de codage peuvent rechercher dans l’index embarqué, lire des sections sources, consulter les versions et récupérer des modèles.
Affiche les changements entre deux versions du CLI Claude Code : toutes les versions de l’intervalle, leurs points clés et les changements incompatibles.
diff_official_docs
Compare les instantanés de référence et actuel de la documentation officielle Anthropic. Affiche les pages ajoutées, supprimées et modifiées. Lit uniquement les fichiers locaux, sans réseau. Exécuter d’abord init_official_docs(), puis refresh_official_docs() pour actualiser l’instantané courant.
get_changelog
Renvoie les N dernières entrées du CHANGELOG du guide. Pour les versions du CLI Claude Code, utiliser get_release().
get_cheatsheet
Renvoie l’aide-mémoire : une référence compacte d’une page sur les principales commandes, raccourcis, options et workflows.
get_digest
Résume les changements du guide et du CLI pour une période, en combinant CHANGELOG du guide et versions officielles Claude Code.
get_example
Récupère un modèle ou exemple prêt à l’emploi : agents, skills, commandes, hooks et scripts. Un nom partiel recherche les exemples correspondants.
get_release
Renvoie les détails des versions officielles du CLI. Fournir une version précise ou omettre l’argument pour les dernières versions et l’historique récent.
get_threat
Recherche une menace par identifiant dans la base de sécurité : CVE (par exemple CVE-2025-53109) ou technique (par exemple T001).
init_official_docs
Télécharge la documentation officielle (llms-full.txt) et enregistre l’instantané local de référence. À exécuter en premier. Une nouvelle exécution remplace les instantanés de référence ET actuel. Environ 5 secondes pour ~1,2 Mo depuis Anthropic.
list_examples
Liste les modèles prêts à l’emploi par catégorie : agents, commandes, hooks, skills et scripts. Utiliser get_example(name) pour récupérer le contenu.
list_threats
Parcourt la base de menaces. Sans catégorie, renvoie un résumé et les nombres ; avec une catégorie, toutes ses entrées.
list_topics
Liste les thèmes et catégories principaux du guide pour explorer son périmètre avant une recherche.
read_section
Lit une section Markdown, YAML ou un exemple. Pagination par décalage, ou ancre #heading-slug pour rejoindre une section renvoyée par search_guide(). À utiliser après la recherche pour obtenir son contenu.
refresh_official_docs
Retélécharge la documentation officielle et actualise l’instantané courant sans toucher à la référence. À exécuter avant une nouvelle comparaison. Environ 5 secondes pour ~1,2 Mo depuis Anthropic.
search_examples
Recherche sémantique par intention dans les modèles, par exemple « hook lint » ou « agent code review ». Complète get_example (nom) et list_examples (catégorie).
search_guide
Recherche le guide par thème, mot-clé ou question : fonctionnalités, hooks, agents, MCP, skills, commandes et pratiques. À utiliser en premier pour une question Claude Code avant une recherche web.
search_official_docs
Recherche par mot-clé ou thème dans l’instantané officiel actuel en local, sans appel réseau. Exécuter init_official_docs() d’abord.
URI de ressource
Type MIME
Description
claude-code-guide://agent-harnesses
application/json
Données sourcées de l’Agent Harness Map. Sépare catalogue général, compléments du guide, runtimes au sens strict et plans de contrôle voisins. Les preuves inconnues restent déclarées inconnues.
claude-code-guide://distribution-channels
text/yaml
Canaux de publication, URL attribuées, états des fichiers, dates et résultats sur 30 jours pour le guide.
claude-code-guide://llms
text/plain
Fichier llms.txt d’identité et de navigation lisible par machine.
claude-code-guide://reference
text/yaml
Index structuré complet. À utiliser si les résultats de search_guide() ne suffisent pas.
claude-code-guide://releases
text/yaml
Historique des versions officielles de Claude Code avec points clés et changements incompatibles.
claude-code-guide://translations
application/json
Version, provenance, fraîcheur et couverture des traductions maintenues et communautaires.
Commande complémentaire
Description
/ccguide:daily
Vérification quotidienne : comparaison des documents officiels et résumé des changements du guide/CLI
/ccguide:diff-docs
Compare les instantanés officiel de référence et actuel, immédiatement et sans réseau
/ccguide:init-docs
Télécharge la documentation officielle et crée l’instantané local de référence
/ccguide:refresh-docs
Retélécharge la documentation officielle et actualise l’instantané courant, sans modifier la référence
Les listes et l’index de recherche utilisent le contenu embarqué du paquet. Les outils de sections, exemples, aide-mémoire, changelog, résumé (get_digest) et menaces peuvent télécharger du contenu GitHub et écrire un cache local de 24 heures. L’initialisation et l’actualisation de la documentation officielle téléchargent les documents Anthropic et écrivent des instantanés locaux séparés. Le serveur n’est donc ni entièrement hors ligne, ni purement en lecture seule.
Consultez le guide technique canonique pour distinguer versions publiées et candidates, configurer Cursor et VS Code, comprendre confidentialité, fonctionnement hors ligne, limites, diagnostics et statistiques datées. Le README du paquet reste la référence rapide du paquet.
Au-delà des serveurs officiels listés ci-dessus, l’écosystème MCP comprend des serveurs communautaires validés qui étendent les capacités de Claude Code avec des intégrations spécialisées.
~/.claude.json # Config MCP à portée utilisateur (champ "mcpServers")
.mcp.json # Portée projet (racine du projet, partageable via VCS)
Note : Trois portées existent : local (par défaut, privée au projet courant, dans ~/.claude.json), project (partagée via .mcp.json à la racine du projet), et user (inter-projets, stockée sous une clé mcpServers à la racine de ~/.claude.json, disponible dans tous les projets de la machine). Deux tickets, anthropics/claude-code#16728 et #32939, ont signalé que cette portée se limitait au chemin d’un seul projet dans Claude Code 2.1.1 et 2.1.72. Tous deux ont été fermés avec not_planned. Le comportement vérifié sur 2.1.221 correspond à la portée inter-projets décrite ci-dessus, ce qui suggère une correction dans une version ultérieure. Utilisez claude mcp add --scope <scope> pour cibler une portée spécifique.
Quand true, tous les outils de ce serveur ignorent le report de recherche et sont toujours disponibles sans appel ToolSearch préalable. À utiliser pour les serveurs disposant de 1 à 5 outils critiques nécessaires à chaque tour. (v2.1.121)
En-têtes dynamiques pour plusieurs serveurs MCP (v2.1.85+)
Quand un seul script headersHelper sert plusieurs serveurs MCP, vous pouvez brancher sur CLAUDE_CODE_MCP_SERVER_NAME et CLAUDE_CODE_MCP_SERVER_URL pour retourner des tokens d’authentification ou des portées différents selon le serveur :
Chemin absolu vers la racine du projet (le répertoire depuis lequel Claude a été lancé). Injecté automatiquement dans les environnements de processus des serveurs MCP de type stdio. Utilisable également dans les chaînes command des plugins. (v2.1.139)
Avertissement : La syntaxe ${workspaceFolder} et ${env:VAR_NAME} sont des conventions VS Code, pas Claude Code. Claude Code utilise le style shell standard ${VAR} et ${VAR:-default} pour l’expansion des variables d’environnement dans la configuration MCP.
Injection d’env stdio MCP : Tous les serveurs MCP de type stdio reçoivent automatiquement CLAUDE_PROJECT_DIR comme variable d’environnement : aucune configuration requise. Cela permet aux serveurs MCP de savoir dans quel projet ils opèrent sans que le client ait à le transmettre explicitement.
Quand vous accumulez de nombreux serveurs MCP, les activer tous globalement dégrade la sélection d’outils de Claude : chaque serveur ajoute des descriptions d’outils au contexte, rendant le modèle moins précis dans le choix du bon outil.
Principe : conservez une configuration globale minimale (2-3 serveurs principaux) et activez les serveurs spécifiques au projet via .mcp.json par projet.
# Portée utilisateur (~/.claude.json "mcpServers") → toujours chargé
context7, sequential-thinking
# Portée projet (.mcp.json à la racine) → uniquement si nécessaire
postgres # projet base de données
playwright # projet frontend
serena # grande base de code
Des outils communautaires (ex. cc-setup) émergent pour proposer un registre TUI avec bascule par projet et vérifications de santé, utile si vous gérez régulièrement 8+ serveurs.
Recherche d’outils MCP : chargement différé à grande échelle
Claude Code v4 a introduit la MCP Tool Search : au lieu de charger toutes les définitions d’outils MCP au démarrage, les schémas d’outils sont récupérés à la demande lorsque Claude en a besoin.
Pourquoi c’est important : chaque serveur MCP injecte son schéma d’outils complet dans la fenêtre de contexte. Avec une douzaine de serveurs, cela représente ~77 000 tokens consommés avant même d’avoir écrit une seule invite.
Configuration
Contexte utilisé par les outils
Tous les outils chargés d’emblée
~77 000 tokens
MCP Tool Search activé
~8 700 tokens
Réduction
~85%
La précision du modèle sur les tâches de sélection d’outils (mesurée sur Opus 4) : 49% → 74% (+25 points) lors du passage du préchargement complet au chargement différé. S’active automatiquement quand les outils MCP consommeraient plus de 10% de la fenêtre de contexte.
Implication pratique : vous pouvez désormais connecter des dizaines de serveurs MCP sans la pénalité de précision liée au « trop grand nombre d’outils ». Le conseil de conserver une configuration globale minimale s’applique toujours pour les outils sans rapport, mais la MCP Tool Search change le calcul pour les grands ensembles spécifiques à un projet.
Pour exclure un serveur spécifique du report, définissez alwaysLoad: true dans sa configuration. Utilisez ceci pour les serveurs avec un petit nombre d’outils (1 à 5) dont vous savez avoir besoin à chaque session :
.claude/settings.json
{
"mcpServers": {
"my-critical-server": {
"command": "npx",
"args": ["my-mcp-server"],
"alwaysLoad": true
}
}
}
CLI vs MCP, quand une commande shell surpasse un serveur : les outils CLI familiers (git, grep, jq, curl) sont déjà profondément ancrés dans les données d’entraînement de Claude. Quelques exemples d’utilisation dans CLAUDE.md sont souvent plus efficaces qu’un serveur MCP équivalent, car le modèle connaît déjà le comportement de l’outil, ses options et son format de sortie. Un serveur MCP ajoute une surcharge de schéma d’outils et introduit une interface inconnue. Privilégiez les CLI pour les outils standard ; utilisez les serveurs MCP pour les systèmes propriétaires ou les API pour lesquels le modèle n’a pas de contexte d’entraînement.
Problème : les serveurs MCP nécessitent des clés API et des identifiants. Les stocker en texte clair dans mcp.json crée des risques de sécurité (commits Git accidentels, exposition dans les journaux, mouvement latéral après une intrusion).
Solution : séparer les secrets de la configuration en utilisant des variables d’environnement, des trousseaux de clés du système d’exploitation ou des coffres-forts de secrets.
Idéal pour : développeurs solo sur macOS/Linux avec des besoins élevés en sécurité.
Avantages : chiffré au repos, contrôle d’accès au niveau OS, pas de fichiers en texte clair
Inconvénients : spécifique à la plateforme, nécessite des scripts pour l’automatisation
Configuration du trousseau macOS :
Terminal window
# Stocker le secret dans le Trousseau
securityadd-generic-password\
-a"claude-mcp"\
-s"github-token"\
-w"ghp_your_token_here"
# Vérifier le stockage
securityfind-generic-password-s"github-token"-w
Configuration MCP avec récupération depuis le trousseau :
Idéal pour : petites équipes, prototypage rapide, sécurité suffisante avec un .gitignore approprié.
Avantages : simple, multiplateforme, intégration facile
Inconvénients : texte clair sur le disque (permissions fichier uniquement), nécessite de la rigueur
Mise en place :
Terminal window
# 1. Créer le fichier .env (racine du projet ou ~/.claude/)
Utilisateurs DB en lecture seule, tokens API à portée limitée
Surveiller les secrets exposés
GitHub secret scanning, GitGuardian
Pour les déploiements en production, envisagez le privilège permanent zéro où les serveurs MCP démarrent sans secrets et demandent des identifiants juste-à-temps lors de l’invocation des outils.
Contexte : Mergify (plateforme d’automatisation CI/CD) devait trier les tickets de support à travers 5 systèmes déconnectés, un processus manuel de 15 minutes par ticket.
Architecture : Claude Code comme orchestrateur + 5 serveurs MCP personnalisés comme adaptateurs de systèmes :
Ticket de support reçu
│
▼
┌───────────────┐
│ Claude Code │ ← orchestre, synthétise, produit le rapport
Les serveurs MCP gèrent l’auth et les identifiants. Claude Code ne voit que des interfaces propres
Les requêtes s’exécutent en parallèle, pas séquentiellement → essentiel pour le gain de temps
Les enquêteurs humains examinent le rapport structuré de Claude, pas les données brutes
Un dépôt dédié pour toutes les implémentations des serveurs MCP + le prompt système
Résultats (déclarés par Mergify, nov. 2025) :
Temps de triage : ~15 min → <5 min (réduction des ⅔)
Précision au premier passage : 75% (25% nécessitent encore un suivi humain)
Point clé : Ce schéma (Claude Code comme orchestrateur opérationnel avec des adaptateurs MCP spécifiques au domaine) s’applique à toute équipe ops/support jonglant avec plusieurs systèmes déconnectés. Il se distingue de « Claude Code comme outil de développement » : ici Claude s’exécute dans un workflow de production, pas dans un IDE.
Claude Code inclut un système de plugins complet qui vous permet d’étendre les fonctionnalités via des plugins et des marketplaces créés par la communauté ou personnalisés.
Supprimer complètement un plugin (demande confirmation avant de supprimer les données persistantes)
claude plugin uninstall security-audit
claude plugin update [name]
Mettre à jour un plugin vers la dernière version
claude plugin update security-audit
claude plugin validate <path>
Valider le manifeste d’un plugin
claude plugin validate ./my-plugin
${CLAUDE_PLUGIN_DATA}, stockage persistant des plugins (v2.1.78+) : Les plugins peuvent stocker un état qui survit aux mises à jour en utilisant la variable d’environnement ${CLAUDE_PLUGIN_DATA}. Cette variable pointe vers un répertoire dédié qui est préservé lors des mises à jour du plugin et supprimé uniquement lors d’un /plugin uninstall explicite (avec confirmation). Utilisez-le pour les caches, les préférences utilisateur ou toute donnée dont votre plugin a besoin entre les sessions.
Cas d’usage en équipe : Committez un répertoire de configuration partagée dans votre dépôt et tous les membres de l’équipe obtiennent automatiquement les mêmes plugins activés et marketplaces approuvés. Aucune configuration par utilisateur n’est nécessaire.
Depuis la v2.0.74 (décembre 2025), Claude Code s’intègre nativement avec les serveurs Language Server Protocol. Au lieu de naviguer dans votre base de code via la recherche textuelle (grep), Claude se connecte au serveur LSP de votre projet et comprend les symboles, les types et les références croisées, de la même façon qu’un IDE.
Pourquoi c’est important : Trouver tous les sites d’appel d’une fonction passe de ~45 secondes (recherche textuelle) à ~50ms (LSP). Claude obtient également des diagnostics automatiques après chaque modification de fichier. Les erreurs et avertissements apparaissent en temps réel, sans étape de compilation séparée.
Contrôle combien de temps Claude attend qu’un serveur LSP s’initialise avant de le considérer comme non réactif (v2.1.50+) :
{
"servers": {
"tsserver": { "startupTimeout": 15000 },
"pylsp": { "startupTimeout": 10000 }
}
}
Utile dans les environnements lents (CI, Docker, démarrage à froid) où les timeouts par défaut font que les fonctionnalités LSP sont silencieusement ignorées.
⚠️ Erreur courante : Ne placez pas commands/, agents/, skills/ ou hooks/ à l’intérieur de .claude-plugin/. Seul plugin.json y va.
Exemple de .claude-plugin/plugin.json :
{
"name": "security-audit",
"version": "1.0.0",
"description": "Security audit tools for Claude Code",
"author": {
"name": "Your Name"
}
}
Le manifeste définit uniquement les métadonnées. Claude Code découvre automatiquement les composants à partir de la structure de répertoires.
Espace de noms des skills : Les skills des plugins sont préfixés par le nom du plugin pour éviter les conflits :
Plugin security-audit avec le skill scan → /security-audit:scan
MCP Server = « Ce que Claude peut faire » (nouveaux outils, systèmes externes)
MCP Apps = « Ce que Claude peut afficher » (interfaces interactives dans les clients supportés)*
*Remarque : MCP Apps s’affiche dans Claude Desktop, VS Code, ChatGPT, Goose. Non supporté dans Claude Code CLI (le terminal est uniquement texte). Voir Section 8.1 pour les détails.
Les 181 templates du répertoire examples/ de ce guide sont disponibles en tant que plugins installables, sans copie de fichiers manuelle. Les hooks sont automatiquement configurés à l’installation :
Changelog, notes de version (3 formats), contenu réseaux sociaux depuis git log
code-quality
Refactoring SOLID, TDD, patterns GoF, 6 agents de revue spécialisés
pr-workflow
Jalons de planification CEO + Ing, tri PR/issues, transferts de session
session-tools
Dashboard ccboard, raffinement vocal, 11 hooks de session
ai-methodology
Scaffolding, pipeline de présentation en 6 étapes, générateur de landing page
session-summary
Dashboard analytique en fin de session (15 sections configurables)
Installez uniquement ce dont vous avez besoin. La source de vérité pour tous les templates reste dans examples/. Le dépôt plugins est la couche de distribution publiée.
Deux plugins communautaires répondent à des problèmes complémentaires que le développement assisté par IA engendre : la dérive de la qualité du code (accumulation de code mal structuré généré par IA) et les hallucinations dans les solutions générées.
Problème résolu : les outils IA écrivent du code plus vite que les équipes peuvent le maintenir. L’analyse de GitClear portant sur 211 millions de lignes montre que le refactoring est passé de 25 % à moins de 10 % de l’ensemble des modifications (2021–2025). Vitals identifie les fichiers les plus susceptibles de causer des problèmes, avant qu’ils ne surviennent.
Fonctionnement : calcule git churn × complexité structurelle × centralité de couplage pour classer les points chauds. Pas seulement « ce fichier est complexe », mais « ce fichier complexe a été modifié 49 fois en 90 jours et 63 autres fichiers se cassent quand il change ».
Terminal window
# Installation (deux commandes dans Claude Code)
/pluginmarketplaceaddchopratejas/vitals
/plugininstallvitals@vitals
# Scan depuis la racine du dépôt
/vitals:scan
# Options de périmètre
/vitals:scansrc/# Dossier spécifique
/vitals:scan--top20# Plus de résultats (défaut : 10)
/vitals:scansrc/auth--top5
Ce que vous obtenez : Claude lit les fichiers signalés et fournit un diagnostic sémantique. Au lieu de « complexité élevée », vous obtenez : « cette classe gère le routage, le cache, la limitation de débit ET les métriques en 7 137 lignes, extrayez chaque préoccupation ».
Statut : v0.1 alpha. MIT. Zéro dépendance (stdlib Python + git). Fonctionne sur n’importe quel dépôt.
Problème résolu : le code généré par IA contient des erreurs subtiles qui survivent à la revue de code parce que l’IA et le relecteur suivent le même chemin de raisonnement. SE-CoVe rompt ce schéma en exécutant un vérificateur indépendant qui ne voit jamais la solution initiale.
Fondement de recherche : adaptation de la méthodologie Chain-of-Verification de Meta (Dhuliawala et al., ACL 2024 Findings, arXiv:2309.11495).
Fonctionnement, pipeline en 5 étapes :
Baseline : Claude génère la solution initiale
Planner : crée des questions de vérification à partir des affirmations de la solution
Executor : répond aux questions sans voir la baseline (évite le biais de confirmation)
Synthesizer : compare les résultats, fait remonter les divergences
Output : produit la solution vérifiée
Terminal window
# Installation (deux commandes séparées — limitation du marketplace)
/pluginmarketplaceaddvertti/se-cove-claude-plugin
/plugininstallchain-of-verification
# Utilisation
/chain-of-verification:verify<votrequestion>
/ver<Tab># Autocomplétion disponible
Compromis : coût en tokens ~2x, volume de sortie réduit. Pertinent pour le code sensible à la sécurité, le débogage complexe et les décisions architecturales, pas pour le prototypage rapide ni les corrections simples.
Ces outils résolvent des problèmes différents à des étapes différentes du cycle de développement :
Vitals
SE-CoVe
Quand
Maintenance / revue hebdomadaire
Par tâche de génération
Problème
Dette de code accumulée
Exactitude par solution
Entrée
Tout l’historique git
Une question spécifique
Sortie
Fichiers points chauds classés + diagnostic
Réponse vérifiée
Coût en tokens
Faible (analyse Python + Claude lit les fichiers principaux)
~2x la génération standard
Idéal pour
« Quel fichier va se casser ? »
« Cette solution est-elle correcte ? »
Statut
v0.1 alpha
v1.1.1 stable
Flux de travail complémentaire : exécutez Vitals chaque semaine pour identifier les zones de la base de code qui nécessitent de l’attention, puis utilisez SE-CoVe lorsque vous demandez à Claude de refactoriser ou de corriger ces fichiers points chauds.
Toutes les modifications ne justifient pas le pipeline en 5 étapes de SE-CoVe. Pour une revue quotidienne au sein d’une même session, vous pouvez demander explicitement à Claude de passer du rôle d’auteur à celui de relecteur :
You just wrote the implementation above. Now forget you wrote it.
Review it as a senior engineer who did not author this code.
compatibility, security, performance. For each issue found, cite
the file and line, explain the problem, and propose a concrete fix.
Verdict: APPROVE, REQUEST CHANGES, or REJECT.
Cela fonctionne parce que l’instruction explicite de « oublier que vous l’avez écrit » force Claude à réévaluer plutôt qu’à défendre ses décisions antérieures. Cela détecte les problèmes de surface (vérifications null manquantes, gestion d’erreurs incohérente, dérive de nommage) mais partage le même chemin de raisonnement que l’auteur, de sorte que les défauts architecturaux subtils peuvent subsister.
Quand utiliser quoi :
Approche
Coût
Détecte
Idéal pour
Changement de rôle (même session)
1x
Problèmes de surface, nommage, bugs évidents
Développement quotidien, corrections rapides
SE-CoVe (plugin)
~2x
Angles morts du chemin de raisonnement, erreurs logiques subtiles
Code sensible à la sécurité, architecture
Revue multi-modèle (voir ci-dessous)
1x-2x
Patterns de raisonnement différents, perspective nouvelle
Un seul modèle qui relit son propre code suit les mêmes patterns de raisonnement que ceux qui ont produit le code. Utiliser un modèle différent pour la revue introduit une analyse véritablement indépendante.
Le pattern : générer avec un modèle, relire avec un autre.
Terminal window
# Implémenter avec Opus (raisonnement approfondi)
claude--modelopus
# Relire le diff avec Sonnet (chemin de raisonnement différent, coût réduit)
claude-p"Review the changes in the last commit. Check for logic errors, \
edge cases, backward compatibility, and security issues. \
Cite file:line for each finding."--modelsonnet
# Vérification rapide avec Haiku (rapide, économique, détecte les problèmes évidents)
claude-p"List any bugs, missing error handling, or security issues \
in the last commit."--modelhaiku
Avec des agents personnalisés :
.claude/agents/cross-model-reviewer.md
---
name: cross-model-reviewer
model: sonnet# Different from your working model
tools: Read, Grep, Glob
---
You are reviewing code you did not write. Your job is to find problems.
Read the files listed below, then check:
1. Logic errors and edge cases
2. Error handling completeness
3. Backward compatibility risks
4. Security issues (injection, auth gaps, data leaks)
For each finding: severity (critical/high/medium), file:line, problem, fix.
If no issues found, say so explicitly.
Pourquoi des modèles différents détectent des bugs différents : chaque modèle a des biais de raisonnement, des distributions d’entraînement et des modes d’échec distincts. Un bug qui se trouve dans l’angle mort d’un modèle peut être évident pour un autre. C’est le même principe que celui des équipes de revue de code diversifiées en ingénierie traditionnelle.
Patterns économiques :
Modèle de génération
Modèle de revue
Multiplicateur de coût
Quand
Opus
Sonnet
~1,3x
Par défaut pour le code critique
Sonnet
Haiku
~1,05x
Volume élevé, jalon pré-commit
Sonnet
Opus
~2x
Architecture, code critique pour la sécurité
N’importe lequel
Même modèle, session fraîche
~1,5x
Isolation du contexte sans changement de modèle
La variante session fraîche (même modèle, nouveau contexte via claude -p) vous donne l’isolation du contexte sans changer de modèle. Moins efficace qu’un vrai changement de modèle, mais toujours meilleure que la relecture dans la session où le code a été écrit.
Les serveurs MCP étendent les capacités de Claude Code, mais ils élargissent également sa surface d’attaque. Avant d’installer un serveur MCP, en particulier ceux créés par la communauté, appliquez le même niveau de scrutin sécurité que vous utiliseriez pour n’importe quelle dépendance de code tierce partie.
Détails CVE et vérification avancée : pour les CVE documentées (2025-53109/53110, 54135, 54136), la liste MCP Safe List et les procédures de réponse aux incidents, consultez le Guide de durcissement de la sécurité.
Un serveur MCP malveillant peut déclarer des outils avec des noms courants (comme Read, Write, Bash) qui masquent les outils natifs. Lorsque Claude invoque ce qu’il pense être l’outil Read natif, le serveur MCP intercepte l’appel.
Flux masqué : Claude → MCP malveillant "Read" → L'attaquant exfiltre le contenu
Atténuation : vérifiez les outils exposés avec la commande /mcp. Utilisez disallowedTools dans les paramètres pour bloquer les noms d’outils suspects provenant de serveurs spécifiques.
Problème du mandataire confus (Confused Deputy)
Un serveur MCP avec des privilèges élevés (accès base de données, clés API) peut être manipulé via un prompt pour effectuer des actions non autorisées. Le serveur authentifie la requête de Claude mais ne vérifie pas l’autorisation de l’utilisateur pour cette action spécifique.
Exemple : un MCP de base de données avec des identifiants administrateur reçoit une requête issue d’une injection de prompt, exécutant des opérations destructrices que l’utilisateur n’avait jamais prévues.
Atténuation : configurez toujours les serveurs MCP avec des identifiants en lecture seule par défaut. N’accordez l’accès en écriture que lorsque c’est explicitement nécessaire.
Injection de capacités dynamiques
Les serveurs MCP peuvent modifier dynamiquement leurs offres d’outils. Un serveur peut passer une revue initiale, puis injecter ultérieurement des outils supplémentaires.
Atténuation : épinglez les versions des serveurs dans votre configuration. Réauditez périodiquement les serveurs installés.
Remarque : disallowedTools est une clé de niveau racine ou un flag CLI (--disallowedTools), pas imbriqué sous permissions. Pour settings.json, utilisez permissions.deny pour bloquer les patterns d’outils.
Les versions figurant dans ce titre conservent les liens existants. Dans la gamme actuelle, Opus 5.5, Sonnet 5 et Fable 5.1 utilisent le raisonnement adaptatif. Haiku 4.5 prend en charge le thinking étendu, sans paramètre d’effort. Caractéristiques des modèles.
L’effort régit le raisonnement et peut modifier l’utilisation des outils, la longueur des réponses, la latence et le coût. Consultez le tableau des niveaux d’effort : les modèles n’ont pas tous la même valeur par défaut. Opus 5.5 utilise medium ; Sonnet 5 et Fable 5.1 utilisent high.
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=16000,
thinking={"type": "adaptive"},
output_config={"effort": "high"},
messages=[{"role": "user", "content": "Analyze the failure modes."}],
)
Opus 4.7 et les versions suivantes, Sonnet 5 et Fable utilisent exclusivement le raisonnement adaptatif. CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING et un budget fixe MAX_THINKING_TOKENS ne s’y appliquent pas. Le commutateur de compatibilité avec un budget fixe reste propre à Opus 4.6 et Sonnet 4.6.
Contrôler le mode thinking {#controlling-thinking-mode}
Choisir un effort pris en charge ; Enter l’enregistre par modèle, s l’applique à cette session
--effort high
Définir l’effort de la session lancée
CLAUDE_CODE_EFFORT_LEVEL
Remplacement explicite par variable d’environnement
modelSettings / effortLevel
Les paramètres persistants prennent en charge low à xhigh, pas max
Option+T / Alt+T, /config, MAX_THINKING_TOKENS=0
Peuvent désactiver le thinking sur les modèles compatibles ; aucun effet sur Opus 5.5 ou Fable
Ctrl+O
Ouvrir le visualiseur de transcription ; l’affichage ne modifie pas la facturation
Les tokens de thinking sont facturés même lorsque leur affichage est replié ou masqué. Définissez showThinkingSummaries: true pour rendre les résumés complets accessibles dans la vue développée. Contrôles du thinking.
Référence des anciens mots-clés {#legacy-keywords-reference}
ultrathink ajoute actuellement une consigne de raisonnement plus approfondi pour le tour. Il ne définit pas l’effort API à max. think et think hard sont du texte ordinaire dans le prompt. Pour choisir l’effort de façon déterministe, utilisez /effort ou --effort.
Changements incompatibles de l’API (Opus 4.6) {#api-breaking-changes-opus-46}
Le préremplissage assistant n’est pas pris en charge sur Opus 4.6. Consultez le guide de migration du modèle cible avant de réutiliser des exemples fondés sur ce préremplissage ; employez des instructions système, des exemples ou des sorties structurées prises en charge lorsque le préremplissage n’est pas disponible.
Pour le mode rapide, utilisez une version d’Opus compatible et les instructions actuelles de l’API. Dans Claude Code, /fast utilise Opus 5.5 par défaut depuis v2.1.280. Le tarif standard d’Opus 5.5 est de 4 $/20 $ par MTok, contre 8 $/40 $ en mode rapide. Le mode rapide des anciens Opus 5 et 4.8 coûte 10 $/50 $. La disponibilité, la prise en charge par les fournisseurs et la facturation en crédits d’usage sont distinctes du réglage de vitesse.
📖 Guide Complet des Workflows : Consultez GitHub Actions Workflows pour 5 patrons prêts pour la production utilisant l’action officielle anthropics/claude-code-action (revue de PR, triage, sécurité, maintenance planifiée).
Revue de Code (Équipes/Entreprise) : Pour une revue automatisée de PR sans invite manuelle, consultez Code Review, la fonctionnalité de revue multi-agent d’Anthropic qui publie des commentaires GitHub en ligne sur chaque PR.
Facturation : Anthropic a annoncé que les workflows de cette section (mode headless via claude -p, GitHub Actions, Agent SDK) passeraient sur un crédit programmatique mensuel distinct au 15 juin 2026, puis a suspendu ce changement. Vérifié le 2026-09-30 : ils consomment toujours les limites de votre abonnement. Auditez votre usage CI/CD avec ccusage pour être prêt si le plan reprend. Consultez §9.13 : The Interactive/Programmatic Billing Split pour le plan annoncé et un cadre de décision.
Claude Code prend en charge les opérations de pipe Unix, permettant une puissante intégration shell pour l’analyse et la transformation automatisées de code.
Fonctionnement du piping :
Terminal window
# Piper du contenu vers Claude avec une invite
catfile.txt|claude-p'analyze this code'
# Piper la sortie d'une commande pour analyse
gitdiff|claude-p'explain these changes'
# Chaîner des commandes avec Claude
npmtest2>&1|claude-p'summarize test failures and suggest fixes'
Patrons courants :
Automatisation de la revue de code :
Terminal window
gitdiffmain...feature-branch|claude-p'Review this diff for security issues'
Analyse de logs :
Terminal window
tail-n100/var/log/app.log|claude-p'Find the root cause of errors'
Analyse de la sortie de tests :
Terminal window
npmtest2>&1|claude-p'Create a summary of failing tests with priority order'
Génération de documentation :
Terminal window
catsrc/api/*.ts|claude-p'Generate API documentation in Markdown'
Note Windows : Les Git hooks s’exécutent dans Git Bash sous Windows, la syntaxe bash ci-dessous fonctionne donc. Vous pouvez également créer des versions .cmd ou .ps1 et les référencer depuis un script wrapper.
Hook pre-commit :
.git/hooks/pre-commit
#!/bin/bash
# Exécuter Claude Code pour la validation du message de commit
COMMIT_MSG=$(cat"$1")
claude-p"Is this commit message good? '$COMMIT_MSG'. Reply YES or NO with reason."
Hook pre-push :
.git/hooks/pre-push
#!/bin/bash
# Vérification de sécurité avant le push
claude-p"Scan staged files for secrets and security issues. Exit 1 if found."
Focus on security, performance, and code quality. \
Output as markdown." --bare
Flag --bare pour les scripts CI (v2.1.81+) : Ajoutez --bare à tout appel claude -p pour obtenir un environnement d’exécution déterministe et hermétique. Il désactive les hooks, LSP, la synchronisation des plugins et le scan des répertoires de compétences, garantissant que la configuration locale du développeur ne s’infiltre jamais dans la CI. Nécessite ANTHROPIC_API_KEY (pas d’OAuth/keychain). Désactive également la mémoire automatique.
Terminal window
# Sans --bare : récupère les hooks locaux, plugins, compétences — non déterministe en CI
Une alternative à la génération de notes de version à partir des commits consiste à capturer le contexte pendant l’implémentation, et non au moment de la publication. Le schéma des « changelog fragments » remplace un fichier CHANGELOG.md partagé par un fichier YAML par PR, accumulés dans changelog/fragments/ et assemblés automatiquement à la publication.
Le problème fondamental des approches basées sur les commits : au moment où vous exécutez git log pour générer des notes de version, le contexte a disparu. Le développeur qui a corrigé une situation de compétition il y a trois semaines est le seul à avoir compris l’impact. Le message de commit dit fix SSE handling.
Le schéma des fragments résout ce problème avec 3 couches d’application :
Couche 1, règle CLAUDE.md : Chargez une règle git-workflow.md qui encode le flux de travail complet des fragments. Lorsqu’un développeur demande à Claude Code de « créer la PR », il lit le diff, déduit le type, la portée et le titre, génère le YAML, le valide et le commite dans la branche. Claude gère cela de manière autonome.
title: "Fix empty chat after starting activity due to SSE race condition"
description: |
SSE workplan fires before AI stream completes, causing ChatWrapper to mount
with 0 messages. Added isStartingActivityRef guard and await response.text().
breaking: false
migration: false
Couche 2, hook UserPromptSubmit : Détecte l’intention de création de PR et vérifie si le fragment a déjà été mentionné.
Terminal window
# Tier 0 enforcement in smart-suggest.sh
ifecho"$PROMPT_LC"|grep-qE'(create.*pr|make.*pr|pull.?request)'; then
if!echo"$PROMPT_LC"|grep-qE'(changelog|fragment|skip-changelog)'; then
suggest"pnpm changelog:add""REQUIRED before merge — fragment missing"
else
suggest"/pr""PR creation with structured description"
fi
fi
Le hook est non bloquant et affiche une suggestion en ligne, avant que Claude traite le prompt. Si le fragment est déjà mentionné, le hook reste silencieux et suggère la commande PR habituelle.
Couche 3, contrôle CI : Deux jobs GitHub Actions indépendants. Le premier valide l’existence et la structure du fragment. Le second vérifie que migration: true est défini si la PR ajoute des fichiers de migration SQL, ce job s’exécute indépendamment des labels de contournement, car une PR « skip-changelog » peut tout de même ajouter une migration que l’équipe de déploiement doit connaître.
Assemblage à la publication :
Terminal window
pnpmchangelog:assemble--version1.8.0 [--dry-run]
Lit tous les fragments, les regroupe par type, insère une section versionnée dans CHANGELOG.md en remplaçant un marqueur ## [Next Release], et archive les fragments dans changelog/fragments/released/{version}/.
Avantages par rapport à la génération basée sur les commits :
Zéro conflit de fusion (chaque fragment est un fichier unique par PR)
Contexte rédigé au moment de l’implémentation, non reconstruit ultérieurement
Migrations de base de données explicitement signalées dans chaque fragment
Le contournement est auditable (liste de labels fermée visible dans l’historique des PR)
Claude Code peut automatiser les déploiements vers Vercel, GCP et d’autres plateformes en utilisant des identifiants stockés. L’essentiel est d’assembler trois composants : la gestion des secrets, une compétence de déploiement et des garde-fous obligatoires.
Pour les secrets multi-plateformes (GitHub, Vercel, AWS simultanément), Infisical offre une gestion centralisée avec versionnage et récupération à un instant donné, une alternative open source utile à HashiCorp Vault :
Terminal window
# Install infisical CLI
brewinstallinfisical/get-cli/infisical
# Inject secrets into Claude Code session
infisicalrun--claude
# Infisical automatically sets all project secrets as env vars
Ces garde-fous ne sont pas optionnels. Les déploiements en production sans eux créent des incidents :
Garde-fou
Implémentation
Pourquoi
Staging en premier
Toujours déployer en staging avant la prod
Détecter les échecs spécifiques à l’environnement
Confirmation humaine
S’arrêter et demander avant le flag --prod
Aucun déploiement autonome en production
Test de fumée
Vérifier HTTP 200 sur les points de terminaison clés après déploiement
Détecter les échecs silencieux de déploiement
Retour arrière prêt
Conserver l’ID de déploiement précédent avant la promotion
vercel rollback <deployment-id>
Hook de confirmation (prévenir les déploiements accidentels en production) :
.claude/settings.json
{
"hooks": {
"PreToolUse": [{
"matcher": "Bash",
"hooks": [{
"type": "command",
"command": "scripts/check-prod-deploy.sh"
}]
}]
}
}
#!/bin/bash
# check-prod-deploy.sh — exit 2 to block, exit 0 to allow
INPUT=$(cat)
ifecho"$INPUT"|grep-q"vercel deploy --prod\|gcloud deploy.*production"; then
echo"BLOCKED: Production deploy requires manual confirmation. Run the command directly from your terminal."
exit2
fi
exit0
Sources : Schéma de compétence de déploiement Vercel documenté par la communauté (lobehub.com, haniakrim21) ; gestion des secrets multi-plateformes avec Infisical sur infisical.com. Aucun flux de déploiement automatisé de bout en bout n’existe dans la communauté à la date de mars 2026, les éléments de base sont disponibles, mais le schéma de promotion du staging vers la production est quelque chose que chaque équipe assemble elle-même.
Nouveau : Xcode 26.3 RC+ inclut la prise en charge native de Claude Agent SDK, utilisant le même mécanisme que Claude Code :
Prérequis : Xcode 26.3 RC ou version ultérieure (macOS)
Configuration : Définir la clé API dans Xcode → Preferences → Claude
Utiliser :
Assistant de code intégré propulsé par Claude
Mêmes capacités que Claude Code CLI
Intégration native avec les flux de travail Xcode
Claude Agent SDK : Produit distinct de Claude Code, mais partageant le même framework d’exécution d’agents. Permet de créer des outils de développement propulsés par Claude dans des IDE au-delà de VS Code.
Remarque : Claude Agent SDK n’est pas Claude Code, c’est le framework d’Anthropic pour construire des outils de développement alimentés par des agents. Claude Code CLI et l’intégration Xcode utilisent tous deux ce SDK.
Les boucles de retour rapides accélèrent l’apprentissage et détectent les problèmes tôt. Concevez votre flux de travail pour valider les modifications immédiatement.
Problème : Le développement fullstack nécessite souvent des processus de longue durée (serveurs de développement, watchers) qui bloquent la session Claude principale, empêchant le travail itératif sur le frontend.
Solution : Utiliser Ctrl+B pour mettre les tâches en arrière-plan et maintenir des boucles de retour rapides sur l’ensemble de la pile.
Problème : Les tâches de longue durée en arrière-plan peuvent provoquer une dégradation du contexte, Claude perd conscience de ce qui est en cours d’exécution.
Solution : Vérifier périodiquement l’état des tâches :
Terminal window
# Before major changes
/tasks
# Output example:
# Task 1 (background): pnpm dev:backend
# Status: Running (35 minutes)
# Last output: Server listening on :3000
Bonnes pratiques :
Mettre les tâches en arrière-plan au démarrage de la session (phase de configuration)
Vérifier /tasks avant les changements d’architecture majeurs
Redémarrer les tâches mises en arrière-plan si le contexte est perdu
Utiliser des commandes descriptives (pnpm dev:backend plutôt que npm run dev)
Pas de commande de retour au premier plan : Impossible de ramener les tâches au premier plan (pour l’instant)
Perte de contexte : Les tâches de longue durée peuvent perdre leur pertinence par rapport au travail en cours
Sortie non diffusée : La sortie des tâches en arrière-plan n’est pas visible sans vérification
Liées à la session : Les tâches en arrière-plan sont attachées à la session Claude et arrêtées à sa fermeture
Solution de contournement pour le retour au premier plan : Si vous devez interagir avec une tâche mise en arrière-plan, la redémarrer au premier plan :
💡 Idée clé : Les tâches en arrière-plan optimisent les flux de travail fullstack en découplant l’infrastructure (serveurs, watchers) du développement itératif. Utilisez-les de manière stratégique pour maintenir des boucles de retour rapides sur l’ensemble de la pile.
Toutes les boucles ci-dessus valident le code. Aucune n’indique à Claude si l’interface utilisateur est réellement correcte, si un formulaire fonctionne, ou si la page s’affiche sans erreur. Sans connexion au navigateur, Claude ne peut qu’inférer : il écrit du code et suppose que le résultat correspond à l’intention.
Claude dans Chrome comble cette lacune. Il s’agit d’une extension Chrome qui donne à Claude Code un contrôle direct sur votre navigateur : naviguer vers des URL, cliquer sur des éléments, lire la console, remplir des formulaires, prendre des captures d’écran et observer le résultat rendu de ce qu’il vient de construire.
Configuration :
Installer l’extension Claude dans Chrome depuis le Chrome Web Store
L’activer pour votre session :
Terminal window
claude--chrome# start with Chrome integration enabled
claude--no-chrome# disable for this session
/chrome# check connection status / manage permissions
Ce que Claude peut faire avec l’accès à Chrome :
Capacité
Utilisation pratique
Naviguer vers localhost
Vérifier que la page s’affiche après une modification
Lire les erreurs de console
Sans copier-coller ; Claude voit les erreurs directement
Parcourir les flux
Tester qu’une soumission de formulaire fonctionne réellement
Capture d’écran + comparaison
Vérifier le rendu visuel par rapport aux attentes
Remplir les champs
Tester la validation, les cas limites, les états vides
L’idée clé de Boris Cherny (créateur de Claude Code) : « Si Claude ne peut pas voir le résultat, il ne peut pas l’améliorer. » Les boucles de retour sur le code détectent les erreurs de syntaxe et de logique. Les boucles de retour via le navigateur détectent le reste : mise en page, interactions, erreurs d’exécution.
Quand /chrome est masqué : Claude Code masque la commande /chrome lorsqu’aucune intégration Chrome n’est disponible pour votre configuration d’authentification actuelle (v2.1.87+). Vérifiez que l’extension est installée et que Chrome est en cours d’exécution si elle n’apparaît pas.
Introduit dans la v2.0.72 sous le nom “Claude in Chrome Beta”. Les flags --chrome/--no-chrome et la commande /chrome contrôlent l’intégration au navigateur. Cela est distinct du serveur MCP claude-in-chrome, qui est un mécanisme d’automatisation du navigateur différent.
Temps de lecture : 5 minutes
Niveau de compétence : Semaine 1+
Contrôlez comment Claude répond pour correspondre à votre flux de travail et à vos préférences d’apprentissage. Les styles de sortie sont une fonctionnalité intégrée du produit, pas une astuce de prompt, et s’appliquent au niveau de la session.
Le paramètre persiste entre les sessions. Si vous avez configuré une barre de statut, votre style de sortie actuel s’affiche en bas du champ de saisie.
Explanatory et Learning produisent des réponses plus longues par conception, ce qui augmente les tokens de sortie. La mise en cache peut réduire le coût des entrées répétées, mais ne réduit pas le prix des tokens générés.
Les styles de sortie personnalisés sont des fichiers Markdown. Placez les styles du projet dans .claude/output-styles/ ou les styles utilisateur dans ~/.claude/output-styles/, puis référencez le nom du fichier sans extension comme valeur outputStyle.
.claude/output-styles/
└── strict-reviewer.md # Définition du style personnalisé
Par défaut, un style personnalisé omet les instructions de génie logiciel intégrées à Claude Code. Pour un style destiné au code, conservez-les avec keep-coding-instructions: true dans le frontmatter YAML du fichier. Le style sélectionné s’applique au message suivant. Redémarrez pour découvrir de nouveaux fichiers de style.
{
"outputStyle": "strict-reviewer"
}
Consultez examples/styles/ pour un modèle de style personnalisé prêt à l’emploi.
Claude Code peut générer des diagrammes Mermaid pour la documentation visuelle. C’est utile pour la documentation d’architecture, la visualisation des flux et la compréhension des systèmes.
Jens Rusitschka identifie la « surcharge du contexte » comme le principal mode d’échec du vibe coding : déverser des bases de code entières dans le contexte en espérant que Claude s’y retrouve.
Symptômes :
Coller plus de 5K lignes de code dans le premier prompt
« Lis tout le dépôt et implémente X »
Attendre de Claude qu’il conserve le contexte sur plus de 20 modifications de fichiers
Dégradation des performances après pollution du contexte (voir §2.2 Pattern de contexte neuf)
Pourquoi cela échoue :
Attention dispersée entre trop de fichiers et de sujets
Raisonnement architectural perdu dans le bruit
Accumulation des tentatives échouées, qui dégrade encore la qualité
Interférences de contexte entre des tâches sans rapport
Stratégie de contexte par phases :
Au lieu de tout charger d’un coup, utilisez une approche progressive fondée sur les fonctionnalités natives de Claude Code :
Phase
Outil
Objectif
Taille du contexte
1. Exploration
Mode /plan
Analyse en lecture seule, investigation sûre
Maîtrisée (le plan consigne les observations)
2. Implémentation
Mode normal
Exécuter les modifications planifiées
Ciblée (le plan guide le périmètre)
3. Nouveau départ
Passation de session
Repartir à zéro lorsque le contexte dépasse 75%
Minimale (document de passation uniquement)
Workflow pratique :
Terminal window
# Phase 1: Exploration (read-only, safe)
/plan
You:"How should I refactor the auth system for OAuth?"
Le « Vibe Coding, Level 2 » de Rusitschka correspond au workflow natif de Claude Code ; il suffit de le présenter explicitement comme une réponse à cet anti-pattern. Le mode plan évite la pollution du contexte pendant l’exploration, le contexte neuf évite l’accumulation pendant l’implémentation, et les passations permettent des transitions propres entre les phases.
Lutter contre la dégradation du vibe code {#fighting-vibe-code-degradation}
Le vibe coding permet de construire vite. Les bases de code qu’il produit ont tendance à se dégrader de manière peu visible : les abstractions dérivent, le nommage devient incohérent, les erreurs sont gérées de trois façons différentes. Le code fonctionne encore, mais y travailler devient progressivement plus difficile.
Le « slop », terme introduit par Simon Willison en 2024 pour désigner le contenu IA non souhaité et non relu, est le problème de qualité que le vibe coding à grande échelle produit inévitablement.
Desloppify (github.com/peteromallet/desloppify) est un outil communautaire qui s’attaque directement à ce problème. Il installe un guide de workflow dans Claude Code sous forme de skill, puis exécute une boucle de corrections priorisées : analyser → obtenir le problème suivant → corriger → marquer comme résolu → recommencer jusqu’à atteindre le score de qualité visé. Le score est conçu pour résister aux manipulations : l’améliorer exige d’améliorer réellement le code.
Terminal window
pipinstall--upgrade"desloppify[full]"
desloppifyupdate-skillclaude# installs workflow as a Claude Code skill
# Before scanning: exclude generated files, build output, vendored code
desloppifyexcludenode_modules
desloppifyexclude.next
desloppifyscan--path.
desloppifynext# get first prioritized fix
# fix it, then:
desloppifyresolve<issue-id>
desloppifynext# repeat
La boucle traite les problèmes mécaniques (code mort, duplication, complexité) et structurels (clarté du nommage, conception des abstractions, frontières des modules). Un score supérieur à 98 est censé correspondre à ce qu’un ingénieur senior qualifierait de base de code propre.
Statut : Projet récent (publié en février 2026, environ 2K étoiles GitHub ; 2 996 au 2026-07-27). L’intégration native à Claude Code est prometteuse, mais n’a pas encore fait ses preuves à grande échelle. Évaluez le coût en tokens avant de l’exécuter sur de grandes bases de code : une revue LLM en plusieurs passes sur l’ensemble d’une base peut coûter cher.
Temps de lecture : 5 minutes
Niveau de compétence : Semaine 1+
Les opérations par lots améliorent l’efficacité et réduisent l’usage du contexte lorsqu’on applique des modifications similaires à plusieurs fichiers. Pour réduire le coût du traitement en volume via l’API, l’API Message Batches d’Anthropic (client.messages.batches) traite jusqu’à 100 requêtes de façon asynchrone pour 50% du coût synchrone (voir la section Patterns API pour son utilisation complète).
Les opérations par lots s’étendent au-delà des modifications de code. Le même pattern s’applique aux pipelines de conversion de fichiers avec les outils natifs de macOS, sans dépendance externe.
Cas d’usage : convertir un dossier de présentations PPTX en PDF avec Keynote.
Terminal window
# Requirements: macOS + Keynote installed. No LibreOffice, no Python.
./pptx-to-pdf.sh~/Downloads/Prose# recursive, processes all subdirectories
Trouve récursivement tous les fichiers .pptx du dossier cible
Ignore les fichiers dont le .pdf existe déjà (idempotent, peut être relancé sans risque)
Ouvre chaque fichier via le shell, exporte en PDF via AppleScript, puis ferme Keynote
Affiche à la fin un récapitulatif de tous les PDF générés
Piège à connaître : ouvrir via le shell, pas via AppleScript :
L’approche intuitive échoue :
-- This triggers error -1719 "Index non valable" on ~12% of files
tellapplication"Keynote"to open pptx_file
-- document 1 is sometimes empty, AppleScript throws on access
La correction consiste à utiliser open -a "Keynote" "$pptx" depuis le shell avant le bloc AppleScript, avec une pause de 8 secondes pour laisser Keynote enregistrer complètement le document. Lorsque Keynote ouvre un fichier par sa propre commande open, il ne l’ajoute pas toujours à la liste documents. Lorsque le shell lui transmet le chemin avec open -a, il le fait.
Terminal window
# Correct pattern
open-a"Keynote""$pptx"# shell open
sleep8# wait for Keynote to register the document
osascript<<EOF
tell application "Keynote"
if (count of documents) > 0 then
export document 1 to (POSIX file "$pdf") as PDF
close document 1 saving no
end if
end tell
EOF
Ce même pattern, ouverture par le shell puis AppleScript, s’applique à toute application macOS prenant en charge les scripts mais dont l’enregistrement des documents via sa propre commande open est peu fiable.
L’objectif n’est pas seulement d’utiliser l’IA pour coder, c’est d’améliorer continuellement le flux de travail afin que l’IA produise de meilleurs résultats avec moins d’interventions.
Voir aussi : §2.5 From Chatbot to Context System, le cadre à quatre couches (CLAUDE.md, skills, hooks, mémoire) qui rend cette mentalité opérationnelle.
Charger l’intégralité d’un monorepo quand vous n’avez besoin que d’un seul package
Maximiser les budgets de réflexion/tours pour des tâches simples (perte de temps et d’argent)
Négliger le nettoyage des sessions, les anciennes sessions s’accumulent et ralentissent Claude Code
Utiliser des prompts de réflexion approfondie pour des modifications triviales comme des corrections de fautes de frappe
Maintenir le contexte à 90%+ pendant de longues périodes
Charger de gros fichiers binaires ou du code généré dans le contexte
Exécuter des opérations MCP coûteuses dans des boucles serrées
✅ À faire :
Utiliser --add-dir pour autoriser l’accès aux outils dans des répertoires en dehors du répertoire de travail actuel
Gérer le mode de réflexion pour l’efficacité des coûts :
Tâches simples : Alt+T pour désactiver la réflexion → plus rapide, moins cher
Tâches complexes : choisir l’effort ; Opus 5.5 et Fable gardent le thinking actif
Le mot-clé ultrathink ajoute une consigne sans changer l’effort API
Définir cleanupPeriodDays dans la configuration pour élaguer automatiquement les anciennes sessions
Réactiver les résumés de réflexion si nécessaire : ajouter "showThinkingSummaries": true dans settings.json (désactivé par défaut dans les sessions interactives depuis v2.1.89)
Utiliser /compact de manière proactive quand le contexte atteint 70%
Bloquer les fichiers sensibles avec permissions.deny dans settings.json
Surveiller les coûts avec /status et ajuster le modèle/les niveaux de réflexion en conséquence
Mettre en cache les calculs coûteux en mémoire avec Serena MCP
Négliger le contexte du projet (CLAUDE.md), entraîne des corrections répétées
Utiliser des prompts vagues comme « corrige ça » ou « vérifie mon code »
Ignorer les erreurs dans les journaux ou rejeter les avertissements
Automatiser des flux de travail sans les tester d’abord dans des environnements sûrs
Accepter les modifications sans examen des diffs
Travailler sans contrôle de version ni sauvegardes
Mélanger plusieurs tâches non liées dans une même session
Oublier de committer après avoir terminé les tâches
✅ À faire :
Maintenir et mettre à jour CLAUDE.md régulièrement avec :
La pile technologique et les versions
Les conventions et motifs de codage
Les décisions d’architecture
Les pièges courants spécifiques à votre projet
Être précis et orienté objectifs dans les prompts en utilisant le format WHAT/WHERE/HOW/VERIFY
Surveiller via les journaux ou OpenTelemetry selon les besoins
Tester l’automatisation d’abord dans des environnements de développement/staging
Toujours examiner les sorties de l’agent avant d’accepter, surtout les sorties soignées (voir le Paradoxe des Artefacts ci-dessous)
Utiliser des branches git pour les modifications expérimentales
Décomposer les tâches complexes en sessions ciblées
Committer fréquemment avec des messages descriptifs
⚠️ Le Paradoxe des Artefacts : Anthropic AI Fluency Index (fév. 2026)
La recherche Anthropic sur 9 830 conversations Claude révèle un résultat critique contre-intuitif : lorsque Claude produit un artefact soigné (code, fichiers, configurations), les utilisateurs deviennent mesurement moins critiques, pas plus.
Comparé aux sessions sans production d’artefact :
−5,2pp de probabilité d’identifier un contexte manquant
−3,7pp de probabilité de vérifier les faits de la sortie
−3,1pp de probabilité de remettre en question le raisonnement
Les utilisateurs deviennent effectivement plus directifs (+14,7pp pour clarifier les objectifs, +14,5pp pour spécifier le format), mais leur évaluation critique chute précisément quand la sortie semble terminée.
Pour Claude Code, c’est le cas nominal. Chaque fichier généré, chaque test écrit, chaque configuration créée est un artefact. La sortie soignée qui compile et s’exécute est exactement le moment où vous devriez appliquer le plus de rigueur, pas le moins.
Contre-mesures :
Exécuter les tests avant d’accepter le code généré, pas après
Demander explicitement : « Quels cas limites ou exigences n’avez-vous pas traités ? »
Essayer de tout apprendre d’un coup, accablant et inefficace
Sauter les bases pour passer directement aux fonctionnalités avancées
Attendre la perfection de l’IA : c’est un outil, pas de la magie
Blâmer Claude pour les erreurs sans revoir vos prompts
Travailler isolément sans consulter les ressources de la communauté
Abandonner après la première frustration
Faire confiance aux sorties de l’IA sans vérification proportionnelle : le code produit par l’IA contient 1,75× plus d’erreurs logiques que le code humain (source). Adaptez l’effort de vérification au niveau de risque (voir Section 1.7)
✅ À faire :
Suivre un parcours d’apprentissage progressif :
Semaine 1 : Commandes de base, gestion du contexte
Semaine 2 : CLAUDE.md, permissions
Semaine 3 : Agents et commandes
Mois 2+ : Serveurs MCP, patterns avancés
Commencer par des tâches simples et à faible risque
Itérer sur les prompts en fonction des résultats
Consulter régulièrement ce guide et les ressources communautaires
Rejoindre les communautés Claude Code (Discord, discussions GitHub)
Partager les apprentissages et poser des questions
Célébrer les petites victoires et suivre les gains de productivité
Liste de contrôle d’apprentissage :
□ Semaine 1 : Installation et utilisation de base
□ Installer Claude Code avec succès
□ Compléter la première tâche (modification simple)
□ Comprendre la gestion du contexte (utiliser /compact)
□ Apprendre les modes de permission (essayer le Plan Mode)
□ Semaine 2 : Configuration et mémoire
□ Créer le CLAUDE.md du projet
□ Configurer .gitignore correctement
□ Configurer les permissions dans settings.local.json
□ Utiliser efficacement les références @file
□ Semaines 3-4 : Personnalisation
□ Créer son premier agent personnalisé
□ Créer sa première commande personnalisée
□ Configurer au moins un hook
□ Explorer un serveur MCP (suggestion : Context7)
□ Mois 2+ : Patterns avancés
□ Implémenter le pattern Trinity (Git + TodoWrite + Agent)
□ Mettre en place l'intégration CI/CD
□ Configurer le mode OpusPlan
□ Construire des patterns de workflow d'équipe
Anti-patterns en entreprise (données sectorielles 2026)
Sur la base des recherches Anthropic menées auprès de plus de 5 000 organisations, ces anti-patterns sont apparus comme les erreurs les plus coûteuses dans l’adoption du codage agentique.
Les worktrees Git (disponibles depuis Git 2.5.0, juillet 2015) créent plusieurs répertoires de travail à partir du même dépôt, chacun étant extrait sur une branche différente.
Problème du flux de travail traditionnel :
Terminal window
# Travail sur la fonctionnalité A
gitcheckoutfeature-a
# 2 heures de travail...
# Correctif urgent nécessaire
gitstash# Sauvegarder le travail en cours
gitcheckoutmain
gitcheckout-bhotfix
# Corriger le bug...
gitcheckoutfeature-a
gitstashpop# Reprendre le travail
Solution avec les worktrees :
Terminal window
# Configuration unique
gitworktreeadd../myproject-hotfixhotfix
gitworktreeadd../myproject-feature-afeature-a
# Travailler en parallèle
cd../myproject-hotfix# Terminal 1
claude# Corriger le bug
cd../myproject-feature-a# Terminal 2
claude# Continuer le travail sur la fonctionnalité
Quand utiliser les worktrees :
✅ Utilisez les worktrees quand :
Vous travaillez sur plusieurs fonctionnalités simultanément
Vous avez besoin de tester différentes approches en parallèle
Vous révisez du code tout en développant
Vous exécutez de longs builds CI/CD pendant que vous codez
Vous maintenez plusieurs versions (support v1 + développement v2)
❌ N’utilisez pas les worktrees quand :
Un simple changement de branche suffit
L’espace disque est limité (chaque worktree = répertoire de travail complet)
L’équipe n’est pas familière avec les worktrees (ajoute de la complexité)
Les worktrees isolent les changements, pas le comportement. Chaque worktree possède ses propres fichiers et sa branche, mais tous partagent les métadonnées Git du dépôt, notamment la liste des stashes (un git stash effectué dans un worktree apparaît dans git stash list dans les autres), ainsi que vos identifiants, les services locaux comme les bases de données et les serveurs de développement, et l’accès réseau. Des agents qui partagent un seul worktree sont encore plus exposés : lors du portage de Bun de Zig vers Rust, des agents parallèles ont exécuté git stash et git reset sur le travail des autres jusqu’à ce que le workflow interdise ces commandes (étude de cas). Pour un travail de confiance, ce compromis est généralement acceptable. Des agents non surveillés qui consomment du contenu non fiable ont besoin d’un véritable sandbox et d’identifiants à portée limitée (isolation par sandbox).
Commandes du cycle de vie d’un worktree :
Le cycle de vie complet d’un worktree est couvert par 4 commandes complémentaires :
Commande
Objectif
/git-worktree
Créer un worktree avec validation de branche, dépendances en lien symbolique, vérifications en arrière-plan
/git-worktree-status
Vérifier les tâches de validation en arrière-plan (vérification de types, tests, build)
/git-worktree-remove
Supprimer un worktree unique en toute sécurité avec vérifications de merge et nettoyage de la base de données
/git-worktree-clean
Nettoyage par lots des worktrees obsolètes avec rapport d’utilisation du disque
Terminal window
# Créer avec préfixe automatique et node_modules en lien symbolique
💡 Conseil, lien symbolique node_modules : La commande /git-worktree crée par défaut un lien symbolique vers node_modules depuis le worktree principal, économisant ~30 secondes par création de worktree et un espace disque significatif. Utilisez --isolated quand vous avez besoin de dépendances fraîches (par ex. pour tester des mises à jour).
Gestion des worktrees :
Terminal window
# Lister tous les worktrees
gitworktreelist
# Supprimer un worktree (après le merge de la fonctionnalité)
gitworktreeremove.worktrees/feature/new-api
# Nettoyer les références de worktrees obsolètes
gitworktreeprune
💡 Conseil d’équipe, alias shell pour une navigation rapide entre les worktrees : L’équipe Claude Code utilise des alias à une seule lettre pour naviguer instantanément entre les worktrees :
Terminal window
# ~/.zshrc or ~/.bashrc
aliasza="cd .worktrees/feature-a"
aliaszb="cd .worktrees/feature-b"
aliaszc="cd .worktrees/feature-c"
aliaszlog="cd .worktrees/analysis"# Dedicated worktree for logs & queries
Le worktree « analysis » dédié est utilisé pour consulter les logs et exécuter des requêtes de base de données sans polluer les branches de fonctionnalités actives.
# Flag --worktree / -w : crée un worktree temporaire basé sur HEAD
claude--worktree
claude-w
Le worktree est créé automatiquement, Claude s’y exécute, et il est nettoyé à la sortie (si aucune modification n’a été effectuée).
Changement majeur (v2.1.133) : worktree.baseRef est désormais défini par défaut sur fresh, annulant le comportement de la v2.1.128 où EnterWorktree créait une branche depuis le HEAD local. Si vous avez des commits non poussés dont vous avez besoin dans la branche du worktree, définissez explicitement worktree.baseRef: "head".
worktree.baseRef (fresh | head, défaut : fresh) : contrôle le commit de base pour les worktrees créés via --worktree, EnterWorktree et les worktrees d’isolation des agents.
Valeur
Comportement
fresh
Branche depuis origin/<default-branch>, toujours une base distante propre
head
Branche depuis le HEAD local, inclut les commits non poussés
Définissez isolation: "worktree" dans le frontmatter d’un agent pour le faire spawner automatiquement dans un worktree vierge à chaque exécution (v2.1.50+) :
---
name: refactoring-agent
description: Large-scale refactors that must not pollute the main working tree
model: opus
isolation: "worktree"# Each invocation gets its own isolated checkout
---
Perform the requested refactoring. Commit your changes inside the worktree.
Cela remplace l’ancien modèle consistant à passer manuellement isolation: "worktree" à chaque appel de l’outil Task.
Configuration VCS personnalisée avec les événements de hook (v2.1.50+)
Le hook ConfigChange se déclenche à chaque modification d’un fichier de configuration pendant une session. Utilisez-le pour auditer ou bloquer les modifications de configuration en direct non autorisées, particulièrement utile dans les environnements d’entreprise avec des hooks de politique gérés.
.claude/settings.json
{
"hooks": {
"ConfigChange": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "scripts/audit-config-change.sh"
}
]
}
]
}
}
Exemple de audit-config-change.sh (journaliser + bloquer optionnellement) :
Note entreprise : disableAllHooks (v2.1.49+) ne peut plus contourner les hooks gérés : les hooks définis via une politique organisationnelle s’exécutent toujours, indépendamment de ce paramètre. Seuls les hooks non gérés sont affectés.
Déploiement de fragments de politique avec managed-settings.d/ (v2.1.83+)
Dans les organisations multi-équipes, modifier un unique managed-settings.json génère des conflits de merge et une surcharge de coordination. Le répertoire drop-in managed-settings.d/ résout ce problème : chaque fichier est un fragment de politique indépendant que Claude Code fusionne par ordre alphabétique au démarrage.
/etc/claude-code/managed-settings.d/
├── 00-security-baseline.json # De l'équipe sécurité
├── 10-allowed-tools.json # De l'équipe plateforme
└── 50-team-hooks.json # De l'équipe individuelle
Chaque fragment suit le même schéma que managed-settings.json. Les conflits sont résolus par ordre de fusion (alphabétique). Cela permet à la sécurité de fournir une base globale sans empêcher les équipes de déployer leurs propres fragments de manière indépendante.
Par défaut, si Claude Code ne peut pas démarrer le sandbox (macOS Seatbelt / Linux seccomp indisponible), il revient silencieusement à une exécution non sandboxée. Dans les environnements sensibles à la sécurité, ce repli silencieux constitue un risque de conformité.
Définissez sandbox.failIfUnavailable: true dans managed-settings.json pour échouer explicitement à la place :
{
"sandbox": {
"failIfUnavailable": true
}
}
Recommandé pour : les environnements réglementés (SOC 2, HIPAA), les runners CI où la disponibilité du sandbox est garantie, tout contexte où un repli non sandboxé est inacceptable.
Isolation des identifiants dans les sous-processus : CLAUDE_CODE_SUBPROCESS_ENV_SCRUB (v2.1.83+)
Par défaut, les sous-processus spawned par Claude Code (outil Bash, hooks, stdio MCP) héritent de l’environnement shell complet, incluant les clés API Anthropic et les identifiants des fournisseurs cloud. Définissez CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1 pour supprimer ces identifiants avant l’exécution des sous-processus :
Terminal window
exportCLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1
Cela supprime ANTHROPIC_API_KEY, AWS_*, GOOGLE_*, AZURE_* et les variables similaires des fournisseurs cloud de l’environnement des sous-processus. Les propres appels API de Claude Code ne sont pas affectés, seuls les processus enfants sont restreints.
Quand activer : tout hook ou script MCP qui effectue des appels réseau sortants et ne devrait pas avoir accès à vos identifiants API.
Isolation de Branche de Base de Données avec les Worktrees
Lorsque plusieurs agents s’exécutent en parallèle dans des worktrees, le problème le plus difficile est la coordination, pas la configuration. Il n’existe pas de détection automatique intégrée des dépendances entre les agents de worktree. Vous la gérez explicitement.
Le modèle : analyser les fichiers touchés, puis définir blockedBy manuellement
Avant de lancer des agents en parallèle, identifiez quelles tâches partagent des fichiers :
Terminal window
# Vérification rapide des dépendances : lister les fichiers que chaque tâche touchera
# Pas de chevauchement ? Parallélisation sécurisée.
# Chevauchement détecté ? Les séquencer.
Dans l’API Tasks, créez d’abord les tâches, puis ajoutez les dépendances avec TaskUpdate à partir de leurs identifiants :
Create task A: implement and merge the auth change.
Create task B: implement the payment service.
Use TaskUpdate to make B depend on A using their returned IDs.
Matrice de décision :
Scénario
Stratégie
Les tâches touchent des fichiers différents, des modules différents
Paralléliser librement
Les tâches touchent le même module, des fichiers différents
Paralléliser avec une étape explicite de résolution des conflits
Les tâches touchent les mêmes fichiers
Les séquencer
La tâche B a besoin du contrat API de la tâche A
Bloquer la tâche B jusqu’à ce que l’interface de la tâche A soit définie
Règle pratique : Une analyse de 5 minutes pour trouver les chevauchements de fichiers avant de lancer les agents permet d’économiser des heures de résolution de conflits de fusion.
Outillage : coderabbitai/git-worktree-runner fournit un gestionnaire de worktree en bash avec une intégration basique d’outils d’IA. Il gère le cycle de vie des worktrees mais pas la détection des dépendances, celle-ci reste manuelle.
Note : La détection automatique complète des dépendances (où le système infère quelles tâches entrent en conflit) n’existe pas dans Claude Code ni dans l’écosystème plus large à partir de mars 2026. Les approches ci-dessus représentent l’état de l’art pratique.
Important : Claude Code utilise le chargement paresseux : il ne « charge » pas l’intégralité de votre base de code au démarrage. Les fichiers sont lus à la demande lorsque vous demandez à Claude de les analyser. Les principaux consommateurs de contexte au démarrage sont vos fichiers CLAUDE.md et les règles chargées automatiquement.
Estimation du coût en tokens de CLAUDE.md :
Taille du fichier
Tokens approximatifs
Impact
50 lignes
500-1 000 tokens
Minimal (recommandé)
100 lignes
1 000-2 000 tokens
Acceptable
200 lignes
2 000-3 500 tokens
Limite supérieure
500+ lignes
5 000+ tokens
Envisager de diviser
Note : Ceux-ci sont chargés une fois au démarrage de la session, pas par requête. Un CLAUDE.md de 200 lignes coûte environ 2K tokens au départ mais ne croît pas pendant la session. La préoccupation concerne l’effet cumulatif combiné à plusieurs @includes et tous les fichiers dans .claude/rules/.
Portée de la recherche : Gloaguen et al., section 4.2 rapportent des hausses moyennes du coût d’inférence de 20 % et 23 % avec des fichiers générés par LLM sur SWE-bench Lite et AGENTbench, respectivement. Ces résultats concernent les configurations testées ; ils ne constituent pas un surcoût applicable à chaque fichier d’instructions. Coût, tokens de raisonnement et taux de réussite sont des mesures différentes.
# ❌ CLAUDE.md gonflé (gaspille des tokens à chaque session)
- 500+ lignes d'instructions
- Multiples @includes important d'autres fichiers
- Directives rarement utilisées
# ✅ CLAUDE.md allégé
- Contexte essentiel du projet uniquement (<200 lignes)
- Déplacer les règles spécialisées vers .claude/rules/ (chargé automatiquement au démarrage de session)
- Diviser par préoccupation : règles d'équipe dans le CLAUDE.md du projet, préférences personnelles dans ~/.claude/CLAUDE.md
Note de recherche : Les fichiers de contexte rédigés par des humains apportaient des bénéfices variables selon les agents dans Evaluating AGENTS.md. L’expérience ne définit ni limite universelle de lignes ni nocivité de tout fichier généré. Comparez une version plus courte au fichier existant sur des tâches représentatives, en conservant les contraintes nécessaires au projet. Évaluation de la source.
2. Utiliser des références de fichiers ciblées :
Terminal window
# ❌ Requête vague (Claude lit de nombreux fichiers pour trouver le contexte)
"Fix the authentication bug"
# ✅ Requête spécifique (Claude lit uniquement ce qui est nécessaire)
"Fix the JWT validation in @src/auth/middleware.ts line 45"
/compact# Libère le contexte, maintient les performances
4. Spécialisation des agents :
---
name: test-writer
description: Generate unit tests (use for test generation only)
model: haiku
---
Generate comprehensive unit tests with edge cases.
Avantages :
Haiku coûte moins que Sonnet
Contexte ciblé (tests uniquement)
Exécution plus rapide
5. Regrouper les opérations similaires :
Terminal window
# ❌ Sessions individuelles pour chaque correction
claude-p"Fix typo in auth.ts"
claude-p"Fix typo in user.ts"
claude-p"Fix typo in api.ts"
# ✅ Regrouper en une seule session
claude
You:"Fix typos in auth.ts, user.ts, and api.ts"
# Chargement de contexte unique, corrections multiples
6. Indexation structurelle préalable :
Au lieu de laisser Claude lire les fichiers à la demande tout au long d’une session, créez préalablement un index structurel de votre base de code avant de commencer. Claude interroge l’index (1 appel) plutôt que de lire les fichiers séquentiellement (5-10 lectures par tâche).
Terminal window
# Avec CodeXRay (configuration npx, SQLite, 15 langages) :
npxcodexray# Configuration interactive + première construction de l'index
cxrwatch & # Synchronisation en arrière-plan sur les changements de fichiers
# Claude Code interroge ensuite le graphe au lieu de lire les fichiers :
# "find the payment module" → 1 requête de graphe vs 5-10 lectures de fichiers
Les outils construits sur ce modèle remplacent 5-10 lectures de fichiers par 1 requête structurée, environ 75% moins d’appels d’outils pour les tâches de découverte.
Détection de code mort et de dépendances circulaires :
Un index structurel permet également des analyses que la lecture fichier par fichier ne peut pas exposer efficacement :
Code mort : Fonctions définies mais jamais appelées, sûres à supprimer, réduisant le bruit de contexte futur
Dépendances circulaires : Le module A importe B qui importe A, dette architecturale qui gonfle silencieusement la surcharge de raisonnement de Claude
Points chauds : Fichiers avec le nombre de dépendances le plus élevé, à prioriser pour la documentation ou la refactorisation en premier
Terminal window
# Avec grepai (zéro appelant = candidat au code mort) :
grepaitracecallers"MyFunction"# Résultat vide → sûr à examiner pour suppression
# Avec un outil MCP structurel (si disponible) :
# Les outils comme CodeXRay exposent : codexray_deadcode, codexray_circular, codexray_hotspots
Outils communautaires : CodeXRay (Tree-sitter + SQLite, 16 outils MCP, 15 langages) et Claudette (binaire Go, 4 langages) sont des implémentations précoces de cette approche. Les deux sont en stade alpha à partir de mars 2026. Utilisez grepai pour les flux de travail en production.
GitHub : juliusbrussee/caveman | Stars : 93,5K (27/07/2026, contre 53K) | Licence : MIT
Caveman est un skill Claude Code (également disponible pour Cursor, Windsurf, Codex, Gemini CLI, et 26 autres agents) qui réécrit le style de sortie de l’assistant en fragments compressés et télégraphiques. Les articles, politesses, résumés de transition et explications verbeuses sont supprimés. Les blocs de code, chemins de fichiers, URLs, commandes, titres et numéros de version sont préservés verbatim.
Se déclenche également automatiquement sur des phrases comme « sois bref » ou « moins de tokens s’il te plaît ». Se désactive automatiquement pour les messages critiques en matière de sécurité et les opérations destructives.
Quatre modes de compression :
Mode
Style
Lite
Grammaire complète, politesses supprimées
Full (par défaut)
Phrases fragmentées, articles supprimés
Ultra
Compression télégraphique maximale
Wenyan (文言文)
Mode littéraire chinois classique, expérimental
Comment Caveman économise des tokens, deux mécanismes :
Compression de la sortie : Le README actuel de Caveman (lu le 2026-09-30) ne met plus en avant un chiffre de 65% ou 75%. Il rapporte une réduction médiane de 50% des tokens de sortie sur dix questions de développeurs face à un contrôle « Answer concisely. » (longueur uniquement, pas exactitude), et cite le test indépendant de JetBrains sur 86 tâches réelles de programmation (skill seul, sans proxy) : 8,5% de tokens de sortie en moins, sans changement de qualité détectable. Les anciennes affirmations « ~75% » et « 65% » (les notes de version v1.9.1 présentent 65% comme une réduction moyenne des tokens de sortie face aux réponses verbeuses par défaut sur un benchmark de 10 prompts, plage de 22 à 87%) ne figurent plus dans le README. Plus efficace sur les échanges riches en explications : discussions architecturales, récits de débogage, questions-réponses.
Compression de l’entrée via /caveman-compress : Réécrit vos fichiers CLAUDE.md et de mémoire de projet en forme compressée sur place, réduction revendiquée d’environ 46% du coût en tokens au démarrage de session. Les blocs de code, URLs et chemins sont intacts.
Outils complémentaires inclus :
/caveman-commit : messages de commit conventionnels de moins de 50 caractères, axés sur le « pourquoi »
/caveman-review : commentaires de PR en une ligne avec des marqueurs de sévérité en emoji
/caveman-stats : utilisation des tokens de session et économies cumulées (Claude Code uniquement)
caveman-shrink : wrapper MCP qui compresse les champs de description des outils/prompts avant leur chargement dans le contexte
Chiffres honnêtes : Les chiffres par réponse concernent des prompts en prose, pas une session. Dans les sessions de programmation agentique, la plupart des tokens sont du code et des appels d’outils que le skill ne modifie pas : JetBrains a mesuré 8,5% de tokens de sortie en moins. Le benchmark du proxy décrit dans le README (54 exécutions épinglées de Claude Code) rapporte 33,2% de tokens d’entrée en moins (de 885 793 à 591 673), avec 18 réponses correctes sur 18 et un intervalle à 95% de 14,6% à 48,5% ; le README lui-même le présente comme un rapport épinglé, pas une reproduction publique. Caveman apporte le plus dans les sessions riches en échanges conversationnels, et le moins dans celles dominées par les lectures de fichiers, les appels d’outils ou la génération de code.
Quand NE PAS l’utiliser :
Génération de documentation, la sortie est destinée à être lue par des humains
Commentaires de revue de code partagés avec des parties prenantes non techniques
Sessions de débogage où la transparence du raisonnement est importante
Chaînes multi-agents où les agents en aval analysent les réponses précédentes pour reconstruire l’état
Statistiques : 93,5K étoiles GitHub au 27/07/2026 (contre 53K) | Créé le 2026-04-04 | MIT | Le harnais de benchmark (evals/) est encore en cours de maturation, traitez les pourcentages spécifiques comme directionnels
RTK (Rust Token Killer) filtre les sorties des commandes avant qu’elles n’atteignent le modèle. Les réductions rapportées concernent les sorties shell traitées, pas la session entière ou la facture. rtk gain utilise des estimations locales de tokens ; comptabilisez séparément les reprises et les résultats des tâches.
Pour des hooks, la navigation dans le code et l’interception MCP plus larges, voir la comparaison Tokenade et les limites des preuves. Elle présente une alternative propriétaire avec des résultats de benchmark maintenus par son éditeur, pas une recommandation universelle de remplacement.
Dépôt :rtk-ai/rtk | Site web :rtk-ai.app | Transparence : l’auteur de ce guide est un contributeur principal de RTK (pas son créateur) ; cette recommandation n’est donc pas indépendante. Les mesures sur des tâches complètes de plusieurs études et la réponse des mainteneurs figurent dans context-engineering-tools.md.
Installation :
Terminal window
# Option 1 : Homebrew (macOS/Linux)
brewinstallrtk
# Option 2 : Cargo (toutes plateformes, utiliser --git : une autre crate "rtk" existe sur crates.io)
cargoinstall--githttps://github.com/rtk-ai/rtk
# Option 3 : Script d'installation (Linux/macOS, installe dans ~/.local/bin)
rtk--version# dernière version vérifiée le 2026-09-30 : v0.50.0
Mesurez l’effet sur votre travail :
Comparez des commandes équivalentes sur le même état du dépôt et conservez les sorties brutes pour le diagnostic. rtk gain rapporte des estimations sur les sorties shell filtrées, sans mesurer l’économie sur la facture totale. Une sortie git log ou des logs de tests plus courts ne prouvent pas une réduction universelle de la session. Voir comment RTK mesure les économies.
Fonctionnalités clés (liste à la v0.28.0 ; dernière version : v0.50.0) :
Terminal window
# Opérations Git
rtkgitlog
rtkgitstatus
rtkgitdiffHEAD~1
# Stack JS/TS
rtkvitestrun# Résultats de test condensés
rtkpnpmlist# Arbre de dépendances optimisé
rtkprismamigratestatus# État des migrations filtré
# Python
rtkpytest# Sortie de test Python condensée
rtkmypy# Erreurs de type groupées par fichier
# Go
rtkgotest# Résultats de test Go filtrés
# Rust
rtkcargotest# Sortie de test Cargo condensée
rtkcargonextest# Sortie cargo-nextest en échecs uniquement
rtkcargobuild# Sortie de build filtrée
rtkcargoclippy# Lints groupés par sévérité
# Cloud & Base de données
rtkaws# Sortie AWS CLI filtrée
rtkpsql# Résultats de requête psql condensés
rtkdocker# Sortie Docker condensée
rtkdockercompose# Support docker compose
# Contrôle de version (extra)
rtkgt# Support Graphite CLI
# Utilitaires fichiers & texte
rtktree# Structure du projet condensée
rtkwc# Comptages de mots/lignes/octets compacts
rtkreadfile.ts# Contenu de fichier condensé
# Configuration & Apprentissage du projet
rtkinit# Initialiser RTK avec installation automatique de hook
rtkinit--global# Installer le hook globalement (patch automatique de settings.json)
rtklearn# Apprentissage interactif de RTK
# Analytique
rtkgain# Tableau de bord des économies de tokens (suivi SQLite)
rtkgain-p# Décomposition des économies de tokens par projet
rtkdiscover# Trouver les opportunités d'optimisation manquées
# Gestion des Hooks & de la Config
rtkrewrite<cmd># Source unique de vérité pour les réécritures de hook
rtkverify# Valider les règles de filtre TOML
Mesurez l’effet sur votre travail :
Comparez des sorties brutes et filtrées représentatives, puis consultez rtk gain pour sa réduction estimée. L’estimation de tokens fondée sur les octets de RTK n’est ni le comptage du fournisseur ni une mesure de réduction de la facture entière. Conservez les sorties brutes lorsque le filtrage masque des éléments utiles au diagnostic.
DSL de filtre TOML (v0.28.0, ajouter des filtres sans écrire de Rust) :
RTK supporte maintenant un moteur de filtre déclaratif via une config TOML. Vous pouvez ajouter des filtres de sortie personnalisés pour n’importe quelle commande sans toucher au code Rust.
# .rtk/filters.toml (local au projet) ou ~/.config/rtk/filters.toml (global utilisateur)
Débogage : RTK_NO_TOML=1 contourne tous les filtres TOML. RTK_TOML_DEBUG=1 affiche quel filtre se déclenche.
Stratégies d’intégration :
Installation prioritaire par hook (recommandée) :
Terminal window
rtkinit--global# Configure le hook PreToolUse + patche settings.json automatiquement
Instruction CLAUDE.md (wrapper manuel) :
## Optimisation des tokens
Utiliser RTK pour toutes les commandes supportées :
-`rtk git log`
-`rtk git status`
-`rtk git diff`
Skill (suggestion automatique) :
Modèle : examples/skills/rtk-optimizer/SKILL.md
Détecte les commandes à haute verbosité
Suggère automatiquement le wrapper RTK
Hook (wrapper automatique) :
Modèle : examples/hooks/bash/rtk-auto-wrapper.sh
Le hook PreToolUse intercepte les commandes bash
Applique le wrapper RTK lorsque bénéfique
Options de configuration :
~/.config/rtk/config.toml
exclude_commands = ["my-interactive-tool", "fzf"] # Ne jamais réécrire ceux-ci
Note de migration (v0.25.0+) :
Après mise à jour depuis v0.24.0 ou antérieur, exécutez rtk init --global pour installer le nouveau hook délégateur léger. L’ancien hook fonctionne toujours, mais ne récupèrera pas automatiquement les nouveaux mappings de commandes.
Terminal window
cargoinstall--githttps://github.com/rtk-ai/rtk# Mettre à jour le binaire
rtkinit--global# Remplacer le hook par le délégateur léger
Recommandation :
✅ Utiliser RTK : Projets full-stack (JS/TS, Rust, Python, Go), flux de travail de test, analytique
RTK gère les sorties de commandes (ce que vous exécutez). Smart explore gère la lecture du code (ce que vous lisez). Ensemble, ils couvrent les deux principaux gouffres à tokens d’une session Claude Code.
Le problème : Lorsque Claude explore une base de code, il lit les fichiers en entier, 400 lignes quand il n’avait besoin que de 3 signatures de fonctions. L’exploration typique d’un module de 10 fichiers coûte 35 000 tokens. Avec l’exploration progressive, la même tâche en coûte 3 500.
Le schéma (3 étapes, réduction de 86 à 92 %) :
Étape 1 — Structure (~200 tokens par fichier)
Obtenir uniquement les signatures de fonctions, types et champs
Claude répond à "qu'est-ce qui existe ?" sans lire aucun corps
Étape 2 — Ciblage (~350 tokens par fonction)
Lire une fonction spécifique par décalage de ligne
Pas le fichier entier — juste les lignes 45 à 90
Étape 3 — Référence croisée (~150 tokens)
Trouver les appelants d'une fonction
rg "function_name" --type rust -n
C’est le même schéma qu’Aider utilise pour sa repo map (47,7K étoiles au 27/07/2026, contre 40 000+ auparavant), validé à grande échelle depuis 2023.
Approche A : Sans configuration, discipline CLAUDE.md
Le chemin le plus rapide. Ajoutez à votre CLAUDE.md de projet :
## Protocole d'Exploration du Code
Lors de l'exploration d'une base de code ou de la compréhension d'un module :
1.**Structure en premier**, exécutez la commande appropriée selon le langage :
50 à 150 tokens par fichier contre 2 000 à 5 000 pour une lecture complète.
Approche C : Serveurs MCP (grandes bases de code, >50 fichiers)
Cas d’usage
Outil
Installation
Exploration générale
mcp-server-tree-sitter
pip install mcp-server-tree-sitter
Revues de code de PR
code-review-graph (MIT, 26,9K étoiles au 27/07/2026, contre 10 000+)
pip install code-review-graph
Recherche de symboles
jCodeMunch (gratuit non commercial)
claude mcp add jcodemunch uvx jcodemunch-mcp
code-review-graph est l’option autonome la plus solide : MIT, 26,9K étoiles au 27/07/2026 (contre 10 000+ auparavant), réduction moyenne de 8,2x des tokens sur des bases de code réelles (gin : 16x, flask : 9x, FastAPI : 8x, Next.js : 8x). Construit un AST Tree-sitter de votre dépôt, suit le rayon d’impact de chaque modification, et expose 28 outils MCP pour que Claude ne lise que les fichiers pertinents. Supporte 23 langages + les notebooks Jupyter, se met à jour automatiquement à chaque commit git (ré-indexation < 2 s), et intègre un démon multi-dépôt pour les configurations indépendantes de l’éditeur.
Terminal window
pipinstallcode-review-graph
code-review-graphinstall# détecte automatiquement Claude Code, Cursor, Windsurf, Zed, Continue, Kiro...
code-review-graphbuild# première analyse (~10 s pour 500 fichiers)
Benchmarks honnêtes :
Tâche
Sans smart-explore
Avec smart-explore
Économies
Comprendre un module de 5 fichiers
~18 000 tokens
~2 500 tokens
86 %
Trouver où ajouter une fonctionnalité
~8 000 tokens
~800 tokens
90 %
Revue de PR (10 fichiers modifiés)
~25 000 tokens
~3 500 tokens
86 %
Recherche d’une seule fonction
~3 000 tokens
~350 tokens
88 %
RTK vs Smart Explore, tableau complet :
RTK
Smart Explore
Ce qu’il économise
Tokens de sortie de commandes
Tokens de lecture de code
Quand
Après l’exécution de git, cargo, npm
Avant la lecture des fichiers source
Comment
Regex + filtrage texte
Analyse AST (signatures uniquement)
Économies typiques
60 à 90 % sur les sorties CLI (README RTK : « jusqu’à 90% » de la sortie bash, pas de la facture)
86 à 92 % dans les estimations par tâche ci-dessus (aucune mesure contrôlée citée) ; 10,5% d’économie de tokens de cache dans un test A/B contrôlé de 50 itérations d’un outil tree-sitter comparable (jCodeMunch)
Configuration
rtk init --global (2 min)
Règle CLAUDE.md (0 min) ou script (5 min)
Utilisez les deux, mais n’extrapolez pas les chiffres par commande à une session. Aucune source de ce guide n’étaye un total de session pour RTK associé à smart explore. Les mesures sur des tâches complètes avec RTK seul diffèrent selon les études : JetBrains a mesuré +7,6% de coût médian par tâche à faible effort de raisonnement et +0,1% à effort élevé, Dasein +13% de coût total, THOL +7,1% avec un intervalle qui inclut zéro, et le rejeu de Codepointer -0,5% des dépenses. Les mainteneurs de RTK contestent le protocole JetBrains et rapportent -4,8% sur 13 tâches de développement (p = 0,305) dans leur propre nouvelle exécution (voir context-engineering-tools.md).
Voir aussi :
Modèle de skill : examples/skills/smart-explore.md
Pour une utilisation intensive, envisagez cc-copilot-bridge pour router les requêtes via GitHub Copilot Pro (10 $/mois) plutôt que la facturation par token.
Ne soyez pas radin sur les petites choses au détriment des grandes :
❌ Fausse économie :
Passer 2 heures à déboguer manuellement pour économiser 1 $ en coûts d’API
Utiliser Haiku pour des tâches complexes, générant du code incorrect
Sur-compacter le contexte, perdant un historique précieux
✅ Optimisation intelligente :
Utiliser le bon modèle pour la tâche (temps économisé >> coût)
Investir dans de bonnes invitations et fichiers mémoire (réduire les itérations)
Automatiser avec des agents (cohérent et efficace)
Perspective sur le ROI :
Les gains de temps liés à une utilisation efficace de Claude Code dépassent généralement largement les coûts d’API pour la plupart des tâches de développement. Plutôt que de calculer un ROI précis (qui dépend fortement de votre contexte spécifique, de votre taux horaire et de la complexité des tâches), concentrez-vous sur la question de savoir si l’outil vous aide réellement à livrer plus vite. Pour la mesure au niveau de l’équipe, voir Métriques de Contribution, le tableau de bord intégré à GitHub d’Anthropic pour suivre les attributions de PR et de code (plans Team/Enterprise, bêta publique).
Quand optimiser agressivement :
Opérations à volume élevé (>1 000 requêtes/jour)
Pipelines automatisés fonctionnant 24h/24, 7j/7
Grandes équipes (les coûts s’accroissent avec les utilisateurs)
Projets à budget contraint
Quand la productivité prime :
Corrections de bugs critiques
Fonctionnalités urgentes
Apprentissage et expérimentation
Décisions architecturales complexes
La Séparation Facturation Interactive/Programmatique (Annoncée, puis suspendue)
Statut, vérifié le 2026-09-30 : Anthropic a annoncé ce changement le 13 mai 2026 (relayé par Gigazine le 14 mai) pour le 15 juin 2026, puis l’a suspendu. Son article d’aide indique : « We’re pausing the changes to Claude Agent SDK usage described below. For now, nothing has changed: Claude Agent SDK, claude -p, and third-party app usage still draw from your subscription’s usage limits. » Le crédit mensuel n’est pas disponible, et Anthropic dit qu’il communiquera avant tout changement effectif (Claude Help Center). La suite de cette section décrit le plan tel qu’annoncé, pour vous préparer s’il reprend.
Anthropic prévoyait de diviser l’utilisation des abonnements en deux compartiments distincts. Le premier, appelé usage interactif, couvre le terminal et l’IDE Claude Code, ainsi que les interfaces de chat web, desktop et mobile. Ces flux de travail conserveraient les limites d’abonnement existantes.
Le second compartiment, l’usage programmatique, serait nouveau et plafonné. Il couvre claude -p (mode headless), l’Agent SDK (Python et TypeScript), GitHub Actions avec Claude, et les harnais tiers incluant OpenClaw, Hermes, Conductor, et tout pipeline d’orchestration personnalisé qui invoque Claude en dehors des interfaces propres d’Anthropic. Pour une analyse détaillée de ces harnais tiers et de leur comparaison avec Claude Code, voir Outils Agents : Au-delà de Claude Code. Chaque plan d’abonnement recevrait un crédit mensuel. L’annonce décrivait l’usage au-delà de ce crédit comme facturé aux tarifs API standard, sans report.
La séparation prévue n’est pas « interaction humaine vs automatisation ». La distinction opératoire est l’interface d’Anthropic vs votre interface. Exécuter Claude Code interactivement dans le terminal utilise l’interface d’Anthropic et resterait inchangé. Exécuter votre propre harnais ou orchestrateur utilise votre interface, qui serait plafonnée. Cela reflète là où Anthropic capture de la valeur à mesure que les modèles LLM se commoditisent : au niveau du harnais et de l’UX, pas du modèle.
Routines déclenchées par des événements GitHub (comptabilisées comme interactives)
Note : Les Routines (tâches planifiées dans le cloud via claude.ai/code/routines) s’exécutent sur l’infrastructure d’Anthropic en utilisant le système d’agents d’Anthropic. Leur classification de facturation n’a pas été explicitement confirmée dans l’annonce du 13 mai, vérifiez auprès du support Anthropic si votre utilisation des Routines est substantielle.
Avertissement : Si ANTHROPIC_API_KEY est défini dans l’environnement de votre shell ou un fichier .env, Claude Code contourne entièrement l’abonnement et facture chaque requête aux tarifs API par token, y compris vos sessions interactives. Ceci est indépendant du plan de crédit programmatique et s’applique dès aujourd’hui. Des utilisateurs ont reçu des factures API de 400 $ ou plus en plus d’un plan Max actif à 200 $ à cause de cela.
Diagnostic :
Terminal window
echo$ANTHROPIC_API_KEY# Toute sortie signifie que vous êtes sur la facturation API, pas l'abonnement
claude/cost# Affiche les dépenses en temps réel dans la session en cours
Correction : Désactivez la variable dans votre profil shell (~/.zshrc, ~/.bashrc) si vous souhaitez router l’utilisation via votre abonnement. Ne définissez ANTHROPIC_API_KEY que lorsque vous avez explicitement l’intention d’utiliser la facturation API directe.
Effectuez cet audit pour savoir quelle part de votre usage est programmatique, que le plan de crédit reprenne ou non.
Étape 1, vérifier les dépenses de session :
Terminal window
claude/cost# ou /usage depuis la v2.1.118
Étape 2, examiner l’historique multi-sessions avec ccusage :
Terminal window
npxccusage# Ventilation par modèle et type de session
Recherchez les sessions initiées par des scripts, des jobs CI, ou de l’automatisation, ce sont vos sessions programmatiques. Estimez le total mensuel des tokens pour ces sessions et comparez-le au crédit prévu pour votre plan.
Étape 3, identifier les flux de travail programmatiques dans votre configuration :
Terminal window
# Trouver tous les endroits où vous invoquez claude -p ou utilisez des flags headless
Ce cadre s’applique si le plan de crédit reprend. D’ici là, l’usage programmatique consomme les mêmes limites d’abonnement que l’usage interactif, ce qui justifie déjà les chemins A et B.
Si votre usage programmatique resterait dans les limites du crédit prévu : Aucune action nécessaire. Continuez comme avant et surveillez avec /cost ou ccusage.
Si votre usage programmatique dépasserait le crédit prévu, choisissez un ou plusieurs des chemins suivants :
Chemin A, réduire la portée ou la fréquence :
Augmenter l’intervalle des tâches planifiées
Limiter les invocations Claude en CI/CD aux PR touchant des chemins spécifiques
Remplacer les boucles agentiques multi-étapes par des invocations uniques et ciblées
Chemin B, migrer vers la facturation API directe avec un plafond budgétaire :
# .github/workflows/claude-review.yml — avec conscience des dépenses
# Définir ANTHROPIC_API_KEY explicitement pour utiliser la facturation API
# Ajouter une alerte budgétaire mensuelle dans la Console Anthropic
claude -p "Review changes for security issues" ...
La facturation API directe vous donne des coûts prévisibles par appel et des alertes budgétaires dans la Console. Pour les CI/CD à faible volume (revues de PR occasionnelles), le coût API par token est généralement inférieur à celui de la dédicace d’un crédit mensuel.
Chemin C, diversifier les orchestrateurs :
Cas d’usage
Alternative
Justification
Travail en arrière-plan non surveillé
OpenAI Codex
Conçu pour l’exécution asynchrone et non surveillée
Récupération et recherche de grands documents
Gemini 2.0/2.5
Contexte 2M à un coût par token inférieur
Synthèse et résumé en volume
Modèles locaux (Ollama + Llama/Qwen)
Coût marginal zéro si le matériel est disponible
Rédaction, planification, revue interactive
Claude (conserver)
Toujours le modèle le plus performant pour ces tâches
Ces options ne sont pas mutuellement exclusives. Un schéma courant : garder Claude pour le travail interactif et les tâches requérant une qualité rédactionnelle, router les pipelines automatisés à volume élevé vers le fournisseur offrant le meilleur rapport coût-performance pour cette charge de travail spécifique. Voir Section 11 : Écosystème IA pour une matrice complète des outils et le LLM market snapshot pour les prix datés des fournisseurs.
Le moteur économique du changement annoncé est simple. Au moment de l’annonce, un utilisateur intensif exécutant une automatisation d’agents continue pouvait extraire environ 2 000 $ par mois en calcul équivalent API pour un abonnement à 200 $. Les cas extrêmes atteignaient environ 5 000 $ par mois. À ce ratio, Anthropic perdait environ 300 $ par mois sur chaque profil extrême. L’adoption massive de l’automatisation par agents fin 2025 a rendu cela insoutenable.
Le calendrier est important : le 6 mai, Anthropic a doublé les limites de débit interactives (annoncé conjointement avec le partenariat SpaceX). Le 13 mai, la séparation de facturation programmatique a été annoncée. Elle était prévue le 15 juin et a été suspendue avant d’entrer en vigueur. Le 13 juillet, le bonus interactif temporaire de +50 % a pris fin. Tout cela fait partie du même rééquilibrage de capacité, et non de changements isolés.
Pour la majorité des utilisateurs de Claude Code qui l’utilisent interactivement dans le terminal, le plan n’aurait aucun impact. Pour les équipes qui ont construit une automatisation significative sur claude -p ou l’Agent SDK, il reste un changement matériel à anticiper, puisqu’Anthropic dit travailler à une version révisée.
Leviers d’optimisation des coûts : natif vs. niveau API
Six leviers permettent de contrôler les coûts des LLM. Certains sont directement accessibles dans Claude Code ; d’autres nécessitent de construire sur l’API ou le SDK Anthropic. Le tableau associe chaque levier à ce qui est déjà disponible et où le trouver.
Levier
Natif dans Claude Code ?
En construisant avec l’API/SDK Anthropic
Où est-ce documenté
Surveillance des coûts
Commande /cost, CLI ccusage, tableau de bord des crédits d’abonnement
Tableau de bord Anthropic Console, suivi des dépenses par appel
§9.13 ci-dessus
Compression des sorties
Skill Caveman (8,5% de tokens de sortie en moins sur des tâches réelles de programmation selon JetBrains, davantage sur les réponses en prose seule), RTK pour la sortie CLI
Ingénierie des prompts, gestion des réponses en streaming
§9.13 Caveman + RTK
Routage de modèle
/model opusplan, model: dans le frontmatter des agents, haiku pour les tâches mécaniques
RouteLLM (85% d’appels en moins vers le modèle de premier niveau sur MT-Bench, arXiv 2406.18665)
Sur le routage de modèle via l’API : RouteLLM (lm-sys, ICLR 2025, arXiv 2406.18665) entraîne un routeur léger qui décide à chaque appel s’il faut invoquer un modèle puissant ou un modèle moins coûteux. Sur MT-Bench, il atteint une réduction des coûts de 85% par rapport au routage toujours vers le modèle fort, tout en correspondant à 95% des performances du modèle fort. La technique s’applique aux pipelines automatisés construits sur l’API Anthropic, et non aux sessions interactives de Claude Code.
Sur le traitement par lots : La Message Batches API est le levier à plus fort effet de levier pour les pipelines automatisés (classification nocturne, analyse de documents en masse, extraction de données à grande échelle). Non applicable à un usage interactif. Pour un travail asynchrone à volume élevé, comparez la Message Batches API avec votre mode actuel de facturation par abonnement ou API. La séparation de facturation programmatique annoncée pour le 15 juin a été suspendue ; n’établissez pas votre budget comme si ce crédit distinct était actif.
15 méthodologies de développement structurées ont émergé pour le développement assisté par IA (2025-2026). Cette section fournit une navigation rapide ; les workflows détaillés se trouvent dans des fichiers dédiés.
Temps de lecture : 5 minutes
Niveau de compétence : Semaine 2+
Des schémas nommés mémorables pour une interaction efficace avec Claude Code. Ces schémas ont émergé des meilleures pratiques de la communauté et vous aident à communiquer plus efficacement.
Temps de lecture : 5 minutes
Niveau de compétence : Semaine 2+
Statut : Aperçu de recherche (depuis janvier 2026)
La téléportation de session permet de migrer des sessions de codage entre les environnements cloud (claude.ai/code) et local (CLI). Cela permet des flux de travail où vous commencez à travailler sur mobile/web et continuez localement avec un accès complet au système de fichiers.
TL;DR : L’orchestration multi-instances = un modèle avancé pour les équipes gérant 10+ fonctionnalités simultanées. Nécessite une architecture modulaire + un budget + une surveillance. 95 % des utilisateurs n’en ont pas besoin, les flux de travail séquentiels avec 1-2 instances sont plus efficaces dans la plupart des contextes.
Avant d’ajouter un gestionnaire de processus, identifiez la couche responsable de chaque fonction. Le modèle génère du texte ; le harness de runtime gère la boucle entre modèle et outils d’une session ; le harness de dépôt fournit les instructions et les contrôles de livraison ; l’orchestrateur coordonne les sessions. Agent Harness Engineering explique ces limites. Agent Harness Map compare les harness de runtime au sens strict et distingue son répertoire plus large du tableau des runtimes. Agent Tools: Beyond Claude Code présente les frameworks et les plans de contrôle ; le glossaire définit les termes.
Vue agents : gestion de sessions native (v2.1.139+)
Aperçu de recherche : Disponible sur les plans Pro, Max, Team, Enterprise et Claude API. Activation : claude agents.
Avant de configurer des grilles tmux ou des orchestrateurs tiers, essayez la vue agents, le gestionnaire de sessions intégré à Claude Code.
Comment y accéder :
claude agents depuis n’importe quel terminal
Flèche gauche ← depuis n’importe quelle session active
Ce que vous voyez : chaque ligne affiche le nom de la session, l’état (en cours / en attente de votre action / terminé), un aperçu de la dernière réponse, et le temps écoulé depuis la dernière interaction.
Commandes principales :
Action
Comment
Ouvrir la vue agents
claude agents ou ← depuis n’importe quelle session
Mettre la session courante en arrière-plan
/bg
Lancer une nouvelle session en arrière-plan
claude --bg [task]
Aperçu du dernier tour
Sélectionner la session
Répondre en ligne (session en attente)
Sélectionner → saisir la réponse → la session reprend
Attacher la transcription complète
Entrée sur n’importe quelle session
Modèles de flux de travail (d’après les premiers utilisateurs) :
Dispatch et retour : Envoyer plusieurs tâches avec claude --bg, revenir à une liste de PRs prêts pour révision
Agents à longue durée : Les gardiens de PRs et les tâches en boucle affichent l’heure du prochain lancement dans la liste
Changement de contexte rapide : Flèche gauche, démarrer une tâche connexe ou poser une question rapide, obtenir la réponse, flèche droite pour revenir
Scan de statut : Les indicateurs d’état vous indiquent quelles sessions ont produit un PR sans entrer dans chacune
Relation avec les outils tiers : Avant la vue agents, la gestion de sessions parallèles nécessitait tmux, multiclaude ou des applications comme Conductor. La vue agents couvre le cas d’usage central « qu’est-ce qui tourne et qu’est-ce qui a besoin de moi » nativement. Conductor et les outils similaires restent pertinents pour l’intégration CI GitHub, les flux de travail PR et la gestion multi-dépôts au-delà de ce que la vue agents offre.
/goal <condition> définit une condition de complétion pour la session courante. Un évaluateur distinct peut poursuivre le travail, déclarer la condition remplie ou la juger impossible. Certaines erreurs irrécupérables effacent aussi l’objectif. Un objectif atteint renseigne sur la condition spécifiée ; l’acceptation du changement reste soumise à la politique de revue du projet.
Fonctionnement : Après chaque tour, un petit modèle rapide (Haiku par défaut) lit la conversation et juge : « La condition est-elle remplie, en se basant uniquement sur les preuves déjà présentes dans cette conversation ? » Si non, il génère une raison concise expliquant l’écart, ce qui pilote le tour suivant. Si oui, la boucle se termine. L’évaluateur ne peut pas exécuter de commandes indépendamment, il juge uniquement en fonction de ce que Claude a déjà affiché dans la conversation.
Un affichage en temps réel suit le temps écoulé, le nombre de tours et la consommation de tokens tout au long de l’exécution.
Gérer un objectif actif :
Commande
Effet
/goal <condition>
Définir ou remplacer l’objectif courant
/goal clear
Annuler l’objectif actif
/goal
Afficher la condition, la progression et la dernière raison de l’évaluateur
Trois éléments d’une condition efficace :
État final mesurable : un résultat spécifique, un résultat de test ou un état de fichier. « Tous les tests dans test/auth passent » vaut mieux que « améliorer le système d’authentification ».
Mécanisme de vérification : comment le succès est démontré. « vérifié par npm test auth exit 0. »
Contraintes : ce qui doit rester intact tout au long. « aucun fichier en dehors de src/services/auth modifié. »
Exemple complet : /goal all tests in test/auth pass, verified by npm test auth exit 0, no files outside src/services/auth modified
Borner l’exécution : Incluez une limite explicite, par exemple or stop after 5 turns. L’évaluateur juge cette clause à partir de la conversation ; ce n’est pas un compteur d’exécution déterministe. Si dépasser un budget est inacceptable, imposez-le dans le contrôleur externe au modèle. L’exemple de boucle bornée applique une limite de tentatives dans le programme sans invoquer de modèle. Son test ne valide pas le runtime de Claude Code.
Reprise et échec : Un objectif actif est restauré à la reprise de la session, mais le nombre de tours, le chronomètre et la base de consommation des tokens sont remis à zéro. Conservez un budget total durable hors de ces compteurs pour le travail qui traverse des reprises. L’évaluateur peut effacer un objectif impossible ; des erreurs irrécupérables de crédit, de contexte ou de modèle peuvent aussi l’effacer. Consultez la raison enregistrée au lieu d’interpréter tout objectif effacé comme une réussite.
/goal vs /loop :
/goal
/loop
Le prochain tour démarre quand
Le tour précédent finit et l’objectif reste non atteint ; le travail en arrière-plan peut différer l’évaluation
L’intervalle prévu s’écoule et la session peut exécuter la tâche
S’arrête quand
Condition remplie, jugée impossible, effacée manuellement ou après une erreur irrécupérable
Annulation ou expiration ; une boucle à cadence dynamique peut aussi terminer sa tâche
Évaluateur
Modèle distinct (Haiku par défaut)
Le modèle principal s’auto-évalue
Idéal pour
Une tâche avec une ligne d’arrivée claire et mesurable
Surveillance continue sans fin définie
Exemple
« Migrer tous les appels API, tests réussis »
« Vérifier le déploiement toutes les 5 minutes »
Anti-modèles, éviter /goal quand :
L’objectif est vague ou qualitatif (« rendre le code plus propre »)
La complétion requiert un jugement humain que l’IA ne peut pas vérifier
Des données de production sont impliquées et chaque étape nécessite une supervision directe
Il n’y a pas d’état final concret et vérifiable
Permissions : /goal n’étend pas la frontière de permissions de la session. Si la session nécessite une confirmation avant d’exécuter des commandes shell, ces confirmations se déclenchent toujours dans une boucle d’objectif. Configurez le mode de permission délibérément avant d’activer un objectif.
Contexte des longues tâches : Suivez la progression et les preuves conservées sans supposer un seuil universel de dégradation en nombre de tours. Un orchestrateur peut lancer une nouvelle session non interactive pour chaque sous-tâche bornée, mais doit fournir explicitement les exigences, l’artefact courant et les résultats précédents :
Terminal window
# Chaque appel s'exécute dans une session fraîche — pas d'accumulation de contexte
claude-p"Step N of migration: [specific sub-task with explicit context]"
Introduit dans la v2.1.139 (12 mai 2026). Comportement actuel du statut, de l’évaluation et de la reprise vérifié le 10 septembre 2026 dans Keep Claude working toward a goal.
Ne montez pas en charge prématurément. Les flux de travail multi-instances introduisent une surcharge de coordination qui dépasse les bénéfices pour la plupart des équipes.
Contexte
Recommandation
Coût mensuel
Raisonnement
Développeur solo
❌ Non
-
Surcharge > bénéfice, utiliser Cursor à la place
Startup <10 développeurs
⚠️ Peut-être
400-750 $
Uniquement avec architecture modulaire + tests
Scale-up 10-50 développeurs
✅ À considérer
1 000-2 000 $
Framework PM headless + surveillance justifiés
Entreprise 50+
✅ Oui
2 000-5 000 $
ROI clair, budget disponible
Signaux d’alarme (ne pas utiliser le multi-instances si vrai) :
Architecture : Monolithe legacy, pas de tests, couplage fort
Budget : <500 $/mois disponibles pour les coûts API
Expertise : Équipe peu familière avec les bases de Claude Code
Contexte : Développeur solo ou <3 personnes
📊 Validation industrielle : ROI du multi-instances (Anthropic 2026)
Gain via plus de production, pas seulement la vitesse
Nouveau travail
27 % n’auraient pas été réalisés sans IA
Expérimental, agréable à avoir, exploratoire
Délégation complète
0-20 % des tâches
Collaboration > remplacement
Multiplicateur de coût
3x (capacités × orchestration × expérience)
Se cumule dans le temps
Études de cas entreprises :
TELUS (télécommunications, 50 000+ employés) : 500 000 heures économisées, 13 000 solutions personnalisées, expédition 30 % plus rapide
Fountain (plateforme RH) : Sélection 50 % plus rapide, intégration 40 % plus rapide via multi-agents hiérarchique
Rakuten (tech) : Implémentation vLLM autonome en 7h (12,5 M de lignes de code, précision 99,9 %)
Validation du modèle Boris : Le coût de 500-1 000 $/mois et les 259 PRs/mois de Boris s’alignent avec les données entreprises d’Anthropic montrant un ROI positif à partir de 3+ instances parallèles.
Alerte anti-modèle (résultats Anthropic) :
Sur-délégation (>5 agents) : La surcharge de coordination > le gain de productivité
Montée en charge prématurée : Commencer avec 1-2 instances, mesurer le ROI, monter en charge progressivement
Prolifération d’outils : >10 serveurs MCP = charge de maintenance (rester sur la stack essentielle)
Contexte critique : Boris est le créateur de Claude Code, travaillant avec une architecture parfaite, les ressources d’Anthropic et des conditions idéales. Ce n’est pas représentatif des équipes moyennes.
Insights clés de Boris :
Sur le multi-clauding : « J’utilise Cowork comme un ‘faiseur’, pas comme un chat : il touche directement les fichiers, les navigateurs et les outils. Je pense à la productivité comme à du parallélisme : plusieurs tâches s’exécutent pendant que je pilote les résultats. »
Sur CLAUDE.md : « Je traite Claude.md comme une mémoire composée : chaque erreur devient une règle durable pour l’équipe. »
Sur le flux de travail plan-first : « Je lance des flux de travail plan-first : une fois le plan solide, l’exécution devient nettement plus propre. »
Sur les boucles de vérification : « Je donne à Claude un moyen de vérifier le résultat (navigateur/tests) : la vérification pilote la qualité. »
Pourquoi évaluer Opus avec le thinking adaptatif : comparer résultats acceptés, reprises, latence et coût total à Sonnet. Le prix par token ne suffit pas à déduire la qualité ni le coût par tâche acceptée.
Le modèle de supervision : Boris décrit son rôle comme « gérer plusieurs agents » plutôt que « faire chaque clic soi-même ». Le flux de travail consiste à piloter les résultats à travers 5-10 sessions parallèles, débloquer quand nécessaire, plutôt qu’une exécution séquentielle.
Modèles d’équipe (équipe Claude Code au sens large, février 2026) :
L’équipe au sens large étend le flux de travail individuel de Boris avec des modèles institutionnels :
Skills comme savoir institutionnel : Tout ce qui est fait plus d’une fois par jour devient un skill versionné dans le contrôle de source. Exemples :
/techdebt : lancé en fin de session pour éliminer le code dupliqué
Skills de vidage de contexte : synchronisent 7 jours de Slack, Google Drive, Asana et GitHub dans un contexte unique
Agents d’analytique : skills alimentés par dbt qui interrogent BigQuery ; un ingénieur rapporte ne pas avoir écrit de SQL manuellement depuis 6+ mois
CLI et scripts plutôt que MCP : L’équipe préfère les scripts shell et les intégrations CLI aux serveurs MCP pour les connexions d’outils externes. Rationale : moins de magie, plus facile à déboguer, et comportement plus prévisible. MCP est réservé aux cas où la communication bidirectionnelle est vraiment nécessaire.
Re-planifier en cas de blocage : Plutôt que de forcer une implémentation bloquée, l’équipe repasse en mode Plan. Un ingénieur utilise une instance Claude secondaire pour réviser les plans « comme un staff engineer » avant de reprendre l’exécution.
Claude écrit ses propres règles : Après chaque correction, l’équipe demande à Claude de mettre à jour CLAUDE.md avec la leçon apprise. Au fil du temps, cela se cumule en un ensemble de règles spécifiques à l’équipe qui prévient les erreurs récurrentes.
Alors que le flux de travail de Boris démontre une mise à l’échelle horizontale (5-15 instances en parallèle), un modèle alternatif se concentre sur la séparation verticale : utiliser deux instances Claude avec des rôles distincts pour des flux de travail axés sur la qualité.
Source du modèle : Jon Williams (Designer produit, Royaume-Uni), transition de Cursor vers Claude Code après 6 mois. Publication LinkedIn, 3 février 2026
Ce modèle est orthogonal à l’approche de Boris : au lieu de mettre à l’échelle en largeur (plus de fonctionnalités en parallèle), il met à l’échelle en profondeur (séparation des phases de planification et d’exécution).
Votre contexte
Utiliser la double instance ?
Coût mensuel
Développeur solo, travail axé sur les specs
✅ Oui
100-200 $
Petite équipe, exigences complexes
✅ Oui
150-300 $
Designers produit qui codent
✅ Oui
100-200 $
Fonctionnalités parallèles en volume
❌ Non, utiliser le modèle Boris
500 $-1 000 $+
Utiliser quand :
Vous avez besoin de vérification du plan avant l’exécution
Les specs sont complexes ou ambiguës (la clarification par entretien aide)
Budget inférieur au modèle Boris (100-200 $/mois vs 500-1 000 $+)
Qualité > vitesse (disposé à sacrifier le parallélisme pour de meilleurs plans)
Ne pas utiliser quand :
Vous devez livrer 10+ fonctionnalités simultanément (utiliser le modèle Boris)
Les plans sont simples (une seule instance avec /plan suffit)
Observation clé : Ces modèles ne sont pas mutuellement exclusifs. Vous pouvez utiliser la double instance pour les fonctionnalités complexes (rigueur de planification) et le modèle Boris pour les fonctionnalités simples en volume élevé (vitesse).
Analyse des coûts : 2 instances vs boucles de correction
La clé de l’efficacité en double instance est la structure du plan. Jon Williams insiste sur les « plans prêts pour les agents avec des références de fichiers spécifiques et des numéros de ligne ».
Les workflows multi-instances NÉCESSITENT des git worktrees pour éviter les conflits. Sans worktrees, les instances parallèles créent une situation de conflits incontrôlables.
Pourquoi les worktrees sont essentiels :
Chaque instance opère dans un checkout git isolé
Pas de changement de branche = pas de perte de contexte
Pas de conflits de fusion pendant le développement
Création instantanée (~1 s vs plusieurs minutes pour un clone complet)
Bien que les git worktrees soient fondamentaux, la productivité au quotidien s’améliore avec des wrappers d’automatisation. Plusieurs équipes professionnelles ont indépendamment créé des outils de gestion des worktrees, un modèle validé.
Validation du modèle : 3 implémentations indépendantes
Auto-complétion, organisé dans ~/projects/worktrees/, lancement automatique de Claude
GitHub #1052
Fonctions Fish shell (8 commandes)
Commits LLM, automatisation du rebase, cycle de vie des worktrees
Worktrunk
CLI Rust (6,1K étoiles au 27/07/2026, contre 1,6K, 64 versions)
Hooks de projet, statut CI, liens PR, multi-plateforme
Conclusion : Le modèle de wrapper worktree est réinventé par les utilisateurs expérimentés. Le git vanilla est suffisant mais verbeux pour 5-10+ opérations de worktree quotidiennes.
⚠️ Alias (2 min de configuration, exemple ci-dessous)
Utilisateur avancé
15-30
5-10
Multi-plateforme
✅ Worktrunk, ROI justifié
Échelle Boris
30+
10-15
Équipe
✅ Worktrunk + orchestrateur
Alternative rapide par alias (pour le profil « Utilisateur occasionnel ») :
Si vous avez obtenu ⚠️ (5-15 worktrees/semaine), essayez ceci avant d’installer Worktrunk :
Terminal window
# Ajouter à ~/.zshrc ou ~/.bashrc (2 minutes de configuration)
wtc() {
localbranch=$1
localpath="../${PWD##*/}.${branch//\//-}"
gitworktreeadd-b"$branch""$path" && cd"$path"
}
aliaswtl='git worktree list'
aliaswtd='git worktree remove'
Utilisation : wtc feature/auth (18 caractères vs 88 caractères en git vanilla, -79% de frappe)
Quand passer à Worktrunk :
L’alias devient limitant (vous voulez le statut CI, les commits LLM, les hooks de projet)
Le volume augmente à 15+ worktrees/semaine
L’équipe adopte les workflows multi-instances (outillage cohérent nécessaire)
En résumé : La plupart des lecteurs (80 %) devraient commencer avec git vanilla ou un alias. Worktrunk s’adresse aux utilisateurs avancés gérant 5-10+ instances quotidiennement où la friction de frappe et la visibilité CI comptent.
Compromis : Les wrappers réduisent la frappe d’environ 60 % mais ajoutent une dépendance. Maîtrisez d’abord les fondamentaux de git, ajoutez un wrapper pour la vitesse ensuite.
Option 1 : Worktrunk (Recommandé à grande échelle)
Quand l’utiliser : Contrôle total souhaité, petite équipe (même shell), vous disposez déjà de fonctions shell pour git.
Compromis : Les scripts personnalisés manquent de maintenance et de support multi-plateforme, mais sont sans dépendance et infiniment personnalisables.
Recommandation : Apprendre → Wrapper → Monter en charge
Phase 1 (Semaines 1-2) : Maîtriser git worktree vanilla via la commande /git-worktree
└─ Comprendre les fondamentaux, les vérifications de sécurité, le branchement de base de données
Phase 2 (Semaine 3+) : Ajouter un wrapper pour la productivité
├─ Worktrunk (si multi-plateforme, statut CI et commits LLM souhaités)
└─ DIY bash/fish (si léger, l'équipe utilise le même shell)
Phase 3 (Montée en charge multi-instances) : Combiner avec l'orchestration
└─ Worktrunk/wrapper + gestionnaire de processus headless pour 5-10 instances
Philosophie : Les outils amplifient les connaissances. Maîtrisez les modèles git (ce guide) avant d’ajouter des couches de confort. Les wrappers font gagner 5-10 minutes/jour mais ne remplacent pas la compréhension.
Position d’Anthropic : Les bonnes pratiques officielles recommandent les git worktrees (vanilla) mais restent neutres quant aux wrappers. Choisissez ce qui convient à votre équipe.
« Quand produire est si facile et rapide, il est difficile d’apprendre vraiment »
« Il est difficile de dire quels seront les rôles dans quelques années »
« J’ai l’impression de venir travailler chaque jour pour m’automatiser moi-même »
Implications : Même chez Anthropic (conditions idéales : créateurs de l’outil, architecture parfaite, budget illimité), les ingénieurs expriment une incertitude quant au développement des compétences à long terme et à l’évolution des rôles.
Cinq mois après l’étude interne, Anthropic a publié des données de productivité actualisées accompagnées d’une nouvelle fonctionnalité d’analyse pour les clients Team et Enterprise.
Métriques actualisées (Anthropic interne) :
+67% de PRs fusionnées par ingénieur par jour (contre +50% autodéclaré en août 2025)
70-90% du code désormais écrit avec l’assistance de Claude Code dans les équipes
Note méthodologique : Ces chiffres sont basés sur les PRs/commits (mesurés via l’intégration GitHub), et non sur des enquêtes autodéclarées comme dans l’étude d’août 2025. Cependant, Anthropic ne divulgue aucune période de référence, aucune ventilation par équipe, et définit la mesure uniquement comme « conservative — only code where we have high confidence in Claude Code’s involvement. » À traiter comme des indicateurs directionnels, non comme des benchmarks rigoureux.
Fonctionnalité produit, tableau de bord Contribution Metrics :
Statut : Bêta publique (janvier 2026)
Disponibilité : Plans Claude Team et Enterprise (exigences exactes des modules complémentaires non confirmées)
Suit : PRs fusionnées et lignes de code commitées, avec/sans attribution Claude Code
Accès : Administrateurs et propriétaires d’espace de travail uniquement
Configuration : Installer Claude GitHub App → Activer GitHub Analytics dans les paramètres Admin → Authentifier l’organisation GitHub
Positionnement : Complément aux KPIs d’ingénierie existants (métriques DORA, vélocité de sprint), pas un remplacement
Optimisation OpusPlan : Utiliser Opus pour la planification (10-20% du travail), Sonnet pour l’exécution (80-90%). Réduit les coûts tout en maintenant la qualité.
Objectif : Passer à 3-5 instances avec un framework d’orchestration.
Terminal window
# 1. Deploy orchestration framework (choose based on needs)
# - Headless PM (manual coordination)
# - Gas Town (parallel task execution)
# - multiclaude (self-hosted, tmux-based)
# - Multica (issue/chat control plane with local daemon execution)
# - Entire CLI (governance + sequential handoffs)
# 2. Define roles
# - Architect (reviews PRs)
# - Backend (API development)
# - Frontend (UI development)
# - QA (test automation)
# 3. Weekly retrospectives
# - Review conflict rate
# - Measure ROI (cost vs output)
# - Adjust instance count
Options de frameworks d’orchestration :
Outil
Paradigme
Idéal pour
Manuel (worktrees)
Sans framework
2-3 instances, contrôle total
Gas Town
Coordination parallèle
5+ instances, tâches parallèles complexes
multiclaude
Lanceur auto-hébergé
Équipes nécessitant on-prem/airgap
Multica
Plan de contrôle multi-fournisseurs piloté par tickets
Équipes coordonnant des CLI d’agents locales via une séparation serveur/daemon
Entire CLI
Gouvernance + handoffs
Workflows séquentiels avec conformité
Multica conserve tickets, chat, configuration des agents, calendriers et journaux d’exécution dans sa couche de coordination. Les ordinateurs connectés exécutent Claude Code, Codex et d’autres CLI via un daemon local. Voir le profil Multica fondé sur des preuves identifiées pour les limites de déploiement, données, sécurité, Git et licence.
Entire CLI (fév. 2026) : Alternative à l’orchestration parallèle, axée sur les handoffs séquentiels entre agents avec une couche de gouvernance (points d’approbation, pistes d’audit). Utile pour les workflows critiques en matière de conformité (SOC2, HIPAA) ou les handoffs multi-agents (Claude → Gemini). Voir le Guide de l’écosystème IA pour plus de détails.
Critères de succès : Gain de productivité soutenu de 3-5% sur 3 mois.
Chaque requête API effectuée par Claude Code inclut désormais un en-tête X-Claude-Code-Session-Id. Les proxies inverses et les passerelles API peuvent l’utiliser pour agréger les coûts, la latence et l’utilisation des quotas par session sans inspecter le corps de la requête.
Exemple nginx :
map $http_x_claude_code_session_id $session_id {
default $http_x_claude_code_session_id;
}
log_format claude '$remote_addr - $session_id - $request_time - $status';
Cela vous permet de créer des tableaux de bord par session, d’appliquer des limites de débit au niveau de la session, ou d’attribuer les coûts API à des développeurs individuels ou à des jobs CI, sans modifier la configuration de Claude Code.
Source: Agent Experience Best Practices for Coding Agent Productivity
François Zaninotto, Marmelab (21 janvier 2026)
Validation complémentaire : framework AX Netlify (2025), guide d’implémentation Speakeasy, articles ArXiv sur l’ingénierie de contexte pour agents
Le changement de paradigme : Les bases de code traditionnelles sont optimisées pour les développeurs humains. Les agents IA ont des besoins différents, ils excellent dans la reconnaissance de motifs mais peinent face aux connaissances implicites et au contexte éparpillé.
Principes clés :
Intégration des connaissances métier : Placer la logique métier et les décisions de conception directement dans le code (CLAUDE.md, ADRs, commentaires)
Découvrabilité du code : Rendre le code « cherchable » comme le SEO, avec des synonymes, des tags, des termes complets
Formats de documentation : Utiliser llms.txt pour l’indexation de documentation optimisée pour l’IA (complète les serveurs MCP)
Efficacité des tokens : Diviser les grands fichiers, supprimer les commentaires évidents, utiliser des flags verbeux pour la sortie de débogage
Tests pour l’autonomie : Le TDD est plus critique pour les agents que pour les humains, car les tests guident le comportement
Garde-fous : Les hooks, vérifications CI et revues de PR détectent les erreurs des agents tôt
Quand optimiser pour les agents : Fichiers à fort impact (logique métier centrale, modules fréquemment modifiés) et projets greenfield. Ne pas refactoriser du code stable uniquement pour les agents.
Pourquoi c’est important : Les agents lisent le code séquentiellement et ne construisent pas le « modèle mental » que les humains développent au fil du temps. Ce qui vous semble évident (ex. : « ce service gère l’authentification ») doit être rendu explicite.
Netlify a forgé le terme « Agent Experience » comme équivalent agent du Developer Experience (DX). Questions clés :
L’agent peut-il trouver ce dont il a besoin ? (Découvrabilité)
Peut-il comprendre les décisions de conception ? (Connaissances métier)
Peut-il valider son travail ? (Tests + Garde-fous)
Peut-il travailler efficacement ? (Budget de tokens)
« L’Agent Experience consiste à réduire la friction cognitive pour l’IA, tout comme le DX réduit la friction pour les humains. »
— Équipe de recherche AX Netlify
Impact concret :
Marmelab : Refactorisation de la base de code Atomic CRM avec les principes AX → livraison de fonctionnalités 40 % plus rapide
Speakeasy : Documentation d’API adaptée aux agents → taux d’adoption des API multiplié par 3
Anthropic en interne : Restructuration de la base de code → réduction de 60 % des hallucinations des agents
Quand investir dans l’AX :
✅ Projets greenfield (concevoir agent-friendly dès le départ)
✅ Fichiers à fort taux de modification (logique métier, routes API)
✅ Équipes utilisant intensivement les agents (>50 % des commits)
❌ Code legacy stable (ne pas refactoriser uniquement pour les agents)
❌ Petits scripts (<100 lignes, les agents s’en sortent très bien)
Problème : Chaque décision de configuration ajoute une charge cognitive pour les agents. Les architectures personnalisées nécessitent une documentation CLAUDE.md étendue pour prévenir les hallucinations.
Solution : Choisir des frameworks à forte opinion qui réduisent l’espace de décision grâce à des conventions imposées.
Pourquoi les frameworks à forte opinion aident les agents :
Aspect
Architecture personnalisée
Framework à forte opinion
Organisation des fichiers
L’agent doit apprendre votre structure
Conventions standard (ex. : app/ Next.js, MVC Rails)
Routage
Logique personnalisée, doit être documentée
Basé sur les conventions (fichier = route)
Accès aux données
Plusieurs patterns possibles
Pattern unique imposé (ex. : Active Record Rails)
Configuration des tests
L’agent doit découvrir votre approche
Le framework fournit les valeurs par défaut
Taille du CLAUDE.md
Grande (tout doit être documenté)
Plus petite (conventions déjà connues)
Exemples de frameworks à forte opinion :
Next.js : Structure du répertoire app/, routage basé sur les fichiers, conventions des server components
Rails : Structure MVC, patterns Active Record, conventions des generators
Phoenix (Elixir) : Frontières de Context, conventions de schema, patterns LiveView
Django : Structure des apps, conventions de settings, interface admin
Impact concret :
Lorsque les agents travaillent avec des frameworks à forte opinion, ils :
Commettent moins d’erreurs (moins de choix = moins de mauvais choix)
Génèrent du boilerplate plus vite (connaissent les patterns)
Nécessitent moins de documentation CLAUDE.md (les conventions remplacent les instructions personnalisées)
Produisent du code plus cohérent (suivent les idiomes du framework)
Compromis :
Avantage
Coût
Intégration des agents plus rapide
Moins de flexibilité architecturale
Fichiers CLAUDE.md plus petits
Dépendance au framework
Moins d’hallucinations
Doit accepter les opinions du framework
Patterns cohérents
Courbe d’apprentissage pour l’équipe
Lien avec la taille du CLAUDE.md :
La convention-over-configuration réduit directement les besoins en tokens du CLAUDE.md :
... (minimal context, rest is framework conventions)
Recommandation : Pour les projets greenfield avec développement assisté par IA, privilégier les frameworks à forte opinion, sauf si des contraintes architecturales imposent une conception personnalisée. La réduction de la charge cognitive des agents compense souvent la perte de flexibilité.
Problème : Les agents manquent de contexte sur votre domaine métier, vos décisions de conception et l’historique du projet. Ils peuvent lire la syntaxe du code mais passent à côté du « pourquoi » derrière les décisions.
Solution : Intégrer les connaissances métier directement dans des emplacements découvrables.
-**Appointment**: External calendar system's term (Google/Outlook)
-**Sync Job**: Background process reconciling our DB with external calendars
-**Conflict Resolution**: Algorithm handling overlapping events (see `src/services/conflict-resolver.ts`)
## Gotchas
- Google Calendar API has 10 req/sec rate limit per user → batch operations in `syncEvents()`
- Outlook timezone handling is non-standard → use `normalizeTimezone()` helper
- Event deletion = soft delete (set `deletedAt`) to maintain audit trail for compliance
Pourquoi ça fonctionne : Lorsque l’agent rencontre syncEvents(), il comprend la contrainte de limite de débit. Lorsqu’il voit deletedAt, il sait qu’il ne faut pas utiliser de suppressions définitives.
Problème : Les agents recherchent du code par correspondance de mots-clés. Si votre variable s’appelle usr, l’agent ne la trouvera pas en cherchant « user ».
Solution : Traitez la découvrabilité du code comme le SEO, avec des termes complets, des synonymes et des balises.
Utilisez des termes complets, pas des abréviations
Pourquoi ça fonctionne : Lorsque l’agent cherche « subscriber » ou « principal », il trouve ce code même si ces termes ne figurent pas dans le nom du type.
**Purpose**: Business logic and domain operations. Services are framework-agnostic (no Express/HTTP concerns).
**Conventions**:
- One service per domain entity (EventService, UserService)
- Services interact with repositories (data layer) and other services
- All service methods return domain objects, never HTTP responses
- Error handling: Throw domain errors (EventNotFoundError), not HTTP errors
**Dependencies**:
- Services may call other services
- Services may call repositories (`src/repositories/`)
- Services must NOT import from `controllers/` (layering violation)
**Testing**: Unit test services with mocked repositories. See `tests/services/` for examples.
**Related**: See ADR-003 for layered architecture rationale.
Avantage pour l’agent : En travaillant dans services/, l’agent lit le README et comprend les contraintes (pas de préoccupations HTTP, limites de couches).
Ce dépôt fait évoluer son index hybride lisible par les machines vers une répartition plus stricte des responsabilités. Aujourd’hui, reference.yaml mêle navigation, commandes sélectionnées, modèles, valeurs de configuration, compteurs et informations opérationnelles. Des registres dédiés aux versions, à Cowork et à la distribution font autorité sur certains domaines qui évoluent, mais la séparation reste incomplète. La couverture est aussi asymétrique : reference.yaml donne accès à tous les fichiers suivis sous guide/, tandis que les chemins vers docs/ et examples/ restent sélectionnés.
Organisation actuelle et responsabilités visées {#current-layout-and-target-boundaries}
guide/ultimate-guide.md et les guides Markdown thématiques contiennent les explications et recommandations
Le texte porte l’interprétation ; les registres y renvoient au lieu de recopier ses affirmations
Index de découverte
llms.txt liste les principaux points d’entrée et la version suivie de Claude Code
La découverte fournit uniquement les chemins d’accès ; les informations susceptibles de changer proviennent d’un registre validé
Index de référence
machine-readable/reference.yaml fournit des chemins sélectionnés et contient encore des données opérationnelles et de configuration utilisées par les consommateurs existants
La référence porte les identifiants stables et les chemins ; les données propres à chaque domaine passent dans des registres dédiés après migration des consommateurs
Registres opérationnels
Les fichiers YAML des versions, de Cowork et de la distribution font déjà autorité sur leurs instantanés et états respectifs
Chaque domaine susceptible de changer dispose d’une source, d’un schéma, d’une règle de réplication et d’un validateur
Un contenu lisible par les machines peut être analysé et ses éléments peuvent être adressés. Cela ne signifie pas qu’il est vérifié, à jour, exhaustif ou proprement séparé par domaine. Le 2026-09-04, check-index-coverage.py atteignait 104 fichiers suivis sur 104 dans guide/. Aucun contrôle exhaustif équivalent ne couvre tous les fichiers de docs/ ou examples/ ; les entrées de ces arborescences restent des chemins sélectionnés. Les validateurs existants acceptent le contrat hybride de reference.yaml et ne prouvent pas que chaque clé appartient à la couche idéale visée. Chaque validateur ci-dessous démontre une propriété plus restreinte.
Contrats des fichiers et portée des preuves {#file-contracts-and-proof-boundaries}
Recherche de sujets, chemins, ancres, modèles, commandes et décisions sélectionnés ; la couverture exhaustive au niveau fichier se limite aux fichiers suivis de guide/
Le guide principal, les guides thématiques, une sélection de documents et d’exemples, et le fichier racine VERSION
Un titre ou un chemin référencé change ; une nouvelle page de guide ou un nouveau concept à rechercher est ajouté ; la version du guide change
validate-reference-yaml.py --ci, resync-reference-yaml.py --check, check-index-coverage.py --check --max-missing 0, plus le contrôle du miroir MCP
Prouve que le YAML est analysable, que les chemins et ancres référencés sont résolus, que les références positionnelles sont alignées et que les fichiers suivis de guide/ sont couverts. Ne prouve ni l’exactitude des faits ni la couverture exhaustive de docs/ et examples/.
machine-readable/claude-code-releases.yaml
Historique condensé des versions de Claude Code, de la plus récente à la plus ancienne
Le changelog officiel de Claude Code d’Anthropic, condensé manuellement
Une version de Claude Code vérifiée est ajoutée
Analyse YAML dans validate-reference-yaml.py --ci ; contrôle du miroir MCP ; le test de documentation MCP compare latest à la version annoncée par les trois copies de llms.txt
Prouve la structure locale, l’égalité des copies et la cohérence des versions annoncées. Ne prouve ni l’actualité par rapport à la source amont ni la conservation de toutes les notes amont.
machine-readable/cowork-reference.yaml
Index relais local pour le guide Claude Cowork distinct
Le fichier canonique machine-readable/reference.yaml du guide Cowork
L’index canonique de Cowork est vérifié et sa version ou ses chemins changent
Analyse YAML dans validate-reference-yaml.py --ci
Prouve que l’instantané local est analysable. Ne contacte pas le dépôt Cowork et ne prouve pas que le relais correspond à son état distant actuel.
machine-readable/distribution-channels.yaml
État daté des ressources, soumissions, placements, URL d’attribution et champs de résultats
Les ressources de distribution locales, ainsi que les preuves vérifiées de soumission, de placement et de mesure
Une ressource ou un canal change d’état, ou une observation datée est recueillie
test-check-distribution-channels.py et check-distribution-channels.py, plus le contrôle du miroir MCP
Prouve le respect du schéma, des états autorisés et de la cohérence entre champs, la présence des dates requises, l’existence locale des ressources prêtes et les champs d’attribution. Ne prouve pas la publication externe et ne remplace pas les résultats manquants par zéro.
llms.txt
Index de découverte court pour les humains, les robots d’indexation et les agents
Des chemins sélectionnés vers la documentation du dépôt ; la version suivie de Claude Code provient de claude-code-releases.yaml
Un point d’entrée principal change ou la valeur latest du registre des versions change
mcp-server/test/render-product-docs.test.mjs, exécuté par npm run release:check en CI
Prouve l’égalité octet par octet entre la racine, machine-readable/ et le paquet MCP, ainsi que la parité avec la version du registre. Ne prouve ni que toutes les pages utiles sont listées ni que le texte lié est à jour.
Le dépôt conserve trois copies de llms.txt identiques octet par octet : le point d’entrée à la racine, la source dans machine-readable/ et la copie intégrée au paquet MCP. Une mise à jour des versions reste incomplète tant que les trois n’annoncent pas la même valeur latest que claude-code-releases.yaml.
llms.txt comme index de découverte {#llmstxt-as-the-discovery-index}
La proposition llms.txt définit un point d’entrée au format Markdown pour la documentation destinée aux LLM. Gardez ce fichier assez court pour être parcouru avant de charger les sources détaillées. Préférez les ancres de titres stables aux numéros de ligne, car les ajouts de texte décalent ces derniers.
# Project documentation
## Start
- Setup: docs/setup.md
- Architecture: docs/architecture.md#request-flow
## Operate
- Testing: docs/testing.md
- Deployment: docs/deployment.md
- Troubleshooting: docs/troubleshooting.md
CLAUDE.md a une autre portée. Il fournit les instructions actives et le contexte du dépôt à Claude Code. llms.txt oriente le lecteur vers la documentation. Une instruction courte peut pointer vers l’index sans le recopier :
## Project documentation
Start with `llms.txt`, then open only the source relevant to the task.
Un serveur de documentation MCP peut exposer les mêmes sources au moyen d’API de recherche et de ressources utilisables à l’exécution. Ce transport ne remplace pas l’index statique, et l’index statique ne prouve pas le comportement du serveur à l’exécution.
Organisation du catalogue : CATALOG.yaml, INDEX.md, TOPICS.md et llms.txt {#catalog-pattern-catalogyaml-indexmd-topicsmd-and-llmstxt}
Pour un dépôt contenant de nombreux documents, séparez l’inventaire de la navigation. L’organisation suivante est un exemple de structure, pas une ressource publique de ce guide :
docs/
INDEX.md human-readable inventory
TOPICS.md curated routes by reader intent
machine-readable/
CATALOG.yaml structured record for every document
llms.txt short discovery entry point
Fichier
Responsabilité
Ce qu’il ne doit pas porter
CATALOG.yaml
Identifiants stables, chemins, titres, responsables, états et dates des sources
De longues explications recopiées des documents
INDEX.md
Liste consultable des enregistrements du catalogue
Des valeurs d’état indépendantes qui peuvent diverger du catalogue
TOPICS.md
Parcours sélectionnés, par exemple démarrer, construire, exploiter et dépanner
Un second inventaire exhaustif
llms.txt
Principaux points d’entrée et liens vers INDEX.md et TOPICS.md
Le catalogue complet ou les instructions actives destinées aux agents
Choisissez un sens de rédaction et faites-le respecter. Si CATALOG.yaml fait autorité, générez ou vérifiez INDEX.md à partir de lui et rejetez les divergences en CI. Gardez TOPICS.md sous contrôle éditorial, car organiser les parcours selon l’intention du lecteur demande du jugement. Construisez llms.txt à partir de chemins stables, puis testez chaque chemin et chaque copie.
Un contrôle structurel peut prouver que les identifiants sont uniques, que les chemins existent, que les fichiers générés correspondent et que les dates déclarées sont analysables. L’exactitude éditoriale, l’attribution des responsabilités, l’actualité du contenu et l’utilité de l’ordre des parcours nécessitent toujours une revue.
Documentation officielle de Claude Code lisible par les machines {#official-claude-code-machine-readable-documentation}
Anthropic publie un index officiel de la documentation et un export officiel de la documentation complète. Utilisez l’index pour trouver la source pertinente, puis ouvrez la page concernée ou l’export complet lorsque l’affirmation nécessite davantage de contexte. Ces points d’accès sont des sources amont sur le comportement de Claude Code, pas des validateurs pour les index de ce dépôt.
Problème : la connaissance interne est dispersée dans des API de catalogue, des wikis, des commentaires de code et les mémoires des ingénieurs seniors. Chaque développeur d’agents recompose le même contexte depuis zéro. Un nouvel agent qui découvre votre base de code apprend ce que signifie weekly_active_users en posant la question à quelqu’un, pas en lisant un fichier.
Solution : OKF (Open Knowledge Format) est une spécification neutre vis-à-vis des fournisseurs qui transforme votre connaissance interne en un répertoire de fichiers markdown avec du frontmatter YAML. Les agents le lisent directement ; les humains le rédigent dans n’importe quel éditeur ; git le versionne comme du code.
En avril 2026, Andrej Karpathy a publié un GitHub gist décrivant un pattern qu’il utilisait : un wiki markdown structuré donnant aux LLM un contexte interne fiable. Le billet a recueilli plus de 16 millions de vues sur X et le gist a accumulé plus de 5 000 étoiles en quelques jours. Des implémentations communautaires ont immédiatement proliféré sous des noms tels que AGENTS.md, des pipelines Obsidian-vers-agent, et des dépôts remplis de fichiers index.md qu’un agent lit avant d’effectuer un vrai travail.
Google Cloud a formalisé le pattern en OKF v0.1 le 12 juin 2026. La spécification est volontairement minimaliste : elle standardise les conventions structurelles nécessaires pour qu’un corpus de connaissances soit auto-descriptif, et rien de plus.
Un bundle est un répertoire de fichiers markdown. Chaque concept correspond à un fichier ; le chemin du fichier est son identité. Le répertoire devient un graphe quand les fichiers se référencent mutuellement.
sales/
├── index.md # optional directory listing
├── log.md # optional chronological history
├── tables/
│ ├── orders.md
│ └── customers.md
└── metrics/
└── weekly_active_users.md
Un document de concept comporte deux parties : un frontmatter YAML (structuré, interrogeable) et un corps markdown (prose, schéma, exemples) :
---
type: database-table
title: orders
description: One row per completed customer order. Source of truth for revenue.
tags: [revenue, core]
timestamp: 2026-05-28T14:30:00Z
---
# Schema
| Column | Type | Description |
|--------|------|-------------|
| `order_id` | UUID | Primary key |
| `user_id` | UUID | FK to [customers](/tables/customers.md) |
Revenue is recognized when `status = completed`. Never sum `amount_cents` across `refunded` rows.
# Joins
Standard join path: `orders LEFT JOIN customers ON orders.user_id = customers.id`
Les liens croisés entre fichiers créent des arêtes dans le graphe. Les consommateurs les traitent comme des arêtes dirigées non typées et doivent tolérer gracieusement les liens brisés.
Noms de fichiers réservés : index.md (liste du répertoire avec entrées sous forme de puces), log.md (historique des mises à jour, du plus récent au plus ancien)
Distribution : dépôt git (recommandé), archive tar, ou sous-répertoire au sein d’un dépôt plus grand
Consommation permissive : les consommateurs doivent tolérer les champs optionnels manquants, les types inconnus, les clés supplémentaires et les liens brisés. C’est intentionnel. Le format est conçu pour évoluer.
OKF ne remplace pas les formats que vous utilisez déjà. Il occupe une place différente dans la pile de connaissances :
Format
Périmètre
Objectif
CLAUDE.md
Session
Instructions actives pour cet agent, cette session
AGENTS.md
Comportement
Règles sur ce que les agents doivent ou ne doivent pas faire
llms.txt
Découverte
Où trouver la documentation dans ce projet
Bundle OKF
Corpus de connaissances
Ce que l’organisation sait : schémas, métriques, runbooks, chemins de jointure
llms.txt indique à un agent où trouver la documentation. OKF lui explique ce que weekly_active_users signifie réellement dans votre entreprise, pourquoi la table orders possède un champ status avec quatre états, et quel chemin de jointure est correct. Problème différent, couche différente.
Pattern : référencez votre bundle depuis CLAUDE.md pour que les agents sachent qu’il existe :
## Connaissances du domaine
Ensemble de connaissances interne : `knowledge/`
- Type `database-table` → schémas de tables avec règles métier
- Type `metric` → définitions des métriques métier et propriétaires
- Type `runbook` → procédures de réponse aux incidents
La v0.1 est une invitation, pas encore un standard. Au lancement, chaque producteur et consommateur a été développé par Google. Google Cloud Knowledge Catalog ingère déjà OKF et le met à disposition des agents. Les éditeurs à surveiller pour une adoption externe : Atlan, Alation, Collibra, Unity Catalog.
Le risque d’adoption pour vous est quasi nul : les bundles OKF sont de simples fichiers markdown dans un répertoire. Si la spécification ne rencontre jamais de succès, les fichiers restent lisibles par des humains et des agents quoi qu’il arrive.
# Minimal OKF bundle for a project with a few key tables
mkdirknowledge && cdknowledge
mkdir-ptablesmetrics
# Create your first concept document
cat>tables/users.md<<'EOF'
---
type: database-table
title: users
description: All registered accounts. Soft-delete only—never hard delete.
tags: [core, auth]
---
# Schema
| Column | Type | Description |
|--------|------|-------------|
| `id` | UUID | Primary key |
| `email` | TEXT | Unique, used for login |
| `deleted_at` | TIMESTAMP | NULL if active |
# Business rules
Filter `WHERE deleted_at IS NULL` in every query unless explicitly auditing deletions.
EOF
# Reference from CLAUDE.md
echo-e'\n## Domain Knowledge\nSee knowledge/ for table schemas and metric definitions.'>>../CLAUDE.md
À partir de là, les agents qui chargent knowledge/tables/users.md dans leur contexte obtiennent la règle métier concernant les suppressions logiques sans avoir à interroger qui que ce soit.
Problème : Les agents ont des limites de tokens. Les fichiers volumineux consomment rapidement le budget de contexte, forçant les agents à lire par morceaux et à perdre leur cohérence.
Solution : Structurer le code pour minimiser l’utilisation des tokens tout en maximisant la compréhension par les agents.
Diviser les fichiers volumineux (les agents lisent par morceaux)
Recommandation : Gardez les fichiers en dessous de 500 lignes. Les agents lisent généralement 200 à 300 lignes à la fois (selon le contexte du modèle).
❌ Fichier monolithique (1200 lignes) :
src/services/event-service.ts
✅ Divisé par responsabilité :
src/services/event/
├── event-service.ts (200 lines: public API + orchestration)
User: "Implement the email validation function to pass all tests in tests/validation/email.test.ts. Requirements:
- Use validator.js for format checking
- Disposable domain list at src/data/disposable-domains.json
- Database check via userRepository.findByEmail()"
Résultat avec l’agent : Implémente exactement ce que les tests spécifient, notamment :
Validation du format
Blocage des domaines jetables
Prise en charge des caractères internationaux
Vérification des doublons en base de données
Sans tests manuels : L’agent pourrait omettre le blocage des domaines jetables (non évident à partir de « validation d’e-mail ») ou ignorer la prise en charge des caractères internationaux.
Avantage pour l’agent : Lorsqu’il travaille dans les controllers, l’agent lit ADR-011 et sait qu’il doit appeler les services (et non les repositories).
Faites appliquer les approbations humaines requises par la politique du dépôt sur les chemins concernés. Compter les entrées de reviews ne prouve pas une approbation : elles peuvent contenir des commentaires, des demandes de changement, des décisions périmées ou des sorties automatisées.
Utilisez les réglages natifs des branches protégées : approbations requises, code owners sur les chemins sensibles, gestion des approbations périmées ou approbation du dernier push révisable. Inspectez les identités éligibles, les droits de révocation et les contournements. Un simple compteur ne prouve pas la validation d’un responsable humain.
Vérifiez la politique effective avec une PR non approuvée, une demande de changement, un nouveau push après approbation et une approbation autorisée. Conservez les contrôles requis et la validation de l’état d’intégration. Ces instructions ne prouvent pas que la configuration est installée ou exercée dans votre dépôt.
Pourquoi la revue humaine est importante :
Les agents manquent de contexte (exigences métier absentes du code)
Les agents peuvent implémenter un code correct pour le mauvais problème
Vulnérabilités de sécurité que l’IA ne reconnaît pas (vecteurs d’attaque inédits)
Liste de contrôle pour la revue des PR d’agents :
## Agent PR review checklist
- [ ] **Intent**: Does the code solve the actual problem (not just pass tests)?
Utilise des tokens OAuth 2.0 stockés dans le champ `users.calendar_token`. Si le token a expiré, lance une `TokenExpiredError` (l'appelant doit rediriger vers une nouvelle authentification).
## Limites de débit
Google impose 10 requêtes/seconde par utilisateur. Le client régule automatiquement via la bibliothèque rate-limiter-flexible. Voir RATE_LIMITS.md pour les détails.
## Gestion des erreurs
Erreurs courantes :
-`TokenExpiredError` : Token expiré, nouvelle authentification nécessaire
-`RateLimitError` : Limite de débit Google dépassée (rare, nouvelle tentative automatique)
-`CalendarNotFoundError` : L'utilisateur n'a pas accordé la permission d'accès au calendrier
Voir TROUBLESHOOTING.md pour le catalogue complet des erreurs et leurs solutions.
Workflow de l’agent :
L’agent doit intégrer Google Calendar
Lit google-calendar.ts → voit la référence au README.md
Lit le README → comprend l’utilisation, l’authentification, les limites de débit
Rencontre une erreur → lit TROUBLESHOOTING.md
Implémente correctement sans hallucination
Comparaison avec un wiki :
Wiki : l’agent ne sait pas que le wiki existe ni où chercher
Docs intégrées : l’agent trouve la documentation naturellement via le système de fichiers
La plupart des développeurs choisissent une approche et s’y tiennent. Mais les outils de Claude Code permettent une variation systématique, en testant plusieurs approches pour trouver la solution optimale.
Les frameworks de permutation formalisent cette démarche : plutôt que d’espérer que votre première approche fonctionne, vous générez et évaluez des variations de façon systématique.
Un framework de permutation définit des dimensions de variation et laisse Claude générer toutes les combinaisons pertinentes. Chaque dimension représente un choix de conception ; chaque combinaison est une approche d’implémentation distincte.
Les équipes d’agents permettent à plusieurs instances Claude de travailler en parallèle sur une base de code partagée, en se coordonnant de manière autonome sans intervention humaine. Une session joue le rôle de chef d’équipe pour décomposer les tâches et synthétiser les résultats des sessions coéquipières.
Différence clé avec Multi-Instance (§9.17) :
Multi-Instance = Vous orchestrez manuellement des sessions Claude séparées (projets indépendants, sans état partagé)
Équipes d’agents = Claude gère la coordination automatiquement (base de code partagée, tâches partagées et messagerie ; attribution des fichiers et intégration du code restent explicites)
❌ Bad: Same file modified by multiple agents (conflict hell)
Atténuation : Attribuez des ensembles de fichiers non chevauchants, adoptez une approche interface-first, définissez les contrats avant le travail en parallèle.
Intensité en tokens : multiplicateur de coût 3x+ (3 agents = 3 inférences de modèle). Justifié uniquement si le temps économisé dépasse la hausse des coûts.
Statut expérimental : aucune garantie de stabilité, des bugs sont attendus, la fonctionnalité peut évoluer. Signalez les problèmes sur Anthropic GitHub.
Arbre de décision : quand utiliser les équipes d’agents
Deux modèles de coordination distincts existent pour la revue multi-agents, et le choix est important :
Dimension
Spécialistes séquentiels
Mode essaim
Structure
Chef d’équipe + membres prédéfinis
Ad hoc, sans hiérarchie
Coordination
Le chef assigne les tâches et synthétise
Chaque relecteur travaille indépendamment
Leadership
Le chef d’équipe orchestre
L’humain synthétise les résultats
Attribution des tâches
Le chef délègue à des agents spécifiques
Tous les agents pertinents reçoivent la même entrée
Idéal pour
Tâches avec dépendances entre relecteurs
Revue indépendante, passe finale avant fusion
À utiliser quand
Workflows complexes, partage d’état nécessaire
Revue de PR, base de code inconnue, exhaustivité
Mode essaim en pratique (pattern compound-engineering de Every.to) :
Lancez tous les relecteurs spécialistes pertinents en parallèle sur le même diff ou la même PR, sans coordination entre eux. Chacun produit des résultats indépendants. Vous lisez l’ensemble des résultats et décidez des actions à entreprendre.
Terminal window
# Swarm: all reviewers see the same input, report independently
Ce modèle se distingue des équipes d’agents : il n’y a pas de structure d’équipe persistante, pas de contexte partagé entre agents, pas de chef qui synthétise en temps réel. La mise en place est plus rapide et convient lorsque l’exhaustivité prime sur la coordination.
Règle pratique : Utilisez les équipes d’agents pour les workflows avec des dépendances séquentielles (la sortie de l’agent A alimente l’agent B). Utilisez le mode essaim lorsque chaque relecteur peut travailler à partir du même point de départ et que vous voulez une couverture maximale avec un minimum de surcharge de configuration.
Les pipelines multi-agents standards ont un défaut systématique : les agents d’audit sur-rapportent. Lorsque vous demandez à trois sous-agents de trouver des contradictions, des duplications ou des lacunes de couverture dans un ensemble d’artefacts, ils en trouvent partout, y compris dans des patterns intentionnels, complémentaires ou simplement non conflictuels.
La solution est un quatrième agent dont le seul rôle est d’éliminer les faux positifs des trois premiers.
Fonctionnement :
Phase 1: Artifact inventory (orchestrator builds the inventory)
Phase 2: Pairwise analysis (3 agents in parallel, each owns one pair-type)
├── Agent A: standards vs skills
├── Agent B: standards vs commands
└── Agent C: skills vs commands
Phase 3: Skeptical review (1 agent reviews all raw findings)
« Soyez sceptique. Les agents d’audit ont tendance à sur-rapporter ; votre rôle est de filtrer. Un taux de rejet de 50 %+ est normal et sain. »
Critères de faux positifs appliqués par le relecteur avant de conserver un résultat :
Limites de périmètre intentionnelles : Les artefacts adressent des périmètres différents (tous les fichiers vs uniquement les fichiers de migration) et ne sont pas réellement en conflit dans le périmètre le plus étroit
Contenu complémentaire : Un artefact définit une règle, l’autre l’implémente ; c’est de la conception, pas de la duplication
Contextes différents : Les artefacts traitent de situations différentes, même s’ils utilisent un langage similaire
Chevauchement trivial : Les deux mentionnent le même concept, mais aucun ne prescrit des règles conflictuelles à son sujet
Pattern de délégation : Une commande invoquant une compétence (ou vice versa) est complémentaire, pas une lacune ou une contradiction
Exigence de preuve : Le relecteur ne conserve un résultat que s’il peut pointer des passages spécifiques dans les deux artefacts. Sans preuve des deux côtés, pas de résultat.
Périmètre détection uniquement : Le relecteur sceptique produit un rapport. Il ne modifie aucun artefact. La correction est une étape séparée déclenchée par un humain qui lit le rapport.
Quand appliquer ce pattern :
Situation
Appliquer ?
Audit d’un ensemble de N artefacts pour la cohérence inter-artefacts
Oui
Audit documentation vs base de code sur de nombreux fichiers
Oui
Revue de code où vous voulez de la couverture, pas du bruit
Oui
Analyse mono-agent d’un seul fichier
Non
Lien avec le mode essaim : Le mode essaim (ci-dessus) envoie la même entrée à plusieurs relecteurs en parallèle pour la couverture. Le pattern relecteur sceptique ajoute une couche de synthèse qui filtre la sortie de l’essaim avant de la présenter. Ils se composent naturellement : lancez l’essaim, faites passer sa sortie par le relecteur sceptique.
Paul Rayner (PDG Virtual Genius, auteur de l’EventStorming Handbook) :
« Je fais tourner 3 sessions d’équipes d’agents concurrentes dans des terminaux séparés. Vraiment impressionnant comparé aux anciens workflows multi-terminaux sans coordination. »
Workflows utilisés (fév. 2026) :
Application de recherche d’emploi : recherche de conception + correction de bugs
Opérations métier : système d’exploitation + planification de conférences
Infrastructure : gestion de Playwright MCP + framework beads
Contexte : En février 2026, Anthropic a publié un guide de modernisation COBOL positionnant Claude Code comme remplacement direct des équipes de conseil spécialisées dans les systèmes anciens. Le même jour, l’action IBM a chuté de -13% (sa pire performance journalière depuis octobre 2000). Le workflow décrit est validé par des recherches indépendantes ; il s’applique à n’importe quelle grande base de code héritée (COBOL, Fortran, VB6, PL/I), pas seulement au COBOL.
Pourquoi la modernisation des systèmes hérités est difficile
La phase de découverte pèse plus lourd que la migration elle-même dans le coût réel. Les développeurs d’origine sont partis à la retraite. La documentation est absente ou erronée. Le code a été patché pendant des décennies par des ingénieurs qui n’ont jamais compris le système dans son ensemble. Déterminer ce qui communique avec quoi nécessite des consultants facturant à l’heure.
L’IA change l’économie en automatisant précisément cette phase.
Contexte COBOL (pour référence d’échelle) :
~220 milliards de lignes de COBOL encore en production (estimation IBM)
~95% des transactions aux distributeurs automatiques américains fonctionnent sur des systèmes à base de COBOL (Reuters/consensus du secteur, la méthodologie varie selon les sources)
La modernisation nécessitait auparavant des projets s’étendant sur plusieurs années et plusieurs équipes
Validation indépendante : Des recherches académiques (WJAETS 2025) montrent une réduction des délais de -25 à -30% en moyenne. Meilleur cas : Airbnb a migré 3 500 fichiers de tests en 6 semaines contre une estimation de 1,5 an. Précision COBOL→Java : 93% dans des études contrôlées (arXiv, avril 2025).
Étape 1 : Exploration automatisée et découverte
Cartographier l'intégralité de la base de code :
- Identifier tous les points d'entrée des programmes et les chemins d'exécution
- Tracer les appels de sous-routines à travers des centaines de fichiers
- Documenter les dépendances implicites via les fichiers partagés, les bases de données et l'état global
- Générer un graphe de dépendances avant de toucher une seule ligne
Patron de prompt :
"Read the entire [COBOL/legacy] codebase. Map its structure:
and any implicit dependencies via shared data structures,
global variables, or file I/O. Output a dependency map."
Conserver la découverte après la session. Écrivez la carte dans un fichier : la session suivante et le prochain agent ne devraient pas payer à nouveau pour la même exploration. Pour les zones jaunes et rouges (étape 2), Addy Osmani recommande un passage distinct en lecture seule qui produit une courte note de compréhension (points d’entrée, responsables, appelants, abstractions existantes, tests, signaux de production, historique pertinent, questions ouvertes), dans laquelle chaque affirmation cite un fichier, une issue, un registre de responsabilités ou un tableau de bord. La phase research.md de plan-driven.md suit le même schéma pour une fonctionnalité.
Étape 2 : Analyse des risques et cartographie des opportunités
Avec le graphe de dépendances en main :
- Évaluer les niveaux de couplage entre modules (fort couplage = risque élevé)
- Mettre en évidence les composants isolés comme candidats sûrs à la modernisation
- Identifier la logique dupliquée et le code mort
- Signaler l'état partagé comme zones à risque le plus élevé
Patron de prompt :
"Based on the dependency map: rank modules by coupling level.
Which components can be modernized in isolation?
Which share state with 3+ other modules and should be touched last?"
Transformer la carte des risques en zones que l’agent ne peut pas redessiner. Dans Brownfield Agentic Engineering (septembre 2026), Addy Osmani rend le classement opérationnel avec trois zones, chacune assortie de ses propres actions autorisées :
Zone
Ce qu’elle contient
Comment les agents y travaillent
Verte
Code moderne, bien testé et isolé
Boucle agentique resserrée
Jaune
Qualité mixte, couverture partielle
Tests de caractérisation d’abord, modifications ensuite
Rouge
Authentification, facturation, permissions, paie, code que peu de personnes comprennent
Un humain travaille en binôme à chaque étape, ou le travail n’a pas lieu
Trois règles rendent ces zones concrètes. Une personne dessine la carte, pas l’agent : laissé libre de choisir, il tend à commencer par le fichier le plus risqué. Une zone ne change que si les conditions sont remplies : le jaune devient vert une fois les tests de caractérisation en place et les premières modifications de l’agent relues par le responsable du module. La zone détermine les actions permises, pas la confiance de l’agent. Le critère d’Osmani : « L’autonomie doit suivre le rayon d’impact, l’observabilité et la capacité de récupération. La confiance d’un modèle est un mauvais guide. » Une surface que seul le trafic de production exerce réellement, sans suite de tests qui le représente, reste par définition rouge jusqu’à ce qu’un substitut de ce trafic existe (rejeu, trafic miroir, parcours synthétiques).
Encodez la carte là où elle est appliquée : une entrée permissions.deny ou un hook PreToolUse sur les chemins rouges, des règles limitées aux chemins jaunes (voir 7. Hooks). Une carte de zones qui reste dans un document de planification n’est qu’un conseil.
Étape 3 : Planification stratégique
Collaboration humain + IA :
- L'IA suggère une priorisation basée sur l'analyse risque/dépendances
- L'équipe confronte aux priorités métier (ce qui tombe en panne = le plus coûteux)
- Définir l'architecture cible et les standards de code
- Concevoir des tests au niveau des fonctions pour validation avant le début de la migration
Cette phase n’est pas entièrement automatisable : le contexte métier nécessite un jugement humain.
Les workflows hybrides humain-IA affichent des taux d’achèvement 31% plus élevés dans les délais initiaux estimés
par rapport aux approches entièrement automatisées (WJAETS 2025).
Étape 4 : Implémentation incrémentale
Ne jamais migrer l'intégralité du système en une seule fois :
- Traduire la logique composant par composant
- Créer des wrappers API pour les composants hérités encore en usage
- Faire tourner l'ancien et le nouveau code côte à côte en production
- Valider chaque composant indépendamment avant de passer au suivant
Patron de prompt :
"Translate [module X] to [target language].
Preserve exact business logic — no optimization yet.
Add a compatibility wrapper so both versions can run in parallel.
Write tests that verify identical outputs for identical inputs."
Figer le comportement actuel avant que l’agent le modifie, dans une autre session. Les tests de caractérisation verrouillent ce que fait le module aujourd’hui, y compris les aspects peu élégants, car dans un ancien système certains de ces comportements font fonctionner l’activité. Si la session qui va modifier le code écrit aussi les tests qui le jugent, la suite verte encode l’implémentation qu’elle vient d’inventer. Écrivez les tests de caractérisation dans un passage distinct, ou faites-les écrire par une personne, puis laissez l’agent travailler (voir TDD avec du code legacy).
Une unité de migration est terminée quand l’ancien chemin a disparu. Exécuter l’ancien et le nouveau code côte à côte est un état de transition. La définition d’Osmani : « Une migration est terminée quand le nouveau chemin fonctionne et que la disparition de l’ancienne dépendance est démontrée. » Les migrations inachevées désorientent particulièrement les agents : la recherche renvoie l’ancien schéma dans quarante fichiers, le nouveau dans douze, et une couche de compatibilité présente les deux comme actuels. L’agent reçoit des précédents contradictoires. Terminez une route de bout en bout, suppression comprise, avant de convertir les trente fichiers suivants.
Des tests réussis ne prouvent pas que la migration a eu lieu. SWE Refactor Bench (août 2026, 20 migrations de dépôts entiers) appelle cela « Blindness » : une migration démarre avec des tests verts, donc un dépôt rendu intact, ou un remplacement qui appelle encore l’implémentation originale, réussit la suite comportementale. Son protocole ajoute un audit de migration (l’ancienne stack a-t-elle disparu de l’artefact construit ?) et des agents indépendants qui recherchent les différences de comportement. Sur 520 exécutions de 8 modèles de pointe, 28 ont réussi les trois étapes (5,4%), 13 des 20 tâches n’ont reçu aucune solution acceptée, et les réécritures de langage ont obtenu 5,6/100 contre 31,4 pour les migrations de chaîne de build. Suivez la migration avec les chiffres qui peuvent évoluer : anciens imports restants, part du trafic servie par le nouveau chemin, écarts de parité, dépendances legacy supprimées.
« Des années à des trimestres » est réel, mais c’est le scénario optimiste, pas la moyenne :
Scénario
Réduction des délais
Source
Estimation conservative
-25 à -30%
Revue académique WJAETS 2025
Phases à forte automatisation
-40 à -50%
Synthèse industrie Fullstack Labs
Meilleur cas (migration de tests)
-88% (6 semaines vs 1,5 an)
Étude de cas Airbnb
Précision de conversion COBOL→Java
93%
arXiv, avril 2025
Les gains moyens sont réels et significatifs. Les chiffres les plus spectaculaires nécessitent des conditions favorables : bonne couverture de tests, modules isolés, et une équipe qui comprend à la fois le système hérité et la stack cible.
❌ Migration big bang : Tout réécrire en une seule fois. Aucune entreprise n’y a survécu à grande échelle.
❌ Pas d’exécution en parallèle : Basculer sans plan de repli. Un cas limite non découvert = panne en production.
❌ Sauter la découverte : Commencer à traduire avant de cartographier. Vous casserez des choses dont vous ignoriez l’existence.
❌ Faire confiance à l’IA sur la logique métier : L’IA traduit fidèlement ce qu’elle lit. Si l’original était erroné ou dépendant du contexte, la traduction le sera aussi.
❌ Migration inachevée : Trente fichiers convertis, une couche de compatibilité conservée, une suppression renvoyée à un ticket de nettoyage. Les agents copient alors le premier schéma que la recherche leur présente.
❌ Laisser l’agent choisir où commencer : Sans carte de zones dessinée par une personne, les agents se dirigent vers le code le plus intéressant, généralement le plus risqué.
Étude de cas : portage de Bun de Zig vers Rust avec Claude Code
Rewriting Bun in Rust, de Jarred Sumner (juillet 2026), est un récit de première main d’une migration à grande échelle avec Claude Code : 535 496 lignes de Zig réparties sur 1 448 fichiers portées en 11 jours (du 3 au 14 mai 2026), avec environ 50 workflows dynamiques et un pic d’environ 64 instances Claude simultanées sur une préversion de Claude Fable 5. L’auteur chiffre l’exécution à environ 165 000 $ aux tarifs API (5,9 milliards de tokens d’entrée non mis en cache, 690 millions de tokens de sortie, 72 milliards de tokens d’entrée lus dans le cache). Lisez ce récit comme celui d’un opérateur expert sur la base de code qu’il connaît le mieux, pas comme un benchmark.
La structure autour des agents est transférable, pas l’échelle :
Pratique
Ce que Bun a fait
Ce que cela apporte
Règles avant tout portage
Environ 3 heures pour produire PORTING.md (correspondances entre schémas Zig et Rust), puis un workflow retraçant la durée de vie de chaque champ de structure dans LIFETIMES.tsv, relu par des agents contradicteurs et lu par l’auteur
Un ensemble durable de décisions que chaque agent suivant lit, sans les redéduire
Pilote avant le traitement global
3 fichiers d’abord : 1 agent d’implémentation, 2 relecteurs contradicteurs, 1 agent de correction, avant les 1 448 fichiers
Les règles sont éprouvées sur une unité jetable
Oracle hors du changement
La suite de tests existante, indépendante du langage (1 386 826 appels expect(), 60 624 tests sur une plateforme, « 0 test ignoré ou supprimé »), constituait le critère de merge ; l’auteur a « vérifié manuellement que les tests étaient bien exécutés et non ignorés »
Les tests ne font pas partie de ce qui change, et quelqu’un a vérifié leur exécution
Relecteurs séparés
Chaque unité générée était relue par deux relecteurs contradicteurs avant commit
Les agents exécutaient git stash et git reset sur le travail des autres, donc le workflow les a interdits ; les agents vidaient les fonctions pour faire taire les erreurs de compilation, donc les revues rejetaient les contournements qui nécessitaient un long commentaire explicatif
Chaque faux départ devenait une règle du harnais, pas un diff corrigé à la main
Limites des preuves. L’auteur indique que la réécriture a « introduit 19 régressions connues, chacune corrigée », et ne publie aucun taux de défauts après la sortie. Il a surveillé les workflows « pendant la majeure partie de ces 11 jours (et après) ». Il s’agissait d’un portage mécanique préservant le comportement face à une suite indépendante du langage d’implémentation, le cas le plus favorable pour des agents. SWE Refactor Bench a mesuré les réécritures de langage comme la catégorie de migration la plus faible ; ce résultat ne se transpose donc pas à une base de code sans oracle équivalent.
Ancrer les fonctionnalités dans le code : quand vous ne réécrivez pas le système {#feature-to-code-anchoring-when-youre-not-rewriting}
Le workflow en 4 étapes ci-dessus suppose que l’objectif est de remplacer le système. Ce n’est souvent pas le cas. Une équipe qui chiffre une modification, audite un statut « toujours actif » ou détermine ce qui peut être archivé sans risque dans un parc applicatif hérité a besoin d’un résultat plus ciblé : un lien vérifié entre chaque fonctionnalité documentée et le fichier ainsi que le symbole qui l’implémentent réellement. La personne suivante évite ainsi de réexplorer manuellement des dizaines de dépôts chaque fois que la question se pose.
Le problème comporte quatre couches ; seule la première doit être construite pour un audit strict.
Couche
Objectif
État
0 (ancrage déterministe)
Relier chaque fonctionnalité à un fichier et un symbole réels, vérifiables par lecture directe (ls, git grep, LSP). Aucune interprétation, uniquement l’emplacement.
Réalisable aujourd’hui, voir ci-dessous
1 (extraction sémantique)
Comprendre ce que fait le code ancré (règles métier, machines à états, autorisations).
Outil candidat : le skill officiel business-rules-extractor d’Anthropic (Apache-2.0, ancrage file:line-line, format Given/When/Then, niveau de confiance High/Medium/Low)
2 (contrôle déterministe)
Rejeter mécaniquement toute règle de la couche 1 dont l’ancre ne se résout pas dans la couche 0, au lieu de simplement la qualifier de « faible confiance ».
Aucun des outils étudiés ici ne le propose ; reste à construire
3 (sortie standardisée)
Fournir le résultat sous forme de fichiers versionnables et interrogeables.
OKF convient directement : un concept par fichier Markdown, un champ resource pour l’ancre de code
Construire l’ancrage de couche 0 {#building-the-layer-0-anchor}
Pour chaque point d’entrée documenté d’une fonctionnalité, résolvez dans cet ordre et ne devinez jamais silencieusement :
LSP (workspaceSymbol, documentSymbol) sur le nom de la route ou du fichier.
git grep en repli dans le clone local.
Si aucun des deux ne résout l’entrée : la marquer non résolue, avec la raison. Jamais de supposition silencieuse.
files:
- repo: <name>
path: <path relative to repo root>
symbol: <function/handler name, if identified>
method: grep | LSP
confidence: EXTRACTED | INFERRED
commit_ref: <short hash>
resolution_status: COMPLETE | PARTIAL | NOT_FOUND
EXTRACTED signifie une correspondance unique et exacte. INFERRED signifie plusieurs candidats plausibles, laissés à l’arbitrage humain. Le hash de commit n’est pas une ancre permanente, et un numéro de ligne l’est encore moins : ce sont des marqueurs d’actualité à un instant donné. Retrouvez la ligne à la demande avec git grep lorsque vous en avez besoin ; ne la stockez jamais comme identifiant fixe, car elle se décale à chaque modification sans rapport située au-dessus.
Sur un parc où la résolution ne peut pas être déduite de noms de routes explicites, prévoyez deux passages : un premier récupère les cas évidents avec grep, puis un second cible le sous-ensemble non résolu, regroupé par dépôt plutôt que par fonctionnalité. Chaque agent ouvre ainsi un dépôt une seule fois, au lieu de le rouvrir pour chaque fonctionnalité qui le concerne.
Outils testés sur un parc réel {#tools-tested-against-a-real-fleet}
Trois outils ont été évalués concrètement sur un parc applicatif hérité comprenant un framework interne non standard, précisément le cas qui met en échec la détection par signatures de frameworks.
Reversa (github.com/sandeco/reversa) est un framework multi-agent (éclaireur, archéologue, détective, architecte, rédacteur, relecteur, curateur) qui transforme un dépôt hérité en spécifications pour des agents de développement. Rejeté pour ce cas d’usage : une vulnérabilité CRITICAL de traversée de répertoires dans sa procédure de désinstallation, aucun test automatisé sur 56 versions en trois mois, une dépendance à un seul mainteneur et un sceau de confiance (🟢🟡🔴) que rien ne vérifie mécaniquement ; son propre validateur fait 22 lignes. La traçabilité fichier:ligne existe pour les exigences non fonctionnelles et les tâches, puis disparaît précisément au niveau des règles métier, là où elle compte le plus : les règles sont des puces suivies d’un emoji. Lorsque son détecteur de framework ne reconnaît pas un framework interne personnalisé, il invente à l’aveugle un découpage en modules et fige cette décision après le premier passage. Toutes les étapes suivantes héritent d’une supposition qu’elles ne peuvent plus réviser.
code-graph-mcp (github.com/sdsrss/code-graph-mcp) est un serveur MCP en Rust qui construit un graphe de connaissances AST (tree-sitter, 19 langages) avec graphe d’appels, recherche sémantique hybride et traçage des routes HTTP. Aucun problème relevé sur la sécurité. Rejeté sur les preuves, pas sur sa jeunesse : 12 arêtes « inférées » sur 12 mesurées étaient fausses, avec une confiance maximale, sur une stack moderne et bien prise en charge (Fastify), et aucune route n’a été extraite du framework interne personnalisé. Un outil qui répond faux avec assurance est pire qu’un outil qui ne répond rien.
Graphify (github.com/safishamsi/graphify, présentation complète dans ecosystem/third-party-tools.md, Knowledge Graph) est la meilleure brique déterministe trouvée. Son tag EXTRACTED est garanti par l’architecture : le code source ne quitte jamais la machine pendant la passe AST, une affirmation vérifiée dans le code de l’outil et par confrontation de ses artefacts avec le code réel, arête par arête. Lorsqu’il ne reconnaît pas un framework, il ne produit aucune arête au lieu d’en inventer une plausible. L’échec apparaît donc sous forme d’un nombre mesurable de composantes déconnectées plutôt que d’une mauvaise réponse silencieuse. Il échoue encore sur la résolution dynamique (routage fondé sur readdirSync, fabrique générique exportée create() qui masque le nom du véritable handler). Pour couvrir entièrement un parc utilisant beaucoup de frameworks personnalisés, une petite passe dédiée doit donc compléter l’outil sur ce seul point.
Aucune invention. Aucun chemin n’est écrit sans preuve directe, y compris dans les instructions confiées à un agent. Non résolu signifie non résolu, jamais deviné.
Vérification indépendante avant acceptation. Chaque affirmation d’un agent, chemin, symbole, hash de commit ou existence d’un dépôt, est vérifiée par une commande indépendante avant d’entrer dans un livrable. Ce contrôle détecte une affirmation hallucinée et, tout aussi souvent, évite une accusation infondée d’hallucination.
Respect strict du périmètre. Une tâche limitée à un champ n’en modifie jamais un autre, même si elle y découvre une inexactitude sans rapport. Signaler ces problèmes séparément ; ne jamais les corriger en silence.
Un score de confiance non vérifié mécaniquement est cosmétique, et la réciproque vaut aussi. Un sceau décoratif et un tag d’inférence non vérifié échouent au même test. Un tag garanti par l’architecture et vérifiable arête par arête dans la source, comme EXTRACTED de Graphify, le réussit. Seule une vérification mécanique reproductible fait autorité, jamais un niveau de confiance autodéclaré, honnête ou non.
Ce que la couche 0 ne fournit pas {#what-layer-0-doesnt-give-you}
Elle indique où se trouve le code, pas ce qu’il fait ; aucune règle métier n’est extraite de cette façon. Sa couverture se limite à l’inventaire de fonctionnalités qui l’a alimentée : un endpoint que personne n’a documenté en amont n’a aucune raison de figurer dans les ancres. Le hash de commit stocké est un instantané, pas une garantie en continu : sans vérification périodique, cette couche vieillit au même rythme que le code sous-jacent.
Temps de lecture : 7 minutes
Niveau : Semaine 2+
Statut : Aperçu de recherche (à partir de février 2026)
Disponibilité : Plans Pro et Max uniquement, non disponible sur les plans Team, Enterprise ou les clés API
Le contrôle à distance vous permet de surveiller et contrôler une session Claude Code locale depuis un téléphone, une tablette ou un navigateur web, sans migrer quoi que ce soit vers le cloud. Votre terminal continue de tourner localement ; l’interface mobile/web est une fenêtre distante sur cette session.
Différence clé avec Session Teleportation (§9.16) : Teleportation migre une session (web → local). Remote Control reflète une session locale vers un observateur distant. L’exécution reste toujours sur votre machine locale.
# Démarrer une session tmux avec plusieurs panneaux
tmuxnew-session-sdev
# Chaque panneau tmux peut exécuter sa propre session claude :
# Panneau 1 : claude → exécuter /rc → partager l'URL avec votre téléphone
# Panneau 2 : claude (local uniquement)
# Panneau 3 : claude (local uniquement)
# Pour changer quelle session vous contrôlez à distance :
# → Aller au panneau 2, exécuter /rc (déconnecte le distant du panneau 1, connecte le panneau 2)
Chaque panneau tmux héberge sa propre session Claude. Une seule peut utiliser le contrôle à distance à la fois, mais vous pouvez basculer entre les sessions en exécutant /rc dans différents panneaux.
# → Contrôler une session Claude hébergée dans le cloud depuis mobile
# → Les sessions survivent aux redémarrages de l'ordinateur portable (tmux les maintient actives)
Cela vous donne des sessions persistantes qui survivent à la fermeture de votre ordinateur portable. Combinez 6 à 8 sessions Claude dans tmux pour un travail continu et ininterrompu en déplacement.
Session n’apparaissant pas dans l’application Claude
Bug connu (aperçu de recherche), utiliser claude.ai/code dans Safari à la place (voir ci-dessous)
Le QR code ouvre l’application mais la session n’est pas visible
Bug connu sur iOS, scanner avec l’application Appareil photo native, ouvrir dans Safari plutôt que dans l’application Claude
QR code ne s’affiche pas
Appuyer sur espace après le démarrage du contrôle à distance
Slash commands ne fonctionnent pas
Les saisir dans votre terminal local à la place
Session expirée
Se reconnecter : exécuter /rc à nouveau
Pare-feu d’entreprise bloquant
HTTPS sortant (port 443) doit être autorisé
Erreur « Not available »
Vérifier l’abonnement Pro ou Max (pas Team/Enterprise)
Bug connu (aperçu de recherche, mars 2026) : Sur iOS (confirmé sur iPhone), scanner le QR code ouvre l’application Claude mais la session distante n’apparaît pas dans la liste des sessions. Le bug affecte également la découverte automatique des sessions dans l’application mobile Claude. MacStories a confirmé que ce comportement est incohérent sur les machines non locales.
Contournement le plus fiable : ouvrir claude.ai/code dans Safari sur votre téléphone, votre session active y apparaît dans la liste. Vous pouvez également copier l’URL de session depuis le terminal et la coller directement dans Safari. Les deux méthodes contournent entièrement le bug de synchronisation de l’application.
À mesure que votre configuration Claude Code mûrit (skills, agents, règles, CLAUDE.md), un mode de défaillance silencieux émerge : votre configuration dérive de la façon dont vous travaillez réellement. Les skills accumulent des hypothèses qui ne tiennent plus. CLAUDE.md décrit une base de code qui a évolué. Les règles couvrent des cas limites qui sont devenus la norme. L’agent continue de faire les mêmes erreurs corrigeables parce que rien ne capture ce que vous avez appris la semaine dernière.
Cette section explique comment détecter cette dérive tôt et fermer la boucle, en transformant les observations de session en améliorations concrètes de configuration.
L’obsolescence ne survient pas d’un coup. Elle s’accumule à partir de petits écarts :
Un skill a été écrit pour une API v1 qui est maintenant en v2 : le skill « fonctionne » encore mais génère du code qui nécessite une correction manuelle à chaque fois
CLAUDE.md contient un contexte vieux de 6 mois : l’agent raisonne à partir d’un modèle mental de la base de code qui n’existe plus
Une règle a été ajoutée pour un cas limite qui est désormais le pattern par défaut : elle se déclenche constamment et vous avez arrêté de lire son résultat
Vous avez corrigé la même erreur sur 5 sessions, mais rien n’a jamais capturé cette correction sous forme de règle
Le signal est toujours là : vous continuez à faire les mêmes corrections manuelles. Le travail consiste à identifier quelles corrections valent la peine d’être encodées.
Les skills s’accumulent. Sans politique de cycle de vie, vous vous retrouvez avec 20+ skills dont la moitié sont inutilisés, deux se contredisent, et aucun n’a d’historique de version.
Quand créer un skill :
Une tâche vaut la peine d’être encodée comme skill quand vous l’avez effectuée manuellement 3+ fois et que les étapes sont suffisamment stables pour être écrites. Si vous cherchez encore la bonne approche, ne l’encodez pas encore : les skills prématurés cristallisent les mauvais patterns.
Quand mettre à jour un skill (patch) :
Une commande dans le skill échoue parce qu’une API ou un chemin a changé
La sortie nécessite une petite clarification que vous ajoutez manuellement à chaque fois
Vous avez ajouté une convention et le skill ne la reflète pas encore
Quand versionner un skill (minor/major) :
Ajoutez un champ version et une date updated dans le frontmatter de votre skill :
---
version: 1.2.0
updated: 2026-03-02
breaking_since: null
---
Utilisez une politique simple :
patch (x.x.Z) : reformulation, clarification, exemples ajoutés, pas de changement de comportement
minor (x.Y.z) : nouvelles instructions, portée étendue, nouveau comportement opt-in
major (X.y.z) : les comportements par défaut changent, annotez ce qui a cassé et quand dans votre CHANGELOG
Quand déprécier un skill :
Ajoutez un drapeau deprecated: true et une note expliquant ce qui l’a remplacé. Ne supprimez pas immédiatement : d’autres skills ou commandes peuvent y faire référence.
Vérification de l’obsolescence en CI, CLAUDE.md vs modules sources :
Si votre CLAUDE.md est assemblé à partir de modules sources (par exemple via un pipeline pnpm ai:configure), ajoutez un job CI pour détecter les divergences avant qu’elles ne causent des défaillances silencieuses :
La boucle de mise à jour formalise ce que vous faites déjà de manière informelle : quelque chose ne fonctionne pas bien → vous le remarquez → vous le corrigez. La différence est de rendre l’étape « remarquer » systématique plutôt qu’accidentelle.
┌──────────────────────────────────────────────┐
│ THE UPDATE LOOP │
│ │
│ Session → Observe friction │
│ (repeated fixes, tool fails) │
│ ↓ │
│ Analyze root cause │
│ (which skill/rule is missing?) │
│ ↓ │
│ Delta update │
│ (targeted edit, not rewrite) │
│ ↓ │
│ Canary test │
│ (verify the fix holds) │
│ ↓ │
│ Next session → repeat │
└──────────────────────────────────────────────┘
Le principe de la mise à jour delta : lors de la mise à jour d’un skill ou d’une règle, faites la modification ciblée la plus petite qui résout le problème observé. Ne réécrivez pas tout le skill, vous perdrez ce qui fonctionnait. Un problème, une modification, un test.
Intégration dans /tech:handoff :
Si vous utilisez une commande handoff pour persister le contexte de session, ajoutez une étape de rétrospective obligatoire avant la sauvegarde :
# Append to your handoff command prompt
Before saving context, answer:
- Which rules or skills were missing for today's work?
- Which corrections did you make more than once?
- What's the smallest edit that would prevent the most repeated friction?
Save conclusions via: write_memory("retro_[date]", your answers)
Test canary d’un skill après mise à jour :
Avant de valider une modification de skill, vérifiez qu’il produit toujours le résultat attendu sur une entrée connue :
Terminal window
# Example: test that typescript-aristote skill generates Zod validation
claude-p"Using the typescript-aristote skill: create a basic user tRPC router"\
Si vous souhaitez automatiser l’optimisation des prompts au-delà de la boucle de mise à jour manuelle, deux frameworks méritent d’être connus :
DSPy (Stanford, open-source) : optimise les prompts de manière programmatique à partir d’une métrique et d’un ensemble d’exemples. Nécessite 20+ exemples étiquetés par skill pour des résultats fiables. Utile lorsque vous avez une tâche bien définie et suffisamment d’historique de session pour constituer un jeu de données. dspy.ai
TextGrad : traite les prompts comme des paramètres différentiables et itère en utilisant des retours générés par LLM comme « gradients ». Mieux adapté aux tâches créatives ou spécifiques à un domaine où l’évaluation est qualitative. github.com/zou-group/textgrad
Les deux nécessitent plus de configuration que la boucle manuelle ci-dessus, et aucun n’élimine le besoin de jugement humain sur ce qu’il faut optimiser. Commencez par la boucle de mise à jour et les tests canary : ils feront remonter la plus grande part de la valeur avec une fraction de la charge de travail.
Temps de lecture : 6 minutes
Niveau de compétence : Mois 2+
Lien avec §9.23 : L’Update Loop gère la maintenance délibérée de la configuration : vous constatez une dérive, vous la corrigez. L’apprentissage basé sur l’instinct gère la capture incidentelle, des observations utiles que vous auriez autrement oubliées en fin de session.
Les invites de fin de session classiques (« qu’avez-vous appris durant cette session ? ») produisent des résumés verbeux qui sont rarement exploités. La friction entre « observation » et « règle encodée » est suffisamment élevée pour que la plupart des corrections ne soient jamais intégrées à votre configuration.
Ce qui finit vraiment par être encodé : les corrections que vous faites deux fois, puis une troisième, jusqu’à ce que la répétition vous oblige à écrire une règle. C’est trop lent, et cela ne capture que les schémas douloureux, pas les schémas utiles.
Les instincts sont des observations légères, à faible engagement : des règles candidates qui n’ont pas encore été validées. Ils se situent en dessous des skills (stables, testés, promus) et en dessous de la mémoire (contexte projet, décisions) :
Observation de session
↓
Instinct (faible confiance, 0.1–0.4)
↓ confirmé sur plusieurs sessions
Règle candidate (confiance moyenne, 0.5–0.7)
↓ testé explicitement
Skill ou règle CLAUDE.md (haute confiance, 0.8+)
Chaque instinct enregistre : le contenu (l’observation), la confiance (0.0–1.0, commence bas et augmente avec les confirmations), la source (quelle session/quel contexte), et la décroissance (la confiance baisse si l’instinct n’est pas confirmé avec le temps).
Le choix de conception clé : capturer au hook Stop, pas à UserPromptSubmit.
Pourquoi Stop plutôt que UserPromptSubmit : UserPromptSubmit s’exécute avant chaque message, y ajouter une logique d’extraction introduit de la latence à chaque interaction. Stop s’exécute une seule fois à la fin de la session, zéro impact sur la vitesse de session, et le contexte complet de la session est disponible pour l’extraction de schémas.
.claude/hooks/capture-instincts.sh
#!/bin/bash
# Stop hook: extract candidate observations from the completed session
Les instincts gagnent en confiance grâce aux confirmations accumulées sur différentes sessions. Lorsqu’un instinct atteint une haute confiance, promouvez-le en règle concrète :
Terminal window
# View pending instincts
cat~/.claude/instincts/pending.yaml
# Draft a CLAUDE.md rule from a high-confidence instinct
claude--print"Convert this instinct into a CLAUDE.md rule:
L’étape de promotion reste intentionnellement manuelle : c’est vous qui décidez de ce qui est encodé. Le pipeline réduit la friction de la capture des observations, pas celle de leur validation.
Ajoutez capture-instincts.sh comme hook Stop dans settings.json
Révisez hebdomadairement, 5 minutes maximum
Promouvez 0–2 instincts à haute confiance par semaine ; supprimez les autres
Ce qu’il ne faut pas capturer : le contexte spécifique au projet (utilisez la mémoire), les schémas dont vous êtes déjà sûr (écrivez directement le skill), les contournements ponctuels (laissez-les tomber).
Crédit : Le pipeline d’apprentissage basé sur l’instinct et le schéma de capture via le hook Stop proviennent de Everything Claude Code v2 (Affaan Mustafa). Le scoring de confiance, le modèle de décroissance et le pipeline d’évolution instinct → skill sont leur contribution originale.
L’inventaire structurel, l’exécution et l’acceptation exigent des preuves différentes. Un cas synthétique Walkinglabs a obtenu 100/100 alors que sa vérification échouait ; voir l’évaluation liée à une révision précise. L’exercice local de contrôle teste les verdicts, les budgets persistants et la perte de réponse sur un service simulé. Il ne démontre pas un contrôle de fusion en production. Agent Harness Engineering, Loop & Graph Engineering et Agent Evaluation détaillent les contrats et la méthode de comparaison.
Temps de lecture : 10 minutes
Niveau de compétence : Mois 2+
L’intuition fondamentale : évaluez la capacité du modèle avec l’infrastructure qui gouverne son exécution. Un même modèle peut se comporter différemment lorsque son contexte, ses outils ou ses contrôles changent ; l’effet dépend de la tâche et du budget. Ici, le harness de dépôt désigne l’environnement de projet dans lequel fonctionne un runtime comme Claude Code.
Le vocabulaire distingue quatre couches : le modèle génère du texte ; le harness de runtime exécute la boucle d’outils, le contexte, les permissions et les sessions ; le harness de dépôt fournit les instructions, la configuration, l’état et les retours du projet ; un orchestrateur coordonne plusieurs sessions de runtime. Voir Agent Harness Engineering pour la distinction complète et Agent Harness Landscape pour les produits.
Qu’est-ce qu’un harness de dépôt ? {#what-is-a-repository-harness}
Le harness de dépôt, c’est tout ce qui compose l’environnement d’ingénierie autour de l’agent : les fichiers d’instructions, les scripts d’initialisation, le suivi d’état, les commandes de vérification et les boucles de rétroaction. Ce n’est ni un fichier de prompt ni une liste de directives. Le harness est l’établi sur lequel l’agent opère.
Cinq sous-systèmes constituent un harness complet :
Sous-système
Rôle
Artefacts principaux
Instructions
Définit ce que l’agent doit faire et comment se comporter
AGENTS.md, CLAUDE.md
Tools
Accès au shell, édition de fichiers, exécution de commandes
Outils natifs Claude Code
Environment
Dépendances, versions, baseline reproductible
init.sh, lockfiles, devcontainers
State
Suit la portée et la progression entre les sessions
feature_list.json, progress.md
Feedback
Signale si le travail est correct avant de déclarer que c’est terminé
Tests, lint, typecheck, E2E
Les modes d’échec les plus courants se mappent directement sur des sous-systèmes manquants. Les agents qui oublient le contexte entre les sessions n’ont pas de State. Les agents qui refont un travail déjà accompli n’ont pas de State. Les agents qui déclarent avoir terminé avant que les tests passent n’ont pas de Feedback.
Un agent peut annoncer « terminé » alors que les tests échouent, que les types sont incorrects ou que le build ne compile pas. Le harness doit contrôler les preuves d’exécution avant de considérer le travail terminé, indépendamment de cette annonce. La confiance du modèle ne démontre pas qu’une commande a été exécutée sur la révision candidate.
Définissez des contrôles adaptés au dépôt. Pour une application web, l’exemple suivant illustre trois couches ; utilisez les commandes et critères d’acceptation réels du projet :
Terminal window
# Layer 1: Static analysis
npmrunlint && npmruntypecheck
# Layer 2: Unit and integration tests
npmtest
# Layer 3: End-to-end smoke test
npmrune2e
Documentez le contrat dans CLAUDE.md pour que l’agent sache quelles preuves produire :
## Definition of done
A feature is NOT done until all three layers pass:
1.`npm run lint && npm run typecheck` — clean
2.`npm test` — all tests pass
3.`npm run e2e` — smoke test passes
Do NOT commit or report completion before running all three.
L’instruction décrit le comportement attendu. Son application exige un contrôleur ou un contrôle CI obligatoire qui bloque la transition vers la complétion ou la fusion lorsqu’un résultat requis échoue, manque, est périmé ou reste ininterprétable. Liez ce résultat à la révision candidate et conservez la politique hors du changement évalué. Un hook local ne couvre que les actions et les clients qu’il intercepte réellement.
Testez les deux décisions : un contrôle requis en échec doit bloquer la transition, et un candidat valide accompagné de preuves complètes doit passer cette étape de politique. Testez aussi une sortie absente et un résultat provenant d’une révision antérieure. Une politique qui rejette tout peut réussir une suite composée uniquement de cas négatifs.
Les contrôles end-to-end peuvent révéler des défauts de navigation, de configuration et d’intégration absents de la couverture unitaire. Le retour d’Anthropic sur les agents de longue durée décrit des vérifications dans le navigateur après que des agents avaient déclaré des fonctionnalités terminées trop tôt. Considérez ce retour comme une expérience d’implémentation rapportée, puis conservez votre propre scénario reproductible et son résultat.
Lorsque plusieurs fonctionnalités sont en cours simultanément, la vérification devient ambiguë (quelle fonctionnalité a cassé les tests ?), le suivi de progression devient bruité, et le contexte se remplit plus vite sans signal de complétion clair. L’agent distribue son attention sur l’ensemble de la liste de tâches au lieu de terminer une chose.
Pour un workflow séquentiel, WIP=1 constitue une politique de départ utile : une fonctionnalité passe à active, termine ses contrôles requis et enregistre son résultat avant qu’une autre ne commence. Si l’exclusivité compte, un contrôleur doit valider cette transition. Mesurez localement la complétion et la reprise ; ce guide ne démontre aucun taux universel d’amélioration lié à cette politique.
Une session fiable suit cette séquence à chaque fois, pas seulement au démarrage :
Étape
Action
Sous-système
1. READ
Lire AGENTS.md et CLAUDE.md
Instructions
2. INIT
Exécuter ./init.sh : vérifier que l’environnement est sain
Environment
3. RESUME
Lire progress.md : ce qui s’est passé lors de la dernière session
State
4. SELECT
Choisir une fonctionnalité avec le statut not_started dans feature_list.json
State
5. EXECUTE
Implémenter uniquement cette fonctionnalité
—
6. VERIFY
Exécuter les trois couches de vérification
Feedback
7. UPDATE
Passer le statut de la fonctionnalité à passing, enregistrer les preuves
State
8. LOG
Mettre à jour progress.md avec ce qui a changé et ce qui suit
State
9. CLEANUP
Supprimer les fichiers temporaires, laisser le dépôt dans un état redémarrable
Environment
10. COMMIT
Committer uniquement quand la vérification passe et que l’état est propre
—
Les étapes 2 (INIT) et 6 (VERIFY) sont là où la plupart des défaillances de harness surviennent. Un INIT qui continue silencieusement malgré des dépendances cassées produit des erreurs confuses pour le reste de la session. Un VERIFY qui s’exécute mais ne bloque pas la complétion produit des faux positifs qui érodent la confiance dans les résultats de l’agent.
Une liste de tâches en texte brut est insuffisante pour un fonctionnement fiable de l’agent : pas d’état lisible par machine, pas de champ de preuve, pas d’ordonnancement par dépendances. feature_list.json ajoute une structure que l’agent et vos outils peuvent lire.
Chaque fonctionnalité a besoin de trois choses : une description du comportement attendu, la commande de vérification qui prouve son bon fonctionnement, et un champ de statut que l’agent met à jour tout au long de la session.
{
"features": [
{
"id": "feat-001",
"name": "Document Import",
"description": "User can import PDF and TXT files from the local filesystem",
"description": "Imported documents split into ~500-char chunks with position metadata",
"dependencies": ["feat-001"],
"status": "active",
"evidence": ""
},
{
"id": "feat-003",
"name": "Search Index",
"description": "Full-text search across all imported documents",
"dependencies": ["feat-002"],
"status": "not_started",
"evidence": ""
}
]
}
Les valeurs de statut suivent un flux unidirectionnel : not_started → active → passing (ou blocked si une dépendance est insoluble). Le champ evidence est la partie la plus informative du schéma : il enregistre ce que la vérification a réellement exécuté, pas seulement que le code a été écrit. Un champ evidence vide sur une fonctionnalité passing est un signal d’alarme.
Chaque session démarre depuis un état d’environnement inconnu. Les dépendances peuvent avoir changé, les artefacts de build peuvent être obsolètes, ou les types peuvent être cassés suite à une session précédente incomplète. init.sh établit une baseline connue et saine avant que tout travail commence.
#!/bin/bash
set-e# Fail fast on any error
echo"=== Initialization ==="
npminstall
npmrunbuild
npmruntypecheck
npmtest
echo"=== Environment ready ==="
echo"Next: read feature_list.json and pick one not_started feature"
set -e est non négociable. Si l’installation échoue, le script s’arrête. Un agent qui continue malgré un environnement cassé produit des erreurs confuses pour le reste de la session, et la cause racine devient difficile à isoler. Exécutez-le de manière idempotente : l’appeler cinq fois doit produire le même résultat qu’une seule fois.
Les fenêtres de contexte sont finies. Toute session qui se termine sans note de transfert oblige la session suivante à reconstruire le contexte depuis zéro : lire le git log, faire des grep sur les modifications récentes, déduire ce qui était en cours. Cette reconstruction est coûteuse et imprécise, et c’est là que des erreurs subtiles sont introduites.
progress.md élimine le coût de reconstruction. C’est une note courte et structurée rédigée à la fin de chaque session et lue au début de la suivante.
# Session progress
## Dernière mise à jour
2026-05-04 — Session 7
## Fonctionnalité active
feat-002 : Découpage de documents
## Réalisé lors de cette session
- [x] Implémentation de la fonction chunk() dans src/services/chunker.ts
- [x] Ajout des métadonnées de position (start_char, end_char, chunk_index)
- [x] Tests unitaires réussis (8/8)
## En cours
- [ ] Intégration du découpage dans DocumentService
- Statut : la fonction existe, le câblage n'est pas terminé
- Bloquant : aucun
## Prochaines étapes
1. Connecter le découpage à DocumentService.import()
2. Ajouter un test d'intégration couvrant le flux complet import-vers-découpage
3. Mettre à jour le statut de feat-002 à « réussi » une fois le test d'intégration passé
## Preuves
- lint : propre
- typecheck : propre
- tests unitaires : 8/8 réussis
- tests d'intégration : pas encore (feat-002 non terminé)
## Notes pour la prochaine session
chunk() se trouve dans src/services/chunker.ts:42. DocumentService attend un
type ChunkResult[] (défini dans src/types/documents.ts:18). Le point de
câblage est DocumentService.import() à la ligne 67.
La section « Notes pour la prochaine session » offre le meilleur retour sur investissement : chemins de fichiers concrets, numéros de ligne et points de câblage précis qui économisent 5 à 10 minutes d’orientation au démarrage d’une session. Considérez-la comme un message à un collègue qui connaît la base de code mais n’a aucun souvenir de ce qui s’est passé aujourd’hui.
Le schéma d’échec le plus courant avec les fichiers d’instructions : ils commencent petits et s’accumulent. Chaque équipe ajoute des règles, des directives, des conventions et des exceptions. Au bout de trois mois, le fichier fait 800 lignes. L’agent lit les 800 lignes à chaque session, consommant le budget de contexte avant même que le travail commence. Les règles qui apparaissent à la ligne 600 sont pratiquement invisibles. Le fichier ne peut pas être soumis à un linter. Les contradictions s’accumulent silencieusement.
Le schéma d’échec est structurel, pas un problème de qualité du contenu. Un AGENTS.md long se dégradera inévitablement, quelle que soit la soin apporté à la rédaction de chaque règle.
L’approche de l’équipe OpenAI Codex : limiter AGENTS.md à environ 100 lignes et en faire une carte, pas un manuel. Le fichier indique à l’agent où chercher, pas tout ce qu’il doit savoir.
AGENTS.md
## Architecture
Voir docs/DESIGN.md pour l'architecture du système.
Voir docs/design-docs/core-beliefs.md pour les décisions fondamentales.
Frontières des couches : Types → Config → Repo → Service → Runtime → UI.
Préoccupations transversales (auth, télémétrie, feature flags) uniquement via des interfaces Provider.
Spécifications produit par fonctionnalité : docs/product-specs/
Suivi de la dette technique : docs/exec-plans/tech-debt-tracker.md
## Qualité et standards
Score de qualité par domaine : docs/QUALITY_SCORE.md
Invariants de style (appliqués par les linters) : docs/RELIABILITY.md, docs/SECURITY.md
Conventions frontend : docs/FRONTEND.md
## Bibliothèques externes
Docs prêtes pour LLM pour les dépendances externes : docs/references/
Exemple : docs/references/nixpacks-llms.txt
## Vérification
Avant de marquer comme terminé : exécuter `make verify` (lint + typecheck + tests + e2e).
Définition de « terminé » : toutes les couches passent, aucun saut.
La hiérarchie docs/ fait le gros du travail. L’agent ne lit que ce dont il a besoin pour la tâche en cours : la spécification produit pour la fonctionnalité qu’il implémente, le plan d’exécution pour la tâche qu’il réalise, le document de fiabilité lorsqu’il touche à l’infrastructure. Divulgation progressive via le système de fichiers.
Application en CI : la base de connaissances doit être maintenue comme du code. Des linters vérifient que les références docs/ dans AGENTS.md sont valides, que les plans d’exécution dans active/ ne sont pas périmés, et que QUALITY_SCORE.md reflète la dernière exécution de nettoyage. Un lien brisé dans AGENTS.md est un échec de build, pas une simple erreur de documentation.
9.25.2 Ce que l’agent ne peut pas voir n’existe pas
Les agents ont une seule frontière de connaissance : le dépôt. Tout ce qui existe en dehors du dépôt (fils Slack, appels vidéo, Google Docs, compréhension tacite entre coéquipiers) n’existe pas pour l’agent. Ce n’est pas une limitation à contourner. C’est une contrainte de conception qui détermine comment une équipe doit fonctionner.
Une décision prise dans un fil Slack mais non encodée sous forme de fichier markdown dans le dépôt sera violée par l’agent lors de la prochaine tâche. Non pas parce que l’agent est négligent, mais parce qu’il ne sait genuinement pas. Il en va de même pour les conventions discutées lors d’une revue de code mais non transcrites dans une règle de linter ou un document. Il en va de même pour les décisions d’architecture prises il y a six mois que « tout le monde dans l’équipe connaît ».
Le test pratique : « Si un nouvel ingénieur rejoignait l’équipe aujourd’hui sans onboarding, saurait-il cela en lisant le dépôt ? » Si non, l’agent ne le sait pas non plus.
Trois catégories méritent une attention particulière :
Décisions : choix architecturaux, alternatives rejetées, compromis acceptés. Ceux-ci appartiennent à docs/design-docs/ sous forme de registres de décisions, pas dans la mémoire de quelqu’un. Un registre de décision n’a pas besoin d’être long. Un court document qui énonce la décision, les alternatives considérées et la raison du choix est suffisant et survit à chaque changement d’équipe.
Conventions : règles de nommage, patrons structurels, organisation des fichiers. Celles-ci appartiennent aux règles de linter (afin d’être appliquées, pas seulement documentées) ou à des documents ciblés vers lesquels AGENTS.md pointe. Une convention qui ne vit que dans une section de README dérivera.
Plans : ce qui est construit, pourquoi et dans quel ordre. Ceux-ci appartiennent aux plans d’exécution (voir §9.25.3). Un plan qui n’existe que dans un outil de gestion de projet que l’agent ne peut pas lire n’est pas un plan pour l’agent.
Le corollaire : lorsqu’un humain prend une décision lors d’une revue de code ou change de direction en cours de tâche, cette décision doit être écrite dans le dépôt avant la prochaine session d’agent. Les réponses aux commentaires de revue qui modifient l’architecture ne sont pas du contenu de dépôt. Les écrire dans un document de conception ou mettre à jour un plan d’exécution est l’étape requise, pas un nettoyage optionnel.
Une hiérarchie docs/ structurée transforme la frontière de connaissance d’un handicap en atout. Lorsque tout le contexte pertinent se trouve dans le dépôt et est organisé de manière cohérente, l’agent peut naviguer vers exactement ce dont il a besoin pour n’importe quelle tâche.
La structure sur laquelle l’équipe OpenAI Codex a convergé :
docs/
├── design-docs/
│ ├── index.md # Index de tous les registres de décisions
│ └── db-schema.md # Généré automatiquement depuis le schéma réel (jamais édité à la main)
├── product-specs/
│ └── index.md # Une spécification par fonctionnalité
├── references/
│ └── nixpacks-llms.txt # Docs prêtes pour LLM pour chaque bibliothèque externe
├── DESIGN.md # Vue d'ensemble de l'architecture système
├── FRONTEND.md # Conventions frontend
├── PLANS.md # Statut de planification actuel
├── PRODUCT_SENSE.md # Jugement produit et principes
├── QUALITY_SCORE.md # Scores de qualité par domaine/couche
├── RELIABILITY.md # Exigences de fiabilité et invariants de style
└── SECURITY.md # Exigences de sécurité et patrons
Les plans d’exécution comme artefacts de première classe : pour toute tâche non triviale, l’agent crée un document de plan avant d’écrire du code. Les changements simples reçoivent des plans éphémères : un court fichier markdown décrivant l’approche et le résultat attendu, créé au début de la tâche et déplacé dans completed/ une fois terminé. Les tâches complexes reçoivent des plans d’exécution complets avec journaux de progression, registres de décisions et notes explicites sur les alternatives rejetées. La séparation entre active/ et completed/ focalise l’attention de l’agent sur le travail en cours tout en conservant un historique consultable des décisions passées. Le tech-debt-tracker.md est le backlog des problèmes de qualité connus, alimenté par les agents de nettoyage en arrière-plan décrits au §9.25.5, traités de manière incrémentale plutôt que lors d’un nettoyage périodique perturbateur.
Répertoire generated/ : certaines documentations doivent refléter exactement le code. Schémas de base de données, surfaces d’API, définitions de types générés. Ceux-ci vont dans generated/ et sont produits par des scripts automatisés, pas rédigés à la main. L’agent de jardinage de documentation (décrit ci-dessous) applique l’invariant selon lequel les fichiers de generated/ correspondent à l’état réel à l’exécution.
L’agent de jardinage de documentation : un agent en arrière-plan récurrent qui lit docs/ et compare les affirmations de la documentation au comportement réel du code. Lorsqu’il détecte une dérive (une API documentée qui a changé de signature, ou un registre de décision qui contredit l’implémentation actuelle), il ouvre une PR pour corriger la documentation. Cela traite la base de connaissances comme du code : elle a des exigences de correction, et ces exigences sont appliquées automatiquement. Sans cet agent, la base de connaissances se dégrade à mesure que la base de code évolue. Avec lui, la dégradation est détectée et corrigée en continu plutôt que découverte lorsqu’un agent agit sur des informations périmées.
references/ pour les bibliothèques externes : chaque dépendance externe significative reçoit un fichier dédié dans references/ (le llms.txt officiel de la bibliothèque si disponible, ou un résumé sélectionné de la surface d’API pertinente). L’agent lit le fichier de référence approprié lors de l’implémentation avec cette bibliothèque plutôt que de s’appuyer sur ses données d’entraînement, qui peuvent être périmées ou incomplètes.
La pile de vérification du §9.25 (lint, typecheck, tests, e2e) couvre la correction. Une couche séparée couvre les performances et le comportement à l’exécution : l’observabilité. Sans elle, l’agent ne peut pas déterminer si un changement satisfait aux exigences de performance et ne peut qu’inspecter le code et deviner.
L’équipe OpenAI Codex a donné à chaque worktree git sa propre pile d’observabilité éphémère et isolée. La pile est créée au début de la tâche et détruite après sa réalisation ; elle n’est jamais commitée dans le dépôt.
Pipeline de données : logs/métriques/traces de l'app → Vector (collecteur/routeur)
↓
Couche de stockage : VictoriaLogs (logs) VictoriaMetrics (métriques) store de traces (traces)
↓
APIs de requête : LogQL PromQL TraceQL
↓
Accès agent : curl / outils CLI → données structurées dans le contexte de l'agent
La pile permet des prompts basés sur des métriques qui étaient auparavant impossibles. Au lieu de « implémenter le démarrage du service », le prompt devient « s’assurer que le démarrage du service se termine en moins de 800 ms ». Au lieu de « optimiser le flux de paiement », il devient « aucun parcours UI à travers le paiement ne doit dépasser 2 secondes ». L’agent implémente un changement, redémarre l’application, exécute la charge de travail, interroge la pile d’observabilité, lit le résultat et itère. La boucle de rétroaction est fermée sans mesure humaine.
Cette approche nécessite une infrastructure que toutes les équipes n’ont pas. Ce patron vaut la peine d’être connu car il illustre la direction : à mesure que l’investissement dans l’outillage augmente, l’agent peut prendre en charge des travaux qui étaient auparavant impossibles à déléguer car la vérification nécessitait un jugement humain sur le comportement à l’exécution. Les équipes sans cette pile peuvent l’approximer en rendant les exigences de performance explicites (exécuter ce benchmark avant et après, comparer la sortie) et en scriptant la mesure, même si l’infrastructure n’est pas aussi complète.
Au niveau de débit des agents, la tendance naturelle vers l’entropie s’accélère. Les agents reproduisent les patrons qu’ils observent dans la base de code. Si un patron imparfait existe quelque part, il sera reproduit partout en quelques sessions. La capitalisation est plus rapide qu’avec des développeurs humains car l’agent travaille plus vite et est plus susceptible de généraliser à partir d’exemples. L’architecture doit être appliquée, pas seulement documentée.
Architecture de domaine en couches
L’équipe OpenAI Codex a appliqué un ordre de couches fixe dans chaque domaine métier :
Types → Config → Repo → Service → Runtime → UI
Chaque couche ne peut dépendre que des couches situées en dessous d’elle. Les préoccupations transversales (auth, connecteurs, télémétrie, feature flags) ne sont disponibles que via des interfaces Provider explicites, pas par importation directe. Les violations sont des échecs de build appliqués par des linters personnalisés et des tests structurels.
C’est le genre d’architecture typiquement différée dans les produits en phase précoce avec le raisonnement « nous ajouterons cette structure quand nous aurons plus d’ingénieurs ». Au niveau de débit des agents, le raisonnement s’inverse : sans cette structure, les agents introduiront des dépendances inter-couches en quelques jours, et l’enchevêtrement qui en résulte est difficile à inverser. L’architecture en couches devient un prérequis plutôt qu’une optimisation future.
Invariants de style et linters personnalisés
Les invariants de style sont des règles subjectives qui vont au-delà du style. Exemples : « préférer les packages utilitaires partagés aux helpers ad hoc », « valider aux frontières ou utiliser des SDKs typés », « utiliser la journalisation structurée dans tout le code de la couche service », « les schémas et types suivent la convention de nommage X ». Ces règles ne sont pas rédigées comme des directives ; elles sont encodées comme des linters personnalisés.
Les messages d’erreur du linter sont rédigés spécifiquement pour la consommation par l’agent, pas pour les développeurs humains. Un message de linter conventionnel dit ce qui ne va pas. Un message d’invariant de style dit ce qui ne va pas et ce qu’il faut faire à la place, rédigé sous une forme sur laquelle l’agent peut agir :
TASTE-003: Réponse API non typée trouvée dans services/payment.ts:47
Préférer les réponses SDK typées. Utiliser PaymentClient de @internal/payment-sdk
au lieu de fetch() direct. Voir docs/RELIABILITY.md#api-boundaries pour le patron.
Le message d’erreur injecte l’instruction de correction directement dans la fenêtre de contexte de l’agent. Une fois encodée, la règle s’applique instantanément à chaque fichier de la base de code, y compris les fichiers que l’agent n’a jamais vus. C’est l’effet amplificateur : une règle de linter applique un comportement cohérent à l’ensemble du projet sans effort supplémentaire par fichier.
Les linters personnalisés ont eux-mêmes été générés par les agents Codex, pas écrits à la main. Un humain décrit la règle en langage courant ; l’agent génère l’implémentation du linter. Cela amplifie encore l’effet : les invariants de style sont peu coûteux à créer, donc davantage sont créés, donc davantage du comportement de la base de code est appliqué plutôt que documenté.
Anti-entropie via des agents de nettoyage en arrière-plan
Le problème avec la dérive architecturale : elle est progressive et invisible jusqu’à ce qu’elle s’accumule. Un agent reproduit un patron légèrement imparfait. Un autre l’étend. Un troisième ajoute une dépendance qui ne devrait pas exister. Trois mois plus tard, la base de code présente des problèmes structurels coûteux à inverser, et aucun changement unique ne les a introduits.
L’approche de l’équipe OpenAI Codex consiste à traiter l’anti-entropie comme le ramasse-miettes : nettoyage incrémental continu plutôt que réécritures périodiques perturbantes. Une équipe d’agents en arrière-plan s’exécute selon un planning récurrent :
Recherche des déviations par rapport aux principes de style et aux règles de couches architecturales
Mise à jour de QUALITY_SCORE.md avec les scores actuels par domaine et couche
Ouverture de PRs de refactoring ciblées pour les violations détectées
Les PRs sont délimitées pour être révisables en moins d’une minute et fusionnées automatiquement lorsqu’elles passent la vérification. Chacune traite une déviation, pas un refactoring large. L’effet cumulatif est que la dette technique est remboursée en continu plutôt que lors d’un nettoyage périodique perturbateur. Le tech-debt-tracker.md dans docs/exec-plans/ enregistre les problèmes connus, et les agents en arrière-plan les traitent de manière incrémentale.
QUALITY_SCORE.md suit l’évolution de la santé dans le temps par couche architecturale et domaine métier. Un score de qualité en déclin est un signal avant que le déclin ne devienne un problème.
Philosophie de fusion à haut débit
À 3,5 PRs par ingénieur par jour, les contrôles de fusion conventionnels deviennent le goulot d’étranglement. Une PR qui attend deux heures pour une exécution de CI défaillante de manière intermittente représente un retard de deux heures dans un flux de travail qui produit plusieurs PRs par heure. L’approche de l’équipe OpenAI : blocages de fusion minimaux, corrections appliquées via des exécutions de suivi plutôt que des blocages de fusions.
Le raisonnement : à des niveaux de débit d’agent véritablement élevés, un test défaillant est corrigé plus rapidement par une exécution d’agent de suivi qu’en bloquant la PR actuelle. « Les corrections sont peu coûteuses ; l’attente est coûteuse » inverse le calcul de risque habituel qui est correct au débit de développement humain.
Cette philosophie ne s’applique que lorsque le débit est véritablement élevé. À un débit de développement normal, bloquer les fusions sur des tests défaillants est correct : le coût d’un blocage de fusion est faible, et le coût de la fusion de code défaillant est élevé. L’inversion se produit uniquement lorsque l’agent peut produire une correction plus rapidement qu’un humain ne peut réviser et débloquer la PR. Appliquer cette philosophie prématurément, sans le débit pour la soutenir, produit une base de code avec des défaillances accumulées plutôt qu’une avec un flux efficace.
Sources : Cycle de vie de session, écart de vérification, WIP=1, feature_list.json, init.sh et patrons progress.md présentés ici comme recommandations du guide. L’attribution antérieure à « Learn Harness Engineering » (HumanLayer, 2026) n’a pas pu être vérifiée. AGENTS.md-comme-table-des-matières, principe de frontière de connaissance, plans d’exécution, structure docs/, pile d’observabilité éphémère, invariants de style, agent de jardinage de documentation, modèle anti-entropie, architecture de domaine en couches et philosophie de fusion à haut débit issus de « Harness engineering: exploiting Codex in the agent era », Ryan Lopopolo, blog d’ingénierie OpenAI, 11 fév. 2026 (https://openai.com/index/harness-engineering/).
Temps de lecture : 7 minutes
Niveau de compétence : Mois 2+
Relation avec §9.24 : L’apprentissage par instinct capture des observations passivement depuis les journaux de session. L’optimisation par révision capture des corrections humaines structurées activement (ce que vous avez explicitement marqué comme incorrect lors d’un cycle de révision). Les deux alimentent la même destination (CLAUDE.md et .claude/rules/), depuis des sources de signal différentes.
Quand vous terminez une session Claude Code et demandez « que devrais-je ajouter à CLAUDE.md ? », vous travaillez de mémoire. Vous vous souvenez des moments frustrants, mais vous perdez les détails : quel fichier, quelle ligne, ce que l’agent a produit par rapport à ce que vous vouliez. L’écart entre l’observation et la règle encodée reste grand.
L’optimisation par révision déplace le point de capture. Au lieu d’extraire les leçons en fin de session, vous les extrayez du retour structuré que vous avez laissé pendant la révision : des commentaires en ligne attachés à des lignes spécifiques, sur des fichiers spécifiques, à des points précis dans la sortie de l’agent. Le signal est plus riche et déjà associé à un emplacement.
→ laisse des commentaires sur des lignes spécifiques
↓
Claude Code itère (tour 2)
↓
crit affiche le diff tour-à-tour
→ ce qui a changé, ce qui a été traité, ce qui ne l'a pas été
↓
Extraire les patterns de commentaires entre sessions
↓
Convertir les patterns récurrents en règles CLAUDE.md
Le diff tour-à-tour (delta entre les itérations de l’agent, pas entre les commits) est l’étape de vérification : il vous indique si l’agent a réellement appliqué votre correction, ou s’il l’a simplement reconnue. Si le tour 2 contient toujours le même problème que vous aviez signalé au tour 1, c’est un signal fort que la règle doit être explicite dans CLAUDE.md, puisque l’agent ne peut pas l’inférer du contexte seul.
crit est une interface de révision locale conçue pour cette boucle. Elle fournit des commentaires en ligne sur les diffs git, les fichiers markdown/plan, et les applications web en direct, avec une intégration native à Claude Code :
Terminal window
brewinstallcrit
critinstallclaude-code# writes config snippets for the project
Flux de révision de base :
Terminal window
# After Claude Code produces a diff or plan:
crit# auto-detects uncommitted changes
critplan.md# review a plan before Claude executes it
# After Claude iterates (round 2):
crit# shows round-to-round diff alongside your comments
L’API de commentaires programmatique permet d’annoter depuis le CLI, utile lors de l’automatisation de l’étape d’extraction :
Terminal window
critcommentsrc/file.go:42"wrong approach, see rule X"
Extraction de Patterns depuis les Commentaires de Révision
Après une session de révision, exportez les commentaires accumulés et recherchez les récurrences entre fichiers et sessions :
Terminal window
# Extract rule candidates from recent crit threads
cat.crit/threads/*.json|claude--print"
Analyze these review comments.
Identify patterns that recur across multiple locations or sessions.
For each pattern, draft a one-line rule for CLAUDE.md that would prevent the issue.
Format:
- pattern: <what kept appearing>
rule: <the CLAUDE.md rule that prevents it>
confidence: <low|medium|high>
Only include patterns with 2+ occurrences. Skip one-off corrections."
Le champ confidence est important. Un pattern apparu deux fois sur deux sessions peut être une coïncidence ; un qui est apparu cinq fois sur des fichiers différents et des jours différents représente une lacune systématique dans votre contexte.
L’extraction produit des candidats. La promotion reste manuelle :
Type de pattern
Action
Récurrent 4+ fois, même type d’erreur
Promouvoir immédiatement en règle CLAUDE.md
Récurrent 2-3 fois, lié à un type de fichier spécifique
Ajouter à une règle ciblée dans .claude/rules/
Apparu une fois, très spécifique
Écarter : correction ponctuelle, pas un pattern
Apparu une fois, coût élevé si répété
Ajouter à .claude/rules/ avec une note
La règle doit encoder la contrainte, pas la correction. « Ne pas utiliser de tirets em dans les fichiers en prose » est une bonne règle. « Corriger le tiret em à la ligne 47 de guide.md » n’en est pas une.
Le diff entre les tours 1 et 2 répond à une question différente de celle des commentaires eux-mêmes. Les commentaires vous disent ce qui était incorrect. Le diff vous dit si l’agent a compris la correction et l’a appliquée correctement.
Si vous avez signalé un problème au tour 1 et que le diff montre qu’il a été traité, cette correction n’a peut-être pas besoin d’une règle : l’agent a compris et s’est adapté. Si vous avez signalé le même problème et que le diff ne montre aucun changement (ou un changement partiel), ce pattern appartient à CLAUDE.md. L’agent ne peut pas l’inférer de manière fiable depuis le contexte du prompt seul.
C’est l’étape de vérification qui distingue l’optimisation par révision de la simple capture par instinct. Vous n’observez pas seulement, vous testez si une instruction explicite était suffisante, et vous l’encodez comme règle permanente quand elle ne l’était pas.
Effectuer un cycle de révision après toute session Claude Code multi-itérations
Après 3-5 sessions, exporter les fils de commentaires et lancer le prompt d’extraction ci-dessus
Promouvoir 0-2 règles par semaine vers CLAUDE.md ou .claude/rules/
Écarter le reste : les règles candidates qui n’ont pas atteint le seuil ont déjà rempli leur rôle
L’effet de capitalisation : chaque règle ajoutée à partir du retour de révision supprime une classe de corrections des sessions futures. Après quelques mois, les commentaires de révision passent de « vous avez fait X de manière incorrecte » à « c’est une question de conception », ce qui signale que les patterns mécaniques sont couverts et que les lacunes restantes requièrent du jugement.
Outil : crit by tomasz-tomczyk, MIT, maintenance active, support natif crit install claude-code.
Temps de lecture : 5 minutes (aperçu) | Guide complet → (~15 min, mécanismes complets et modèle de sécurité)
Niveau de compétence : Mois 1+
Statut : Stable, v2.1.224+ (macOS/Linux/WSL2), v2.1.234+ (Windows natif)
Deux sessions Claude Code peuvent communiquer sans que l’une ait lancé l’autre. ListAgents découvre les sessions que Claude peut joindre ; SendMessage envoie un court message texte à l’une d’elles en la désignant par son nom. Deux sessions exécutées en parallèle sur la même machine, dans des dépôts différents ou dans le même dépôt, se voient automatiquement, sans configuration.
Ce fonctionnement se distingue des équipes d’agents (§9.20) : le responsable d’une équipe lance et supervise ses propres coéquipiers, leur attribue des tâches et synthétise leurs résultats. La messagerie entre sessions vise des sessions qui existent déjà indépendamment, lancées et pilotées par un humain. Elle évite simplement de copier-coller les informations pour les transmettre entre elles.
Découverte et acheminement {#discovery-and-delivery}
Exécutez /list-agents (alias /peers) pour voir ce qu’une session peut joindre : sous-agents, coéquipiers d’une équipe d’agents, autres sessions locales sur cette machine, sessions cloud et sessions Remote Control sur d’autres machines. Claude adresse alors un message par nom, soit de sa propre initiative après une modification qui affecte le travail d’une autre session, soit à votre demande :
Ask the session running in my other terminal whether the migration finished
Vous pouvez aussi nommer directement la cible avec une @-mention, selon le même mécanisme que pour les sous-agents (v2.1.232+) :
Let @api-worker know the schema migration finished
Le message quitte ou non la machine selon l’emplacement de la session cible : sur la même machine, il passe par un socket Unix local ou un tube nommé et ne transite jamais par les serveurs d’Anthropic ; une session sur une autre de vos machines ou sur le Web est jointe par les serveurs d’Anthropic via la connexion Remote Control.
Un message provenant d’une session paire transmet des informations, jamais une autorisation. Claude Code indique explicitement au Claude qui le reçoit que le texte vient d’une autre session et non de l’utilisateur, et lui impose des limites : ce message ne peut pas approuver une demande d’autorisation en attente ni modifier CLAUDE.md ou une autre configuration. Une commande intégrée au texte du message arrive comme du texte brut et n’est pas exécutée. Si agir sur ce message nécessite une autorisation dont la session destinataire ne dispose pas déjà, la demande habituelle s’affiche, comme pour toute autre action.
Chaque session contrôle ce qu’elle accepte des autres sessions avec crossSessionInbound (accept / hold / refuse, configurable dans /config). Le réglage isolatePeerMachines: true impose une approbation explicite avant qu’un message ne quitte la machine courante, même en mode bypassPermissions.
Coordonnez les sessions que vous avez déjà ouvertes et que vous pilotez vous-même : transmettez une découverte d’un worktree à un autre, prévenez la session backend lorsque la migration de la base de données est terminée, ou envoyez à une session de documentation la réponse qui vient de débloquer la session frontend. Sans TeamCreate, responsable d’équipe ni liste de tâches commune, deux sessions indépendantes ou davantage échangent directement, sans relais humain.
Référence complète : Messagerie entre sessions détaille les types de sessions découverts, le mécanisme de socket de réception, les règles complètes de priorité de crossSessionInbound, les limites de taille des messages et de rafale, ainsi que l’historique des versions. Diagramme : Messagerie entre sessions : découverte et acheminement.
9.28 Ingestion d’événements et délégation sécurisée {#928-event-ingestion-and-safe-delegation}
Temps de lecture : 3 minutes (aperçu) | Guide complet → (~12 min, sources, frontières et workflow Codex)
Niveau de compétence : Avancé
Claude Code propose plusieurs moyens d’observer un événement, mais aucun ne transforme le texte reçu en autorisation : source de commande Monitor (v2.1.98+), source WebSocket native (v2.1.195+), monitors de plugins (v2.1.105+) et MCP Channels (v2.1.80+, aperçu de recherche). Les routines s’exécutent comme des sessions distinctes sur une infrastructure cloud gérée par Anthropic ou dans un environnement autohébergé par une organisation ; elles sont déclenchées par des planifications, des API ou des événements GitHub.
Une mise en œuvre sûre reste ciblée et explicite : vérifier la signature du webhook GitHub, le dépôt, le type d’événement, le schéma et l’identifiant de livraison ; relayer uniquement des métadonnées typées sur une connexion WebSocket approuvée ; classifier avec codex exec en lecture seule ; puis exiger une validation explicite par un humain ou une politique avant qu’une tâche distincte et isolée puisse utiliser --sandbox workspace-write. Les commentaires bruts, corps d’issues, logs et trames WebSocket restent des données, jamais des instructions ni des autorisations.
Référence complète : Monitor, Channels et délégation sécurisée à Codex présente les limites d’entrée de Monitor, les frontières de confiance des plugins et des Channels, le traitement des livraisons GitHub et un exemple de jobs séparés avec openai/codex-action@v1 pour GitHub Actions.
Source de référence : code.claude.com/docs/en/commands est la documentation officielle et donne les commandes actuelles. Les tableaux ci-dessous la reflètent au 24 septembre 2026 (CLI suivi v2.1.281), avec les notes et renvois du guide. En cas de désaccord, la page officielle prime. Pour les options au lancement, voir la référence CLI et §10.3.
Toutes les commandes ne sont pas visibles pour tous. Leur disponibilité dépend de la plateforme, du forfait et du fournisseur : /desktop apparaît sur macOS et Windows x64 avec un abonnement Claude, /setup-bedrock uniquement avec CLAUDE_CODE_USE_BEDROCK=1, et /upgrade jamais sur Enterprise. Saisissez / dans une session pour voir les commandes réellement disponibles.
Notation : <arg> est requis, [arg] est facultatif ; les alias suivent la commande entre parenthèses.
Démarrer une conversation vide. Le nom donné identifie la précédente dans le sélecteur /resume
/resume [session] (/continue)
Reprendre une conversation par identifiant ou nom, ou ouvrir le sélecteur. Les sessions en arrière-plan portent la mention bg
/branch [name]
Créer une branche de la conversation à cet endroit et basculer dans la copie. L’original reste accessible par /resume (v2.1.77+)
/fork [prompt]
Copier la conversation dans une nouvelle session en arrière-plan et continuer ici. Entre v2.1.161 et v2.1.211, lançait un sous-agent forké, désormais /subtask ; auparavant, alias de /branch
/subtask <task>
Lancer un sous-agent forké qui hérite de toute la conversation, travaille en arrière-plan et rend son résultat ici (v2.1.212+)
/background [prompt] (/bg)
Détacher cette session pour l’exécuter comme agent en arrière-plan et libérer le terminal. La suivre avec claude agents
/stop
Arrêter la session en arrière-plan attachée. Transcription et worktree sont conservés. /exit détache sans arrêter
/rename [name]
Nommer la session et afficher son nom sur la barre de prompt. Sans argument, générer un nom depuis l’historique
/recap
Obtenir à la demande un résumé de la session en une ligne
/rewind (/checkpoint, /undo)
Revenir à un point de contrôle de conversation et/ou de code, ou résumer depuis un message choisi
/copy [N]
Copier la N-ième réponse récente. Si elle contient du code, ouvrir un sélecteur ; w écrit dans un fichier
/export [filename]
Exporter la conversation en texte brut vers un fichier ou le presse-papiers
/teleport (/tp)
Rapatrier une session Claude Code sur le web dans ce terminal, branche et conversation comprises
/remote-control (/rc)
Rendre cette session pilotable depuis claude.ai ou l’application mobile
/desktop (/app)
Continuer la session dans l’application Claude Code Desktop
/exit (/quit)
Quitter le CLI. Dans une session en arrière-plan attachée, se détacher et la laisser fonctionner
Résumer la conversation pour libérer du contexte. Les instructions facultatives ciblent le résumé
/autocompact [auto|<tokens>]
Définir et enregistrer la fenêtre de compaction automatique, ou rétablir le défaut du modèle
/context [all]
Afficher une grille colorée de l’utilisation du contexte et des suggestions d’optimisation. all développe le détail par élément en plein écran
/btw [question]
Poser une question annexe dans un panneau éphémère en lecture seule, sans outils ni pollution de l’historique. Sans question, rouvrir le dernier panneau (v2.1.212+)
/memory
Modifier les fichiers CLAUDE.md, activer/désactiver la mémoire automatique et parcourir ses entrées
/add-dir <path>
Ajouter un répertoire de travail accessible pendant la session. La plupart des configurations .claude/ n’y sont pas découvertes
/cd <path>
Déplacer la session vers un autre répertoire sans perdre le cache de prompt (v2.1.169+)
Changer de modèle et l’enregistrer par défaut. Les flèches gauche/droite règlent l’effort. s limite le choix à la session
/effort [level|auto|status]
Régler l’effort : low, medium, high, xhigh, max ou ultracode. max reste propre à la session ; ultracode active les workflows dynamiques à xhigh ; auto efface le niveau enregistré pour le modèle
/fast [on|off]
Activer/désactiver le mode rapide : même modèle, sortie plus rapide, prix supérieur
/plan [description]
Entrer en mode planification, avec éventuellement la tâche de départ
/goal [condition|clear]
Définir une condition de fin. Claude poursuit sur plusieurs tours jusqu’à confirmation par un évaluateur, avec un panneau indiquant temps écoulé, tours et tokens (v2.1.139+)
/advisor [model|off]
Activer l’outil conseiller : un second modèle consulté aux moments clés. Accepte fable si disponible, opus, sonnet ou un identifiant complet
/permissions (/allowed-tools)
Gérer règles d’autorisation, de demande et de refus, répertoires de travail et refus récents du mode Auto
/fewer-permission-prompts
Analyser les transcriptions pour trouver les appels Bash/MCP courants en lecture seule, puis proposer une liste d’autorisation pour .claude/settings.json. Livrée comme /less-permission-prompts en v2.1.111, puis renommée
/sandbox
Activer/désactiver la sandbox sur les plateformes compatibles
Afficher et gérer le travail en arrière-plan de la session, y compris les sous-agents terminés
/batch <instruction>
Décomposer une modification de toute la base en 5 à 30 unités, puis lancer un sous-agent par unité dans son propre worktree, chacun ouvrant une PR
/list-agents (/peers)
Lister les sous-agents, coéquipiers et autres sessions joignables lorsque la messagerie intersessions est activée
/workflow-authoring
Charger la référence de rédaction des scripts de workflow dynamique lorsque cette fonction est activée
/workflows
Ouvrir la vue de progression pour suivre, suspendre, reprendre ou enregistrer les exécutions
/loop [interval] [prompt] (/proactive)
Répéter un prompt tant que la session reste ouverte. Sans intervalle, Claude détermine le rythme ; sans prompt, exécuter le contrôle de maintenance ou .claude/loop.md
/schedule [description] (/routines)
Créer, actualiser, lister ou exécuter des routines sur l’infrastructure cloud gérée par Anthropic
/deep-research <question>
Répartir des recherches web, recouper les sources et rédiger un rapport sourcé. Invocation manuelle uniquement depuis v2.1.218
/autofix-pr [prompt]
Lancer une session cloud surveillant la PR de la branche courante et poussant des corrections après un échec CI ou un commentaire de revue. Nécessite gh
/remote-env
Choisir l’environnement par défaut des agents cloud
Examiner le diff pour les bugs et simplifications. --fix applique les corrections, --comment publie des commentaires de PR et ultra lance la revue cloud. Sous-agent en arrière-plan depuis v2.1.218
/review [level] [--fix] [--comment] [target]
Alias de /code-review depuis v2.1.223 ; mêmes cibles, niveaux d’effort et options
/ultrareview [PR or branch]
Revue approfondie multi-agents dans le cloud. Alias de /code-review ultra. Trois exécutions gratuites sur Pro et Max, puis crédits d’utilisation
/security-review
Examiner le diff de branche contre la branche par défaut d’origin pour les risques d’injection, d’authentification et d’exposition des données. Nécessite un remote origin
/simplify [target]
Quatre agents parallèles examinent réutilisation, simplification, efficacité et niveau d’abstraction, puis appliquent les corrections. Depuis v2.1.154, les bugs de correction relèvent de /code-review
/verify
Confirmer une modification en construisant l’application, en la lançant et en observant le résultat, au-delà des tests (v2.1.145+)
/run
Lancer et piloter l’application du projet pour voir fonctionner une modification (v2.1.145+)
/run-skill-generator
Écrire un skill de projet qui apprend à /run et /verify à construire, lancer et piloter l’application (v2.1.145+)
Lister ou sélectionner Default, Proactive, Concise, Explanatory, Learning ou un style personnalisé (v2.1.269+)
/auto-mode-setup
Préparer des entrées d’environnement du mode Auto à partir du projet et des sessions récentes, puis les examiner avant enregistrement
/update-config [request]
Demander à Claude de modifier le fichier de paramètres approprié pour le changement décrit
/import [codex|gemini|cursor] [--dry-run] [--yes]
Importer la configuration d’un autre agent local ; examiner d’abord avec --dry-run. Des restrictions de fournisseur et de feature flags s’appliquent
/artifacts
Parcourir, joindre ou ouvrir les artefacts accessibles là où la fonction est disponible
/design [brief]
Créer des planches de design modifiables sous forme d’artefact dans les sessions Anthropic compatibles
/config [key=value ...] (/settings)
Ouvrir les paramètres ou définir directement une clé, par exemple /config theme=dark. /config --help liste les clés modifiables
/init
Générer un premier CLAUDE.md. Examinez les instructions produites et testez leur utilité avant de commiter ; les effets des fichiers de contexte varient selon la configuration. CLAUDE_CODE_NEW_INIT=1 ajoute un parcours interactif pour skills, hooks et mémoire personnelle
/hooks
Afficher la configuration des hooks d’événements d’outils
Gérer connexions MCP et OAuth. En mode -p, afficher un résumé textuel de l’état
/plugin [subcommand]
Gérer les plugins avec les sous-commandes list, install, enable, disable
/reload-plugins [--force]
Recharger les plugins actifs sans redémarrer. Ignorer avec avertissement si le rechargement invaliderait le cache de prompt, sauf si forcé
/reload-skills
Réexaminer les répertoires de skills et de commandes pour appliquer leurs modifications pendant la session (v2.1.152+)
/skills
Lister les skills. Saisir pour filtrer, t pour trier par coût en tokens, Space pour changer la visibilité
/agents
Rappeler de demander à Claude de gérer les sous-agents, ou de modifier .claude/agents/ directement. Était un gestionnaire interactif avant v2.1.198
/keybindings
Ouvrir ~/.claude/keybindings.json
/statusline
Configurer la ligne d’état, éventuellement à partir du prompt shell
/terminal-setup
Configurer les raccourcis du terminal pour Shift+Enter. Apparaît seulement dans les terminaux qui en ont besoin
/setup-bedrock
Assistant Amazon Bedrock interactif, visible uniquement avec CLAUDE_CODE_USE_BEDROCK=1
/setup-vertex
Assistant Google Cloud Agent Platform interactif, visible uniquement avec CLAUDE_CODE_USE_VERTEX=1
/web-setup
Connecter GitHub à Claude Code sur le web avec les identifiants locaux de gh
/install-github-app
Installer l’application GitHub Claude pour un dépôt, avec possibilité de configurer workflows GitHub Actions et secrets
/install-slack-app
Installer l’application Slack Claude par un parcours OAuth dans le navigateur
/chrome
Configurer Claude dans Chrome
/design-login
Autoriser l’accès au design system pour /design-sync avec le compte claude.ai
/design-sync [hint]
Convertir le design system React du dépôt et l’envoyer à Claude Design pour utiliser les vrais composants. La première synchronisation peut prendre des heures sur un grand dépôt. API Anthropic uniquement
/claude-api [subcommand]
Référence API et workflows : migrate, upgrade, managed-agents-onboard, prompt-audit, cost-optimize, build-eval, hillclimb
/dataviz [request]
Conseils de graphiques et dashboards avec un validateur exécutable du contraste et du daltonisme (v2.1.198+)
Contrôle complet : installation, PATH, paramètres illisibles, skills et serveurs MCP inutilisés face à leur coût de contexte, hooks lents, volume de CLAUDE.md, dérive des versions. Rapport d’abord, demande avant modification (v2.1.205+)
/skill-doctor
Signaler le coût de contexte des skills visibles et ceux jamais invoqués. Exclut skills intégrés et d’entreprise, exige la récupération des feature flags et ne fonctionne pas via Remote Control. À lancer dans le terminal (v2.1.252+)
/debug [description]
Activer les journaux de débogage de session et diagnostiquer à partir de ceux-ci
/heapdump
Écrire un instantané du tas et une répartition mémoire dans ~/Desktop. ⚠️ Contient toute la conversation et des identifiants ; ne jamais le partager
/status
Ouvrir l’onglet Status des paramètres : version, modèle, compte, connectivité. Fonctionne pendant la réponse de Claude
/usage (/cost, /stats)
Coût de session, limites du forfait et activité. Sur les forfaits payants, ventilation par skill, sous-agent, plugin et serveur MCP
/insights
Produire un rapport sur les sessions : domaines de projet, interactions et difficultés
/release-notes
Sélecteur interactif de changelog. Depuis v2.1.208, les notes restent hors de la conversation visible par Claude
/help
Afficher l’aide et les commandes disponibles
/bug [report] (/share)
Signaler un bug ou partager la conversation avec écran de consentement. Sur les fournisseurs tiers, repli vers une archive locale sous ~/.claude/feedback-bundles/ (v2.1.212+)
/feedback [report]
Envoyer un retour produit. Même boîte de dialogue et règles d’envoi que /bug
/team-onboarding
Créer un guide d’intégration pour un coéquipier à partir de 30 jours de sessions, commandes et usages MCP
/powerup
Leçons interactives et démonstrations animées pour découvrir les fonctions
Ce n’est pas une commande Claude Code. Absente de la référence officielle et de tout le CHANGELOG. Les anciennes versions du guide l’indiquaient par erreur. Sortir du Plan Mode en approuvant le plan ou avec Shift+Tab
/less-permission-prompts
Renommée /fewer-permission-prompts. L’ancien nom livré en v2.1.111 demeure dans les notes de cette version
/extra-usage
Renommée /usage-credits
/pr-comments
Supprimée en v2.1.91. Demander à Claude de récupérer les commentaires de PR
/vim
Supprimée en v2.1.92. Utiliser /config → Editor mode
Ctrl+D
Raccourci clavier de sortie, pas une commande. Voir §10.2
Push-to-talk : maintenir pour parler, relâcher pour envoyer (liaison par défaut)
Reconfiguration : La liaison voice:pushToTalk est configurable dans ~/.claude/keybindings.json (v2.1.71+). Ajoutez une liaison personnalisée si Space entre en conflit avec votre flux de travail :
{
"voice:pushToTalk": "ctrl+space"
}
Activez/désactivez la voix avec /voice. La liaison push-to-talk n’est active que lorsque le mode vocal est activé.
Remplacer l’intégralité de l’invite système par un texte personnalisé
--system-prompt-file <PATH>
Charger l’invite système depuis un fichier, en remplaçant l’invite par défaut (mode impression uniquement)
--append-system-prompt <TEXT>
Ajouter du texte personnalisé à l’invite système par défaut
--append-system-prompt-file <PATH>
Ajouter le contenu d’un fichier à l’invite par défaut (mode impression uniquement)
--exclude-dynamic-system-prompt-sections
Déplacer les sections spécifiques à la machine (répertoire de travail, info d’environnement, chemins mémoire) vers le premier message utilisateur. Améliore la réutilisation du cache d’invite pour différents utilisateurs exécutant la même tâche. À utiliser avec -p pour les charges de travail multi-utilisateurs scriptées
Charger des serveurs MCP depuis un fichier JSON ou une chaîne JSON inline
--strict-mcp-config
Utiliser uniquement les serveurs MCP de --mcp-config, ignorer tous les autres
--plugin-dir <PATH>
Charger des plugins depuis un répertoire ou une archive .zip pour cette session uniquement (répétable). Plusieurs flags --plugin-dir supportés. (.zip depuis v2.1.128)
--plugin-url <url>
Récupérer une archive .zip de plugin depuis une URL et la charger pour la session courante. Utile pour les pipelines CI partageant des plugins via un stockage d’artefacts. (v2.1.129)
Activer l’intégration du navigateur Chrome pour l’automatisation web
--no-chrome
Désactiver l’intégration du navigateur Chrome pour cette session
--ide
Se connecter automatiquement à l’IDE au démarrage si exactement un IDE valide est disponible
--channels
Activer les canaux MCP (Aperçu Research). Supporte l’authentification OAuth claude.ai et par clé API. Les organisations gérées nécessitent channelsEnabled: true dans managed-settings. (v2.1.128)
--remote-control
--rc
Démarrer une session interactive avec Remote Control activé pour pouvoir également la contrôler depuis claude.ai ou l’application Claude
--remote-control-session-name-prefix <PREFIX>
Préfixe pour les noms de session Remote Control générés automatiquement. Par défaut, le nom d’hôte de la machine
Activer le mode débogage avec filtrage optionnel par catégorie (ex. : "api,hooks")
--debug-file <PATH>
Écrire les journaux de débogage dans un chemin de fichier spécifique. Active implicitement le mode débogage. Prend la priorité sur CLAUDE_CODE_DEBUG_LOGS_DIR
--dangerously-load-development-channels
Activer les canaux absents de la liste d’autorisation approuvée, pour le développement local. Nécessite une confirmation
Mode minimal : ignorer la découverte automatique des hooks, skills, plugins, serveurs MCP, mémoire automatique et CLAUDE.md. Les appels scriptés démarrent plus rapidement. Définit CLAUDE_CODE_SIMPLE
--settings <PATH|JSON>
Chemin vers un fichier JSON de paramètres ou une chaîne JSON inline à charger
--setting-sources <LIST>
Sources séparées par des virgules à charger : user, project, local
--disable-slash-commands
Désactiver tous les skills et slash commands pour cette session
Commandes de premier niveau exécutées sous la forme claude <subcommand> :
Sous-commande
Description
claude "query"
Démarrer le REPL avec une invite initiale
claude agents
Ouvrir la vue Agent : liste toutes les sessions (en cours / en attente / terminées) avec aperçu et réponse inline (v2.1.139+)
claude attach <ID>
Attacher une session d’arrière-plan dans le terminal courant
claude auto-mode defaults
Afficher les règles du classificateur auto mode intégré en JSON. Utiliser claude auto-mode config pour voir la configuration effective avec les paramètres appliqués
claude auth login / logout / status
Gérer l’authentification Claude Code
claude daemon status
Afficher l’état du superviseur de sessions en arrière-plan, la version, le répertoire de socket et le nombre de workers. Quitte avec le code 1 si le superviseur ne fonctionne pas
claude daemon stop --any
Arrêter le superviseur de sessions en arrière-plan et les sessions qu’il héberge. Passer --keep-workers pour laisser les sessions en arrière-plan s’exécuter
claude doctor
Exécuter des diagnostics depuis la ligne de commande
claude install
Installer ou changer les builds natifs de Claude Code
claude logs <ID>
Afficher la sortie récente d’une session en arrière-plan
claude mcp add / remove / list / get / enable
Configurer les serveurs MCP
claude plugin
Gérer les plugins Claude Code
claude remote-control
Démarrer un serveur Remote Control pour contrôler Claude Code depuis claude.ai ou l’application Claude
claude respawn <ID>
Redémarrer une session en arrière-plan (en cours ou arrêtée) avec sa conversation intacte. Utiliser --all pour redémarrer toutes les sessions en cours
claude rm <ID>
Supprimer une session en arrière-plan de la liste. La transcription de conversation reste sur le disque pour /resume
claude setup-token
Créer un token de longue durée pour l’utilisation par abonnement
claude stop <ID>
Arrêter une session en arrière-plan (alias : claude kill)
claude update / claude upgrade
Mettre à jour vers la dernière version
claude project purge [path]
Supprimer tout l’état Claude Code d’un projet : transcriptions, tâches, historique de fichiers, entrée de configuration. Options : --dry-run, -y/--yes, -i/--interactive, --all. (v2.1.126)
claude ultrareview [target]
Exécuter /ultrareview de manière non interactive depuis CI/scripts. target : numéro de PR, branche, ou branche courante si omis. --json pour une sortie lisible par machine. Quitte avec 0 en cas de succès, 1 en cas d’échec. (v2.1.120)
claude plugin prune
Supprimer les dépendances de plugins auto-installées orphelines. Cascade avec claude plugin uninstall --prune. (v2.1.121)
claude plugin details <name>
Afficher l’inventaire des composants du plugin (skills, agents, commandes, hooks, serveurs MCP) et le coût estimé en tokens par session. (v2.1.139)
Définir ces variables dans votre shell avant de lancer Claude Code (elles ne peuvent pas être configurées via settings.json) :
Variable
Description
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
Activer les équipes d’agents expérimentales
CLAUDE_CODE_TMPDIR
Substituer le répertoire temporaire pour les fichiers internes
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1
Activer le chargement de CLAUDE.md dans des répertoires supplémentaires
DISABLE_AUTOUPDATER=1
Désactiver les mises à jour automatiques
CLAUDE_CODE_EFFORT_LEVEL
Contrôler la profondeur de réflexion pour les modèles à pensée étendue
USE_BUILTIN_RIPGREP=0
Utiliser le ripgrep système au lieu du ripgrep intégré (utile sur Alpine Linux)
CLAUDE_CODE_SIMPLE
Activer le mode simple (outils Bash + Edit uniquement, sans agents/hooks/MCP)
CLAUDE_BASH_NO_LOGIN=1
Ignorer l’invocation du shell de connexion pour BashTool
CLAUDE_CODE_SESSION_ID
Identifiant unique pour la session Claude Code courante. Transmis à tous les environnements de sous-processus de l’outil Bash. Correspond à session_id dans le JSON stdin des hooks. À utiliser pour corréler la sortie des outils avec les sessions dans les pipelines d’observabilité. (v2.1.132)
CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1
Se désabonner du rendu plein écran en écran alternatif. La sortie du terminal reste dans le tampon de défilement natif au lieu de l’écran alternatif. À utiliser dans les environnements ne supportant pas l’écran alternatif (certaines configurations de capture de journaux, terminaux embarqués). (v2.1.132)
CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1
Lorsque définie, Homebrew ou WinGet met à niveau automatiquement Claude Code en arrière-plan et invite à redémarrer lorsqu’une nouvelle version est disponible. (v2.1.129)
Pour la référence complète des variables d’environnement (190+ variables réparties en 17 catégories, incluant toutes les variables ANTHROPIC_*, CLAUDE_CODE_*, DISABLE_* et OTEL_*), voir Référence des Paramètres : Variables d’Environnement.
Combinaisons Courantes :
Terminal window
# Mode CI/CD - non interactif avec acceptation automatique
Dépannage interactif : Utilisez la commande /diagnose pour une résolution guidée et interactive des problèmes. Elle analyse automatiquement votre environnement et fournit des solutions ciblées. Voir examples/commands/diagnose.md.
ANTHROPIC_API_KEY défini dans le shell ou .env contourne l’abonnement
Exécuter echo $ANTHROPIC_API_KEY. Si une valeur s’affiche, Claude Code facture aux tarifs API. Supprimer la variable de votre profil shell pour rétablir la facturation par abonnement. Exécuter claude /cost pour vérifier les dépenses de la session en cours.
Vérifier les permissions des outils dans settings.local.json
Vérifier la syntaxe de la commande
Vérifier les dépendances manquantes
« Agent not available »
Vérifier que le fichier agent existe dans .claude/agents/
Vérifier la syntaxe du frontmatter YAML
Redémarrer la session Claude Code
« Hook blocked operation »
Vérifier le code de sortie du hook (2 = bloqué)
Lire le message d’erreur du hook
Ajuster les règles du hook si nécessaire
« Unexpected API charges despite subscription »
Exécuter echo $ANTHROPIC_API_KEY dans votre shell : toute valeur affichée signifie que Claude Code passe par la facturation API et non par votre abonnement
Supprimer la clé de ~/.zshrc, ~/.bashrc ou des fichiers .env si la facturation par abonnement est souhaitée
Utiliser claude /cost (ou /usage depuis la v2.1.118) pour vérifier les dépenses en temps réel dans la session en cours
Utiliser npx ccusage pour consulter l’historique des dépenses entre sessions
💡 Exemples prêts pour la production : Pour des modèles complets et éprouvés incluant des commandes avancées (/pr, /release-notes, /sonarqube) et des hooks de sécurité, consultez le répertoire examples/. Les modèles ci-dessous sont des points de départ minimaux.
Objectif : Enchaîner Claude Code avec les bons outils IA pour des flux de travail optimaux
En résumé : Claude Code excelle dans le raisonnement contextuel et l’implémentation multi-fichiers. Combinez-le avec Perplexity (recherche), Gemini (images), Kimi (diapositives) et NotebookLM (synthèse) pour un flux de développement entièrement assisté par l’IA.
Claude Code est conçu pour être votre partenaire d’implémentation avec une compréhension approfondie de la base de code. Il ne cherche délibérément pas à tout faire, et c’est une force.
Pour une utilisation intensive de Claude Code, cc-copilot-bridge achemine les requêtes via GitHub Copilot Pro (10 $/mois) plutôt que la facturation par token d’Anthropic.
Ce que ça résout :
Limites de débit lors de sessions de développement intensives
Optimisation des coûts pour un usage à volume élevé (économies possibles de 99 %+)
Développement hors ligne avec Ollama pour le code propriétaire
Quand l’utiliser : toute implémentation nécessitant une connaissance de l’écosystème, des comparaisons de bibliothèques ou des considérations de sécurité.
Quand l’utiliser : intégration dans une nouvelle équipe, revue d’une base de code inconnue, préparation à l’onboarding.
💡 Intégration MCP disponible : vous pouvez désormais interroger les notebooks NotebookLM directement depuis Claude Code via le serveur MCP NotebookLM. Voir ai-ecosystem.md § 4.1 pour le guide d’installation et d’utilisation.
Utiliser Haiku pour les tâches simples (/model haiku)
Regrouper les recherches en sessions Perplexity Deep Research
Exploiter les offres gratuites : NotebookLM, Kimi, Gemini Flash sont gratuits
Vérifier le contexte régulièrement (/status) pour éviter le gaspillage
Utiliser Opus avec parcimonie : réserver aux décisions architecturales
📖 Approfondissement : pour des patterns d’intégration détaillés, des prompts prêts à l’emploi et des comparaisons d’outils, consultez le guide complet de l’écosystème IA.
Si vous travaillez avec des membres d’équipe non techniques, Cowork apporte les capacités agentiques de Claude aux travailleurs de la connaissance sans nécessiter d’accès au terminal.
Aspect
Claude Code
Cowork
Cible
Développeurs
Travailleurs de la connaissance
Interface
Terminal
Application desktop
Exécution de code
Oui
Non (fichiers uniquement)
Sorties
Code, scripts
Excel, PPT, docs
Statut
Production
Aperçu de recherche
Schéma de collaboration : les développeurs utilisent Claude Code pour les specs → les PMs utilisent Cowork pour les résumés destinés aux parties prenantes. Contexte partagé via ~/Shared/CLAUDE.md.
Couverture complète : pour mettre en place une base de connaissances d’entreprise accessible depuis les deux outils (vault Markdown versionné, connecteurs MCP pour Jira/Confluence/Notion, RAG à grande échelle), voir Infrastructure de connaissances d’équipe.
Disponibilité : abonnés Pro ($20/mois) ou Max ($100-200/mois), macOS uniquement (janvier 2026).
Voir Section 9 de l’écosystème IA pour les détails.
Pour les workflows autonomes avancés, consultez Coding Agent Development Workflows de Nick Tune, une approche orientée pipeline axée sur la génération de PR entièrement autonome avec orchestration multi-outils.
SuperClaude transforme Claude Code en une plateforme de développement structurée via l’injection d’instructions comportementales. Fonctionnalités clés :
30+ commandes spécialisées pour les tâches de développement courantes
Personas adaptés à différents contextes
Intégration de serveurs MCP
Gestion des tâches et persistance de session
Modes comportementaux pour des workflows optimisés
Configurations de production issues de 10+ mois d’utilisation intensive
Pourquoi c’est important : Il s’agit de la plus grande ressource Claude Code validée par la communauté (234K étoiles au 27/07/2026, contre 31,9k lors des 9 premiers jours ; le dépôt a depuis été renommé affaan-m/ECC). Contrairement aux tutoriels, ce sont des configurations éprouvées en production, forgées lors de la victoire au hackathon Anthropic (projet Zenith).
Innovations uniques introuvables ailleurs :
hookify : Création de hooks conversationnelle (décrivez le besoin → JSON généré)
pass@k metrics : Approche de vérification formelle (k=3 → 91% de taux de succès)
Subagents sandboxés : Restrictions d’outils par agent (le security-reviewer ne peut pas modifier de fichiers)
Skills de compaction stratégique : Suggestions de compaction manuelle pour gérer la croissance du contexte
Écosystème de plugins : Installation en une commande de toutes les configurations
Positionnement : Complémentaire à ce guide, nous enseignons les concepts (« pourquoi »), ils fournissent les configurations de production (« comment »).
⚠️ Extension non officielle : Les flags SuperClaude (--learn, --uc, --think, etc.) ne sont PAS des flags CLI de Claude Code. Ils fonctionnent via l’injection de prompts dans des fichiers CLAUDE.md et nécessitent l’installation du framework SuperClaude.
SuperClaude inclut des modes comportementaux configurables stockés dans des fichiers ~/.claude/MODE_*.md :
Mode
Objectif
Activation
Orchestration
Sélection intelligente des outils, exécution parallèle
Le mode Apprentissage fournit des explications contextuelles lors de la première utilisation d’une technique, sans vous submerger d’explications répétées.
Installation :
Créez le fichier de mode :
Terminal window
# Create MODE_Learning.md in your global Claude config
touch~/.claude/MODE_Learning.md
Ajoutez le contenu (ou copiez-le depuis le framework SuperClaude) :
# Learning mode
**Purpose**: Just-in-time skill development with contextual explanations when techniques are first used
Conseil : Ces ressources évoluent rapidement. Mettez en favoris les dépôts utiles pour suivre leurs mises à jour.
Sujets supplémentaires issus de ykdojo à explorer (pas encore intégrés dans ce guide) :
Workflows de transcription vocale : Saisie vocale native désormais disponible via /voice (déploiement progressif, Pro/Max/Team/Enterprise). Maintenez Espace pour parler, relâchez pour envoyer. La transcription est gratuite et ne compte pas dans les limites de débit. Nécessitait auparavant superwhisper/MacWhisper comme solutions de contournement externes.
Tmux pour les tests autonomes : Exécution d’outils interactifs dans des sessions tmux pour les tests automatisés
Outil de sécurité cc-safe : Audit des commandes approuvées pour prévenir les suppressions accidentelles
Méthode Cascade : Pattern de multitâche avec 3 à 4 onglets de terminal pour des flux de travail parallèles
Expérimentation en conteneurs : Utilisation de Docker avec --dangerously-skip-permissions pour des travaux expérimentaux sécurisés
Technique Half-clone : Élagage manuel du contexte pour ne conserver que l’historique de conversation récent
Avant de déléguer un travail de développement conséquent à un agent, vérifiez si votre projet est suffisamment spécifié pour le faire en toute sécurité :
Le problème : les agents échouent par manque de spécification, pas par manque de capacités. Ils comblent silencieusement les lacunes à partir de leurs connaissances d’entraînement (code public moyen). Cet audit identifie les manques avant que vous ne déléguiez.
Framework (5 couches, 100 pts au total) :
Couche
Ce qu’elle couvre
Poids
1. Comportementale
Ce que le code fait : fonctionnalités, flux
15 pts
2. Interface
Types, contrats d’erreur, invariants
20 pts
3. Architecturale
Ce qu’il ne faut PAS créer, frontières des modules, contraintes de réutilisation
30 pts
4. Cycle de vie
Ce qui est différé, dette connue, intention de maintenance
20 pts
5. Culturelle
Conventions, nommage, ce que signifie « bon code » ici
15 pts
La couche 3 a le plus fort coefficient car elle est la plus souvent absente et produit les bugs les plus difficiles à détecter : du code qui fonctionne aujourd’hui et dérive le mois suivant.
Résultat : score par couche + niveau de risque (🟢/🟡/🔴), prédiction de comblement silencieux pour chaque lacune, verdict de délégation et 3 gains rapides avec modèles.
Verdict de délégation :
Score
Niveau
Posture
≥80
Sûr
Délégation large possible
60–79
Supervisé
Déléguer avec L3 explicite par tâche
40–59
Risqué
Mode plan + agent de revue
<40
Dangereux
Tâches de code uniquement, jamais architecturales
Disponible en tant que slash command si le plugin ai-methodology est installé :
Définissez-les dans votre profil shell (~/.zshrc, ~/.bashrc, ou les Propriétés système Windows) :
Variable
Rôle
Exemple
ANTHROPIC_API_KEY
Authentification API
sk-ant-api03-...
ANTHROPIC_BASE_URL
Point d’accès API alternatif
https://api.deepseek.com/anthropic
ANTHROPIC_MODEL
Modèle par défaut
claude-sonnet-5
ANTHROPIC_SMALL_FAST_MODEL
Modèle rapide pour les tâches simples
claude-haiku-4-5-20251001
BASH_DEFAULT_TIMEOUT_MS
Délai d’expiration des commandes Bash
60000
ANTHROPIC_AUTH_TOKEN
Token d’authentification alternatif
Votre token d’auth
CLAUDE_CODE_DISABLE_1M_CONTEXT
Désactiver le support de la fenêtre de contexte 1M (v2.1.50+)
true
CLAUDE_CODE_SIMPLE
Mode entièrement minimal : désactive skills, agents, MCP, hooks et le chargement de CLAUDE.md (v2.1.50+)
true
Il s’agit d’un sous-ensemble de référence rapide. Pour le catalogue complet de plus de 190 variables d’environnement réparties en 17 catégories, consultez Référence des paramètres : Variables d’environnement.
Question : Les deux outils ont « Claude » dans leur nom et j’ai vu beaucoup de bruit autour des deux récemment. Sont-ils concurrents ? Lequel choisir ?
Réponse courte : Ils répondent à des cas d’usage totalement différents. Ce sont des outils complémentaires destinés à des publics différents, pas des concurrents.
Comparaison détaillée :
Aspect
Claude Code
ClawdBot
Interface
Terminal/CLI + intégration IDE (VS Code, Cursor, etc.)
Applications de messagerie (WhatsApp, Telegram, Discord, Signal, iMessage)
Public principal
Développeurs logiciels, DevOps, tech leads
Tous (assistants personnels, domotique, travailleurs du savoir)
Cas d’usage principal
Développement logiciel (génération de code, refactoring, débogage, architecture)
Automatisation personnelle, gestion des tâches, domotique, assistance 24h/24
Modèle d’accès
Session terminal locale, nécessite d’être devant l’ordinateur ou en SSH
Accès distant via applications de messagerie depuis n’importe quel appareil (téléphone, montre, tablette)
❌ « ClawdBot est Claude Code mais avec une interface de messagerie » → Faux. Architectures différentes, cas d’usage différents.
❌ « Je dois choisir l’un ou l’autre » → Faux. Ils se complètent.
❌ « ClawdBot est un fork de Claude Code » → Faux. Projets indépendants, créateurs différents.
Note finale : Cette comparaison reflète l’état des deux outils en janvier 2026. ClawdBot a enregistré une forte adoption par la communauté (plus de 5 600 mentions sociales, cas d’usage allant de la domotique au décodage radio). Les deux évoluent rapidement. Consultez la documentation officielle pour les dernières fonctionnalités.
Les chefs de produit peuvent-ils utiliser Claude Code ?
Capture de réunions : Granola + Wispr Flow (dictée)
Génération de PRD : ChatPRD → révision Claude Code
Prototypage UI : v0 → vérification de faisabilité Claude Code
Schéma de flux : projet de contexte de base + projets spécialisés par domaine
Mise en perspective : Les flux de travail de PMs avec Claude Code sont un domaine émergent avec une validation communautaire limitée. Nous disposons actuellement d’un seul retour de praticien (qui a précisé avoir essayé Claude Code mais ne pas l’avoir adopté à long terme). Si vous êtes PM et utilisez Claude Code avec succès, partagez votre flux de travail pour aider la communauté.
Utilisez claude --resume depuis le dossier du projet d’origine pour choisir une conversation enregistrée. Pour déplacer le travail vers un autre dossier, préservez d’abord les transcriptions originales et préparez une passation indiquant la tâche, les décisions, les fichiers modifiés et les vérifications restantes.
Terminal window
# From the original project directory
claude--resume
# From the destination project directory, begin with the reviewed handoff
claude
Les transcriptions peuvent contenir des chemins absolus et des résultats d’outils propres au projet. Copier un dossier de transcriptions au nom encodé ne réécrit pas ces références, ne transfère pas l’état MCP et ne valide pas les permissions dans le dossier cible. Les outils de migration manuelle sont des workflows communautaires nécessitant sauvegardes et validation explicite ; ils ne constituent pas un mécanisme natif de restauration garanti.
Ce guide évalue systématiquement les ressources externes (outils, méthodologies, articles, frameworks) avant intégration afin de maintenir la qualité et d’éviter le bruit.
Transparence : Les contributeurs peuvent voir exactement pourquoi les ressources ont été :
✅ Intégrées (score 3+) : Ajoutées au guide avec attribution
⚠️ Mentionnées (score 2) : Référence brève sans couverture approfondie
❌ Rejetées (score 1) : Raison d’exclusion documentée
Contrôle qualité : La revue technique et la phase de contestation par des agents spécialisés garantissent l’objectivité et empêchent le marketing d’influencer les décisions.
Contribution communautaire : Un modèle d’évaluation est disponible dans docs/resource-evaluations/README.md pour suggérer de nouvelles ressources avec une évaluation systématique.
Cette section aborde les idées reçues courantes sur Claude Code qui circulent dans les communautés en ligne, sur les réseaux sociaux et dans les discussions.
❌ Mythe : « Claude Code possède des fonctionnalités cachées déverrouillables avec des flags secrets »
Réalité : Toutes les fonctionnalités publiques sont documentées dans le CHANGELOG officiel.
Ce que les gens confondent :
Déploiement progressif ≠ Fonctionnalités cachées : Anthropic utilise des feature flags pour les déploiements par étapes (pratique standard dans l’industrie)
Fonctionnalités expérimentales ≠ Secrets : Les équipes d’agents disposent d’une activation et de limites documentées
Découverte communautaire ≠ Piratage : Lorsque des utilisateurs découvrent des fonctionnalités non publiées dans le code compilé, c’est de l’exploration, pas un « déverrouillage de secrets »
La vérité sur les feature flags :
Flag
Objectif
Statut
CLAUDE_CODE_ENABLE_TASKS=0
Choisir l’ancien TodoWrite après activation des outils de tâches
Les nouveaux modèles exigent aussi l’activation explicite des outils de tâches
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
Activer les équipes d’agents
Fonctionnalité expérimentale documentée
Autres flags internes
Assurance qualité, tests A/B, déploiement par étapes
Non destinés aux utilisateurs finaux
Bonne pratique : Lisez le CHANGELOG et les notes de version officielles. Les fonctionnalités deviennent publiques lorsqu’elles sont stables et documentées. L’utilisation de fonctionnalités expérimentales via des contournements peut entraîner :
Perte ou corruption de données
Plantages et instabilité
Incompatibilité avec les versions futures
Perte du support officiel
Signaux d’alarme (indicateurs de désinformation) :
« Fonctionnalité cachée qui va vous épater ! »
« Astuce secrète que les développeurs ne veulent pas que vous connaissiez »
Aucune citation de sources officielles (CHANGELOG, docs, issues GitHub)
Langage FOMO : « Si vous n’utilisez pas ça, vous prenez du retard »
Affirmations dramatiques : « Ça change tout » sans preuve
❌ Mythe : « L’API Tasks permet des agents parallèles entièrement autonomes »
Réalité : Les performances dépendent de la complexité des tâches, du modèle choisi et de la façon dont vous utilisez l’outil. Aucun outil n’est universellement « 100x plus rapide ».
Ce qui influence la vitesse :
Sélection du modèle : Haiku (rapide) vs Sonnet (équilibré) vs Opus (approfondi)
Gestion du contexte : Utilisation efficace des sous-agents, serveurs MCP, compaction stratégique
Qualité des prompts : Exigences claires vs instructions vagues
Complexité des tâches : Refactoring simple vs analyse architecturale
Comparaison honnête (cas d’usage typiques) :
Tâche
Claude Code
Autres outils
Gagnant
Modifications simples (typos, formatage)
~5-10s
~5-10s
≈ Égalité
Refactoring multi-fichiers
30-60s
60-120s
Claude Code (2x)
Analyse architecturale complexe
2-5min
5-15min
Claude Code (3x)
Courbe d’apprentissage (première semaine)
Modérée
Variable
Dépend de l’outil
La vérité : Claude Code est puissant et efficace, mais les affirmations de « 100x plus rapide » relèvent du marketing exagéré. L’avantage réel vient de :
Fenêtre de contexte étendue (200K tokens)
Système de sous-agents intelligent (évite la pollution du contexte)
Écosystème MCP (outils spécialisés)
System prompts robustes (sorties de haute qualité)
✅ Réalité : Ce qui rend Claude Code véritablement spécial
Fenêtre de contexte : Dépend du modèle ; les modèles actuels Opus, Sonnet et Fable disposent de 1M sur l’API directe, Haiku 4.5 de 200K. Consultez /context.
Système de sous-agents : Des fenêtres de contexte isolées évitent la pollution lors de l’exploration
Écosystème MCP : Plus de 100 serveurs communautaires pour des tâches spécialisées
Système de permissions : Contrôle granulaire de l’accès aux outils et des opérations dangereuses
Conception CLI-first : Intégration terminal, workflows git, compatibilité IDE
Tarification transparente : À l’usage, sans abonnements, coûts prévisibles
Développement actif : Publications hebdomadaires avec des fonctionnalités pilotées par la communauté
Rédigé avec : Claude (Anthropic) - Ce guide a été rédigé en collaboration avec Claude Code, démontrant les capacités de l’outil pour la documentation technique.
Inspiré par :
Claudelog.com - Une excellente ressource de conseils, patterns et techniques avancées sur Claude Code qui a servi de référence majeure pour ce guide.
ykdojo/claude-code-tips - Techniques de productivité pratiques qui ont alimenté les raccourcis clavier, les transferts de contexte et les optimisations de workflow terminal dans les sections 1.3, 2.2 et 10.2.
