Ce guide n’est pas la documentation officielle d’Anthropic. Il s’agit d’une ressource communautaire fondée sur mon exploration de Claude Code au fil de plusieurs mois.
Ce que vous y trouverez :
Des patterns qui ont fonctionné pour moi
Des observations qui ne s’appliquent pas forcément à votre flux de travail
Des estimations de temps et des pourcentages approximatifs, non issus de mesures
Ce que vous n’y trouverez pas :
Des réponses définitives (l’outil est trop récent)
Des affirmations de performance 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 récemment entendu parler de ClawdBot, c’est un outil différent. ClawdBot est un assistant chatbot auto-hébergé accessible via des applications de messagerie (Telegram, WhatsApp, etc.), conçu pour l’automatisation personnelle et les cas d’usage domotique. Claude Code est un outil CLI pour les développeurs (intégration terminal/IDE) axé sur les flux de travail 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 desktop 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 desktop ajoute par rapport à Claude Code standard :
Fonctionnalité
Détails
Revue visuelle des diffs
Examiner les modifications de fichiers en ligne avec des commentaires avant d’accepter
Prévisualisation live de l’application
Claude démarre votre serveur de développement, ouvre un navigateur intégré et vérifie automatiquement les changements
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
Vous êtes sur Linux (Desktop est macOS + Windows uniquement)
Ce qui N’EST PAS disponible dans Desktop (CLI uniquement) : fournisseurs d’API tiers, flags 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 est automatiquement reprise.
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.
Remarque sur les serveurs MCP : les serveurs MCP configurés dans claude_desktop_config.json (l’onglet Chat) sont distincts de Claude Code. Pour utiliser des serveurs MCP dans l’onglet Code, configurez-les dans ~/.claude.json ou le fichier .mcp.json de votre projet. Voir Section 8.1 — MCP.
Utilisateurs Windows : tout au long de ce guide, quand vous voyez ~/.claude/, utilisez %USERPROFILE%\.claude\ ou C:\Users\VotreNom\.claude\ à la place.
Contraste élevé : assurez-vous que le texte et les diagrammes sont clairement lisibles
Recadrage pertinent : supprimez les éléments d’interface inutiles pour une analyse ciblée
Annoter si nécessaire : encerclez ou surlignez les zones spécifiques sur lesquelles vous voulez que Claude se concentre
Combiner avec du texte : “Concentre-toi sur la section en-tête” apporte un contexte supplémentaire
Exemple de flux de travail :
Vous : [Collez 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éboguez-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 une quantité significative de tokens de contexte (équivalent à ~1000-2000 mots de texte)
Utilisez /status pour surveiller l’utilisation du contexte après avoir collé des images
Envisagez de décrire des diagrammes complexes textuellement si le contexte est serré
Certains terminaux peuvent ne pas prendre en charge le collage d’images depuis le presse-papiers (solution de repli : enregistrez et référencez le chemin du fichier)
💡 Conseil pro : prenez des captures d’écran des messages d’erreur, des maquettes de design et de la documentation plutôt que de les décrire par écrit. La saisie visuelle est souvent plus rapide et plus précise que les descriptions textuelles.
Outils de wireframing pour le développement assisté par 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
✓ Communauté
Wireframes rapides, diagrammes d’architecture
tldraw
Canvas minimaliste
Gratuit
Émergent
Collaboration en temps réel, intégrations personnalisées
Pencil
Canvas 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, zéro configuration
Excalidraw (excalidraw.com) :
Open-source, l’esthétique dessinée à la main réduit la sur-spécification
Idéal pour : ingénieurs-designers souhaitant le paradigme design-as-code, équipes sur Cursor/Claude Code
⚠️ Remarque : lancé en janvier 2026, forte traction (1M+ vues, adoption FAANG) mais encore en maturation. Actuellement gratuit ; modèle de tarification à définir. Recommandé pour les premiers adopteurs à l’aise avec l’itération rapide.
Papier + photo :
Sérieusement, ça fonctionne très bien
Prenez une photo avec votre smartphone → collez directement dans Claude Code
Conseils : bonne luminosité, recadrage serré, éviter les reflets et les ombres
Claude gère bien les rotations et les artefacts des dessins à la main
Paramètres d’export recommandés : format PNG, 1000-1200px sur le côté le plus long, contraste élevé
Figma propose un serveur MCP officiel (annoncé en 2025) qui donne à Claude un accès direct à vos fichiers de design, réduisant considérablement la consommation de tokens par rapport aux seules captures d’écran.
Options de configuration :
Terminal window
# MCP distant (tous les abonnements Figma, toute 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 et diagrammes
Vérifier /status après avoir collé pour surveiller l’utilisation du contexte
Envisager une description textuelle si le contexte dépasse 70%
💡 Conseil tokens : un wireframe 1000×1000 utilise ~1 334 tokens. Les mêmes informations sous forme structurée (via Figma MCP) peuvent n’utiliser que 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 d’une session de terminal à l’autre, en conservant l’intégralité du contexte et de l’historique de conversation.
Deux 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
# Reprendre une session spécifique par son ID
claude--resumeabc123def
# Forme abrégée
claude-rabc123def
Lier à une PR GitHub (--from-pr <number>, 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 reprendre le travail sur une fonctionnalité exactement là où vous l’avez laissé par rapport à une PR spécifique — pas besoin de mémoriser les IDs de session.
Trouver les IDs de session :
Terminal window
# Natif : sélecteur de session interactif
claude--resume
# Natif : lister via Serena MCP (si configuré)
claudemcpcallserenalist_sessions
# Recommandé : recherche rapide avec commandes de reprise prêtes à l'emploi
# Voir examples/scripts/session-search.sh (bash, sans dépendances, liste en 15ms, recherche en 400ms)
# 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 plein texte dans toutes les sessions
# Les sessions s'affichent aussi à la sortie
Vous:/exit
SessionID:abc123def (saved forresume)
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 automatisée de patterns — [GitHub](https://github.com/FlorianBruniaux
Découverte de patterns de session (cc-sessions discover) {#session-pattern-discovery}
Votre historique de sessions est une source de données. Chaque fois que vous demandez à Claude de faire le même type d’action sur plusieurs sessions, c’est un signal : extrayez-le en tant que skill, commande ou règle CLAUDE.md et cessez 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 quoi extraire.
La règle des 20% intégrée au 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), en dessous de 5% ils deviennent des suggestions de command (invocation explicite). Le bonus inter-projet (1,5×) priorise les patterns qui récurrent dans différentes bases de code — ceux-là valent la peine d’être extraits même à faible fréquence.
Lors de l’exécution de plusieurs sessions Claude Code en parallèle (terminaux fractionnés, onglets WebStorm, flux de travail parallèles), le sélecteur /resume affiche les sessions par horodatage ou premier prompt tronqué — 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 CLAUDE.md (en cours de session)
Une instruction comportementale dans ~/.claude/CLAUDE.md fait appeler /rename à Claude automatiquement après 2 à 3 échanges. Aucun outillage requis, fonctionne dans tous les IDEs 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 du respect constant de l’instruction par Claude.
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 se replie 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 gèrent différents moments dans le cycle de vie d’une session. L’approche A renomme tôt pour que la session soit identifiable pendant qu’elle est encore en cours. L’approche B renomme à la fin avec un titre qui reflète la portée complète de la session, remplaçant potentiellement le nom de mi-session par quelque chose de plus précis.
Limitation (les deux approches) : Les noms d’onglets de terminal dans WebStorm et iTerm2 ne sont pas affectés. JetBrains filtre les séquences d’échappement ANSI. La session Claude est renommée, pas l’onglet OS.
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 de la rapidité.
⚠️ Avertissement : N’utilisez l’acceptation automatique que pour des opérations bien définies et réversibles.
Changement de mentalité clé : Claude Code est un système de contexte structuré, pas un chatbot ou un outil d’autocomplétion. Vous construisez un contexte persistant (CLAUDE.md, skills, hooks) qui se renforce au fil du temps — voir §2.5.
Flux de travail natif au 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 renforcent mutuellement dans le temps ; les instructions personnalisées de Copilot sont plus récentes et moins granulaires
Modèle de facturation à l’usage — Pas de quotas de requêtes premium ; le mode agent de Copilot est limité par des plafonds mensuels (300/mois sur Pro, 1500/mois sur Pro+)
Mode headless/CI — Exécution dans des pipelines, des automatisations, des contextes non interactifs
Le code généré par l’IA requiert une vérification proportionnelle au niveau de risque. Accepter aveuglément toutes les sorties ou réviser paranoïaquement chaque ligne sont deux comportements qui font perdre du temps. Cette section vous aide à calibrer votre niveau de confiance.
Enseignement clé : l’IA produit du code plus vite, mais la vérification devient le goulot d’étranglement. La question n’est pas « est-ce que ça fonctionne ? » mais « comment je sais que ça fonctionne ? »
Nuance sur la maintenabilité à long terme : un essai contrôlé randomisé en double aveugle en 2 phases (Borg et al., 2025, n=151 développeurs professionnels) n’a trouvé aucune différence significative dans le temps nécessaire aux développeurs suivants pour faire évoluer du code généré par IA versus du code écrit par un humain. Les taux de défauts ci-dessus sont réels — mais ils ne se traduisent pas systématiquement par une charge de maintenance plus élevée pour le prochain développeur. Le risque est plus circonscrit qu’on ne le suppose généralement. (arXiv:2507.00788)
Commencez prudemment : révisez tout quand vous débutez avec Claude Code
Suivez les patterns d’échec : où les bugs passent-ils à travers les mailles ?
Renforcez les chemins critiques : redoublez d’attention sur les zones ayant eu des incidents
Relâchez les zones à faible risque : faites plus confiance à l’IA pour les types de code stables et testés
Audits périodiques : vérifiez ponctuellement le code « de confiance »
Modèle mental : considérez l’IA comme un développeur junior compétent. Vous ne déploieriez pas son code sans revue, mais vous ne réécririez pas non plus tout ce qu’il produit.
« L’IA vous permet de coder plus vite — assurez-vous de ne pas aussi échouer plus vite. »
— Adapté d’Addy Osmani
Attribution : cette section s’appuie sur “AI Code Review” d’Addy Osmani (jan. 2026), ainsi que sur les recherches d’ACM, Veracode, CodeRabbit et Cortex.io.
1.8 Huit erreurs de débutant (et comment les éviter)
Erreur : « Corrige le bug d’auth ET refactore la base de données ET ajoute de nouveaux tests »
Solution : une tâche focalisée par session. /clear entre des 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
Un changement d’une ligne que vous feriez plus vite manuellement
Session
Manque de contexte ou dérive
Se termine en une session
Prend 30 secondes
Revue
Le relecteur ne peut pas garder tout le diff en tête
Le diff est révisable en une passe
Ne justifie pas une revue
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.
Approfondissement : Spec-First Workflow — Task Granularity couvre le pattern de tranche verticale, la checklist de qualité des PRD et des exemples concrets avant/après.
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é.
Solution : construisez un contexte structuré qui s’accumule dans le temps :
CLAUDE.md : vos conventions, stack et patterns — chargés automatiquement à chaque session
Skills : workflows réutilisables (/review, /deploy) pour une exécution cohérente
Toujours vérifier le pourcentage de contexte avant de commencer des tâches complexes. Un contexte élevé = qualité dégradée.
Lisez cette section si : vous voulez éviter l’erreur n°1 (débordement 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 : Jours 1-3
Objectif : Comprendre comment Claude Code raisonne
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.
« Une tâche, un chat » — mélanger des sujets sans rapport sur plusieurs tours dégrade la précision du modèle d’environ 39%. Le contexte accumule du bruit (« context rot ») qui fausse le jugement même lorsque l’utilisation totale des tokens reste faible. Utilisez /clear de façon agressive entre des tâches distinctes, pas seulement quand la barre de contexte devient rouge.
Option 3 : Résumer à partir d’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 à partir de ce point en conservant le contexte antérieur intact
Libère de l’espace tout en préservant le contexte critique
Plus précis qu’un /compact complet
Option 4 : Approche ciblée
Soyez précis dans vos requêtes
Évitez « lis le fichier entier »
Utilisez des références symboliques : « lis la fonction calculateTotal »
Triage du contexte : ce qu’il faut garder vs. évacuer
Quand on approche de la zone rouge (75%+), /compact seul peut ne pas suffire. Vous devez activement décider quelles informations préserver avant de compacter.
Priorité : Garder
Garder
Pourquoi
Contenu de CLAUDE.md
Les instructions principales doivent persister
Fichiers en cours d’édition active
Contexte du travail en cours
Tests pour le composant actuel
Contexte de validation
Décisions importantes prises
Choix architecturaux
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
Historique encombrant
Long historique de conversation
Résumé par /compact
Fichiers des tâches terminées
Plus nécessaires
Grands fichiers de configuration
Peuvent être relus si besoin
Liste de vérification pré-compactage :
Documenter les décisions critiques dans CLAUDE.md ou une note de session
Committer les modifications en attente dans git (crée un point de restauration)
Noter la tâche en cours explicitement (« Nous implémentons X »)
Exécuter /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 compactage, dites-le explicitement à Claude : « Avant de compacter, rappelle-toi que nous avons décidé d’utiliser la Stratégie A pour l’authentification à cause de X. » Claude l’inclura dans le résumé.
Mémoire de session : résolution de problèmes active, débogage, exploration
Mémoire automatique : décisions et contexte que vous voulez que Claude retrouve à la prochaine session sans effort manuel (v2.1.59+)
Mémoire persistante (Serena) : stockage clé-valeur structuré pour les décisions architecturales sur de nombreux projets
CLAUDE.md : conventions d’équipe, structure du projet (versionné avec git)
Compactage automatique et capture mémoire PostToolUse — un conflit à connaître :
Claude Code se compacte automatiquement lorsque le contexte restant descend sous un seuil de tampon fixe (environ les derniers 6-7% de la fenêtre de contexte, soit environ 13K tokens par rapport à la limite effective). En pratique, cela se déclenche quelque part entre 90 et 95% d’utilisation selon la fenêtre de contexte du modèle et les tokens de sortie réservés. Avant que le compactage complet ne s’exécute, Claude Code applique également une 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 progressivement sans résumer toute la conversation. Si le compactage automatique échoue (par exemple à cause 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 mémoire basé sur des hooks (comme claude-mem) qui sauvegarde l’historique de session via PostToolUse, le compactage automatique peut se déclencher et supprimer l’historique de conversation avant que le pipeline de sauvegarde ait eu la chance de le capturer.
Deux façons de gérer cela :
// Option 1 : désactiver le compactage automatique dans votre settings.json de projet
// (vous gérez le compactage manuellement via /compact)
{
"autoCompactEnabled": false
}
Terminal window
# Option 2 : garder le compactage automatique activé, mais régler le seuil de sauvegarde
# de votre outil pour qu'il se déclenche bien en dessous de 80% (par ex. à 60% d'utilisation du contexte)
# — vérifiez les délais/configuration de seuil de votre plugin mémoire
L’option 1 donne un contrôle total mais exige 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 façon proactive à 75%) s’applique toujours — désactiver le compactage automatique signifie simplement que vous gérez vous-même le timing.
Note de nomenclature : « Ralph Loop » est utilisé de deux façons distinctes dans la communauté. Le pattern original de Geoffrey Huntley (ci-dessus) concerne la rotation du contexte — créer de nouvelles sessions pour éviter la dégradation du contexte. Une autre utilisation, popularisée par Addy Osmani et d’autres en 2026, applique le même terme à l’itération de tâches atomiques 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 de base (boucle sans état avec état externe), mais la portée diffère. Quand le terme apparaît sans attribution, précisez 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 commite de façon 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. Relu au début de chaque nouvelle session.
tasks/
├── todo.md # Plan actuel (éléments cochables)
└── lessons.md # Règles accumulées à partir des corrections
La différence avec PROGRESS.md : lessons.md capture des règles comportementales (« toujours faire un diff avant de marquer comme terminé », « ne jamais mocker sans demander ») plutôt que l’état des tâches. Il s’enrichit dans le temps — le taux d’erreur 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)
Convient mal pour :
Exploration interactive
Conception sans spécification claire
Tâches avec des boucles de retour lentes/ambiguës
Variante : Pipeline session par préoccupation
Au lieu de boucler la même tâche, dédiez une session fraîche à chaque dimension de qualité :
Session de planification — Architecture, périmètre, critères d’acceptation
Session de test — Écrire d’abord les tests unitaires, d’intégration et E2E (TDD)
Session d’implémentation — Coder 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 périmètre 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.
Le modèle par défaut dépend de votre abonnement : les abonnés Max/Team Premium bénéficient d’Opus 4.6 par défaut, tandis que les abonnés Pro/Team Standard obtiennent Sonnet 4.6. Si l’utilisation d’Opus atteint le seuil du plan, il bascule automatiquement sur Sonnet.
Modèle
Entrée (par 1M tokens)
Sortie (par 1M tokens)
Fenêtre de contexte
Notes
Sonnet 4.6
$3.00
$15.00
200K tokens
Modèle par défaut (fév. 2026)
Sonnet 4.5
$3.00
$15.00
200K tokens
Héritage (même prix)
Opus 4.6 (standard)
$5.00
$25.00
200K tokens
Publié fév. 2026
Opus 4.6 (1M context)
$5.00
$25.00
1M tokens
GA pour Max/Team/Enterprise ; API nécessite le palier 4
Opus 4.6 (fast mode)
$30.00
$150.00
200K tokens
2,5× plus rapide, 6× plus cher
Haiku 4.5
$0.80
$4.00
200K tokens
Option économique
Réalité des coûts : Une session typique d’une heure coûte 0,10 $ - 0,50 $ selon les habitudes d’utilisation.
Dépréciations de modèles (fév. 2026) : claude-3-haiku-20240307 (Claude 3 Haiku) a été déprécié le 19 février 2026 avec une mise hors service prévue au 20 avril 2026. Si votre CLAUDE.md, vos définitions d’agents ou vos scripts référencent en dur cet identifiant de modèle, migrez vers claude-haiku-4-5-20251001 (Haiku 4.5) avant avril 2026. Source : platform.claude.com/docs/model-deprecations
200K vs 1M de contexte : performance, coût et cas d’usage
La fenêtre de contexte à 1M (GA pour les plans Max/Team/Enterprise ; le palier 4 de l’API reste nécessaire pour une utilisation directe via l’API) représente un saut de capacité significatif — mais les retours de la communauté la décrivent systématiquement comme un outil premium de niche, et non comme une option par défaut.
Précision de récupération à l’échelle (MRCR v2 8-needle 1M variant)
Le benchmark est la « variante 8-needle 1M » — trouver 8 faits spécifiques dans un document d’1M de tokens. Opus 4.6 passe de 93 % à 76 % en passant de 256K à 1M ; Sonnet 4.5 s’effondre à 18,5 %. Validation communautaire : un développeur a chargé ~733K tokens (4 livres Harry Potter) et Opus 4.6 a retrouvé 49/50 sortilèges documentés en une seule requête (HN, fév. 2026). Le MRCR de Sonnet 4.6 n’est pas encore publié, mais les retours de la communauté indiquent qu’il « peine à suivre des instructions spécifiques et à récupérer des informations précises » à pleine capacité 1M.
Coût par session (approximatif)
Au-delà de 200K tokens en entrée sur l’API directe, tous les tokens de la requête sont facturés aux tarifs premium — pas seulement l’excédent. Remarque : sur les plans Claude Code Max/Team/Enterprise, Opus 4.6 1M est le modèle par défaut aux tarifs standard (sans supplément) depuis la v2.1.75 (mars 2026).
Type de session
~Tokens entrée
~Tokens sortie
Sonnet 4.6
Opus 4.6
Correction de bug / revue de PR (≤200K)
50K
5K
~$0,23
~$0,38
Refactorisation de module (≤200K)
150K
20K
~$0,75
~$1,25
Analyse de service complet (>200K, contexte 1M)
500K
50K
~$4,13
~$6,88
Pour comparaison : Gemini 1.5 Pro offre une fenêtre de contexte de 2M à $3,50/$10,50/MTok — nettement moins cher pour du RAG sur de longs documents. Conseil de la communauté : utilisez Gemini pour le RAG sur grands documents, Claude pour la qualité du raisonnement et les workflows agentiques.
Quel modèle choisir selon le contexte
Scénario
Recommandation
Correction de bug, revue de PR, codage quotidien
Sonnet 4.6 @ 200K — rapide et économique
Audit de dépôt complet, chargement de toute la base de code
Opus 4.6 @ 1M — rentable pour la précision
Refactorisation inter-modules
Sonnet 4.6 @ 1M — mais évaluer le coût face au découpage + RAG
Analyse d’architecture, équipes d’agents
Opus 4.6 @ 1M — meilleure récupération à l’échelle
RAG sur grands documents (PDFs, juridique, livres)
Envisager Gemini 1.5 Pro — moins cher à cette échelle
1M de contexte ≈ 30 000 lignes de code / 750 000 mots
Le contexte 1M est GA pour les plans Claude Code Max/Team/Enterprise (v2.1.75, mars 2026) — l’utilisation directe via l’API nécessite toujours le palier 4 ou des limites de débit personnalisées
Utilisation directe via l’API au-delà de 200K tokens en entrée : Sonnet 4.6 double à $6/$22,50/MTok ; Opus 4.6 double à $10/$37,50/MTok (tarif standard applicable pour les plans Claude Code Max/Team/Enterprise)
Si l’entrée reste ≤200K, la tarification standard s’applique même avec le flag bêta activé
Solution pratique : vérifier le contexte à ~70 % et ouvrir une nouvelle session plutôt que d’atteindre la compaction (pattern HN)
Consensus de la communauté : 200K + RAG est l’approche par défaut ; 1M Opus est réservé aux cas où charger tout le contexte d’un coup est réellement nécessaire
# Utiliser Haiku pour les tâches simples (4× moins cher en entrée, 3,75× moins cher en sortie)
claude--modelhaiku"Fix this typo in README.md"
# Utiliser Sonnet (par défaut) pour le travail courant
claude"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 surcoût par session
// ✅ Moins cher - charger uniquement ce dont vous avez besoin
{
"mcpServers": {
"serena": {...} // Only for this project
}
}
// ~2K tokens de surcoût
Stratégie 5 : Regrouper les opérations
Terminal window
# ❌ Coûteux - 5 requêtes séparées
"Read file1.ts"
"Read file2.ts"
"Read file3.ts"
"Read file4.ts"
"Read file5.ts"
# ✅ Moins cher - 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 le cache de prompts pour un contexte répété (API)
Si vous appelez l’API Anthropic directement (par exemple pour des agents ou pipelines personnalisés), le cache de prompts réduit les coûts jusqu’à 90 % sur les préfixes répétés.
# Mark stable sections with cache_control
response = client.messages.create(
model="claude-sonnet-4-6-20250514",
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 du cache de prompts :
Opération
Multiplicateur de coût
TTL
Écriture en cache
1,25× prix de base
5 minutes (par défaut)
Écriture en cache (étendue)
2× prix de base
1 heure
Lecture en cache (succès)
0,1× prix de base
—
Réduction de latence
Jusqu’à 85 % pour les longs prompts
—
Seuil de rentabilité : 2 succès de cache avec un TTL de 5 minutes. Au-delà, économies nettes.
Règles :
Maximum 4 points de cache par requête
Clé de cache = correspondance exacte du préfixe (un seul caractère différent = échec de cache)
Placer les points de cache après les grandes sections stables : prompt 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 — ceci s’applique aux workflows basés sur l’API que vous construisez par-dessus Claude
Claude Code gère le cache de prompts sans aucune configuration de votre part. Comprendre les mécanismes vous aide à prendre des décisions qui maintiennent un taux de succès de cache élevé et des coûts bas.
Hiérarchie du préfixe 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 échanges nécessitent un calcul frais.
Le lookback de 20 blocs — le piège des longues sessions
La correspondance de cache utilise un lookback limité d’environ 20 blocs. Dans une longue session avec de nombreux appels d’outils et échanges, les blocs du début de la conversation sortent de cette fenêtre et deviennent des échecs de cache. Conséquence pratique : les très longues sessions perdent progressivement leur efficacité de cache au niveau de la couche de messages. La solution est /compact — il compresse l’historique de 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 inférieurs au seuil ne sont jamais mis en cache, quelle que soit leur stabilité :
Famille de modèles
Tokens minimaux
Claude Opus 4.6, Opus 4.5, Haiku 4.5
4 096
Claude Sonnet 4.6
2 048
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 (inférieurs à ~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 prompt système dépasse le seuil pour votre modèle cible.
Taille des résultats d’outils et économie du cache
Les résultats d’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 de git status de 500 tokens coûte 500 × 0,1× à relire à chaque tour suivant. La même sortie à 50 tokens (filtrée par un outil comme RTK) coûte 50 × 0,1× — 90 % de moins, cumulé sur 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 cher à maintenir.
La même logique s’applique aux écritures en cache : un préfixe d’historique plus petit implique des écritures initiales moins chères (1,25× × moins de tokens).
Suivi des 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 written to cache this request
print(response.usage.cache_read_input_tokens) # Tokens read from cache (hits)
Calculez votre taux de succès comme cache_read / (cache_read + cache_creation) entre les requêtes. Un ratio supérieur à 0,8 indique que votre structure de prompt fonctionne bien. Les ratios faibles signifient généralement que le contenu dans le 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 prompt système.
Il n’existe pas d’outil de surveillance dédié spécifiquement aux métriques de cache de session Claude Code. Le suivi des coûts via ccusage couvre les dépenses globales mais ne ventile pas les taux de succès du cache. Pour une visibilité spécifique au cache dans les pipelines personnalisés, analysez les champs de réponse ci-dessus.
Règles pratiques
Gardez CLAUDE.md stable entre les sessions — toute modification invalide le cache système en une seule fois, puis il se réchauffe à la requête suivante
Exécutez /compact avant que la conversation 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 à partir de la v2.1.69+. Appliquez ces solutions de contournement immédiatement :
—resume/—continue provoque une reconstruction complète du cache (0 % de taux de succès) à chaque reprise car le JSONL de session supprime les enregistrements d’outils différés avant l’écriture. Solution : évitez --resume jusqu’à correction.
L’en-tête de facturation par session injecte un hash unique comme premier bloc du prompt système, provoquant un échec de cache froid à chaque démarrage de session et appel de sous-agent. Solution : "CLAUDE_CODE_ATTRIBUTION_HEADER": "false" dans ~/.claude/settings.json.
Tendances historiques : suivez les habitudes d’utilisation sur des jours/semaines/mois
Ventilation par modèle : identifiez 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 par développeur
Pour un inventaire complet des outils communautaires de suivi des coûts, visionneuses de sessions, gestionnaires de configuration et interfaces alternatives, voir Outils tiers.
Suivi mensuel :
Consultez votre Console Anthropic pour un usage détaillé :
Mise en perspective des coûts : Si Claude Code vous fait gagner un temps significatif sur une tâche, le coût API est généralement négligeable comparé à votre taux horaire. N’optimisez pas excessivement les coûts en tokens au détriment de la productivité.
Quand optimiser :
✅ Vous avez un budget serré (étudiant, hobbyiste)
✅ Utilisation intensive (>4 heures/jour)
✅ Usage en équipe (5+ développeurs)
Quand NE PAS optimiser :
❌ Votre temps vaut plus que les coûts API
❌ Vous passez plus de temps à optimiser que vous n’économisez
❌ L’optimisation nuit à la productivité (trop restrictif)
Pour les développeurs solo avec un budget limité :
1. Commencer avec Haiku pour l'exploration/la planification
2. Passer à Sonnet pour l'implémentation
3. Utiliser /compact agressivement (tous les 50-60 % de contexte)
4. Se limiter à 1-2 serveurs MCP
5. Être précis dans toutes les requêtes
6. Regrouper les opérations autant que possible
Coût mensuel estimé : $5-$15 pour 20-30 heures
Pour les développeurs professionnels :
1. Utiliser Sonnet par défaut (équilibre optimal)
2. Utiliser /compact au besoin (contexte ≥70 %)
3. Utiliser
[First analysis draft]
[Revised analysis incorporating second level of thinking]
[Critical review and final validated plan]
User: Ok, now do step 1 with ultrathink.
Result: By allowing Claude to iterate and self-critique, final plans have significantly fewer edge cases missed and critical issues caught before implementation.
MCP is an open standard that allows Claude to connect to external services, databases, and tools beyond its built-in capabilities.
Official Definition: “MCP is an open protocol that standardizes how applications provide context to LLMs. It enables secure, two-way connections between AI assistants and data sources.”
Analogy: If Claude is a programmer, MCP is their access badge to different systems.
How MCP Works:
Claude Code ←→ MCP Protocol ←→ MCP Server ←→ External Service
Key design principle: The description field is what the orchestrating agent reads to decide when to invoke this subagent. Write it as a clear trigger condition.
Agent Invocation:
Subagents can be invoked:
By you: /agent-name or “Use the security-agent to…”
By Claude automatically: When description matches the task
Programmatically: Via task delegation in complex workflows
Basic Agent Example:
.claude/agents/code-reviewer.md:
---
name: code-reviewer
description: Use for reviewing code quality, security, and best practices before commits or PRs
tools: Read, Grep, Glob
---
# Code Review Agent
You perform thorough code reviews focusing on:
1. Security vulnerabilities
2. Performance issues
3. Code style consistency
4. Test coverage gaps
5. Documentation completeness
Output format: Structured report with severity levels (Critical/High/Medium/Low/Info)
Extended thinking is a feature where Claude explicitly reasons through a problem step by step before giving a final answer. This is different from regular responses where the reasoning is implicit.
When thinking occurs:
Complex algorithmic problems
Multi-step planning
Ambiguous requirements with multiple valid solutions
Architecture decisions with significant tradeoffs
Why it improves output:
Forces consideration of multiple approaches before committing
Catches contradictions in requirements early
Reduces confident errors (stating wrong things with certainty)
User: /plan
User: Analyse le système d’authentification actuel. Quels sont les composants clés,
les dépendances et les risques potentiels d’une migration vers OAuth2 ?
Claude: [Analyse initiale]
User: Sur la base des deux tours, rédige le plan de migration définitif.
Inclus une stratégie de retour arrière et une atténuation des risques pour chaque étape.
Claude: [Plan affiné intégrant les deux tours]
User: /execute
User: Implémente le plan du tour 3.
**Pourquoi ça fonctionne** : Chaque tour oblige Claude à reconsidérer ses hypothèses. Le tour 2 détecte généralement 30 à 40 % des problèmes que le tour 1 avait manqués. Le tour 3 synthétise l'ensemble en un plan plus robuste.
> **📊 Base empirique — Anthropic AI Fluency Index (fév. 2026)**
>
> Une étude Anthropic analysant 9 830 conversations avec Claude quantifie précisément pourquoi la révision du plan fonctionne : les utilisateurs qui itèrent et **remettent en question le raisonnement de l'IA ont 5,6 fois plus de chances de détecter un contexte manquant** et des erreurs, par rapport aux utilisateurs qui acceptent le premier résultat. Un deuxième tour de révision vous rend 4 fois plus susceptible d'identifier ce qui a été omis.
>
> Le pattern Rev the Engine opérationnalise ce constat : chaque tour de remise en question approfondie déclenche le comportement de questionnement qui produit des plans mesurément meilleurs.
>
> *Source : Swanson et al., "The AI Fluency Index", Anthropic (2026-02-23) — [anthropic.com/research/AI-fluency-index](https://www.anthropic.com/research/AI-fluency-index)*
### Empilement de mécaniques (Mechanic Stacking)
**Concept** : Superposer plusieurs mécanismes de Claude Code pour une intelligence maximale sur les décisions critiques.
Couche 1 : Plan Mode → Exploration sûre, sans effets de bord
Couche 2 : Extended Thinking → Raisonnement approfondi avec tokens de réflexion
Couche 3 : Rev the Engine → Affinement multi-tours
Couche 4 : Split-Role Agents → Analyse multi-perspectives
Couche 5 : Permutation → Tests de variation systématiques
**Toutes les couches ne sont pas nécessaires pour chaque tâche.** Adaptez la profondeur de la pile à l'impact de la décision :
| Impact de la décision | Profondeur de pile | Exemple |
**Anti-pattern** : Empiler des mécaniques sur des décisions triviales. Si le changement est réversible et à faible risque, exécutez directement. La planification excessive est aussi coûteuse que la planification insuffisante.
- Extended Thinking : voir [§9.1 The Trinity](/guide/ultimate-guide/09-advanced-patterns/#91-the-trinity)
## 2.4 Rewind
Rewind est le mécanisme d'annulation de Claude Code.
### Utiliser Rewind
Accessible via `Esc + Esc` (double appui sur Échap) ou la commande `/rewind`. Ouvre une liste de points de contrôle défilante.
### Ce que fait Rewind
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 à partir du point sélectionné (libère de l'espace sans rétablir) |
Distinction clé : **Restore** = annulation (rétablit l'état). **Summarize** = compression (libère de l'espace sans rétablir). Les points de contrôle persistent entre les sessions (nettoyage après 30 jours).
### Limitations
- Fonctionne uniquement sur les modifications de Claude (pas les modifications manuelles)
- Fonctionne dans la session courante
- Les commits git NE sont PAS automatiquement annulés
### Bonne pratique : créer un point de contrôle avant un risque
Avant une opération risquée :
You: Let’s commit what we have before trying this experimental approach
Cela crée un point de contrôle git vers lequel vous pouvez toujours revenir.
### Échelle de récupération : trois niveaux d'annulation
Quand quelque chose tourne mal, vous disposez de plusieurs options de récupération. Utilisez l'approche la plus légère qui résout votre problème :
┌─────────────────────────────────────────────────────────┐
│ RECOVERY LADDER │
├─────────────────────────────────────────────────────────┤
│ │
│ Level 3: Git Restore (option nucléaire) │
│ ───────────────────────────────────── │
│ • git checkout — (annule les non-commités) │
│ • git stash (sauvegarde pour plus tard)│
│ • git reset —hard HEAD~1 (annule le dernier commit)│
│ • Utilisez pour : modifications manuelles, │
│ sessions multiples │
│ │
│ Level 2: /rewind (annulation de session) │
│ ───────────────────────────── │
│ • Rétablit les modifications récentes de Claude │
│ • Fonctionne dans la session courante uniquement │
│ • Ne touche pas aux commits git │
│ • Utilisez pour : mauvaise génération de code, │
│ mauvaise direction │
│ │
│ Level 1: Reject Change (en ligne) │
│ ──────────────────────────── │
│ • Appuyez sur ‘n’ lors de la révision du diff │
│ • La modification n’est jamais appliquée │
│ • Utilisez pour : détecter les problèmes avant │
│ qu’ils surviennent │
│ │
└─────────────────────────────────────────────────────────┘
**Quand utiliser chaque niveau** :
| Scénario | Niveau de récupération | Commande |
|----------|------------------------|----------|
| Claude a proposé du mauvais code | Niveau 1 | Appuyer sur `n` |
| Claude a fait des modifications, vous voulez annuler | Niveau 2 | `/rewind` |
| Modifications commitées, retour arrière complet nécessaire | Niveau 3 | `git reset` |
| Branche expérimentale a mal tourné | Niveau 3 | `git checkout main` |
**Conseil pro** : La commande `/rewind` affiche une liste de 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ûre
Pour une expérimentation systématique, utilisez le pattern de point de contrôle pour créer des points de restauration sûrs :
┌─────────────────────────────────────────────────────────┐
│ CHECKPOINT WORKFLOW │
├─────────────────────────────────────────────────────────┤
│ │
│ 1. Créer un point de contrôle │
│ ────────────────── │
│ git stash push -u -m “checkpoint-before-refactor” │
│ (sauvegarde toutes les modifications y compris │
│ les fichiers non suivis) │
│ │
│ 2. Expérimenter librement │
│ ────────────────── │
│ Essayez un refactoring risqué, des changements │
│ d’architecture, etc. │
│ Si ça fonctionne → commiter normalement │
│ Si ça échoue → restaurer le point de contrôle │
│ │
│ 3. Restaurer le point de contrôle │
│ ────────────────── │
│ git stash list # trouver votre point │
│ git stash apply stash@{0} # restaurer sans supprimer│
│ # ou │
│ git stash pop stash@{0} # restaurer et supprimer │
│ │
└─────────────────────────────────────────────────────────┘
.claude/hooks/auto-checkpoint.sh
**Point de contrôle automatisé** : créez un hook Stop pour créer automatiquement un point de contrôle en fin de session :
```bash
# Voir : examples/hooks/bash/auto-checkpoint.sh
# Crée automatiquement un git stash en fin de session
Choisir le bon modèle pour chaque tâche est l’amélioration du retour sur investissement la plus rapide que la plupart des utilisateurs de Claude Code puissent réaliser. Une décision par tâche — sans tergiversation.
Développement de fonctionnalité, débogage standard
Sonnet
medium
~$0,23
Refactoring de module
Sonnet
high
~$0,75
Architecture système
Opus
high
~$1,25
Audit de sécurité critique
Opus
max
~$2+
Orchestration multi-agents
Sonnet + Haiku
mixed
variable
Note sur les coûts : Estimations basées sur la tarification API (Haiku $0,80/$4,00 par MTok, Sonnet $3/$15, Opus $5/$25). Les abonnés Pro/Max paient un tarif fixe, privilégiez donc la qualité sur le coût. Voir la Section 2.2 pour le détail complet des tarifs.
Modificateur budgétaire (Teams Standard/Pro) : rétrograder d’un niveau par phase — utiliser Sonnet là où le tableau indique Opus, Haiku là où il indique Sonnet pour les tâches d’implémentation mécanique. Pattern communautaire : Sonnet pour Plan → Haiku pour Implementation avec un abonnement Teams Standard à $25/mois.
Le paramètre effort (API Opus 4.6) contrôle le budget computationnel global du modèle — pas seulement les tokens de réflexion, mais aussi les appels d’outils, la verbosité et la profondeur d’analyse. Effort faible = moins d’appels d’outils, pas de préambule. Effort élevé = plus d’explications, analyse détaillée.
Gradient calibré — un vrai prompt par niveau :
low — Mécanique, aucune décision de conception requise
"Rename getUserById to findUserById across src/" — Portée de recherche-remplacement, aucun raisonnement requis.
medium — Pattern clair, portée définie, une seule préoccupation
"Convert fetchUser() in api/users.ts from callbacks to async/await" — Le pattern est connu, la portée est bornée.
high — Décisions de conception, cas limites, préoccupations multiples
"Redesign error handling in the payment module: add retry logic, partial failure recovery, and idempotency guarantees" — Choix architecturaux, pas seulement application d’un pattern.
max(Opus 4.6 uniquement — retourne une erreur sur les autres modèles) — Raisonnement inter-systèmes, décisions irréversibles
"Analyze the microservices event pipeline for race conditions across order-service, inventory-service, and notification-service" — Test d’hypothèses multi-services, réflexion adversariale.
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, code générique
low
Instanciation de template
Revue de code (PR unique)
medium
Reconnaissance de patterns, portée bornée
Triage d’issues, backlog
medium
Catégorisation + quelques analyses
Audit de sécurité
high
Modélisation des menaces, réflexion adversariale
Revue d’architecture
high
Décisions de conception, raisonnement inter-composants
Orchestration multi-agents
high
Coordination + planification
Modèle de coût : effort low signifie moins d’appels d’outils, pas de préambule, sortie directe. 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. 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
Default: Sonnet. Haiku for mechanical tasks. Opus for architecture and security audits.
É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 patterns : Claude reflète les patterns 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ésorganisées sans abstractions claires, il perpétue le désordre. Si votre code manque de bons patterns, fournissez-les explicitement dans CLAUDE.md ou utilisez des ancres sémantiques (Section 2.9).
Considérez-vous comme un ordonnanceur de CPU. Les instances Claude Code sont des threads de travail. Vous n’écrivez pas le code — vous orchestrez le travail.
┌─────────────────────────────────────────┐
│ YOU (Main Thread) │
│ ┌────────────────────────────────────┐ │
│ │ Responsibilities: │ │
│ │ • Define tasks and priorities │ │
│ │ • Allocate context budgets │ │
│ │ • Review outputs │ │
│ │ • Make architectural decisions │ │
│ │ • Handle exceptions/escalations │ │
│ └────────────────────────────────────┘ │
│ │ │ │ │
│ ┌────▼───┐ ┌────▼───┐ ┌────▼───┐ │
│ │Worker 1│ │Worker 2│ │Worker 3│ │
│ │(Claude)│ │(Claude)│ │(Claude)│ │
│ │Feature │ │Tests │ │Review │ │
│ └────────┘ └────────┘ └────────┘ │
└─────────────────────────────────────────┘
Implications :
N’écrivez pas le code quand Claude peut le faire. Votre temps est consacré aux décisions, pas aux frappes de clavier.
Ne gérez pas dans le détail. 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 reprenez la délégation.
Ce modèle mental passe à l’échelle : un seul développeur peut orchestrer 2 à 5 instances Claude sur des tâches indépendantes (voir §9.17 Scaling Patterns).
L’erreur la plus fréquente est de traiter Claude Code comme un chatbot — en saisissant des requêtes ad hoc en espérant un bon résultat. Ce qui distingue un usage occasionnel des workflows de production, c’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 l’utiliser 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 au fil du temps :
Couche
Rôle
Section
Quand la configurer
CLAUDE.md
Règles persistantes, conventions, connaissance du projet
Ce ne sont pas des fonctionnalités indépendantes. Ce sont des couches d’un même système :
CLAUDE.md apprend à Claude ce dont votre projet a besoin (conventions, stack, patterns)
Skills apprennent à Claude comment exécuter des workflows spécifiques (revue, déploiement, tests)
Hooks appliquent les garde-fous automatiquement (bloquer les secrets, auto-formater, lancer le linting)
La mémoire préserve les décisions entre les sessions (choix architecturaux, compromis résolus)
Avant (mode chatbot) :
« Utilise pnpm, pas npm. Et rappelle-toi que notre convention de nommage est… »
(À chaque session. À chaque fois. En copiant-collant le contexte.)
Après (système de contexte) :
CLAUDE.md charge les conventions automatiquement. Skills garantit des workflows cohérents.
Hooks applique la qualité sans effort manuel. La mémoire transmet les décisions d’une session à l’autre.
Le changement ne consiste pas à mieux formuler les 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 agissent 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
Surcoût 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 uniquement lorsque la structure apporte une réelle valeur ajoutée.
La cohérence est essentielle : Si vous utilisez des balises XML, soyez cohérent. Mélanger les styles au sein d’une même session peut brouiller 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 avec des prompts en langage naturel. Introduisez la structure XML quand :
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 contraint Claude à démontrer son raisonnement plutôt qu’à simplement obéir.
Trois schémas de défi utilisés par l’équipe :
1. Le Gardien — Forcez 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 pointues sur les cas limites et ne poursuit que lorsqu’il est satisfait. Cela détecte des problèmes qu’une revue passive laisse passer.
2. L’Exigence de preuve — Demandez des faits, 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 résultats 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éclenchez une réécriture en plein contexte :
"Knowing everything you know now, scrap this and implement the elegant solution"
Cela force une deuxième tentative substantielle avec le contexte accumulé, plutôt que des correctifs incrémentaux sur une base fragile. L’insight clé : la deuxième tentative de Claude avec le contexte complet surpasse systématiquement les corrections itératives.
Pourquoi ça fonctionne : La provocation active des chemins de raisonnement plus profonds que les requêtes polies. Lorsque Claude doit convaincre plutôt que se conformer, il déclenche une analyse plus poussée et détecte ses propres raccourcis.
Les LLM sont des apparieurs de patterns statistiques entraînés sur d’immenses corpus textuels. L’utilisation d’un vocabulaire technique précis aide Claude à activer les bons patterns de ses données d’entraînement, ce qui produit des résultats de meilleure qualité.
Quand vous dites « code propre », Claude peut générer l’une des dizaines d’interprétations possibles. Mais quand vous dites « principes SOLID avec injection de dépendances suivant les couches Clean Architecture », vous ancrez Claude à un pattern spécifique et bien documenté dans son entraînement.
Insight clé : Les termes techniques agissent comme des coordonnées GPS dans la connaissance de Claude. Plus ils sont précis, meilleure est la navigation.
💡 Conseil pro : Lorsque Claude produit du code générique, essayez d’ajouter des ancres plus spécifiques. « Use clean code » → « Apply Martin Fowler’s Refactoring catalog, specifically Extract Method and Replace Conditional with Polymorphism. »
**Key insight**: Everything read by `Read`, executed by `Bash`, or searched by `Grep` occupies context window space. A 1000-line file read = ~1500 tokens consumed.
**Practical implications**:
- Large file reads → faster context exhaustion
- Many tool calls → faster context exhaustion
- Auto-compact triggers at ~95% full (see CLAUDE.md autocompact settings)
---
## Étape 1 : Initialiser avec une instruction vague
User: "Improve the checkout flow"
## Étape 2 : Examiner la liste de tâches de Claude (sans exécuter)
Claude generates: [task list]
## Étape 3 : Comparer avec votre modèle mental
- Manquant : logique de nouvelle tentative de paiement ? → Ajouter aux instructions
- Inattendu : refonte de l'interface ? → Clarifier le périmètre (backend uniquement)
- Mauvais ordre : tests en dernier ? → Spécifier l'approche TDD
## Étape 4 : Affiner et replanifier
User: "Actually, here's what I need: [refined instruction with specifics]"
Conseil de pro : Exécutez TaskList après la planification initiale comme vérification de cohérence avant l’exécution. Si plus de 30 % des tâches vous surprennent, votre prompt a besoin de travail. Itérez sur le prompt, pas sur les tâches.
Claude Code fonctionne dans une fenêtre de contexte de 200 000 tokens (1 million en bêta disponible via API — voir [comparaison 200K vs 1M](line 1751)) :
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éservé pour la réponse
40-45K tokens
Lorsque le contexte se remplit (~75 % dans VS Code, ~95 % en CLI), le contenu ancien est automatiquement résumé. Cependant, des recherches montrent que cela dégrade la qualité (baisse de performance de 50 à 70 % sur les tâches complexes). Utilisez /compact de manière proactive aux points de rupture logiques, ou déclenchez des transferts de session à 85 % pour préserver l’intention plutôt que l’historique compressé. Voir [Session Handoffs](line 2140) et Auto-Compaction Research.
Statut : Partiellement activé par feature flag, déploiement progressif en cours.
TeammateTool permet une orchestration multi-agents avec une communication persistante entre agents. Contrairement aux sous-agents standard qui travaillent de manière isolée, les teammates peuvent se coordonner via des messages structurés.
Capacités principales :
Opération
Objectif
spawnTeam
Créer une équipe nommée d’agents
discoverTeams
Lister les équipes disponibles
requestJoin
Un agent demande à rejoindre une équipe
approveJoin
Le leader de l’équipe approuve les demandes d’adhésion
Messagerie
Communication inter-agents en JSON
Backends d’exécution (détection automatique) :
In-process : Tâches asynchrones dans le même processus Node.js (le plus rapide)
tmux : Sessions de terminal persistantes (survit aux déconnexions)
⚠️ Note : Il s’agit d’une fonctionnalité expérimentale. Les capacités peuvent changer ou être supprimées dans les versions futures. Vérifiez toujours le comportement actuel avec la documentation officielle.
Anti-patterns des agents : Rôles vs Contrôle du contexte
“Les sous-agents ne servent pas à anthropomorphiser des rôles, ils servent à contrôler le contexte” — Dex Horty
Erreur courante : Créer des agents comme si l’on constituait une équipe humaine avec des intitulés de poste.
❌ Incorrect (Anthropomorphisme) :
- Frontend Agent (role: UI developer)
- Backend Agent (role: API engineer)
- QA Agent (role: tester)
- Security Agent (role: security expert)
Pourquoi ça échoue : Les agents ne sont pas des humains avec des domaines d’expertise. Ce sont des outils d’isolation du contexte pour l’efficacité computationnelle.
✅ Correct (Contrôle du contexte) :
- Agent pour l'analyse isolée des dépendances (scope: package.json + lock files only)
- Agent pour le traitement parallèle de fichiers (scope: batch edits without main context pollution)
- Agent pour un audit de sécurité vierge (scope: security-focused analysis without prior assumptions)
- Agent pour les tests de module indépendants (scope: test execution without interfering with main workflow)
Différences clés :
Anthropomorphisme (Incorrect)
Contrôle du contexte (Correct)
“Agent expert en sécurité"
"Audit de sécurité avec contexte isolé"
"Agent développeur frontend"
"Analyse de composants UI (scope: src/components/ only)"
"Agent réviseur de code"
"Revue de PR sans pollution du contexte principal”
Imite la structure d’une équipe humaine
Optimise les ressources computationnelles
Basé sur les intitulés de poste
Basé sur les frontières de périmètre/contexte
Quand utiliser les agents (bonnes raisons) :
Isoler le contexte : Éviter la pollution du contexte principal de la conversation
Au-delà des sous-agents génériques, l’orchestration à périmètre focalisé assigne des frontières de contexte distinctes à différents agents pour une analyse multi-perspectives.
Le pattern : Au lieu d’un seul agent qui examine tout, on crée des agents à contexte isolé qui analysent chacun des aspects distincts avec un contexte vierge :
User: Review the new payment service using scope-focused analysis:
“Faire plus avec moins. Des choix d’architecture intelligents, une meilleure efficacité d’entraînement et une résolution de problèmes ciblée peuvent rivaliser avec la puissance brute.”
— Daniela Amodei, PDG d’Anthropic
Claude Code fait confiance au raisonnement du modèle plutôt que de construire des systèmes d’orchestration complexes. Cela signifie :
Moins de composants = moins de points de défaillance
Décisions pilotées par le modèle = meilleure généralisation
Raccourcis globaux → Ajouter à ~/.claude/CLAUDE.md
Lire cette section si : Vous travaillez sur plusieurs projets ou en équipe
Passer si : Projet unique, développeur solo (configurable au fur et à mesure)
Temps de lecture : 15 minutes
Niveau : Semaine 1
Objectif : Personnaliser Claude Code pour votre projet
Les fichiers CLAUDE.md sont des instructions persistantes que Claude lit au début de chaque session. Ils sont appelés fichiers « mémoire » car ils donnent à Claude une mémoire à long terme de vos préférences, conventions et contexte de projet — persistant d’une session à l’autre plutôt que d’être oubliés après chaque conversation.
Découverte supplémentaire : Dans les monorepos, les fichiers CLAUDE.md des répertoires parents sont automatiquement inclus, et les fichiers CLAUDE.md des répertoires enfants sont chargés à la demande lorsque Claude travaille avec des fichiers dans ces répertoires. Voir CLAUDE.md dans les monorepos pour plus de détails.
Substitutions personnelles : Pour les instructions personnelles non commitées dans Git, deux options s’offrent à vous :
/project/.claude/CLAUDE.md (à ajouter dans .gitignore)
/project/CLAUDE.md.local (automatiquement ignoré par convention)
La plupart des projets n’ont besoin que de trois choses dans leur CLAUDE.md :
# Nom du projet
Brève description en une phrase de ce que fait ce projet.
## Commandes
-`pnpm dev` - Démarrer le serveur de développement
-`pnpm test` - Lancer les tests
-`pnpm lint` - Vérifier le style du code
C’est tout pour la plupart des projets. Claude détecte automatiquement :
La stack technique (via package.json, go.mod, Cargo.toml, etc.)
La structure des répertoires (par exploration)
Les conventions existantes (à partir du code lui-même)
N’ajoutez davantage que si nécessaire :
Gestionnaire de paquets non standard (yarn, bun, pnpm au lieu de npm)
Commandes personnalisées différant du standard (npm run build → make build)
Conventions propres au projet qui entrent en conflit avec les pratiques courantes
Décisions d’architecture qui ne sont pas évidentes à partir du code
Règle empirique : Si Claude commet deux fois la même erreur en raison d’un contexte manquant, ajoutez ce contexte au CLAUDE.md. Ne documentez pas tout de façon préventive — et ne demandez pas non plus à Claude de le générer pour vous. Les fichiers CLAUDE.md générés automatiquement ont tendance à être génériques, gonflés et remplis de choses que Claude détecte déjà de lui-même.
Note de recherche (fév. 2026) : L’ETH Zürich a publié la première évaluation empirique des fichiers de contexte d’agents sur 138 benchmarks et 12 dépôts. Conclusions principales : les fichiers rédigés par des développeurs améliorent le taux de réussite des tâches d’environ 4 %, mais les fichiers générés par LLM (la sortie de /init) le réduisent d’environ 3 %. Les deux ajoutent 20 à 23 % de coût d’inférence. Le mécanisme : les agents suivent chaque instruction du fichier de contexte, y compris celles non pertinentes pour la tâche en cours — surcharge cognitive, exploration plus large, chaînes de raisonnement plus longues. Source : Gloaguen et al., arXiv 2602.11988
Le filtre de découvrabilité : avant d’ajouter une ligne à CLAUDE.md, posez-vous une question — « L’agent peut-il trouver ceci en lisant le code ? » Si oui, ne l’ajoutez pas. La stack technique, la structure des répertoires et les conventions de test sont toutes découvrables. Ce qui mérite une ligne : les pièges d’outillage (use uv, not pip), les mines opérationnelles (legacy/ is deprecated but imported by prod — do not delete), et les conventions non évidentes qui entrent en conflit avec les pratiques standard. Tout le reste est du bruit qui entre en compétition avec la tâche réelle.
Le risque d’ancrage : chaque entrée dans CLAUDE.md est chargée à chaque session, quelle que soit la tâche du jour. Si votre CLAUDE.md mentionne une bibliothèque dépréciée ou un ancien pattern architectural, l’agent est désormais biaisé en sa faveur à chaque prompt. Les entrées obsolètes sont activement nuisibles — pas neutres. Traitez l’élagage périodique du CLAUDE.md comme de la maintenance, pas du nettoyage.
Quand votre projet grandit, structurez CLAUDE.md autour de trois couches (pattern validé par la communauté) :
« 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 n’est pas simplement un fichier de configuration — c’est un système d’apprentissage organisationnel où chaque erreur se transforme en connaissance permanente de l’équipe.
Comment ça fonctionne :
Claude commet 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 la session → ne répète jamais l’erreur
La connaissance se compose au fil du temps à mesure que l’équipe identifie et documente les cas limites
L’effet de composition :
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 + intégration plus rapide
Exemple pratique (équipe de Boris Cherny) :
CLAUDE.md a atteint 2,5K tokens (≈ 500 mots) en quelques mois
Capture les conventions propres au projet, les décisions architecturales et les « pièges »
Les nouveaux membres de l’é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 façon préventive. Traitez plutôt CLAUDE.md comme un document vivant qui grandit à travers les erreurs réelles identifiées lors du développement.
Aller plus loin : capitaliser les solutions d’une PR à l’autre
CLAUDE.md capture des règles comportementales. Pour les problèmes techniques résolus, un pattern complémentaire tiré 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 complète du Compound Engineering 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ù s’accumulent les véritables gains.
Étape
Ce qui se passe
Allocation de temps
Plan
Comprendre l’exigence, rechercher le code 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 passent en revue 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 de nouveaux patterns, créer des agents pour les tâches de revue récurrentes
~10 %
L’intuition critique : 80 % du temps de l’ingénieur devrait être consacré à la planification et à la revue, 20 % à l’implémentation et à la capitalisation. Écrire du code n’est pas le travail — livrer de la valeur l’est.
La règle 50/50
Allouez 50 % du temps d’ingénierie à la création de fonctionnalités, 50 % à l’amélioration du système (agents de revue, patterns documentés, générateurs de tests). Dans l’ingénierie traditionnelle, les équipes mettent 90/10 sur les fonctionnalités et finissent avec un code qui devient plus difficile à maintenir chaque année. Le rapport 50/50 rend chaque itération plus rapide que la précédente.
L’échelle d’adoption
Votre position détermine ce sur quoi vous devriez vous concentrer ensuite, pas ce que quelqu’un d’autre fait à l’étape cinq.
Étape
Description
Déverrouillage clé
0
Développement manuel
—
1
Assistance par chat (ChatGPT, copier-coller)
Bons prompts, les réutiliser
2
Outils agentiques avec revue ligne par ligne
CLAUDE.md, apprendre ce à quoi faire confiance
3
Plan d’abord, revue uniquement sur PR
S’éloigner pendant l’implémentation, revoir le diff
4
De l’idée à la PR (machine unique)
Délégation complète, points de contact minimaux
5
Exécution cloud parallèle
Flotte d’agents, vous passez les PRs en revue à leur arrivée
La plupart des développeurs plafonnent à l’étape 2 (approuver chaque action) parce qu’ils ne font pas confiance à la sortie. La réponse n’est pas plus de revue, c’est de meilleures filets de sécurité : tests, agents de revue automatisés, git worktrees pour l’isolation.
Croyances clés à adopter
Chaque unité de travail devrait faciliter le travail suivant, pas le compliquer
Le goût appartient aux systèmes (CLAUDE.md, agents, skills), pas à la revue manuelle
Construire des filets de sécurité, pas des processus de revue — la confiance vient de l’infrastructure de vérification, pas du contrôle d’accès
Les plans sont le nouveau code — un plan bien rédigé est l’artefact le plus précieux que vous produisez
La parallélisation est le nouveau goulot d’étranglement — la contrainte est maintenant la capacité de calcul, pas l’attention
Le plugin (optionnel)
Every a livré un plugin Claude Code qui regroupe l’ensemble de ce système : 26 agents de revue 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, ainsi que des commandes comme /workflows:plan, /workflows:work, /workflows:review et /workflows:compound.
L’installation du plugin n’est pas nécessaire 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 à 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 réflexion 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 rédigent 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 complète des répertoires que le plugin établit sépare quatre types distincts de documents que la plupart des projets confondent :
Répertoire
Contenu
Cycle de vie
CLAUDE.md
Règles et contraintes pour l’IA
Mis à jour rarement, signal élevé
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 réflexions, archivé après complétion
docs/solutions/
Problèmes résolus avec contexte complet
Créé après complétion, 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 est importante car une IA lisant CLAUDE.md s’attend à des contraintes, pas à un journal des décisions passées. Quand ces éléments sont mélangés, l’IA traite les anciennes décisions comme des règles actuelles.
Vous pouvez adopter cette structure de façon incrémentielle : 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 compose plus fortement à 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 :
Rédigez les règles CLAUDE.md comme si Claude comprenait mieux les nuances — ne sur-spécifiez pas les 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 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 code est une entrée potentielle pour CLAUDE.md.
Le workflow :
Pendant une session de développement :
Claude découvre : "Ce service utilise une stratégie de retry personnalisée"
→ Immédiatement : Ajouter à CLAUDE.md sous ## Architecture Decisions
Claude rencontre : "Les tests échouent s'ils sont exécutés dans le désordre en raison d'un état DB partagé"
→ Immédiatement : Ajouter à CLAUDE.md sous ## Gotchas
Claude suggère : "Ce pattern est dupliqué dans 3 services"
→ Immédiatement : Ajouter à 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).
Quoi capturer en session :
Type de découverte
Section CLAUDE.md
Exemple
Convention implicite
## Conventions
« Les services retournent des objets 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
« Grouper les appels API par maximum 50 items (limite de l’API externe) »
Justification de 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 connaissances qui rivalise avec la documentation d’intégration.
Directive 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 16K tokens dégradent la cohérence du modèle. Incluez les vues d’ensemble de l’architecture, les conventions clés et les contraintes critiques — excluez les références API complètes ou les exemples de code étendus (liez-y à la place). L’équipe Next.js de Vercel a compressé ~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 via la syntaxe @path/to/file (ex. : @README.md, @docs/conventions.md, @~/.claude/my-overrides.md). Les fichiers importés se chargent à la demande et ne consomment des tokens que lorsqu’ils sont référencés.
📊 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. Ceux qui le font — ces 30 % — produisent des interactions mesurément plus dirigées et plus 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, de sorte 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 — une approche moins efficace et moins fiable.
À ne pas confondre avec la mémoire de Claude.ai : Claude.ai (l’interface web) a lancé une fonctionnalité de mémoire distincte en août 2025 pour les Teams, octobre 2025 pour Pro/Max. Il s’agit d’un système différent — il stocke les préférences de conversation dans votre compte claude.ai. La mémoire automatique de Claude Code est une fonctionnalité locale, par projet, gérée via la commande /memory.
Claude Code sauvegarde automatiquement le contexte utile entre les sessions sans édition manuelle de CLAUDE.md. Introduite dans la v2.1.59 (fév. 2026), partagée entre les git worktrees depuis la v2.1.63.
Fonctionnement :
Claude identifie le contexte clé durant les conversations (décisions, patterns, préférences)
Stocké dans .claude/memory/MEMORY.md (projet) ou ~/.claude/projects/<path>/memory/MEMORY.md (global)
Rappelé automatiquement lors des sessions futures pour le même projet
Géré avec /memory : afficher, modifier ou supprimer les entrées stockées
Limites de fichiers (appliquées à la lecture) :
Limite
Valeur
Comportement si dépassée
Nombre max de lignes de MEMORY.md
200 lignes
Tronqué à la ligne 200, avertissement ajouté
Taille max de MEMORY.md
25 Ko
Tronqué au dernier retour à la ligne avant 25 Ko, avertissement ajouté
Répertoire mémoire
200 fichiers
Les fichiers les plus anciens sont supprimés quand la limite est atteinte
La troncature par lignes s’applique en premier ; si le fichier dépasse encore 25 Ko après cette troncature, une troncature en octets est appliquée à la dernière ligne complète. Les deux troncatures ajoutent un commentaire d’avertissement pour indiquer que du contenu a été coupé. Le processus de consolidation Auto Dream maintient MEMORY.md sous la limite de 200 lignes dans le cadre de son étape d’élagage en Phase 4.
Ce qui est mémorisé (exemples) :
Décisions architecturales : “Nous utilisons Prisma pour l’accès à la base de données”
Préférences : “Cette équipe préfère les composants fonctionnels aux composants classe”
Patterns spécifiques au projet : “Les routes API suivent la nomenclature RESTful dans /api/v1/”
Problèmes connus : “Ne pas utiliser le package X en raison d’un conflit de version avec Y”
Différence avec CLAUDE.md :
Aspect
CLAUDE.md
Mémoires automatiques
Gestion
Édition manuelle
Capture automatique via /memory
Source
Documentation explicite
Analyse des conversations
Visibilité
Suivi par git, partagé en équipe
Local par utilisateur, ignoré par git
Worktrees
Partagé (v2.1.63+)
Partagé sur le même dépôt (v2.1.63+)
Idéal pour
Conventions d’équipe, décisions officielles
Patterns de workflow personnels, découvertes
Workflow recommandé :
CLAUDE.md : Conventions d’équipe que tout le monde doit respecter
Mémoires automatiques : Découvertes personnelles et contexte de session
En cas de doute : Documenter dans CLAUDE.md pour la visibilité de l’équipe — les mémoires automatiques ne sont pas committées dans git
Auto Dream : Consolidation de la mémoire (découverte par la communauté)
Fonctionnalité découverte par la communauté, absente des notes de version officielles d’Anthropic. Source : rétro-ingénierie par Piebald-AI/claude-code-system-prompts. Contrôlée par un flag de fonctionnalité côté serveur (tengu_onyx_plover) — autoDreamEnabled: true dans settings.json existe mais ne peut pas remplacer la valeur par défaut du serveur. Déploiement progressif depuis la v2.1.83+. Le comportement peut varier jusqu’à la version finale.
Après 20+ sessions sans curation, la mémoire automatique se dégrade : contexte obsolète, faits contradictoires, dates relatives qui perdent leur sens (“le refactoring d’hier” n’a plus de sens deux semaines plus tard). Auto Dream s’exécute en tant que sous-agent en arrière-plan entre les sessions pour consolider et élaguer — le prompt système dit littéralement : “You are performing a dream — a reflective pass over your memory files.”
Construit sur Auto-Memory (v2.1.59+). Fondement théorique : “Sleep-time Compute: Beyond Inference Scaling at Test-time” (UC Berkeley + Letta, avril 2025), qui a montré que le pré-calcul durant les périodes d’inactivité réduit le calcul au moment du test d’environ 5×. Le parallèle biologique est délibéré — le sommeil REM consolide la mémoire à court terme en mémoire à long terme en éliminant les connexions faibles et en renforçant les importantes.
Conditions de déclenchement (les deux doivent être réunies) :
Condition
Valeur par défaut
Temps écoulé depuis la dernière consolidation
≥ 24 heures
Sessions depuis la dernière consolidation
≥ 5
Configuration extraite du binaire : { "minHours": 24, "minSessions": 5, "enabled": false }. Le champ enabled est contrôlé par le serveur. Un fichier verrou empêche les exécutions concurrentes sur le même projet.
Les 4 phases :
Phase
Nom
Ce qui se passe
1
Orient
Liste le répertoire mémoire, lit l’index, parcourt les fichiers de sujets existants pour cartographier l’état actuel
2
Gather Signal
Grep ciblé des transcripts de session JSONL — pas de lectures exhaustives. Le prompt indique : “Look only for things you already suspect matter.” Priorise les journaux quotidiens, les mémoires dérivées (faits contredisant le code actuel), puis les transcripts
3
Consolidate
Fusionne le nouveau signal dans les fichiers de sujets existants (ne crée jamais de quasi-doublons), convertit les dates relatives en dates absolues, supprime les faits contredits à la source, déduplique les entrées qui se recoupent
4
Prune & Index
Reconstruit MEMORY.md sous la limite de 200 lignes, supprime les pointeurs obsolètes, applique le format des entrées d’index (- [Title](file.md) — one-line hook, ~150 chars max), retourne un bref résumé des changements
Performances observées : Une exécution documentée a consolidé 913 sessions en ~9 minutes. Résultat typique : MEMORY.md passe de 280+ lignes à ~140 lignes.
Contraintes de sécurité : Lecture seule sur le code source du projet. Accès en écriture limité aux fichiers mémoire uniquement.
Comment y accéder :
/memory → Shows AutoDream status and toggle
La commande /dream est référencée dans l’interface mais retourne “Unknown skill: dream” sur la plupart des installations (issues #38461, #38426 — correction suivie dans la PR #39299). Le déclenchement manuel via le langage naturel fonctionne à la place :
"dream"
"auto dream"
"consolidate my memory files"
Lacunes qualitatives connues (issue #38493, ouverte en mars 2026) :
Lacune
Problème
Exemple concret
Identité
Nomme les fichiers mémoire d’après le contenu de la session, pas le chemin du projet
Renommer my-old-project/ → fichiers orphelins non détectés
Exactitude
Écrit des faits non vérifiés sans lire les fichiers sources
”18 of 21 items resolved” écrit sans vérifier le fichier
Transparence
Aucune trace d’audit — impossible de voir ce qui a changé sans diff manuel
Doit comparer les dossiers avant/après pour comprendre une exécution
Correction proposée : un .dream-log.md par exécution listant les fichiers créés, modifiés, supprimés et les conflits résolus.
Quand Auto Dream est utile : Projets où la mémoire est écrite mais jamais curée manuellement — équipes de développement actives, projets de longue durée avec 50+ sessions, ou tout contexte où MEMORY.md dépasse 150 lignes sans nettoyage. Si vous gérez activement vos fichiers mémoire (élagage régulier, sauvegardes explicites), Auto Dream est largement redondant.
Implémentations communautaires : dream-skill (réplication open-source avec consolidation en 4 phases) et ai-dream (implémentation alternative documentant autoDreamEnabled).
Lorsque vous utilisez plusieurs outils IA (Claude Code, CodeRabbit, SonarQube, Copilot…), ils peuvent entrer en conflit si chacun dispose de conventions différentes. La solution : une source unique 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 — un gaspillage de cycles. 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/
Fonctionnement :
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 uniques
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 packages
-`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-packages
- Types partagés dans @acme/shared
- Tous les packages utilisent ESM
Exemple de CLAUDE.md pour un package :
# @acme/api
Backend Express + Prisma.
## Commands
-`pnpm dev` - Start with hot reload
-`pnpm db:migrate` - Run migrations
-`pnpm db:seed` - Seed test data
## Conventions
- Controllers in /routes
- Business logic in /services
- Prisma queries in /repositories
Sécurité en production : Pour les équipes qui déploient Claude Code en production, consultez les règles de sécurité en production 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 propres à chaque domaine se trouvent dans des fichiers .claude/rules/*.md, chargés automatiquement au démarrage de la session. Les compétences et flux de travail se trouvent dans .claude/skills/.
.claude/
├── CLAUDE.md # Index only — under 100 lines
├── rules/
│ ├── testing.md # Test conventions, coverage thresholds
│ └── api-conventions.md # API standards, naming rules
└── skills/
├── deploy.md # Deployment workflow
└── review.md # Code review process
Pourquoi cela 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 par 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/**
---
# Jupyter Conventions
Always include a markdown cell explaining the experiment goal before any code.
Never use global state between notebook cells.
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, en conservant les guillemets littéraux dans le glob. Utilisez globs: avec des motifs séparés par des virgules, sans guillemets. Ni guillemets, ni 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é) :
See .claude/rules/ for domain-specific conventions:
- testing.md — coverage minimums, test patterns
- security.md — auth rules, input validation
- api-conventions.md — REST naming, error format
## Critical constraints
- Never modify files in src/generated/ (auto-generated by Prisma)
- Always use pnpm, never npm or yarn
Cette séparation maintient l’index d’usage quotidien facilement 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 48 h suivant leur première utilisation de Claude Code (enquête SFEIR Institute). Le chargement conditionnel par chemin est une fonctionnalité officielle documentée dans la référence des paramètres Claude Code.
Problème : Sans contrôle de version, perdre sa configuration Claude Code représente des heures de reconfiguration manuelle entre agents, compétences, hooks et serveurs MCP.
Solution : Versionner sa configuration avec Git et des schémas .gitignore stratégiques pour les secrets.
Global (~/.claude/settings.json) : Appliqué à tous les projets sauf surcharge
Projet (.claude/settings.json) : Configuration partagée d’équipe, committée dans Git
Local (.claude/settings.local.json) : Surcharges spécifiques à la machine, dans le gitignore
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-machines : Valeurs par défaut globales dans ~/.claude/ synchronisées séparément
Note de compatibilité : Claude Code prend encore en charge ~/.claude.json pour la rétrocompatibilité, mais ~/.claude/settings.json est l’emplacement recommandé. Les flags CLI (par exemple --teammate-mode in-process) ont la 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. Create Git repo for global config
mkdir~/claude-config-backup
cd~/claude-config-backup
gitinit
# 2. Symlink directories (not files with secrets)
ln-s~/.claude/agents./agents
ln-s~/.claude/commands./commands
ln-s~/.claude/hooks./hooks
ln-s~/.claude/skills./skills
# 3. Copy settings template (without secrets)
cp~/.claude/settings.json./settings.template.json
# Manually replace secrets with ${VAR_NAME} placeholders
# 4. .gitignore for secrets
cat>.gitignore<<EOF
# Never commit these
.env
settings.json # Contains resolved secrets
mcp.json # Contains API keys
*.local.json
# Session history (large, personal)
projects/
EOF
# 5. Commit and push to private repo
gitadd.
gitcommit-m"Initial Claude Code global config backup"
Ce fichier configure les hooks, les permissions, les variables d’environnement, et bien plus encore. Le fichier .claude/settings.json au niveau du projet est versionné dans le dépôt (partagé avec l’équipe). Les clés disponibles sont : hooks, env, allowedTools, autoApproveTools, dangerouslyAllowedPatterns, teammates, teammateMode, apiKeyHelper, spinnerVerbs, spinnerTipsOverride, plansDirectory, enableAllProjectMcpServers.
Exemple de hooks (utilisation la plus courante 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 versionné) ou .claude/settings.json (partagé avec l’équipe). Aucune valeur fonctionnelle — pure personnalisation UX.
Lecture des chemins de fichiers correspondants (format qualifié par outil)
Edit(file_path:*.pem)
Modification des chemins de fichiers correspondants (format qualifié par outil)
Write(file_path:*.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, et pas seulement par nom d’outil :
{
"permissions": {
"deny": [
"Bash(command:*rm -rf*)",
"Bash(command:*terraform destroy*)",
"Read(file_path:*.env*)",
"Read(file_path:*.pem)",
"Read(file_path:*credentials*)",
"Edit(file_path:*.env*)",
"Edit(file_path:*.key)",
"Write(file_path:*.env*)",
"Write(file_path:*.key)"
]
}
}
Le préfixe file_path: effectue la correspondance sur l’argument de chemin complet passé à Read/Edit/Write. Utilisez des motifs glob (*, **). C’est plus précis que la forme simple (par ex. ".env") qui ne correspond qu’aux noms de fichiers exacts.
Défense en profondeur : permissions.deny présente une limitation connue — l’indexation en arrière-plan peut exposer le contenu de fichiers via des rappels système avant que les vérifications de permissions ne s’appliquent (GitHub #4160). Stockez les secrets en dehors du répertoire du projet pour une protection garantie.
Pour un contrôle précis 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 des valeurs true/false) offre un contrôle fin incluant des 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
N’importe quel 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 alarmants provenant de r/ClaudeAI incluent :
rm -rf node_modules suivi de rm -rf . (erreur de chemin)
git push --force sur main de manière non intentionnelle
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 la désactivation totale des permissions.
Alternative sécurisée : 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 sans danger. Consultez le Guide d’isolation en sandbox pour les instructions de configuration et les alternatives.
Comprendre à quel moment chaque méthode de mémorisation se charge est essentiel pour optimiser la consommation de tokens :
Méthode
Moment du chargement
Coût en tokens
Cas d’usage
CLAUDE.md
Démarrage de session
Toujours
Contexte central du projet
.claude/rules/*.md
Démarrage de session (TOUS les fichiers)
Toujours
Conventions s’appliquant en permanence
@path/to/file.md
À la demande (lors de la référence)
Uniquement à l’utilisation
Contexte optionnel/conditionnel
.claude/commands/*.md
À l’invocation uniquement
Uniquement à l’invocation
Modèles de flux de travail
.claude/skills/*.md
À l’invocation uniquement
Uniquement à l’invocation
Modules de connaissances métier
Point clé : .claude/rules/ ne fonctionne PAS à la demande. Chaque fichier .md de ce répertoire est chargé au démarrage de la session, consommant des tokens. Réservez-le aux conventions toujours pertinentes, pas aux directives rarement utilisées. Les skills ne sont invoqués qu’à la demande et peuvent ne pas être déclenchés 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 les rules à la place.
Depuis décembre 2025, les règles peuvent cibler des chemins de fichiers spécifiques via un frontmatter YAML :
---
globs: 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 tableau paths: échoue silencieusement. Le champ paths: documenté avec un tableau YAML est défaillant en raison d’un bug dans l’analyseur CSV interne (_9A() reçoit un tableau JS et itère sur les caractères de la valeur stringifiée au lieu des 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 problème est confirmé via l’issue GitHub #17204 et 8 rapports en doublon. La solution de contournement consiste à utiliser globs: avec des patterns non cités, 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 délimités par chemin, rapportant des réponses plus précises et une maintenance plus aisée entre domaines. (Björn Jóhannsson)
Fonctionnement de la correspondance :
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 IA (CLAUDE.md, .cursorrules, AGENTS.md) se fragmentent entre les développeurs, les outils et les systèmes d’exploitation — chaque développeur finit avec une version légèrement différente, et personne ne sait laquelle est la « bonne ».
Solution : Assemblage de modules par profil — 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 tout le monde).
# 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’effectuer 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 identique : 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 les profils
Variation
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 une moyenne de ~22 tokens/ligne. 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 contenant des sections non pertinentes pour sa configuration.
Audit : Listez tout ce qui se trouve 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 fichier YAML par développeur, listant les modules dont il a besoin selon ses outils, son OS et son rôle.
Script : Écrivez un assembleur 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 pour les petites équipes.
CI : Ajoutez une tâche GitHub Actions quotidienne qui régénère toutes les sorties et exécute git diff --exit-code pour détecter les dérives.
Lorsque plusieurs développeurs utilisent Claude Code sur le même codebase, la génération 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 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 :
Oblige 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)
Évite que le « vibe coding » n’accumule silencieusement de la dette technique
Crée une trace documentaire des décisions architecturales
Application graduée — adaptez au niveau de maturité de votre équipe :
Niveau du développeur
Exigence de divulgation
Junior / en onboarding
Obligatoire — chaque bloc généré par IA
Intermédiaire
Recommandé — fonctionnalités non triviales
Senior
Optionnel — selon son propre jugement
Ce que ce n’est PAS :
Pas une interdiction de la génération IA
Pas un exercice de comptage de lignes
Pas un mécanisme de sanction
Anti-pattern : Sauter la divulgation pour aller plus vite. Le coût caché, c’est que les reviewers approuvent du code que personne ne comprend, ce qui se cumule sur des mois en zones opaques du codebase 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 d’équipe.
— Lenny’s Newsletter, 19 février 2026
1. Sous-financer les projets intentionnellement
Avoir un excellent ingénieur sur un gros problème — plutôt qu’une équipe complète — force une utilisation intensive de l’IA. La contrainte accélère la livraison au lieu de la ralentir. Le goulot d’étranglement passe du nombre de personnes à la qualité des prompts et des workflows.
2. Donner aux ingénieurs des tokens illimités en premier
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 lorsque personne ne surveille le compteur. Optimisez les coûts après qu’une idée réussie a prouvé sa valeur et a besoin de passer à l’échelle.
3. Encourager les gens à aller plus vite
L’instinct par défaut avec les outils IA est la prudence — réviser chaque sortie, remettre en question chaque suggestion. Le meilleur instinct : livrer, valider, itérer. Claude Code est conçu pour des cycles à haute vélocité, pas pour une délibération soigneuse.
Quand appliquer : Équipes de 2+ utilisant Claude Code professionnellement. Les développeurs solo devraient se concentrer sur les deux premiers principes (sous-financer = se traiter comme une équipe d’une personne avec l’effet de levier de l’IA ; tokens illimités = ne pas autocensurer ses expériences).
Aller plus loin : distribution de standards à l’échelle organisationnelle
La Profile-Based Module Assembly résout le problème de cohérence par développeur. Elle requiert toujours que votre équipe maintienne les modules manuellement et exécute l’assembleur. À 50+ développeurs répartis 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 à travers les outils IA (Claude Code, Cursor, Copilot, Windsurf). Le playbook peut également ingérer des connaissances issues 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.
Qu’est-ce qu’un Agent : Des personas IA spécialisées pour des tâches précises (à concevoir comme des « consultants experts »)
Quand en créer un :
✅ La tâche se répète souvent (revues de sécurité, conception d’API)
✅ Nécessite un domaine de connaissance spécialisé
✅ Requiert un comportement ou un ton cohérent
❌ Tâches ponctuelles (demandez directement à Claude)
Démarrage rapide :
Créer .claude/agents/my-agent.md
Ajouter le frontmatter YAML (name, description, tools, model)
Rédiger les instructions
Utiliser : @my-agent "task description"
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
Passez si : Toutes vos tâches sont ponctuelles et exploratoires
Temps de lecture : 20 minutes
Niveau : Semaine 1-2
Objectif : Créer des assistants IA spécialisés
Tous les champs officiels supportés par Claude Code (source) :
Champ
Requis
Description
name
✅
Identifiant en kebab-case
description
✅
Quand activer cet agent (utilisez “PROACTIVELY” pour l’invocation automatique)
model
❌
sonnet (défaut), opus, haiku, ou inherit
tools
❌
Outils autorisés (séparés par des virgules). Supporte la syntaxe Task(agent_type) pour restreindre les sous-agents instanciables
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 nom de serveur 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 (défaut : false)
isolation
❌
worktree pour exécuter dans un worktree git temporaire (nettoyé automatiquement si aucune modification)
color
❌
Couleur de sortie dans le CLI pour une distinction visuelle (ex. : green, magenta)
Portées de mémoire — choisissez selon la largeur d’application souhaitée de la connaissance :
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é
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 — dans §4.5 Mémoire des Agents.
Compatibilité de version mentionnée si dépendant d’un framework
💡 Règle des trois : Si un agent n’économise pas un temps significatif sur au moins 3 tâches récurrentes, c’est probablement du sur-engineering. Commencez avec des skills, passez aux agents uniquement quand la complexité l’exige.
Audit automatisé : Exécutez /audit-agents-skills pour un audit qualité complet sur tous les agents, skills et commandes. Chaque fichier est noté selon 16 critères avec une notation pondérée (32 points pour les agents et skills, 20 pour les commandes). Voir 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. C’est utile pour les tâches en mode « fire-and-forget » comme l’exécution de tests, le linting ou les notifications.
Mode
Comportement
Utiliser quand
Défaut
Le parent attend la sortie de l’agent
Le résultat est nécessaire avant de continuer
Arrière-plan
L’agent tourne en parallèle, le parent continue
Fire-and-forget (tests, linting, notifications)
Gérer les agents en arrière-plan :
Terminal window
# Lister les agents en cours + overlay de suppression
ctrl+f# Opens agent manager overlay
# Annuler uniquement le thread 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 d’une session à l’autre. Auparavant, chaque invocation d’agent démarrait sur une page blanche, quelles que soient les 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 patterns de retour anticipé aux 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’est arrêtée.
Cela se distingue des autres systèmes de mémoire de Claude Code. Chacun remplit un rôle différent :
Système
Écrit par
Lu par
Portée
Persistance
CLAUDE.md
Vous (manuellement)
Claude principal + tous les agents
Projet ou global
Suivi par Git
Auto-memory
Claude principal (automatique)
Claude principal uniquement
Par projet et par utilisateur
Ignoré par Git
Mémoire agent
L’agent lui-même
Cet agent spécifique uniquement
Configurable
Dépend de 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 en fonction de l’endroit où la connaissance est utile :
Portée
Emplacement de stockage
Versionné
Idéal pour
user
~/.claude/agent-memory/<agent-name>/
Non
Apprentissage multi-projet — un réviseur de code qui accumule des connaissances sur les patterns dans chaque dépôt
project
.claude/agent-memory/<agent-name>/
Oui (commité)
Connaissances spécifiques au projet que toute l’équipe devrait partager — ex. : 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), ce qui rend le modèle mental cohérent dans l’ensemble du 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 prompt système de l’agent. Ce processus est automatique — aucun appel d’outil explicite n’est nécessaire.
~/.claude/agent-memory/code-reviewer/
├── MEMORY.md ← First 200 lines injected at startup
├── react-patterns.md ← Topic-specific file, loaded on demand
└── security-checklist.md ← Topic-specific file, loaded on demand
Lorsque MEMORY.md dépasse 200 lignes, l’agent doit 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 dont memory est défini.
Implication pratique : structurez MEMORY.md comme un résumé intelligent, non comme 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 prompt 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 — les skills pour les connaissances statiques au démarrage, la mémoire pour les connaissances dynamiques accumulées — donne aux agents le meilleur des deux mondes. Les skills injectent du matériel de référence soigneusement sélectionné à la première exécution ; la mémoire conserve ce que l’agent découvre par lui-même.
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 de sévérité : 🔴 À Corriger (bloquants) / 🟡 Devrait Corriger (améliorations) / 🟢 Peut Ignorer (agréables à avoir)
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
Protections 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)
Contrôles qualité : validation tsc && lint avant chaque itération
Source : Revue Finale de Pat CullenImplémentation : Voir la 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 une mauvaise raison d’utiliser des agents (voir §3.x, Quand NE PAS utiliser les agents). Les Agents à Perspective Nommée sont un pattern différent qui ne doit pas être confondu avec cela.
La distinction :
Pattern
Ce que c’est
Problème
Jeu de rôle de 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
« Fais la revue du point de vue 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 condensé. Nommer un agent « DHH » regroupe sans avoir à l’énoncer : fat models, thin controllers, conventions REST over configuration, scepticisme vis-à-vis de l’abstraction prématurée, pragmatisme Rails. Le nom est un raccourci vers un style opinionné distinct, pas un costume.
Quand ça fonctionne : Uniquement pour les ingénieurs dont les vues ont été apprises par Claude et dont les opinions correspondent à un style stable et reconnaissable. DHH (Rails), Kent Beck (TDD, simplicité), Martin Fowler (refactorisation, patterns) sont de bons candidats. Les noms inconnus 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 évidence d’une perspective cohérente qui pourrait être en désaccord avec votre approche par défaut, pas 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 compétences 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 compétences préchargées 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 ses propres connaissances de mise en page/poids à jour :
---
name: presentation-curator
description: PROACTIVELY use when updating slides, structure, or weights
Chaque exécution ajoute des découvertes ici. Les invocations futures démarrent informées.
Les badges de diapositives sont injectés par 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, l'invocation suivante 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 entre les sessions
- Associer avec `memory: project` pour la persistance inter-sessions du contexte global
---
# 5. Skills
_Accès rapide :_ [Deux types de Skills](/guide/ultimate-guide/05-skills/#50-two-kinds-of-skills) · [Comprendre les Skills](/guide/ultimate-guide/05-skills/#51-understanding-skills) · [Créer des Skills](/guide/ultimate-guide/05-skills/#52-creating-skills) · [Cycle de vie des Skills](#5x-skill-lifecycle--retirement) · [Évaluations des Skills](/guide/ultimate-guide/05-skills/#5y-skill-evals) · [Modèle de Skill](/guide/ultimate-guide/05-skills/#53-skill-template) · [Exemples de Skills](/guide/ultimate-guide/05-skills/#54-skill-examples)
---
> **Note (janvier 2026)** : Skills et Commands sont en cours d'unification. Les deux utilisent désormais le même mécanisme d'invocation (`/skill-name` ou `/command-name`), partagent la syntaxe YAML frontmatter, et peuvent être déclenchés de manière identique. La distinction conceptuelle (skills = modules de connaissances, commands = modèles de workflow) reste utile pour l'organisation, mais techniquement ils convergent. Créez de nouveaux éléments selon leur finalité, pas leur mécanisme.
---
**Temps de lecture** : 20 minutes
**Niveau** : Semaine 2
**Objectif** : Créer, tester et gérer des modules de connaissances réutilisables
## 5.0 Deux types de Skills
> **Nouveau en mars 2026** : La mise à jour Skill Creator d'Anthropic formalise une taxonomie qui change la façon de concevoir, tester et éventuellement retirer les skills. Sources : ainews.com, mexc.co, claudecode.jp — pas encore reflétées dans le `llms-full.txt` officiel.
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.
| | Capability Uplift | Encoded Preference |
|---|---|---|
| **Ce que ça fait** | Comble une lacune que le modèle de base ne gère pas de façon fiable | 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 contrôle pour révision NDA, workflow de compte-rendu 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 ? |
**Capability Uplift** enseigne à Claude quelque chose qu'il ne sait genuinement pas bien faire seul — pour l'instant. Très utile aujourd'hui, mais génère une dette de maintenance : à mesure que Claude s'améliore, ces skills peuvent devenir redondants. Les évaluations vous l'indiquent avant que les utilisateurs ne s'en aperçoivent.
**Encoded Preference** 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 compétition avec les améliorations du modèle — ils capturent des décisions de workflow qui vous appartiennent, et restent pertinents tant que votre processus l'est.
> **Implication pratique** : En construisant un skill Capability Uplift, prévoyez du temps pour les évaluations. En construisant un skill Encoded Preference, prévoyez du temps pour maintenir la description du workflow à jour au fil de l'évolution de votre processus.
## 5.1 Comprendre les Skills
Les skills sont des packages de connaissances dont les agents peuvent hériter.
### Skills vs Agents vs Commands
| Concept | Finalité | Invocation |
|---------|---------|------------|
| **Agent** | Outil d'isolation du contexte | Délégation via l'outil Task |
| **Skill** | Module de connaissances | `/skill-name` ou chargement automatique |
| **Command** | Workflow de processus | Slash command |
#### Comparaison détaillée
| Aspect | Commands | Skills | Agents |
|--------|----------|--------|--------|
| **Nature** | Modèle de prompt | Module de connaissances | Outil d'isolation du contexte |
Est-ce un workflow répétable avec des étapes ?
├─ Oui → Utiliser une COMMAND
│ Exemple : /commit, /release-notes, /ship
│
└─ Non → Est-ce une connaissance spécialisée dont plusieurs agents ont besoin ?
├─ Oui → Utiliser un SKILL
│ Exemple : méthodologie TDD, checklist sécurité
│
└─ Non → Le contexte doit-il être isolé ou le travail parallélisé ?
├─ Oui → Utiliser un AGENT
│ Exemple : code-reviewer, performance-auditor
│
└─ Non → L’écrire directement dans CLAUDE.md comme instructions
> **La règle des 20 %** : si une instruction s'applique à plus de 20 % de vos conversations, mettez-la dans `CLAUDE.md` (toujours chargé). Si elle s'applique à moins de 20 %, faites-en un skill (chargé à la demande). La différence est importante pour l'efficacité en tokens : le system prompt d'un skill n'est injecté que lorsque Claude l'invoque, tandis que le contenu de CLAUDE.md compte dans la fenêtre de contexte de chaque requête.
> **Voir aussi** : [§2.7 Guide de décision de configuration](#27-configuration-decision-guide) pour un arbre de décision plus large couvrant les sept mécanismes (y compris Hooks, MCP, et CLAUDE.md vs rules). Pour automatiser la détection de ce qui appartient à chaque catégorie, utilisez [`cc-sessions discover`](#session-pattern-discovery) — cet outil applique ce seuil de 20 % à l'historique réel de vos sessions.
#### Patterns courants
| Besoin | Solution | Exemple |
|------|----------|---------|
| Lancer les tests avant un commit | Command | `/commit` avec étape de test |
| Connaissances en revue de sécurité | Skill + Agent | skill security-guardian → agent security-audit |
| Revue de code en parallèle | Plusieurs agents à périmètre limité | Lancer 3 agents de revue avec des périmètres isolés |
| Workflow git rapide | Command | `/pr`, `/ship` |
| Connaissances en architecture | Skill | skill architecture-patterns |
Agent A : possède des connaissances sécurité (dupliqué)
Agent B : possède des connaissances sécurité (dupliqué)
Agent C : possède des connaissances sécurité (dupliqué)
Avec skills :
skill security-guardian : source unique des connaissances sécurité
Agent A : hérite de security-guardian
Agent B : hérite de security-guardian
Agent C : hérite de security-guardian
### Qu'est-ce qu'un bon Skill ?
| Bon Skill | Mauvais Skill | Durée de vie estimée |
|------------|-----------|-------------------|
| Réutilisable entre agents | Spécifique à un seul agent | — |
| Centré sur un domaine | Trop généraliste | — |
| Contient du matériel de référence | Seulement des instructions | — |
| Inclut des checklists | Vérification absente | — |
| Évaluations définies | Validation du type « ça semble marcher » | Capability Uplift : surveiller régulièrement ; Encoded Preference : stable |
| Critères de retrait clairs | Pas de plan de cycle de vie | Capability Uplift : court à moyen terme ; Encoded Preference : long terme |
## 5.2 Créer des Skills
Les skills résident dans des répertoires `.claude/skills/{skill-name}/`.
low|medium|high — remplace le niveau d’effort de la session lorsque ce skill est invoqué. Utiliser low pour les tâches mécaniques (commit, format, scaffold), high pour l’analyse ou le raisonnement architectural.
argument-hint
CC uniquement
Texte indicatif affiché dans le menu slash command lorsque le skill accepte $ARGUMENTS. Format : "[--flag] [positional_arg]". Exemple : "[--verbose] [--max N] <branch>".
disable-model-invocation
CC uniquement
true pour rendre le skill manuel uniquement (workflow avec effets de bord)
effort par skill (v2.1.80+) — remplace le niveau d’effort de la session pour l’invocation d’un 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 haute intensité, 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 : 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 en profondeur sans que l’utilisateur doive ajuster manuellement le paramètre de session. Cela permet une allocation automatique du budget cognitif par type de tâche : ne payer le coût du raisonnement que là où il apporte de la valeur.
Scoping par joker de allowed-tools — limiter un skill à des espaces de noms de commandes spécifiques plutôt qu’ouvrir un accès Bash complet :
# Limiter à un outil CLI spécifique uniquement — aucune autre commande Bash autorisée
allowed-tools: Bash(agent-browser:*)
# Limiter aux scripts npm uniquement
allowed-tools: Bash(npm run *)
# Lecture seule + écritures ciblées
allowed-tools: Read Grep Glob Edit(/docs/**)
C’est plus sécurisé que d’accorder un accès Bash large : le skill ne peut exécuter que des commandes correspondant au pattern. Idéal pour les skills encapsulant un outil CLI spécifique.
Standard ouvert : Agent Skills suit la spécification agentskills.io, créée par Anthropic et supportée par plus de 30 plateformes (Cursor, VS Code, GitHub, Codex, Gemini CLI, Goose, Roo Code, etc.). Les skills que vous créez pour Claude Code sont portables. Le champ disable-model-invocation est une extension propre à Claude Code.
Utilisez le CLI officiel skills-ref pour valider votre skill avant de le publier :
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'agent
Au-delà de la validation de spec : Deux outils d’audit complémentaires :
/audit-agents-skills — audit qualité global des agents, skills ET commands (16 critères, notation pondérée sur 32 points). À utiliser pour une évaluation générale de la préparation à la production.
/eval-skills — audit dédié aux skills avec moteur d’inférence du 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 patches 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/.
Avant de publier ou de committer un skill, parcourez cette checklist de contenu. /audit-agents-skills évalue le frontmatter et la structure ; cette checklist couvre la couche contenu que les outils automatisés ne peuvent pas détecter.
Checklist (critères de compound-engineering d’Every.to, adaptés) :
Frontmatter complet : name, description, allowed-tools tous présents et exacts
Section “Quand appliquer” : indique 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 des paragraphes libres
Aucun TODO ni placeholder : chaque section est complète et actionnable
allowed-tools limités au minimum : si le skill ne fait que lire 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 dispatche vers 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
Un skill qui passe ces 9 critères est prêt pour une utilisation en production ou pour être partagé via le registre agentskills.io.
Les skills ont un cycle de vie. Les traiter comme des artefacts permanents entraîne une dégradation progressive : du code mort dans .claude/skills/ qui consomme des tokens sans apporter de valeur.
Deux patterns déterminent quand agir :
CATCH REGRESSIONS SPOT OUTGROWTH
───────────────── ──────────────
Model Evolves Model Improves
↓ ↓
Skill Drifts Skill Passes Alone
↓ (without help)
Eval Alerts ↓
(early signal) Skill Retired
↓ (no longer needed)
Fix or Retire
Catch Regressions : 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 la défaillance n’atteigne qui que ce soit.
Spot Outgrowth : vous avez créé un skill Capability Uplift pour couvrir une lacune. Six mois plus tard, Claude gère cette lacune nativement. Exécutez 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.
Les skill evals font passer la qualité de « semble fonctionner » à « fonctionne avec certitude ». C’est la couche de test qui rend les skills prêts pour la production.
Disponible via : plugin Skill Creator (Anthropic GitHub) pour les utilisateurs de Claude Code. En ligne sur Claude.ai et Cowork depuis mars 2026. Sources : ainews.com, mexc.co — pas encore dans le llms-full.txt officiel.
Vous définissez trois éléments : des prompts de test (entrées réalistes qui déclenchent le skill), des sorties attendues (description de ce que « bon » signifie — sans correspondance exacte de chaîne), et un seuil de taux de réussite. Claude exécute le skill sur chaque cas de test et juge la sortie.
Les résultats indiquent : le taux de réussite, le temps écoulé, et l’utilisation de tokens par cas de test.
Benchmark Mode — suit les taux de réussite, le temps écoulé et l’utilisation de tokens lors des mises à jour du modèle. Exécute les tests en parallèle avec des contextes propres et isolés (sans contamination croisée entre les cas). Utilisez-le pour détecter automatiquement les régressions lors des mises à jour de Claude.
A/B Testing (Comparator Agents) — comparaison en aveugle entre deux versions d’un skill. Version A contre Version B, jugées sans savoir laquelle est laquelle. Élimine le biais de confirmation dans les décisions d’amélioration des skills.
Trigger Tuning (Description Optimizer) — analyse le champ description de votre skill et suggère des améliorations pour réduire les faux positifs (le skill se déclenche quand il ne devrait pas) et les faux négatifs (le skill ne se déclenche pas quand il le devrait). Test interne d’Anthropic : 5 skills de création de documents sur 6 ont montré une meilleure précision de déclenchement après optimisation. [Source : claudecode.jp — indicatif, non vérifié indépendamment]
Objectif : Détecter, analyser et suggérer des patrons de conception du Gang of Four dans des bases de code TypeScript/JavaScript, avec des recommandations adaptées à la stack.
Avant d’explorer des dépôts spécifiques, Context7 propose un outil CLI complémentaire (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 des 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
Flux 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 saisie manuelle de 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 de saisir claude mcp add manuellement. 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 de skill (pris en charge 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 manière identique aux skills installés manuellement.
Génération de skills (authentifiée, soumise à limite de débit) :
10/week
npxctx7skillsgenerate# AI-generated custom skill
La génération est à réserver aux skills sans équivalent dans le registre. Pour l’onboarding d’équipe à grande échelle, le flux 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 ligne de commande de ce que fait le serveur MCP Context7. Utile pour consulter de la documentation 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 le gère 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 de pénétration.
Note : Ces skills de 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 de les utiliser dans des évaluations de sécurité en production
Vérifier que vous disposez des autorisations appropriées avant tout test de pénétration
Examiner et valider les techniques par rapport aux politiques de sécurité de votre organisation
N’utiliser que dans des contextes légaux avec l’autorisation écrite des propriétaires des systèmes
Contribuer en retour si vous trouvez des problèmes ou des améliorations
Les skills semblent suivre des directives appropriées de hacking éthique et incluent les prérequis légaux nécessaires, mais comme pour tout outil de sécurité, la vérification est essentielle.
Si vous créez des skills spécialisés pour d’autres domaines (DevOps, science des données, ML/IA, etc.), envisagez de les partager avec la communauté via des dépôts similaires ou des pull requests vers des collections existantes.
Contrairement aux dépôts de skills traditionnels, Claudeception est un meta-skill qui génère de nouveaux skills pendant les sessions Claude Code. Il répond à une limitation fondamentale : « À chaque utilisation d’un agent de codage IA, il repart de zéro. »
Un utilisateur a rapporté que Claudeception avait 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 pattern skill qui crée des skills — une approche méta où Claude Code s’améliore lui-même grâce à l’apprentissage par session. 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
Là où Claudeception crée de nouveaux skills à partir de patterns découverts, Claude Reflect System améliore automatiquement les skills existants en analysant les retours de Claude et les corrections détectées pendant les sessions.
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 le problème manuellement.
Reflect System détecte :
Claude a corrigé un pattern non couvert par le skill
La correction a été vérifiée (les tests ont réussi)
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
Examiner toutes les propositions HIGH confidence, rejeter les modifications suspectes
Empoisonnement de la mémoire
Les modifications malveillantes des patterns appris s’accumulent
Sauvegardes Git, validation syntaxique
Auditer périodiquement l’historique des skills via le log Git
Injection de prompt
Instructions intégrées dans les transcriptions de session
Assainissement des entrées, isolation des propositions
Ne jamais approuver des propositions contenant des commandes exécutables
Prolifération des skills
Croissance non maîtrisée sans curation
Mode manuel /reflect [skill], curation régulière
Archiver ou fusionner 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 les interfaces génériques produites par l’IA par des systèmes de design professionnels et adaptés au secteur d’activité.
Le moteur fonctionne hors ligne — il exécute une recherche BM25 sur environ 400 règles JSON locales pour recommander des styles, palettes et typographies. Aucun appel à un LLM externe, aucune dépendance réseau à l’exécution.
Le générateur de système de design (v2.0+) analyse le type de votre produit et génère en quelques secondes un système de design complet et personnalisé :
Terminal window
# Generate design system for a SaaS dashboard project
Multi-plateforme — prend en charge Cursor, Windsurf, Copilot, Gemini CLI et 10 autres aux côtés de Claude Code
Signal de qualité
33,7k stars, 3,3k forks en 3 mois — la meilleure traction communautaire de tout skill de design
Maintenance
Active — v2.0→v2.2.1 en 10 jours (jan. 2026), mise à jour régulièrement
Communauté chinoise
Forte adoption : référencé sur jimmysong.io, dépôts de référence dans l’écosystème de développement chinois
Note de sécurité : npm install -g uipro-cli installe un package depuis une organisation anonyme (« nextlevelbuilder ») de manière globale. Un audit des sources (fév. 2026) a confirmé :
Aucun script preinstall/postinstall dans le package npm
Aucun appel réseau dans le moteur Python (search.py, core.py, design_system.py — stdlib + CSV/JSON locaux uniquement)
L’option 3 (clone git manuel) reste la voie la plus sûre si vous souhaitez inspecter avant d’installer. Le package n’a pas fait l’objet d’un audit formel par Anthropic ni par les mainteneurs de ce guide.
Skills.sh (Vercel Labs) fournit un marketplace centralisé pour découvrir et installer des skills d’agents avec une installation en une seule commande :
Terminal window
npxadd-skillvercel-labs/agent-skills# React/Next.js best practices (35K+ installs)
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 60 000+ skills :
Partenaire
Méthode
Performance
Socket
Analyse statique multi-écosystème + réduction du bruit par LLM (curl|sh, obfuscation, exfiltration, dépendances suspectes)
95 % de précision, 97 % 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
Continue
Niveaux de risque affichés sur chaque page de skill et présentés avant l’installation via skills@1.4.0+ :
Évaluation
Signification
✅ Sûr
Vérifié selon les bonnes pratiques de sécurité
🟡 Risque faible
Indicateurs de risque mineurs détectés
🔴 Risque élevé
Préoccupations de sécurité significatives
☠️ Critique
Comportement grave ou malveillant — masqué dans les recherches
Surveillance continue : les skills sont réévaluées au fur et à mesure que la détection s’améliore. Si un dépôt devient malveillant après l’installation, son évaluation se met à jour automatiquement.
Modèle mental : traitez une skill comme une image Docker — c’est une dépendance exécutable, pas un prompt. Vérifiez l’évaluation avant de l’installer en production.
Statut : Lancé le 21 jan. 2026, audité en sécurité depuis le 17 fév. 2026 (Socket + Snyk + Gen)
Gouvernance : Projet communautaire par Vercel Labs (non officiel Anthropic). Skills contribuées par Vercel, Anthropic, Supabase et des membres de la communauté.
✅ Installation en une commande (vs clonage manuel depuis GitHub)
✅ Format 100 % compatible avec ce guide
✅ 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 que ~56 % du temps (Gao, 2026). Pour les instructions critiques, préférez le CLAUDE.md toujours chargé
Note (janvier 2026) : Les skills et les commandes sont en cours d’unification. Les deux utilisent désormais le même mécanisme d’invocation (/skill-name ou /command-name), partagent la syntaxe frontmatter YAML, et peuvent être déclenchés de manière identique. La distinction conceptuelle (skills = modules de connaissance, commandes = modèles de workflow) reste utile pour l’organisation, mais techniquement ils convergent. Créez-en de nouveaux selon leur finalité, pas leur mécanisme.
Temps de lecture : 10 minutes
Niveau : Semaine 1-2
Objectif : Créer des slash commands personnalisées
/btw vous permet de poser une question rapide en parallèle 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 sans interruption.
Fonctionnement : Claude instancie un agent éphémère temporaire sans AUCUN outil disponible. Il ne peut pas lire des fichiers, exécuter des commandes, ni effectuer d’actions. Il répond une seule fois en se basant uniquement sur le contexte de la conversation en cours, 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éponses basées sur ce qui est déjà dans la conversation, pas depuis le disque
« Connaissance du contexte complet » signifie le contexte de conversation, pas les fichiers du projet
Quand l’utiliser :
Clarification rapide en pleine tâche (« btw what’s the default port for Postgres? »)
Vérification de terminologie sans interrompre le travail
Vérification d’une 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 route vers l’agent de superposition éphémère.
Note : Cette fonctionnalité (btw-side-question) a été introduite aux alentours de 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 dans 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, remplaçant /fork (qui fonctionne toujours comme alias).
Quand bifurquer plutôt que redémarrer :
Vous êtes dans un état fonctionnel et souhaitez explorer un refactoring risqué sans le perdre
Vous voulez essayer deux approches différentes du même problème en parallèle
Vous avez trouvé un bon point de contrôle en milieu de session et souhaitez bifurquer 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 plus tard 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.
/insights analyse votre historique d’utilisation de Claude Code pour générer un rapport complet identifiant les patterns, les points de friction et les opportunités d’optimisation.
La commande traite vos données de session pour détecter :
Domaines du projet : Regroupe automatiquement votre travail en zones thématiques (ex. : « Développement Frontend », « Outillage CLI », « Documentation ») avec le nombre de sessions
Style d’interaction : Identifie vos patterns de workflow (piloté par plan, exploratoire, itératif, superviseur)
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 bugué, mauvais répertoires, perte de contexte, requêtes mal comprises)
Utilisation des outils : Suit quels outils vous utilisez le plus (Bash, Read, Edit, Grep, etc.) et identifie les opportunités d’optimisation
Comportement multi-clauding : Détecte les patterns de sessions parallèles (exécution simultanée de plusieurs instances de Claude)
Patterns temporels : Identifie vos fenêtres de productivité maximale et la distribution des temps de réponse
Moteur d’analyse : Utilise Claude Haiku (rapide, rentable)
Limite de sessions : Analyse jusqu’à 50 sessions récentes par exécution
Budget de tokens : Max 8192 tokens par passe d’analyse
Emplacement des données : ~/.claude/usage-data/ (sessions stockées en JSONL)
Confidentialité : Toute l’analyse s’exécute 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 (vue d’ensemble 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 : Utilisation de Claude Haiku pour classifier les sessions en catégories structurées
Analyse agrégée : Détection des schémas inter-sessions et des flux de travail récurrents
Résumé exécutif : Génération d’une synthèse “En un coup d’œil” selon quatre dimensions
Génération du rapport : Rendu d’un HTML interactif avec visualisations et sections narratives
Mise en cache des facettes : Sauvegarde des classifications dans ~/.claude/usage-data/facets/<session-id>.json pour des exécutions ultérieures rapides
Système de classification des facettes :
Le système catégorise les sessions selon ces dimensions :
Catégories de succès (7) :
Fast accurate search, Correct code edits, Good explanations, Proactive help, Multi-file changes, Good debugging, None
Types de session (5) :
Single task, Multi-task, Iterative refinement, Exploration, Quick question
Comprendre ces catégories aide à interpréter votre rapport :
Friction “Buggy code” élevée → Envisager la mise en place de pre-commit hooks (voir la fonctionnalité hooks)
Faible satisfaction sur les objectifs “Implement Feature” → Améliorer la précision de la phase de planification
Schéma “Early user stoppage” → 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 ultérieures n’analysent que les nouvelles sessions (et non celles déjà classifiées), rendant les exécutions mensuelles régulières rapides même avec un historique de sessions volumineux.
Ajoutée en 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, et non au niveau du formateur ou du linter. /simplify complète des outils comme ESLint ou Prettier plutôt que de les remplacer.
Ajoutée en v2.1.63, /batch orchestre des changements à grande échelle sur une base de code en distribuant le travail entre 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 avec worktrees parallèles (voir §15). Utilisez-la pour les changements volumineux, répétitifs et au niveau des fichiers, pouvant être divisés en unités indépendantes : migrations, refactorisations, annotations de types en masse, remplacement de dépendances.
Note : /simplify et /batch sont toutes deux des slash commands intégrées livrées avec Claude Code v2.1.63+. Aucune configuration requise.
/loop [interval] [prompt] exécute un prompt ou une slash command à intervalle régulier — jusqu’à ce que vous l’arrêtiez. Transformez n’importe quelle vérification répétitive ou flux de travail en tâche automatisée en arrière-plan.
Terminal window
/loop5mcheckthedeploy
/loop30m/slack-feedback
/loop1h/pr-pruner
Fonctionnement : Claude exécute le prompt, attend l’intervalle, exécute à nouveau, et ainsi de suite. Chaque exécution est horodatée dans le transcript. Vous pouvez référencer une slash command (comme /loop 30m /review-pr) ou écrire un prompt en texte libre directement.
Cas d’usage de Boris Cherny (créateur de Claude Code) :
Boucle
Ce qu’elle fait
/loop 5m /babysit
Gestion automatique de la revue de code, rebase, avancement des PR
/loop 30m /slack-feedback
Publication des PR pour retour d’équipe toutes les 30 min
/loop 1h /pr-pruner
Nettoyage des PR obsolètes selon un planning
Arrêter une boucle : Appuyez sur Ctrl+C ou envoyez un nouveau message.
Ajoutée en v2.1.71. Les marqueurs d’horodatage dans les transcripts de boucle ont été ajoutés en v2.1.86.
Vous avez reçu les arguments suivants : $ARGUMENTS[0] $ARGUMENTS[1] $ARGUMENTS[2]
(Ou en version 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 est passée de la notation pointée ($ARGUMENTS.0) à 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 en version 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]"
---
Deploy to $ARGUMENTS[0] environment.
Lorsque l’utilisateur tape /deploy, le menu affiche : /deploy <env> [--skip-tests] [--dry-run]
Les hooks n’ont pas à ê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 valables uniquement pour la durée 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 : lorsqu’un skill est invoqué, il peut enregistrer un ou plusieurs hooks pour cette invocation sans modifier définitivement 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 je modifie pendant 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 des skills au moment de l’invocation.
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 en 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. Se configure avec url et optionnellement allowedEnvVars pour l’interpolation d’en-têtes.
prompt : Envoie le prompt et l’entrée du hook à un modèle Claude (Haiku par défaut) pour une évaluation en tour unique. Retourne {ok: true/false, reason: "..."}. Le modèle se configure via le champ model.
agent : Lance un sous-agent avec accès aux outils (Read, Grep, Glob, etc.) pour une vérification en plusieurs tours. 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 jeton Bearer).
Le champ if filtre le déclenchement d’un hook en utilisant la même syntaxe de règle 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 d’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 if réduit la surcharge 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) s’y ajoutent.
Les hooks communiquent leurs résultats via des codes de sortie et optionnellement du JSON sur stdout. Choisissez une approche par hook : soit les codes de sortie seuls, soit exit 0 avec du JSON pour un contrôle structuré. Claude Code ne traite le JSON que sur exit 0 ; si votre hook se termine 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 arrête entièrement le traitement
stopReason
aucun
Message affiché à l’utilisateur quand continue est false
suppressOutput
false
Si true, masque stdout du mode verbose
systemMessage
aucun
Message d’avertissement affiché à l’utilisateur
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. Lorsque 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)
Exemple de blocage PreToolUse (préférable au code de sortie 2) :
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "Destructive command blocked by hook"
Lorsque 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" permet de satisfaire la question et de poursuivre l’exécution sans invites interactives.
Décision defer de 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. Lorsqu’un hook retourne permissionDecision: "defer", Claude se met en pause avec stop_reason: "tool_deferred" et attend. Le processus appelant peut alors collecter la saisie 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 maintenir le contexte de l’agent propre : les hooks doivent être silencieux en cas de succès et verbeux uniquement en cas d’échec.
# En cas de succès : complètement silencieux (rien n'entre dans le contexte de l'agent)
# En cas d'échec : faire remonter les erreurs + exit 2 pour solliciter 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) évite que les logs de build réussis, les sorties de tests et les rapports de lint s’accumulent comme du « bruit de contexte » lors de longues sessions. L’agent ne voit que ce qui nécessite une action.
Source : Motif 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, ne faire remonter que les erreurs.
Sous Windows, Claude Code peut utiliser PowerShell comme outil de premier niveau 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.
Activez-le dans ~/.claude/settings.json :
{
"tools": {
"powershell": {
"enabled": true
}
}
}
Une fois activé, Claude peut exécuter des commandes PowerShell directement (par exemple 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 disponible à partir de la v2.1.84. L’outil Bash reste disponible sous Windows via Git Bash ou WSL et reste privilégié 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 pour contourner 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.
Patterns avancés : Pour une sécurité complète incluant la détection d’injection Unicode, la vérification d’intégrité de la configuration MCP et les mitigations spécifiques aux CVE, voir le Guide de durcissement de la sécurité.
Sécurité Claude Code (aperçu de recherche) : Anthropic propose un scanner de vulnérabilités de base de code dédié qui trace les flux de données entre les fichiers, remet en question les résultats en interne avant de les présenter (validation contradictoire), et génère des suggestions de correctifs. Distinct du Security Auditor Agent mentionné plus haut — accès sur liste d’attente uniquement. Voir Guide de durcissement de la sécurité → Claude Code comme scanner de sécurité.
Validé à grande échelle : Dans le cadre d’un partenariat de mars 2026 avec Mozilla, Claude Opus 4.6 a analysé ~6 000 fichiers C++ du moteur JS de Firefox en deux semaines, faisant remonter 22 vulnérabilités confirmées (14 de haute sévérité) — soit environ un cinquième de toutes les CVE de haute sévérité de Firefox corrigées 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 linting de surface.
L’équipe Claude Code utilise un pattern dans lequel les demandes de permission sont acheminées vers un modèle plus capable servant de portail de sécurité, plutôt que de s’appuyer uniquement sur la correspondance de règles statiques.
Concept : Un hook PreToolUse intercepte les demandes de permission et les transmet à Opus 4.6 (ou à un autre modèle capable) via l’API. Le modèle portail recherche les injections de prompt, les patterns dangereux et les usages inattendus d’outils — puis approuve automatiquement les requêtes sûres ou bloque les suspectes.
# Acheminement vers Opus pour l'analyse de sécurité
VERDICT=$(echo"$INPUT"|claude--modelopus--print\
"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 portail : Les règles statiques détectent les patterns connus, mais ratent les 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 non sur la seule correspondance de patterns.
Compromis : Chaque appel filtré ajoute de la latence et du coût. Utilisez des exemptions en chemin rapide pour les outils en lecture seule et ne filtrez que les opérations d’écriture et d’exécution.
# Doit quitter avec le code 1 et afficher "Variable expansion detected"
Référence croisée : Pour un durcissement complet de la sécurité incluant les mitigations spécifiques aux CVE et l’intégrité de la configuration MCP, voir le Guide de durcissement de la sécurité.
Au lieu de configurer des dizaines de hooks individuels, utilisez un répartiteur unique qui achemine les événements intelligemment en fonction du type de fichier, de l’outil et du contexte.
Le problème : À mesure que votre collection de hooks s’agrandit, 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 répartit 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
**Le problème** : Lorsque Claude compacte le contexte durant 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, de sorte que la réponse suivante abandonne entièrement le rôle et commence à se comporter de manière 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 se produit après la compaction — il injecte le contenu du fichier d'identité en tant que `additionalContext`. La réponse suivante rétablit le rôle sans intervention humaine.
```bash
# .claude/agent-identity.txt
# Your agent's identity instructions — anything that should survive compaction
You are the feature team lead. You coordinate the team — you do not write code
Zéro surcharge lorsque le marqueur d’identité est présent (sort immédiatement à la correspondance)
Opération silencieuse si aucun fichier .claude/agent-identity.txt n’existe
Se déclenche automatiquement après la compaction — aucune intervention manuelle requise
Fonctionne aussi bien dans les 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 issue de la sortie standard de l’agent (par ex. "LEAD:", "DEVELOPER:", "🔨"). Si non définie, le hook utilise les 40 premiers caractères du fichier d’identité comme marqueur.
Temps de lecture : 5 minutes
Niveau : Configuration d’équipe
À mesure que votre collection de hooks s’étoffe, une tension apparaît : certains développeurs souhaitent une surcharge minimale (démarrage rapide, sans vérifications bloquantes), tandis que les membres soucieux de la sécurité ou les pipelines CI exigent une application stricte. Un seul settings.json ne peut pas satisfaire les deux.
Le pattern : conditionner chaque hook derrière 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 entre les conversations.
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
Intégration initiale
Analyse automatiquement la structure du projet au premier lancement
Outils :
Outil
Description
find_symbol
Trouver des fonctions, classes, méthodes par nom
get_symbols_overview
Obtenir une vue d’ensemble de la structure d’un fichier
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 localement via les embeddings Ollama (aucune préoccupation cloud/confidentialité), et offre une analyse du graphe d’appels — tracer qui appelle quelle fonction et visualiser 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 localement (pas de cloud)
Indexation en arrière-plan
Le démon grepai watch maintient l’index à jour
Exemple :
Terminal window
# Semantic search (finds code by meaning, not exact text)
grepaisearch"user authentication flow"
# Who calls this function?
grepaitracecallers"createSession"
# → Lists all 23 files that call createSession with context
# What does this function call?
grepaitracecallees"SessionProvider"
# Full dependency graph
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 toute 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.
Motif Blast-Radius (flux de travail pré-refactorisation) :
Avant de modifier toute fonction largement utilisée, lancez une requête de dépendances pour énumérer tous les sites d’appel affectés — puis décidez de la marche à suivre. Ce flux de travail nommé prévient les ruptures en cascade dans les grandes bases de code.
Terminal window
# Step 1: Map all callers before touching a function
grepaitracecallers"processPayment"
# → Returns: 14 call sites across 7 files
# Step 2: Check callees (what it depends on)
grepaitracecallees"processPayment"
# → Returns: 3 downstream dependencies
# Step 3: Decide scope before writing a single line
# 14 callers + 3 deps = significant blast radius → plan the refactor first
À exécuter avant de commencer toute refactorisation touchant une fonction utilisée dans 3 endroits ou plus — pas après avoir rencontré des erreurs de compilation.
Objectif : Mémoire persistante automatique entre les sessions Claude Code grâce à une capture compressée par IA de l’utilisation des outils et des observations.
Pourquoi claude-mem est important : Contrairement aux outils de mémoire manuels (le write_memory() de Serena), claude-mem capture automatiquement tout ce que Claude fait pendant les sessions et injecte intelligemment le contexte pertinent lors de la reconnexion. Cela résout le problème n°1 : la perte de contexte entre les sessions.
Fonctionnalités clés :
Fonctionnalité
Description
Capture automatique
S’accroche aux événements du cycle de vie SessionStart, PostToolUse, Stop, SessionEnd
Compression par IA
Utilise Claude pour générer des résumés sémantiques (~réduction de tokens x10)
Divulgation progressive
Récupération à 3 niveaux (recherche → chronologie → observations) économise ~95% de tokens
# claude-mem automatically activates on next session
Utilisation de base :
Une fois installé, claude-mem fonctionne automatiquement — aucune commande manuelle requise. Il capture toutes les opérations d’outils et injecte le contexte pertinent au démarrage de la session.
Skills disponibles (/claude-mem:*) :
Skill
Objectif
mem-search
Rechercher l’historique de session : “How did we solve the CORS issue?”
smart-explore
Exploration de la base de code basée sur l’AST (économe en tokens, évite les lectures complètes de fichiers)
make-plan
Crée un plan d’implémentation par phases avec découverte de documentation
do
Exécute un plan créé par make-plan via des sub-agents
timeline-report
Génère un récit “Journey Into [Project]” sur l’historique complet
Recherche en langage naturel (via le skill mem-search) :
Terminal window
# Search your session history
"Search my memory for authentication decisions"
"What files did we modify for the payment bug?"
"Remind me why we chose Zod over Yup"
Tableau de bord web :
Terminal window
# Access real-time UI
openhttp://localhost:37777
# Features:
# - Timeline view of all sessions
# - Natural language search
# - Observation details
# - Session statistics
Flux de travail à divulgation progressive :
claude-mem utilise une approche à 3 niveaux pour minimiser la consommation de tokens :
Layer 1: Search (50-100 tokens)
├─ "Find sessions about authentication"
├─ Returns: 5 relevant session summaries
│
Layer 2: Timeline (500-1000 tokens)
├─ "Show timeline for session abc123"
├─ Returns: Chronological observation list
│
Layer 3: Details (full context)
└─ "Get observation details for obs_456"
Returns: Complete tool call + result
Résultat : ~10x de réduction de tokens par rapport au chargement de l’historique de session complet.
Contrôles de confidentialité :
<!-- In your prompts -->
<private>
Database credentials: postgres://prod-db-123
API key: sk-1234567890abcdef
</private>
<!-- claude-mem excludes <private> content from storage -->
Avertissement de sécurité :
⚠️ GET /api/settings retourne vos clés API en clair. Tout processus s’exécutant sur votre machine (extension de navigateur avec accès localhost, paquet npm, autre outil CLI) peut lire cet endpoint sans authentification. Localhost n’est pas une frontière de sécurité.
Atténuation : Définir host: "127.0.0.1" (pas "0.0.0.0") dans votre configuration. Ne jamais exécuter sur une machine partagée ou exposer le port à votre réseau. Envisager d’utiliser l’authentification CLI (auth_method: cli) plutôt que de stocker les clés dans settings.json.
Coût mensuel typique : 5-15 $ pour les utilisateurs intensifs (100+ sessions/mois)
Optimisation des coûts — utiliser Gemini plutôt que Claude pour la compression :
Par défaut, claude-mem utilise Claude (Haiku) pour la résumisation par IA. Vous pouvez configurer Gemini 2.5 Flash Lite à la place pour des économies significatives :
Terminal window
# In ~/.claude-mem/settings.json
{
"provider":"gemini",
"model":"gemini-2.5-flash-lite",
"auth_method":"cli"
}
Modèle
Coût/mois (~400 sessions)
Qualité
Économies
Claude Haiku (défaut)
~102 $
Élevée
—
Gemini 2.5 Flash
~14 $
Bonne
-86%
Gemini 2.5 Flash Lite
~14 $
Correcte
-86%
Flash vs Flash Lite : Flash Lite est moins cher mais produit des compressions moins précises. Le contexte injecté au démarrage de la session sera moins précis. Pour la plupart des utilisateurs le compromis est acceptable ; pour des projets complexes sur plusieurs semaines, envisager Gemini 2.5 Flash (non-Lite) pour préserver la qualité de compression.
Si vous utilisez claude-mem à grande échelle, passer à Gemini est le changement de configuration avec le meilleur retour sur investissement.
Point critique d’installation — coexistence des hooks :
claude-mem ajoute des hooks sur SessionStart, PostToolUse, Stop et SessionEnd. Si vous avez déjà des hooks dans settings.json, claude-mem ne les fusionnera pas automatiquement — il écrasera les tableaux de hooks.
Avant l’installation :
Sauvegardez votre settings.json actuel
Notez tous les hooks existants (tableaux PostToolUse, UserPromptSubmit)
Après l’installation, vérifiez manuellement que les tableaux de hooks contiennent à la fois vos hooks existants ET les nouveaux hooks claude-mem
Si le processus worker de claude-mem est arrêté (crash, redémarrage, conflit de port), Claude Code continue à fonctionner normalement — il ne se bloque pas et ne génère pas d’erreur. Les sessions ne sont simplement pas capturées jusqu’au redémarrage du worker.
Terminal window
# Check worker status
openhttp://localhost:37777# dashboard — if unreachable, worker is down
# Restart worker manually if needed
npxclaude-mem@lateststart
Ce comportement fail-open rend claude-mem sûr à installer dans des flux de travail de production — un worker défaillant ne bloque jamais votre travail.
Limitations :
Limitation
Impact
Solution de contournement
CLI uniquement
Pas d’interface web, pas de VS Code
Utiliser Claude Code CLI exclusivement
Pas de synchronisation cloud
Impossible de synchroniser entre machines
Export/import manuel via claude-mem export
Licence AGPL-3.0
Restrictions commerciales, divulgation du code source
Vérifier la conformité de la licence pour usage commercial
Balises de confidentialité manuelles
Les données sensibles doivent être marquées explicitement
# → "auth_decision: Use JWT for stateless API (2026-02-07)"
serenaread_memory("auth_decision")
# 3. SEMANTIC DISCOVERY (grepai)
grepaisearch"JWT token validation"
# → Finds validateJWT() in auth.service.ts
# 4. DEPENDENCIES (grepai trace)
grepaitracecallers"validateJWT"
# → Called by: ApiGateway, AdminPanel, UserController
# 5. EXACT SEARCH (rg)
rg"validateJWT"--typets-A5
Résultat : Contexte complet sans relire tous les fichiers, décisions architecturales préservées, dépendances cartographiées → refactorisation sécurisée.
Objectif : Recherche sémantique en langage naturel dans le code, la documentation, les PDF et les images.
Pourquoi considérer mgrep : Si vous avez besoin d’une recherche multi-format (code + PDF + images) ou préférez une solution cloud, mgrep est une alternative à grepai. Leurs benchmarks montrent ~2x moins de tokens utilisés comparé aux flux de travail basés sur grep.
Fonctionnalités principales :
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 le code, les PDF, les images, le texte
Intégration web
Capacité de repli vers la recherche web
Exemple :
Terminal window
# Traditional grep (exact match required)
grep-r"authenticate.*user".
# mgrep (intent-based)
mgrep"code that handles user authentication"
Utiliser quand :
Besoin de rechercher dans du contenu mixte (code + PDF + images)
Préférence pour les embeddings cloud plutôt qu’une installation Ollama locale
L’analyse du graphe d’appels de grepai n’est pas nécessaire
Note : Je n’ai pas testé mgrep personnellement. Considérez-le comme une alternative qui mérite d’être explorée.
Source : mgrep GitHub
Objectif : Correspondance de motifs basée sur l’AST pour des recherches de code structurel précises.
Type : Plugin communautaire optionnel (pas un composant central de Claude Code)
Installation :
Terminal window
# Install ast-grep skill for Claude Code
npxskillsaddast-grep/agent-skill
# Or manually via plugin marketplace
/pluginmarketplaceadd
Qu’est-ce qu’ast-grep ?
ast-grep recherche le code en se basant sur la structure syntaxique (Abstract Syntax Tree) plutôt que sur du texte brut. Cela permet de trouver des motifs comme « les fonctions async sans gestion d’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 principales :
Aspect
Comportement
Invocation
Explicite — Claude ne peut pas détecter automatiquement 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 + autres
Les premières versions de Claude Code utilisaient le RAG avec les embeddings Voyage pour la recherche sémantique. Anthropic est passé à la recherche agentique basée sur grep (ripgrep) après que des benchmarks ont démontré des performances supérieures avec une complexité opérationnelle moindre (pas de synchronisation d’index, pas de risques de sécurité liés à l’indexation). Cette philosophie « Chercher, ne pas indexer » privilégie la simplicité.
ast-grep est une extension communautaire pour les recherches structurelles spécialisées où l’approche regex de grep n’est pas suffisante, mais ce n’est pas un remplacement de grep — c’est un outil chirurgical pour des cas d’usage spécifiques.
Statut : En développement actif — v0.15.0 (février 2026). Plus de 12 100 étoiles. Cycle de publication rapide.
Objectif : CLI de navigateur headless conçu pour les agents IA. Utilise Playwright/CDP en coulisses 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 flux de travail agentiques : Playwright MCP est verbeux — chaque instantané DOM ajoute des tokens. agent-browser ne renvoie 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
# Or npm
npminstall-g@vercel-labs/agent-browser
Capacités :
Fonctionnalité
Détails
Navigation et interaction
Clic, saisie, défilement, remplissage de formulaires
Arbre d’accessibilité
Instantanés optimisés pour les LLM (éléments exploitables uniquement)
Différences visuelles
Comparaison pixel par pixel avec les référentiels
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 blanches de domaines, politiques d’action
Streaming 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 principal
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’auth, listes blanches de domaines
Agents auto-vérifiants
Difficile
Motif natif
La boucle Ralph Wiggum — motif d’agent auto-vérifiant :
1. Agent codes the feature
2. Deploys (Vercel, any target)
3. agent-browser navigates to deployed URL autonomously
4. Tests scenarios, reads accessibility snapshots
5. On failure: agent reads output, fixes code, re-deploys
6. Loop until all scenarios pass — no human in the loop
Documenté en production chez Pulumi (2026-03-03) sur 6 scénarios de test d’une application réelle.
Utiliser quand :
L’agent doit vérifier ses propres sorties déployées (boucles auto-vérifiantes)
Le coût en tokens du contexte navigateur est une contrainte
Tests multi-sessions (instances de navigateur isolées en parallèle)
Régression visuelle dans les 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 protégés anti-bot — la détection IP/comportement reste inchangée (les services de type Browserbase restent nécessaires)
⚠️ Statut : En cours de test — Ce serveur MCP est en cours d’évaluation. La documentation ci-dessous est basée sur le dépôt officiel mais n’a pas encore été entièrement validée dans des flux de travail en production. Vos retours sont les bienvenus !
Objectif : Mémoire sémantique persistante avec recherche inter-sessions et support multi-clients.
Pourquoi doobidoo complète Serena :
Serena : Mémoire clé-valeur (write_memory("key", "value")) — nécessite de connaître la clé
doobidoo : Recherche sémantique (retrieve_memory("what did we decide about auth?")) — trouve par signification
Fonctionnalité
Serena
doobidoo
Stockage mémoire
Clé-valeur
Embeddings sémantiques
Recherche par signification
Non
Oui
Multi-clients
Claude uniquement
13+ applications
Tableau de bord
Non
Graphe de connaissances
Indexation des symboles
Oui
Non
Backends de stockage :
Backend
Usage
Performance
sqlite_vec (par défaut)
Local, léger
Requêtes <10ms
cloudflare
Cloud, synchronisation multi-appareils
Performance edge
hybrid
Local rapide + synchronisation cloud en arrière-plan
5ms local
Emplacement des données : ~/.mcp-memory-service/memories.db (SQLite avec embeddings vectoriels)
Outils MCP disponibles (12 outils unifiés) :
Outil
Description
store_memory
Stocker avec tags, type, métadonnées
retrieve_memory
Recherche sémantique (top-N par similarité)
search_by_tag
Correspondance exacte de tags (logique OU/ET)
delete_memory
Supprimer par content_hash
list_memories
Navigation paginée avec filtres
check_database_health
Statistiques, état du backend, infos de synchronisation
⚠️ Statut : En cours de test - Évalué en février 2026. Licence MIT, Python 100%. Retours bienvenus !
Objectif : Mémoire de projet à long terme organisée en graphe de connaissances avec décroissance automatique — les informations obsolètes expirent d’elles-mêmes, évitant la pollution du contexte.
Différenciateurs clés par rapport à doobidoo/Serena :
Relations typées : depends-on, resolves, causes — capture la causalité, pas seulement le contenu
Modèle de décroissance biologique : les solutions persistent ~200 jours, les contournements ~50 jours — élagage automatique sans appels à delete_memory
18 outils MCP : opérations sur le graphe, suivi de projet, gestion des expériences, couche intelligence (recherche plein texte, routage par confiance, patterns inter-espaces de travail)
Fonctionnalité
Serena
doobidoo
Kairn
Modèle de stockage
Clé-valeur
Embeddings sémantiques
Graphe de connaissances
Décroissance mémoire / expiration auto
Non
Non
Oui (biologique)
Relations typées
Non
Tags uniquement
depends-on / resolves / causes
Recherche plein texte
Non
Oui
Oui
Élagage automatique des infos obsolètes
Non
Non
Oui
Quand Kairn est pertinent :
Projets de longue durée où les contournements d’il y a des mois deviennent du bruit
Quand la causalité est importante : « ceci casse à cause de cela », « ce correctif résout ce bug »
Équipes souhaitant une hygiène automatique des connaissances sans nettoyage manuel
Configuration MCP :
"kairn": {
"command": "python",
"args": ["-m", "kairn", "serve"],
"description": "Knowledge graph memory with biological decay"
⚠️ Statut : En cours de test — Évalué en mars 2026. Licence Source-Available (gratuite pour les individus et équipes ≤20). De l’équipe rtk-ai (mêmes auteurs que RTK). Les benchmarks ci-dessous sont fournis par l’éditeur et non vérifiés indépendamment. Retours bienvenus !
Objectif : Mémoire persistante pour agents IA combinant décroissance épisodique (Memories) et graphe de connaissances permanent (Memoirs) dans un binaire Rust unique sans dépendances.
Quand préférer ICM à Kairn/doobidoo :
La gestion des dépendances Python est une source de friction (environnements CI, machines isolées)
Vous souhaitez une installation Homebrew sans configuration d’environnement Python
Vous avez besoin à la fois d’une mémoire épisodique avec décroissance et d’un graphe de connaissances permanent dans un seul outil
Vous utilisez plusieurs éditeurs (14 clients supportés : Claude Code, Cursor, VS Code, Windsurf, Zed, Amp, Cline, Roo Code, OpenAI Codex CLI, et d’autres)
Différenciateurs clés par rapport à Kairn/doobidoo :
Binaire Rust unique : pas de Python, pas de pip, pas d’environnement virtuel — brew install icm et c’est terminé
Architecture double en un seul outil : Memories (décroissance, épisodique) + Memoirs (permanent, graphe typé) — Kairn couvre la couche graphe, doobidoo la couche sémantique, ICM couvre les deux
Extraction automatique : capture automatique en trois couches (hooks de patterns, pré-compaction, démarrage de session) sans appels explicites à store_memory
Déduplication automatique : bloque les entrées avec >85% de similarité au contenu existant
Gains d’efficacité des agents (données fournisseur, modèle Haiku, non vérifiés indépendamment) :
Session 2 : 29% de tours en moins, 17% de réduction de coûts
Session 3 : 40% de tours en moins, 22% de réduction de coûts
⚠️ Note de licence : Gratuit pour les individus et équipes jusqu’à 20 personnes. Licence entreprise requise au-delà de ce seuil. Vérifiez la taille de votre organisation avant de déployer. Contact : license@rtk.ai
Objectif : Accès Git programmatique via 12 outils structurés pour la gestion des commits, diffs, logs et branches.
Pourquoi Git MCP plutôt que Bash git : L’outil Bash peut exécuter des commandes git mais retourne une sortie terminal brute qui nécessite du parsing 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 efficaces en tokens via le paramètre context_lines.
⚠️ Statut : Développement précoce — l’API est susceptible de changer. Adapté aux flux de travail locaux ; testez avant d’adopter en 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 à committer
git_diff
Comparer deux branches, commits ou références 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 par 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, indexation
Plateforme cloud GitHub
GitHub MCP Server
Issues, PRs, Projects, Reviews, Recherche
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é
PAT GitHub 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 l’enregistrement dynamique de client OAuth, que le point d’accès Copilot ne supporte pas. Vous obtiendrez : Incompatible auth server: does not support dynamic client registration. La solution est d’injecter le token manuellement (voir ci-dessous).
Étape 3 — Éditer ~/.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 (PAT GitHub 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"
}
}
}
}
Capacité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
Flux de travail typiques avec Claude Code :
« Liste toutes les PRs ouvertes qui me sont assignées sur org/repo, triées par dernière activité »
« Pour la PR #456, résume les modifications, signale les changements cassants et rédige un commentaire de révision »
« Crée une issue pour le bug X avec une checklist, puis ouvre une branche et pousse un commit de correction »
« Recherche dans tous les dépôts de l’organisation les utilisations de fetchUser() dépréciée et liste les fichiers à migrer »
Différenciateur par rapport à @modelcontextprotocol/server-github : Le serveur GitHub MCP officiel ajoute le support de Projects, l’authentification OAuth 2.1, GitHub Enterprise et le point d’accès hébergé distant. 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, 20k+ étoiles, activement maintenu avec des releases régulières.
Le Claude Code Ultimate Guide embarque son propre serveur MCP — claude-code-ultimate-guide-mcp — pour interroger le guide directement depuis n’importe quelle session Claude Code sans cloner le dépôt.
Ce qu’il apporte : 9 outils couvrant la recherche, la lecture de contenu, les templates, les digests, le cheatsheet et les notes de version. L’index structuré (882 entrées) est intégré dans le package (~130 Ko) ; les fichiers markdown sont récupérés depuis GitHub à la demande avec un cache local de 24h.
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.
.mcp.json # Project-scope (project root, shareable via VCS)
Note : Il existe trois portées : local (par défaut, privée pour vous + projet courant, dans ~/.claude.json), project (partagée via .mcp.json à la racine du projet) et user (inter-projets, également dans ~/.claude.json). Utilisez claude mcp add --scope <scope> pour cibler une portée spécifique.
Lorsqu’un seul script headersHelper sert plusieurs serveurs MCP, vous pouvez vous 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 par serveur :
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.
Lorsque 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.
Modèle : conservez une configuration globale minimale (2-3 serveurs essentiels) et activez les serveurs spécifiques aux projets via des fichiers .mcp.json par projet.
# Project-scope (.mcp.json at project root) → only when needed
postgres # database project
playwright # frontend project
serena # large codebase
Des outils communautaires (ex. cc-setup) émergent pour fournir un registre TUI avec activation par projet et vérifications de santé — utile si vous gérez régulièrement 8+ serveurs.
Recherche d’outils MCP — chargement paresseux à grande échelle
Claude Code v4 a introduit 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 le moindre prompt.
Configuration
Contexte utilisé par les outils
Tous les outils chargés au démarrage
~77 000 tokens
MCP Tool Search activé
~8 700 tokens
Réduction
~85 %
Précision du modèle sur les tâches de sélection d’outils (mesurée sur Opus 4) : 49 % → 74 % (+25 points) en passant du préchargement complet au chargement paresseux. S’active automatiquement lorsque 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 aux « trop nombreux outils ». Le conseil de garder une configuration globale minimale s’applique toujours pour des outils sans rapport, mais MCP Tool Search change le calcul pour les grands ensembles spécifiques à un projet.
CLI vs MCP — quand une commande shell surpasse un serveur : Les outils CLI familiers (git, grep, jq, curl) sont déjà profondément intégré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, les flags et le format de sortie de l’outil. Un serveur MCP ajoute une surcharge de schéma d’outil et introduit une interface moins familière. Privilégiez les CLIs pour les outils standards ; utilisez les serveurs MCP pour les systèmes propriétaires ou les APIs pour lesquelles 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 clair dans mcp.json crée des risques de sécurité (commits Git accidentels, exposition dans les logs, mouvement latéral après compromission).
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 clair
Inconvénients : Spécifique à la plateforme, nécessite des scripts pour l’automatisation
Configuration du trousseau macOS :
Terminal window
# Store secret in Keychain
securityadd-generic-password\
-a"claude-mcp"\
-s"github-token"\
-w"ghp_your_token_here"
# Verify storage
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, multi-plateforme, prise en main facile
Inconvénients : En clair sur le disque (permissions fichier uniquement), nécessite de la rigueur
Configuration :
Terminal window
# 1. Create .env file (project root or ~/.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 zéro privilège permanent où les serveurs MCP démarrent sans secrets et demandent des identifiants juste-à-temps lors de l’invocation d’un outil.
Contexte : Mergify (plateforme d’automatisation CI/CD) avait besoin de 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 :
Support ticket received
│
▼
┌───────────────┐
│ Claude Code │ ← orchestrates, synthesizes, produces report
Les serveurs MCP gèrent l’authentification et les identifiants — Claude Code ne voit que des interfaces propres
Les requêtes s’exécutent en parallèle, pas séquentiellement → majorité des gains 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 de serveurs MCP + le system prompt
Résultats (auto-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)
Conclusion principale : Ce schéma — Claude Code comme orchestrateur opérationnel avec des adaptateurs MCP spécialisés par 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 sa 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 grâce à 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 : Commitez 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 les mêmes marketplaces approuvées — 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 build séparée.
Contrôle le temps d’attente de Claude pour l’initialisation d’un serveur LSP 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 délais d’attente par défaut provoquent le contournement silencieux des fonctionnalités LSP.
⚠️ Erreur courante : Ne mettez pas commands/, agents/, skills/ ou hooks/ dans .claude-plugin/. Seul plugin.json va là.
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 des répertoires.
Nommage des skills : Les skills des plugins sont préfixées avec le nom du plugin pour éviter les conflits :
Plugin security-audit avec la skill scan → /security-audit:scan
Serveur MCP = « 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 textuel). Voir la Section 8.1 pour plus de détails.
Deux plugins communautaires répondent à des problèmes complémentaires que le développement assisté par IA crée : 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 ne peuvent le maintenir. L’analyse de 211M de lignes par GitClear montre que le refactoring est passé de 25% à moins de 10% de tous les changements (2021–2025). Vitals identifie quels fichiers sont les plus susceptibles de causer des problèmes — avant qu’ils ne le fassent.
Fonctionnement : Calcule git churn × structural complexity × coupling centrality pour classer les points chauds. Pas seulement « ce fichier est complexe » mais « ce fichier complexe a changé 49 fois en 90 jours et 63 autres fichiers se cassent quand il change. »
Terminal window
# Install (two commands in Claude Code)
/pluginmarketplaceaddchopratejas/vitals
/plugininstallvitals@vitals
# Scan from repo root
/vitals:scan
# Scope options
/vitals:scansrc/# Specific folder
/vitals:scan--top20# More results (default: 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épendances (Python stdlib + 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 brise ce cycle en exécutant un vérificateur indépendant qui ne voit jamais la solution initiale.
Fondement de la 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
# Install (two separate commands — marketplace limitation)
/pluginmarketplaceaddvertti/se-cove-claude-plugin
/plugininstallchain-of-verification
# Use
/chain-of-verification:verify<yourquestion>
/ver<Tab># Autocomplete available
Compromis : Coût en tokens ~2x, volume de sortie réduit. Utile pour le code sensible à la sécurité, le débogage complexe et les décisions architecturales — pas pour le prototypage rapide ou 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 génération de tâche
Problème
Dette de code accumulée
Précision par solution
Entrée
Historique git complet
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 quelles zones de la base de code nécessitent de l’attention, puis utilisez SE-CoVe quand vous demandez à Claude de refactoriser ou corriger ces fichiers points chauds.
Tous les changements 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 à Claude de passer explicitement d’auteur à 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 « oublie que tu l’as é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 des erreurs incohérente, dérive de nommage) mais partage le même chemin de raisonnement que l’auteur, donc les défauts architecturaux subtils peuvent survivre.
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
Schémas de raisonnement différents, perspective fraîche
Un seul modèle qui relit son propre code suit les mêmes schémas de raisonnement qui ont produit ce code. Utiliser un modèle différent pour la revue introduit une analyse véritablement indépendante.
Le schéma : générer avec un modèle, relire avec un autre.
Terminal window
# Implement with Opus (deep reasoning)
claude--modelopus
# Review the diff with Sonnet (different reasoning path, lower cost)
claude-p"Review the changes in the last commit. Check for logic errors, \
edge cases, backward compatibility, and security issues. \
For each finding: severity (critical/high/medium), file:line, problem, fix.
If no issues found, say so explicitly.
Pourquoi différents modèles détectent différents bugs : chaque modèle possède des biais de raisonnement distincts, des distributions d’entraînement et des modes d’échec. 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 les équipes de revue de code diversifiées en ingénierie traditionnelle.
Schémas é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é, contrôle pré-commit
Sonnet
Opus
~2x
Architecture, sécurité critique
N’importe lequel
Même modèle, nouvelle session
~1.5x
Isolation de contexte sans changement de modèle
La variante nouvelle session (même modèle, nouveau contexte via claude -p) offre une isolation de contexte sans changer de modèle. Moins efficace qu’un vrai changement de modèle, mais toujours meilleure qu’une revue dans la même 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 rigueur sécuritaire que vous utiliseriez pour toute dépendance de code tierce.
Détails CVE et vérification avancée : Pour les CVEs documentés (2025-53109/53110, 54135, 54136), la MCP Safe List et les procédures de réponse aux incidents, voir le Security Hardening Guide.
Un serveur MCP malveillant peut déclarer des outils avec des noms courants (comme Read, Write, Bash) qui masquent les outils natifs. Quand Claude invoque ce qu’il croit être l’outil natif Read, le serveur MCP intercepte l’appel.
Flux masqué : Claude → MCP "Read" malveillant → 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 d’une demande avec 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 Dynamique de Capacités
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ée sous permissions. Pour settings.json, utilisez permissions.deny pour bloquer les schémas d’outils.
⚠️ Changement majeur (Opus 4.6, fév. 2026) : Opus 4.6 remplace le budget-based thinking par l’Adaptive Thinking, qui décide automatiquement quand utiliser le raisonnement approfondi en fonction de la complexité de la requête. Le paramètre budget_tokens est déprécié sur Opus 4.6.
Fonctionnement : Le paramètre effort contrôle le budget computationnel global du modèle — pas seulement les tokens de réflexion, mais l’intégralité de la réponse incluant la génération de texte et les appels d’outils. Le modèle alloue dynamiquement ce budget selon la complexité de la requête.
Point clé : effort affecte tout, même lorsque la réflexion est désactivée. Un effort faible = moins d’appels d’outils, texte plus concis. Un effort élevé = plus d’appels d’outils avec explications, analyse détaillée.
max : Capacité maximale, sans contraintes. Opus 4.6 uniquement (renvoie une erreur sur les autres modèles). Raisonnement inter-systèmes, décisions irréversibles.
Exemple : "Analyze the microservices event pipeline for race conditions across order-service, inventory-service, and notification-service"
high (par défaut) : Raisonnement complexe, codage, tâches agentiques. Idéal pour les workflows de production nécessitant une analyse approfondie.
Exemple : "Redesign error handling in the payment module: add retry logic, partial failure recovery, and idempotency guarantees"
medium : Équilibre entre vitesse, coût et performance. Bien adapté aux tâches agentiques de complexité modérée.
Exemple : "Convert fetchUser() in api/users.ts from callbacks to async/await"
low : Plus efficace. Idéal pour la classification, les recherches, les sub-agents, ou les tâches où la vitesse prime sur la profondeur.
Exemple : "Rename getUserById to findUserById across src/"
Le paramètre effort influe significativement sur la façon dont Claude utilise les outils :
Effort low : Combine les opérations pour minimiser les appels d’outils. Pas de préambule explicatif avant les actions. Plus rapide, plus efficace pour les tâches simples.
Effort high : Plus d’appels d’outils avec des explications détaillées. Décrit le plan avant de l’exécuter. Fournit des résumés complets après les opérations. Mieux adapté aux workflows complexes nécessitant de la transparence.
Exemple : Avec un effort low, Claude peut lire 3 fichiers et les modifier en un seul flux. Avec un effort high, Claude explique pourquoi il lit ces fichiers, ce qu’il cherche, puis fournit un résumé détaillé des modifications apportées.
Relation entre effort et la réflexion :
Opus 4.6 : effort est le contrôle recommandé pour la profondeur de réflexion. Le paramètre budget_tokens est déprécié sur 4.6 (bien que toujours fonctionnel pour la rétrocompatibilité).
Opus 4.5 : effort fonctionne en parallèle avec budget_tokens. Les deux paramètres sont pris en charge et affectent différents aspects de la réponse.
Sans réflexion activée : effort contrôle tout de même la génération de texte et les appels d’outils. Ce n’est pas un paramètre réservé à la réflexion.
Utilisation en CLI : Trois méthodes pour contrôler le niveau d’effort dans Claude Code :
Commande /model avec les touches fléchées gauche/droite pour ajuster le curseur d’effort (low, medium, high)
Variable d’environnement CLAUDE_CODE_EFFORT_LEVEL (définie avant le lancement de Claude)
Champ effortLevel dans settings.json (persistant entre les sessions)
Alt+T bascule la réflexion activée/désactivée globalement (indépendamment du niveau d’effort).
assistant-prefill : Déprécié sur Opus 4.6. Permettait auparavant de pré-remplir la réponse de Claude pour guider le format de sortie. Désormais non pris en charge — utiliser des system prompts ou des exemples à la place.
Nouvelles fonctionnalités :
API Fast mode : Ajouter speed: "fast" + l’en-tête beta fast-mode-2026-02-01 pour des réponses 2,5x plus rapides (coût 6x)
📖 Guide complet des workflows : Voir GitHub Actions Workflows pour 5 modèles 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 prompt manuel, voir Code Review — la fonctionnalité de revue multi-agents d’Anthropic qui publie des commentaires GitHub en ligne sur chaque PR.
Claude Code prend en charge les opérations Unix pipe, permettant une puissante intégration shell pour l’analyse et la transformation automatisées de code.
Fonctionnement du piping :
Terminal window
# Transmettre du contenu à Claude avec un prompt
catfile.txt|claude-p'analyze this code'
# Transmettre la sortie d'une commande pour analyse
gitdiff|claude-p'explain these changes'
# Enchaîner des commandes avec Claude
npmtest2>&1|claude-p'summarize test failures and suggest fixes'
Modèles courants :
Automatisation de la revue de code :
Terminal window
gitdiffmain...feature-branch|claude-p'Review this diff for security issues'
Analyse des journaux :
Terminal window
tail-n100/var/log/app.log|claude-p'Find the root cause of errors'
Analyse de la sortie des 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, donc la syntaxe bash ci-dessous fonctionne. 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 l’analyse des répertoires de compétences — garantissant que la configuration locale des développeurs ne s’infiltre jamais dans le CI. Nécessite ANTHROPIC_API_KEY (sans 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
claude-p"run tests"
# Avec --bare : environnement vierge, clé API uniquement
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 release. Le modèle des « changelog fragments » remplace un fichier CHANGELOG.md partagé par un fichier YAML par PR, accumulés dans changelog/fragments/ et assemblés automatiquement lors de la release.
Le problème fondamental des approches basées sur les commits : au moment où vous exécutez git log pour générer les notes de version, le contexte a disparu. Le développeur qui a corrigé une condition de course trois semaines plus tôt était le seul à en comprendre l’impact. Le message de commit indique fix SSE handling.
Le modèle 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 l’intégralité du workflow des fragments. Lorsqu’un développeur demande à Claude Code de « créer la PR », celui-ci lit le diff, en déduit le type, la portée et le titre, génère le YAML, le valide et le commit comme partie intégrante de 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 d’une 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 — Passerelle 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 avec “skip-changelog” peut tout de même ajouter une migration que l’équipe de déploiement doit connaître.
Assemblage lors de la release :
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, et non reconstitué après coup
Migrations de base de données exposées explicitement dans chaque fragment
Le contournement est auditable (liste fermée de labels 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. La clé est d’assembler trois composants : la gestion des secrets, une skill 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 T — 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 en production autonome
Smoke test
Vérifier HTTP 200 sur les points d’accès clés après le déploiement
Détecter les échecs de déploiement silencieux
Rollback prêt
Conserver l’ID du déploiement précédent avant la promotion
vercel rollback <deployment-id>
Hook de confirmation (prévenir les déploiements en production accidentels) :
.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 : Modèle de skill de déploiement Vercel documenté par la communauté (lobehub.com, haniakrim21) ; gestion des secrets multi-plateformes Infisical sur infisical.com. Aucun workflow de déploiement automatisé de bout en bout n’existe dans la communauté à ce jour (mars 2026) — les briques de base sont disponibles, mais le modèle de promotion de staging vers production est quelque chose que chaque équipe assemble elle-même.
Nouveauté : Xcode 26.3 RC+ inclut la prise en charge native du Claude Agent SDK, utilisant le même environnement d’exécution 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 le CLI Claude Code
Intégration native aux flux de travail Xcode
Claude Agent SDK : Produit distinct de Claude Code, mais partageant le même cadre d’exécution des agents. Permet de créer des outils de développement alimentés par Claude dans des IDE au-delà de VS Code.
Remarque : Claude Agent SDK n’est pas Claude Code — c’est le cadre d’Anthropic pour construire des outils de développement propulsés par des agents. Le CLI Claude Code et l’intégration Xcode utilisent tous deux ce SDK.
Les boucles de rétroaction rapides accélèrent l’apprentissage et détectent les problèmes tôt. Concevez votre flux de travail pour valider les changements 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 : Utilisez Ctrl+B pour mettre les tâches en arrière-plan et maintenir des boucles de rétroaction rapides sur l’ensemble de la pile.
Problème : Les tâches en arrière-plan de longue durée peuvent provoquer une dégradation du contexte — Claude perd conscience de ce qui est en cours d’exécution.
Solution : Vérifiez périodiquement le statut 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 majeurs d’architecture
Relancer les tâches en arrière-plan si le contexte est perdu
Utiliser des commandes descriptives (pnpm dev:backend plutôt que npm run dev)
💡 Insight 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 rétroaction rapides sur l’ensemble de la pile.
Claude dans Chrome : la boucle de rétroaction visuelle
Toutes les boucles ci-dessus valident le code. Aucune d’elles ne dit à Claude si l’interface utilisateur s’affiche correctement, si un formulaire fonctionne, ou si la page s’affiche sans erreurs. 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 cet écart. C’est 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 :
Installez l’extension Claude dans Chrome depuis le Chrome Web Store
Activez-la 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 un changement
Lire les erreurs de console
Pas de copier-coller ; Claude voit les erreurs directement
Parcourir des flux
Tester qu’une soumission de formulaire fonctionne vraiment
Capture d’écran + comparaison
Vérifier le rendu visuel par rapport aux attentes
Remplir des champs
Tester la validation, les cas limites, les états vides
L’insight 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 rétroaction du code détectent les erreurs de syntaxe et de logique. Les boucles de rétroaction du 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 en v2.0.72 sous le nom “Claude in Chrome Beta”. Les options --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.
Claude Code peut générer des diagrammes Mermaid pour la documentation visuelle. C’est utile pour documenter l’architecture, visualiser les flux et comprendre les systèmes.
“Appliquer ce motif de modification à tous les fichiers correspondants :
Motif : Ajouter la directive ‘use client’ aux composants utilisant des hooks
Périmètre : src/components/**/*.tsx
Règle : Si le fichier contient useState, useEffect ou useContext
Modification : Ajouter ‘use client’ en première ligne
Lister d’abord les fichiers concernés, puis effectuer les modifications.”
## 9.10 État d'esprit d'amélioration continue
L'objectif n'est pas seulement d'utiliser l'IA pour coder — il s'agit d'**améliorer continuellement le workflow** afin que l'IA produise de meilleurs résultats avec moins d'intervention.
### La question clé
Après chaque intervention manuelle, posez-vous la question :
> « Comment puis-je améliorer le processus pour éviter cette erreur ou cette correction manuelle la prochaine fois ? »
### Pipeline d'amélioration
Error or manual intervention detected
│
▼
Can a linting rule catch it?
│
YES ─┴─ NO
│ │
▼ ▼
Add lint Can it go in conventions/docs?
rule │
YES ─┴─ NO
│ │
▼ ▼
Add to Accept as
CLAUDE.md edge case
or ADRs
### Exemples pratiques
| Problème | Solution | Où ajouter |
|---------|----------|--------------|
| L'agent oublie de lancer les tests | Ajouter à la commande de workflow | `.claude/commands/complete-task.md` |
| La revue de code détecte un problème de style | Ajouter une règle ESLint | `.eslintrc.js` |
| La même erreur d'architecture se répète | Documenter la décision | `docs/conventions/architecture.md` |
| L'agent utilise un mauvais motif d'import | Ajouter un exemple | `CLAUDE.md` |
### Le changement de mentalité
Traditionnel : *« J'écris le code, l'IA aide »*
Natif IA : *« J'améliore le workflow et le contexte pour que l'IA écrive un meilleur code »*
> « Le génie logiciel relève peut-être davantage de l'ingénierie de workflow et de contexte. »
> — Nick Tune
C'est la méta-compétence : au lieu de corriger le code, **corrigez le système qui produit le code**.
> Inspiré de [Coding Agent Development Workflows de Nick Tune](https://medium.com/nick-tune-tech-strategy-blog/coding-agent-development-workflows-af52e6f912aa)
> **Voir aussi** : [§2.5 From Chatbot to Context System](/guide/ultimate-guide/02-core-workflow/#from-chatbot-to-context-system) — le framework à quatre couches (CLAUDE.md, skills, hooks, memory) qui rend cet état d'esprit opérationnel.
## 9.11 Pièges courants et bonnes pratiques
Apprenez des erreurs courantes pour éviter la frustration et maximiser la productivité.
### Pièges de sécurité
**❌ Ne pas :**
- Utiliser `--dangerously-skip-permissions` sur des systèmes de production ou des bases de code sensibles
- Coder en dur des secrets dans les commandes, fichiers de configuration ou CLAUDE.md
- Accorder des permissions trop larges comme `Bash(*)` sans restrictions
- Exécuter Claude Code avec des privilèges élevés (sudo/Administrator) de manière inutile
- Commiter `.claude/settings.local.json` dans le contrôle de version (contient des clés API)
- Partager des identifiants de session ou des journaux pouvant contenir des informations sensibles
- Désactiver les hooks de sécurité lors du développement normal
**✅ Faire :**
- Stocker les secrets dans des variables d'environnement ou des coffres sécurisés
- Partir de permissions minimales et les étendre progressivement selon les besoins
- Effectuer des audits réguliers avec `claude config list` pour examiner les permissions actives
- Isoler les opérations risquées dans des conteneurs, des VMs ou des environnements séparés
- Utiliser `.gitignore` pour exclure les fichiers de configuration sensibles
- Examiner tous les diffs avant d'accepter les modifications, en particulier dans le code critique pour la sécurité
- Implémenter des hooks PreToolUse pour détecter l'exposition accidentelle de secrets
- Utiliser le Plan Mode pour explorer des bases de code inconnues ou sensibles
**Exemple de hook de sécurité :**
```bash
#!/bin/bash
# .claude/hooks/PreToolUse.sh - Block secrets in commits
Ignorer le contexte du projet (CLAUDE.md) — entraîne des corrections répétées
Utiliser des prompts vagues comme « répare ça » ou « vérifie mon code »
Ignorer les erreurs dans les journaux ou rejeter les avertissements
Automatiser les workflows sans les tester d’abord dans des environnements sûrs
Accepter les modifications à l’aveugle sans examiner les diffs
Travailler sans contrôle de version ni sauvegardes
Mélanger plusieurs tâches sans rapport dans une seule session
Oublier de commiter 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 spécifique et orienté objectif dans les prompts en utilisant le format WHAT/WHERE/HOW/VERIFY
Surveiller via les journaux ou OpenTelemetry le cas échéant
Tester l’automatisation d’abord dans des environnements de développement/staging
Toujours examiner les sorties de l’agent avant de les accepter — en particulier celles qui semblent 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
Commiter fréquemment avec des messages descriptifs
⚠️ Le Paradoxe des artefacts — Anthropic AI Fluency Index (Fév 2026)
La recherche d’Anthropic portant sur 9 830 conversations Claude révèle un résultat contre-intuitif critique : lorsque Claude produit un artefact soigné (code, fichiers, configurations), les utilisateurs deviennent de manière mesurable moins critiques, et non davantage.
Par rapport aux sessions sans production d’artefacts :
−5,2 pp de probabilité d’identifier le contexte manquant
−3,7 pp de probabilité de vérifier les faits de la sortie
−3,1 pp de probabilité de remettre en question le raisonnement
Les utilisateurs deviennent effectivement plus directifs (+14,7 pp pour clarifier les objectifs, +14,5 pp pour spécifier le format) — mais leur évaluation critique diminue précisément lorsque 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 compilée et exécutée de manière soignée est précisément le moment où vous devez exercer le plus de vigilance — et non 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 ? »
WHAT: [Livrable concret - ex. : “Ajouter la validation d’e-mail au formulaire d’inscription”]
WHERE: [Chemins de fichiers - ex. : “src/components/SignupForm.tsx”]
HOW: [Contraintes/approche - ex. : “Utiliser un schéma Zod, afficher les erreurs en ligne”]
VERIFY: [Critères de succès - ex. : “E-mail vide affiche une erreur, format invalide affiche une erreur, e-mail valide autorise la soumission”]
Essayer de tout apprendre d’un coup — contre-productif et inefficace
Sauter les bases pour aller 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 en isolation sans consulter les ressources de la communauté
Abandonner après la première frustration
Faire confiance à la sortie de l’IA sans vérification proportionnée — le code généré par l’IA contient 1,75× plus d’erreurs logiques que le code écrit par des humains (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 de la communauté
Rejoindre les communautés Claude Code (Discord, discussions GitHub)
Partager ses 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
□ Réaliser sa 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 correctement le .gitignore
□ 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
□ Mettre en place 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 workflows d'équipe
Anti-patterns en entreprise (données sectorielles 2026)
D’après les recherches d’Anthropic auprès de plus de 5 000 organisations, ces anti-patterns sont apparus comme les erreurs les plus coûteuses lors de l’adoption du codage agentique.
Les git worktrees (disponibles depuis Git 2.5.0, juillet 2015) créent plusieurs répertoires de travail à partir du même dépôt, chacun extrait sur une branche différente.
Problème du workflow traditionnel :
Terminal window
# Working on feature A
gitcheckoutfeature-a
# 2 hours of work...
# Urgent hotfix needed
gitstash# Save current work
gitcheckoutmain
gitcheckout-bhotfix
# Fix the bug...
gitcheckoutfeature-a
gitstashpop# Resume work
Solution avec les worktrees :
Terminal window
# One-time setup
gitworktreeadd../myproject-hotfixhotfix
gitworktreeadd../myproject-feature-afeature-a
# Now work in parallel
cd../myproject-hotfix# Terminal 1
claude# Fix the bug
cd../myproject-feature-a# Terminal 2
claude# Continue feature work
Quand utiliser les worktrees :
✅ Utiliser les worktrees quand :
Travail simultané sur plusieurs fonctionnalités
Besoin de tester différentes approches en parallèle
Revue de code pendant le développement
Exécution de longs builds CI/CD pendant le codage
Maintenance de plusieurs versions (support v1 + développement v2)
❌ Ne pas utiliser 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é)
Commandes du cycle de vie des worktrees :
Le cycle de vie complet des worktrees est couvert par 4 commandes complémentaires :
Commande
Rôle
/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 individuellement avec vérification de merge et nettoyage de DB
/git-worktree-clean
Nettoyage en lot des worktrees obsolètes avec rapport d’utilisation du disque
Terminal window
# Create with auto-prefix and symlinked node_modules
💡 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 s par création de worktree et un espace disque significatif. Utilisez --isolated lorsque vous avez besoin de dépendances fraîches (par ex. pour tester des mises à jour).
Gestion des worktrees :
Terminal window
# List all worktrees
gitworktreelist
# Remove worktree (after merging feature)
gitworktreeremove.worktrees/feature/new-api
# Cleanup stale worktree references
gitworktreeprune
💡 Conseil d’équipe — Alias shell pour une navigation rapide entre worktrees : L’équipe Claude Code utilise des alias à une lettre pour basculer 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 dédié « analysis » est utilisé pour examiner les logs et exécuter des requêtes de base de données sans polluer les branches de fonctionnalités actives.
Définissez isolation: "worktree" dans le frontmatter d’un agent pour le faire spawner automatiquement dans un worktree vierge à chaque invocation (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.
Ceci remplace l’ancien modèle consistant à passer manuellement isolation: "worktree" à chaque appel de l’outil Task.
Configuration VCS personnalisée avec les événements hook (v2.1.50+)
Le hook ConfigChange se déclenche chaque fois qu’un fichier de configuration change 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 (journalisation + blocage optionnel) :
Note entreprise : disableAllHooks (v2.1.49+) ne peut plus contourner les hooks gérés — les hooks définis par la politique organisationnelle s’exécutent toujours, quelle que soit cette configuration. Seuls les hooks non gérés sont concernés.
Déploiement de fragments de politique avec managed-settings.d/ (v2.1.83+)
Dans les organisations multi-équipes, modifier un seul fichier managed-settings.json crée 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 alphabétiquement au démarrage.
/etc/claude-code/managed-settings.d/
├── 00-security-baseline.json # From security team
├── 10-allowed-tools.json # From platform team
└── 50-team-hooks.json # From individual team
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 à l’équipe sécurité de fournir une base globale sans bloquer les équipes dans le déploiement de leurs propres fragments de manière indépendante.
Fail-safe du sandbox : sandbox.failIfUnavailable (v2.1.83+)
Par défaut, si Claude Code ne peut pas démarrer le sandbox (macOS Seatbelt / Linux seccomp indisponible), il bascule silencieusement vers une exécution sans sandbox. Dans les environnements sensibles à la sécurité, cette bascule silencieuse représente 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ù une bascule sans sandbox est inacceptable.
Isolation des credentials des sous-processus : CLAUDE_CODE_SUBPROCESS_ENV_SCRUB (v2.1.83+)
Par défaut, les sous-processus générés par Claude Code (outil Bash, hooks, MCP stdio) héritent de l’environnement shell complet, y compris les clés API Anthropic et les credentials des fournisseurs cloud. Définissez CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1 pour supprimer ces credentials avant l’exécution des sous-processus :
Terminal window
exportCLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1
Cette option 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 credentials API.
Lorsqu’on exécute plusieurs agents en parallèle dans des worktrees, le problème le plus difficile n’est pas la configuration — c’est la coordination. Il n’existe pas de détection automatique des dépendances entre 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 les tâches qui partagent des fichiers :
Terminal window
# Vérification rapide des dépendances : lister les fichiers que chaque tâche va toucher
Les tâches touchent des fichiers et 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 de conflits
Les tâches touchent les mêmes fichiers
Les séquencer
La tâche B a besoin du contrat d’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 des agents économise 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 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 en date de mars 2026. Les approches ci-dessus représentent l’état de l’art pratique.
Important : Claude Code utilise le chargement différé — 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 pour 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 : Ces fichiers sont chargés une seule fois au démarrage de la session, pas à chaque requête. Un CLAUDE.md de 200 lignes coûte ~2K tokens en amont mais ne croît pas durant la session. Le problème est l’effet cumulatif combiné à plusieurs @includes et à tous les fichiers dans .claude/rules/.
Important : Au-delà de la taille des fichiers, les fichiers de contexte contenant des informations non essentielles (guides de style, descriptions d’architecture, conventions générales) ajoutent +20-23% de coût d’inférence par session indépendamment du nombre de lignes — parce que les agents traitent et appliquent chaque instruction. La même recherche confirme que les fichiers de contexte générés par LLM réduisent le taux de réussite des tâches de ~3%, tandis que les fichiers rédigés par des développeurs l’améliorent de ~4%. (Gloaguen et al., 2026)
# ❌ CLAUDE.md gonflé (gaspille des tokens à chaque session)
- 500+ lignes d'instructions
- Plusieurs @includes important d'autres fichiers
- Directives rarement utilisées
# ✅ CLAUDE.md allégé
- Uniquement le contexte essentiel du projet (<200 lignes)
- Déplacer les règles spécialisées dans .claude/rules/ (chargé automatiquement au démarrage)
- 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 (Gloaguen et al., ETH Zürich, fév. 2026 — 138 benchmarks, 12 dépôts) : La première étude empirique sur les fichiers de contexte montre que les CLAUDE.md rédigés par des développeurs améliorent le taux de réussite des agents de +4%, mais les fichiers générés par LLM le réduisent de -3%. Cause : les agents suivent fidèlement toutes les instructions, même celles non pertinentes pour la tâche, entraînant une exploration plus large des fichiers et des chaînes de raisonnement plus longues. Recommandation : inclure uniquement les commandes de build/test et l’outillage spécifique au projet. Les guides de style et les descriptions d’architecture appartiennent à des documents séparés. (Évaluation complète)
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 du 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 focalisé (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, construisez 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 (installation npx, SQLite, 15 langages) :
npxcodexray# Configuration interactive + première construction de l'index
cxrwatch & # Synchronisation en arrière-plan lors des modifications de fichiers
# Claude Code interroge ensuite le graphe plutôt que de lire les fichiers :
# "find the payment module" → 1 requête 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 effectuer efficacement :
Code mort : Fonctions définies mais jamais appelées — candidates à la suppression, réduisant le bruit de contexte futur
Dépendances circulaires : Le module A importe B qui importe A — dette architecturale qui gonfle silencieusement le raisonnement de Claude
Points chauds : Fichiers avec le plus grand nombre de dépendances — à prioriser pour la documentation ou la refactorisation en premier
Terminal window
# Avec grepai (zéro appelant = candidat code mort) :
grepaitracecallers"MyFunction"# Résultat vide → à investiguer pour suppression
# Avec un outil MCP structurel (si disponible) :
# Des 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 phase alpha en mars 2026 — utilisez grepai pour les flux de travail en production.
RTK (Rust Token Killer) filtre les sorties des commandes bash avant qu’elles n’atteignent le contexte de Claude, atteignant une réduction de 60-90% des tokens sur les flux de travail git, de test et de développement. 446 étoiles, 38 forks, 700+ votes positifs sur r/ClaudeAI.
Économies de tokens avérées (benchmarks sur des sorties réelles) :
Commande
Référence
RTK
Réduction
rtk git log
13 994 caractères
1 076 caractères
92,3 %
rtk git status
100 caractères
24 caractères
76,0 %
rtk git diff
15 815 caractères
6 982 caractères
55,9 %
rtk vitest run
~50 000 caractères
~5 000 caractères
90,0 %
rtk pnpm list
~8 000 caractères
~2 400 caractères
70,0 %
rtk cat CHANGELOG.md
163 587 caractères
61 339 caractères
62,5 %
Moyenne : 60-90 % de réduction des tokens selon les commandes
Fonctionnalités clés (v0.28.0) :
Terminal window
# Opérations Git
rtkgitlog
rtkgitstatus
rtkgitdiffHEAD~1
# Stack JS/TS
rtkvitestrun# Résultats de tests condensés
rtkpnpmlist# Arbre de dépendances optimisé
rtkprismamigratestatus# Statut des migrations filtré
# Python
rtkpythonpytest# Sortie de tests Python condensée
rtkmypy# Erreurs de type regroupées par fichier
# Go
rtkgotest# Résultats de tests Go filtrés
# Rust
rtkcargotest# Sortie de tests Cargo condensée
rtkcargonextest# Sortie cargo-nextest en mode échecs uniquement
rtkcargobuild# Sortie de build filtrée
rtkcargoclippy# Avertissements regroupés par sévérité
# Cloud & Base de données
rtkaws# Sortie AWS CLI filtrée
rtkpsql# Résultats de requêtes psql condensés
rtkdocker# Sortie Docker condensée
rtkdockercompose# Support de docker compose
# Contrôle de version (extra)
rtkgt# Support de la CLI Graphite
# Utilitaires Fichiers & Texte
rtktree# Structure du projet condensée
rtkwc# Comptages compacts mots/lignes/octets
rtkreadfile.ts# Contenu de fichier condensé
# Configuration du projet & apprentissage
rtkinit# Initialiser RTK avec installation automatique du 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# Répartition des économies par projet
rtkdiscover# Trouver les opportunités d'optimisation manquées
# Gestion des hooks et de la configuration
rtkrewrite<cmd># Source unique de vérité pour les réécritures de hooks
rtkverify# Valider les règles de filtrage TOML
Impact dans le monde réel :
Session Claude Code de 30 minutes :
- Sans RTK : ~150K tokens (10-15 commandes git à ~10K tokens chacune)
- Avec RTK : ~41K tokens (10-15 commandes git à ~2,7K tokens chacune)
- Économies : 109K tokens (réduction de 72,6 %)
DSL de filtrage TOML (v0.28.0 — ajouter des filtres sans écrire de Rust) :
RTK prend désormais en charge un moteur de filtrage déclaratif via une configuration 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 par hook en premier (recommandé) :
Terminal window
rtkinit--global# Configure le hook PreToolUse + patch automatique de settings.json
Instruction CLAUDE.md (wrapper manuel) :
## Token Optimization
Use RTK for all supported commands:
-`rtk git log` (92.3% reduction)
-`rtk git status` (76.0% reduction)
-`rtk git diff` (55.9% reduction)
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 ces commandes
Note de migration (v0.25.0+) :
Après une mise à jour depuis v0.24.0 ou antérieure, exécutez rtk init --global pour installer le nouveau hook délégateur léger. L’ancien hook fonctionne encore, mais ne prendra pas automatiquement en compte les nouveaux mappings de commandes.
Terminal window
cargoinstallrtk# 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 principales sources de consommation de tokens dans une session Claude Code.
Le problème : Quand Claude explore une base de code, il lit les fichiers en entier — 400 lignes alors qu’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 pattern (3 étapes, réduction de 86-92 %) :
Étape 1 — Structure (~200 tokens par fichier)
Obtenir uniquement les signatures de fonctions, types, 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 — uniquement les lignes 45-90
Étape 3 — Références croisées (~150 tokens)
Trouver les appelants d'une fonction
rg "function_name" --type rust -n
C’est le même pattern qu’Aider utilise pour sa repo map (plus de 40 000 étoiles) — validé à grande échelle depuis 2023.
Approche A : Sans configuration — discipline CLAUDE.md
Le chemin le plus rapide. Ajoutez à votre CLAUDE.md :
## Code Exploration Protocol
When exploring a codebase or understanding a module:
1.**Structure first** — run the appropriate command for the language:
50-150 tokens par fichier contre 2 000-5 000 pour les lectures complètes.
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 PR
code-review-graph (MIT, ~2k étoiles)
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, marketplace Claude Code, réduction moyenne de 6,8x des tokens sur des revues de PR dans des bases de code réelles (httpx : 26x, FastAPI : 8x, Next.js : 6x).
Ne pas être économe 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 bons prompts et fichiers mémoire (réduire les itérations)
Automatiser avec des agents (cohérent, efficace)
Perspective sur le ROI :
Les gains de temps issus d’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 PR et l’attribution de code (plans Team/Enterprise, bêta publique).
Quand optimiser agressivement :
Opérations à fort volume (>1 000 requêtes/jour)
Pipelines automatisés fonctionnant 24h/24 et 7j/7
Grandes équipes (les coûts évoluent avec le nombre d’utilisateurs)
15 méthodologies de développement structurées ont émergé pour le développement assisté par IA (2025-2026). Cette section offre une navigation rapide ; les workflows détaillés se trouvent dans des fichiers dédiés.
Temps de lecture : 5 minutes
Niveau : À partir de la 2e semaine
Des motifs nommés et mémorisables pour interagir efficacement avec Claude Code. Ces motifs sont issus 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 workflows où vous commencez le travail 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 en parallèle. Nécessite une architecture modulaire + un budget + une surveillance. 95 % des utilisateurs n’en ont pas besoin — les workflows séquentiels avec 1 à 2 instances sont plus efficaces dans la plupart des contextes.
Ne pas mettre à l’échelle prématurément. Les workflows multi-instances introduisent une surcharge de coordination qui dépasse les avantages 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 une architecture modulaire + des 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’alerte (ne pas utiliser le multi-instances si) :
Architecture : Monolithe legacy, pas de tests, couplage fort
Budget : <500 $/mois disponibles pour les coûts API
Expertise : Équipe non familière avec les bases de Claude Code
Contexte : Développeur solo ou <3 personnes
📊 Validation sectorielle : ROI du multi-instances (Anthropic 2026)
Gain via plus de production, pas seulement de la vitesse
Nouveau travail
27 % ne serait pas fait sans l’IA
Expérimental, souhaitable, exploratoire
Délégation complète
0–20 % des tâches
Collaboration > remplacement
Multiplicateur de coût
3× (capacités × orchestration × expérience)
S’accumule dans le temps
Études de cas en entreprise :
TELUS (télécommunications, 50 000+ employés) : 500 000 heures économisées, 13 000 solutions personnalisées, livraison 30 % plus rapide
Fountain (plateforme de main-d’œuvre) : Présélection 50 % plus rapide, intégration 40 % plus rapide via multi-agents hiérarchiques
Rakuten (technologie) : Implémentation vLLM autonome en 7 h (12,5 M de lignes de code, précision 99,9 %)
Validation du modèle Boris : Le coût de 500–1 000 $/mois de Boris et ses 259 PRs/mois s’alignent avec les données entreprise d’Anthropic montrant un ROI positif à partir de 3+ instances parallèles.
Alerte anti-pattern (résultats Anthropic) :
Surdélégation (>5 agents) : Surcharge de coordination > gain de productivité
Mise à l’échelle prématurée : Commencer avec 1–2 instances, mesurer le ROI, évoluer progressivement
Prolifération d’outils : >10 serveurs MCP = charge de maintenance (s’en tenir à la stack de base)
Coût : ~500–1 000 $/mois en API (tarification Opus)
Contexte crucial : 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.
Points clés de Boris :
Sur le multi-clauding : « J’utilise Cowork comme un “exécutant”, pas un chat : il touche directement les fichiers, les navigateurs et les outils. Je conçois la productivité comme du parallélisme : plusieurs tâches tournent pendant que je pilote les résultats. »
Sur CLAUDE.md : « Je traite Claude.md comme une mémoire qui se cumule : chaque erreur devient une règle durable pour l’équipe. »
Sur le workflow plan-first : « Je lance des workflows 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 les sorties (navigateur/tests) : la vérification conduit la qualité. »
Pourquoi Opus 4.6 avec Adaptive Thinking : Bien que plus coûteux par token (5 $/1 M d’entrée contre 3 $/1 M pour Sonnet, ou 10 $/1 M pour le bêta à contexte 1 M), Opus nécessite moins d’itérations de correction grâce à l’adaptive thinking. Résultat net : livraison plus rapide et coût total inférieur malgré un prix unitaire plus élevé.
Le modèle de supervision : Boris décrit son rôle comme « s’occuper de plusieurs agents » plutôt que « faire chaque clic soi-même ». Le workflow devient une question de pilotage des résultats sur 5 à 10 sessions parallèles, en débloquant les situations au besoin, plutôt qu’une exécution séquentielle.
Modèles d’équipe (équipe Claude Code au sens large, fév. 2026) :
L’équipe au sens large étend le workflow individuel de Boris avec des modèles institutionnels :
Les skills comme savoir institutionnel : Tout ce qui est fait plus d’une fois par jour devient un skill intégré dans le contrôle de version. Exemples :
/techdebt — lancé en fin de session pour éliminer le code dupliqué
Skills de dump de contexte — synchronisent 7 jours de Slack, Google Drive, Asana et GitHub en un seul contexte
Agents analytiques — skills alimentés par dbt qui interrogent BigQuery ; un ingénieur rapporte ne plus 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 aux outils externes. Justification : moins de magie, plus facile à déboguer, comportement plus prévisible. MCP est réservé aux cas où une communication bidirectionnelle est réellement nécessaire.
Re-planifier en cas de blocage : Plutôt que de forcer une implémentation bloquée, l’équipe repasse en Plan Mode. Un ingénieur utilise une instance Claude secondaire pour examiner les plans « comme un ingénieur senior » 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.
Tandis que le workflow de Boris illustre 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 workflows 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év. 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 le double instance ?
Coût mensuel
Développeur solo, travail intensif en spécifications
✅ Oui
100–200 $
Petite équipe, exigences complexes
✅ Oui
150–300 $
Designers produit qui codent
✅ Oui
100–200 $
Fonctionnalités parallèles en volume élevé
❌ Non, utiliser le modèle Boris
500 $–1 000 $+
Utiliser quand :
Vous avez besoin de vérifier le plan avant l’exécution
Les spécifications sont complexes ou ambiguës (la clarification par entretien aide)
Budget inférieur au modèle Boris (100–200 $/mois contre 500–1 000 $+)
Qualité > vitesse (prêt à sacrifier le parallélisme pour de meilleurs plans)
Ne pas utiliser quand :
Vous avez besoin de 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 fort volume (vitesse).
Analyse des coûts : 2 instances vs boucles de correction
La clé de l’efficacité de la double instance réside dans 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 lignes ».
Les workflows multi-instances NÉCESSITENT des git worktrees pour éviter les conflits. Sans worktrees, les instances parallèles créent un enfer de fusions.
Pourquoi les worktrees sont critiques :
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 des minutes pour un clone complet)
Bien que les git worktrees soient fondamentaux, la productivité quotidienne s’améliore avec des wrappers d’automatisation. Plusieurs équipes professionnelles ont indépendamment créé des outils de gestion de 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 (1,6K étoiles, 64 versions)
Hooks de projet, statut CI, liens PR, multi-plateforme
Conclusion : le modèle de wrapper worktree est réinventé par les utilisateurs avancés. Vanilla git est suffisant mais verbeux pour 5-10+ opérations de worktrees quotidiennes.
✅ Vanilla git - Apprendre les fondamentaux d’abord
Utilisateur occasionnel
5-15
2-3
Solo/Petite
⚠️ 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 vanilla git, -79% de frappe)
Quand passer à Worktrunk :
L’alias devient limitant (besoin du statut CI, commits LLM, hooks de projet)
Le volume augmente à 15+ worktrees/semaine
L’équipe adopte les workflows multi-instances (besoin d’outillage cohérent)
En résumé : la plupart des lecteurs (80 %) devraient commencer avec vanilla git ou un alias. Worktrunk est réservé 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. Apprenez les fondamentaux de git d’abord, ajoutez un wrapper pour la vitesse ensuite.
Option 1 : Worktrunk (recommandé pour la mise à l’échelle)
Quand utiliser : contrôle total souhaité, petite équipe (même shell), déjà des 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 → mise à l’échelle
Phase 1 (Semaines 1-2) : Maîtriser vanilla git worktree via la commande /git-worktree
└─ Comprendre les fondamentaux, vérifications de sécurité, branchement de base de données
Phase 2 (Semaine 3+) : Ajouter un wrapper pour la productivité
├─ Worktrunk (si multi-plateforme, statut CI souhaité, commits LLM)
└─ DIY bash/fish (si léger, l'équipe utilise le même shell)
Phase 3 (Mise à l'échelle multi-instances) : Combiner avec l'orchestration
└─ Worktrunk/wrapper + Headless PM pour 5-10 instances
Philosophie : les outils amplifient les connaissances. Maîtrisez les modèles git (ce guide) avant d’ajouter des couches de commodité. Les wrappers font économiser 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 agnostiques sur les 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 : outil créé en interne, 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 ainsi qu’une nouvelle fonctionnalité d’analyse pour les clients Team et Enterprise.
Métriques actualisées (internes Anthropic) :
+67 % de PRs fusionnées par ingénieur par jour (contre +50 % autodéclarés en août 2025)
70-90 % du code désormais rédigé avec l’assistance de Claude Code dans les équipes
Note méthodologique : Ces chiffres sont basés sur les PRs et 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 ni période de référence, ni ventilation par équipe, et définit la mesure uniquement comme « prudente — uniquement le code pour lequel nous avons une haute confiance dans l’implication de Claude Code. » À considérer 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 (conditions exactes des modules complémentaires non confirmées)
Suivi : PRs fusionnées et lignes de code committé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), sans les remplacer
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)
# - 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 framework 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
Spawner auto-hébergé
Équipes nécessitant on-prem/air gap
Entire CLI
Gouvernance + handoffs
Workflows séquentiels avec conformité
Entire CLI (fév. 2026) : Alternative à l’orchestration parallèle, axée sur les handoffs d’agents séquentiels 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é de 3-5 % maintenu 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 permet de construire des tableaux de bord par session, d’appliquer des limites de débit au niveau session, ou d’attribuer les coûts API à des développeurs ou des jobs CI individuels — 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 Netlify AX (2025), guide d’implémentation Speakeasy, articles ArXiv sur l’ingénierie du 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 patterns mais peinent face aux connaissances implicites et au contexte dispersé.
Principes clés :
Intégration des connaissances métier : Placez la logique métier et les décisions de conception directement dans le code (CLAUDE.md, ADRs, commentaires)
Découvrabilité du code : Rendez le code « cherchable » comme le SEO — utilisez des synonymes, des balises, des termes complets
Formats de documentation : Utilisez llms.txt pour l’indexation de documentation optimisée pour l’IA (en complément des serveurs MCP)
Efficacité des tokens : Découpez les gros fichiers, supprimez les commentaires évidents, utilisez 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 — les tests guident le comportement
Garde-fous : Les hooks, les vérifications CI et les revues de PR détectent les erreurs des agents tôt
Quand optimiser pour les agents : Les fichiers à fort impact (logique métier principale, modules fréquemment modifiés) et les projets greenfield. Ne refactorisez pas du code stable uniquement pour les agents.
Pourquoi c’est important : Les agents lisent le code séquentiellement et n’ont pas le « modèle mental » que les humains construisent au fil du temps. Ce qui vous paraît évident (par exemple, « ce service gère l’authentification ») doit être rendu explicite.
Netlify a forgé le terme « Agent Experience » comme équivalent de l’expérience développeur (DX) pour les agents. 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 la DX réduit la friction pour les humains. »
— Équipe de recherche Netlify AX
Impact concret :
Marmelab : Refactorisation de la base de code Atomic CRM avec les principes AX → livraison de fonctionnalités 40 % plus rapide
Speakeasy : Docs d’API adaptées aux agents → taux d’adoption de l’API 3 fois plus élevé
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 turnover (logique métier, routes API)
✅ Équipes utilisant intensément les agents (>50 % des commits)
❌ Code legacy stable (ne pas refactoriser uniquement pour les agents)
❌ Petits scripts (<100 lignes, les agents s’en sortent bien)
La Convention Plutôt que la Configuration pour les Agents IA
Problème : Chaque décision de configuration ajoute une charge cognitive pour les agents. Les architectures personnalisées nécessitent une documentation CLAUDE.md extensive pour prévenir les hallucinations.
Solution : Choisir des frameworks à opinions arrêtées qui réduisent l’espace de décision grâce à des conventions imposées.
Pourquoi les frameworks à opinions arrêtées aident les agents :
Aspect
Architecture personnalisée
Framework à opinions arrêtées
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 (les conventions sont déjà connues)
Exemples de frameworks à opinions arrêtées :
Next.js : Structure du répertoire app/, routage basé sur les fichiers, conventions des server components
Rails : Structure MVC, patterns Active Record, conventions des générateurs
Phoenix (Elixir) : Frontières de contexte, conventions de schéma, patterns LiveView
Django : Structure des applications, conventions de settings, interface d’administration
Impact concret :
Lorsque les agents travaillent avec des frameworks à opinions arrêtées, ils :
Font moins d’erreurs (moins de choix = moins de mauvais choix)
Génèrent du code passe-partout plus rapidement (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 :
Bénéfice
Coût
Prise en main 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 plutôt que la configuration réduit directement les besoins en tokens du CLAUDE.md :
... (documentation extensive des patterns personnalisés)
# Next.js (CLAUDE.md 50 lignes)
## Contexte du projet
Nous utilisons Next.js 14 avec App Router.
... (contexte minimal, le reste correspond aux conventions du framework)
Recommandation : Pour les projets greenfield avec développement assisté par IA, préférez les frameworks à opinions arrêtées 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 de votre projet. Ils peuvent lire la syntaxe du code mais passent à côté du « pourquoi » derrière les décisions.
Solution : Intégrez les connaissances métier directement dans des emplacements découvrables.
Au-delà de la configuration de base du projet, utilisez CLAUDE.md pour encoder des connaissances métier approfondies :
Personas et rôles :
CLAUDE.md
## Contexte métier
**Produit** : Plateforme SaaS de gestion d'événements (B2B, clients entreprise)
**Modèle économique** : Abonnement, tarification par paliers
**Proposition de valeur principale** : Intégration fluide avec 20+ fournisseurs de calendriers
## Principes de conception
1.**Idempotence avant tout** : Toutes les mutations API doivent être idempotentes (secteur événementiel = requêtes dupliquées fréquentes)
2.**Cohérence éventuelle** : La synchronisation des calendriers utilise une réconciliation par file d'attente (pas temps réel)
3.**Dégradation gracieuse** : Si l'API de calendrier externe échoue, stocker localement + réessayer (ne jamais bloquer l'utilisateur)
## Termes métier
-**Event** : Entrée de calendrier créée par l'utilisateur (notre modèle de domaine)
-**Appointment** : Terme utilisé par les systèmes de calendrier externes (Google/Outlook)
-**Sync Job** : Processus en arrière-plan réconciliant notre BDD avec les calendriers externes
-**Conflict Resolution** : Algorithme gérant les événements qui se chevauchent (voir `src/services/conflict-resolver.ts`)
## Pièges
- L'API Google Calendar a une limite de 10 req/sec par utilisateur → regrouper les opérations dans `syncEvents()`
- La gestion des fuseaux horaires d'Outlook n'est pas standard → utiliser le helper `normalizeTimezone()`
- La suppression d'événement = suppression douce (définir `deletedAt`) pour maintenir la piste d'audit à des fins de conformité
Pourquoi ça marche : Quand l’agent rencontre syncEvents(), il comprend la contrainte de limitation de débit. Quand il voit deletedAt, il sait qu’il ne faut pas utiliser de suppression définitive.
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 — utilisez des termes complets, des synonymes et des balises.
Utiliser 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 : Lorsqu’il travaille dans services/, l’agent lit le README et comprend les contraintes (pas de gestion HTTP, limites de couches).
Problème : Les agents doivent découvrir et consommer la documentation du projet efficacement. La documentation traditionnelle (wikis, Confluence) est difficile à trouver et à analyser. Les serveurs de documentation MCP nécessitent une installation et une configuration.
Solution : Utilisez le standard llms.txt pour l’indexation de documentation optimisée pour l’IA.
llms.txt est un standard léger pour rendre la documentation découvrable par les LLM. C’est comme robots.txt pour les agents IA — un fichier d’index simple qui indique aux agents où trouver la documentation pertinente.
Anthropic publie deux variantes LLM-optimized pour Claude Code :
Fichier
URL
Taille
Tokens (approx)
Cas d’usage
llms.txt
code.claude.com/docs/llms.txt
~65 pages
~15-20K
Index rapide, découverte de sections
llms-full.txt
code.claude.com/docs/llms-full.txt
~98 KB
~25-30K
Vérification des faits, doc complète, source de vérité
Pattern recommandé : récupérer llms.txt d’abord pour identifier la section pertinente, puis récupérer la page spécifique (ou llms-full.txt) pour les détails. Évite de charger 98 Ko quand seules 2 pages sont nécessaires.
Ces URLs sont la source officielle à consulter en priorité quand une affirmation sur Claude Code semble incertaine ou potentiellement obsolète.
Implémentation de ce guide : machine-readable/llms.txt
Source déconseillée : Les articles de blog spécifiques à un framework (présentent souvent llms.txt en opposition aux serveurs MCP, alors qu’ils sont complémentaires).
Problème : Les agents ont des limites de tokens. Les gros fichiers consomment rapidement le budget de contexte, forçant les agents à lire par morceaux et à perdre la cohérence.
Solution : Structurer le code pour minimiser l’utilisation des tokens tout en maximisant la compréhension des agents.
Découper les gros fichiers (les agents lisent par morceaux)
Recommandation : Garder 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
✅ Découpé 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 ignorer le blocage des domaines jetables (non évident à partir de « validation d’email ») ou ne pas gérer les caractères internationaux.
**Avantage pour l'agent** : Lorsqu'il travaille dans les contrôleurs, l'agent lit ADR-011 et sait qu'il doit appeler les services (pas les repositories).
---
### 9.18.8 Garde-fous et validation
**Problème** : Les agents font des erreurs — hallucinations, hypothèses incorrectes, lacunes de sécurité.
**Solution** : Des garde-fous multicouches pour intercepter les erreurs avant qu'elles n'atteignent la production.
#### Hooks comme validateurs d'anti-patterns
**Au-delà des secrets** : Utilisez les hooks pour faire respecter les conventions de la base de code.
**Exemple : Prévenir les violations de couches** :
```bash
#!/bin/bash
# .claude/hooks/PreToolUse.sh
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool.name')
if [[ "$TOOL_NAME" == "Edit" ]] || [[ "$TOOL_NAME" == "Write" ]]; then
Utilise des tokens OAuth 2.0 stockés dans le champ `users.calendar_token`. Si le token a expiré, lève `TokenExpiredError` (l'appelant doit rediriger vers la ré-authentification).
## Limites de débit
Google applique 10 requêtes/seconde par utilisateur. Le client limite automatiquement le débit via la bibliothèque rate-limiter-flexible. Voir RATE_LIMITS.md pour les détails.
La plupart des développeurs choisissent une approche et s’y tiennent. Pourtant, les outils de Claude Code permettent une variation systématique — tester plusieurs approches pour trouver la solution optimale.
Les frameworks de permutation formalisent cela : au lieu d’espérer que votre première approche fonctionne, vous générez et évaluez des variations de manière 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.
Temps de lecture : 5 minutes (vue d’ensemble) | Démarrage rapide → (8-10 min, pratique) | Guide complet → (~30 min, théorie)
Niveau de compétence : Mois 2+ (Avancé)
Statut : ⚠️ Expérimental (v2.1.32+, Opus 4.6 requis)
Les équipes d’agents permettent à plusieurs instances Claude de travailler en parallèle sur une base de code partagée, en se coordonnant de façon 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 fournis par les 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, pas d’état partagé)
Équipes d’agents = Claude gère la coordination automatiquement (base de code partagée, communication via git)
✅ Adapté : traçage de bugs (les agents lisent les journaux, tracent l'exécution)
✅ Adapté : analyse d'architecture (les agents lisent la structure)
⚠️ Risqué : refactorisation de types partagés (conflits de fusion)
⚠️ Risqué : modifications du schéma de base de données (migrations coordonnées)
❌ Inadapté : même fichier modifié par plusieurs agents (enfer des conflits)
Atténuation : attribuer des ensembles de fichiers sans chevauchement, adopter une approche interface-first, définir les contrats avant le travail en parallèle.
Intensité en tokens : multiplicateur de coût de 3x+ (3 agents = 3 inférences du modèle). Justifié uniquement lorsque le temps gagné dépasse l’augmentation 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 + membres prédéfinis
Ad hoc, sans hiérarchie
Coordination
Le chef assigne les tâches et synthétise
Chaque réviseur travaille indépendamment
Direction
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 des dépendances entre réviseurs
Revue indépendante, passe finale avant fusion
Quand l’utiliser
Flux de travail complexes, partage d’état nécessaire
Revue de PR, base de code inconnue, exhaustivité
Mode essaim en pratique (modèle compound-engineering d’Every.to) :
Lancez tous les réviseurs 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 tous les résultats et décidez des actions à entreprendre.
Terminal window
# Essaim : tous les réviseurs voient la même entrée et rapportent indépendamment
Ceci se distingue des équipes d’agents : il n’y a pas de structure d’équipe persistante, pas de contexte partagé entre les agents, pas de chef qui synthétise en temps réel. La configuration est plus rapide et cette approche est appropriée quand l’exhaustivité compte plus que la coordination.
Règle empirique : utilisez les équipes d’agents pour les flux de travail avec des dépendances séquentielles (la sortie de l’agent A alimente l’agent B). Utilisez l’essaim quand chaque réviseur peut travailler à partir du même point de départ et que vous souhaitez une couverture maximale avec un minimum de configuration.
Paul Rayner (PDG de Virtual Genius, auteur de l’EventStorming Handbook) :
« Je lance 3 sessions d’équipes d’agents en simultané dans des terminaux séparés. C’est impressionnant par rapport aux anciens flux de travail multi-terminaux sans coordination. »
Flux de travail utilisés (février 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 + du framework beads
Contexte : En février 2026, Anthropic a publié un manuel de modernisation COBOL positionnant Claude Code comme un remplacement direct des équipes de conseil traditionnelles sur les systèmes hérités. Le même jour, le cours de 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 à toute grande base de code héritée (COBOL, Fortran, VB6, PL/I), pas uniquement au COBOL.
Pourquoi la modernisation des systèmes hérités est difficile
Le vrai coût n’est pas la migration en elle-même — c’est la phase de découverte. Les développeurs d’origine sont à 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. Identifier ce qui communique avec quoi nécessite des consultants facturés à l’heure.
L’IA change l’économie de cette démarche 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 reposent sur des systèmes COBOL (Reuters/consensus industriel — la méthodologie varie selon les sources)
La modernisation nécessitait auparavant des projets pluriannuels mobilisant plusieurs équipes
Validation indépendante : Des recherches académiques (WJAETS 2025) montrent une réduction moyenne de -25 à -30 % des délais. Dans le meilleur des cas : Airbnb a migré 3 500 fichiers de tests en 6 semaines contre une estimation de 1,5 an. Précision de la conversion COBOL→Java : 93 % dans des études contrôlées (arXiv, avril 2025).
Étape 1 — Exploration et découverte automatisées
Cartographier l'ensemble de la base de code :
- Identifier tous les points d'entrée du programme 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
Modèle 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."
Étape 2 — Analyse des risques et cartographie des opportunités
Une fois le graphe de dépendances en main :
- Évaluer les niveaux de couplage entre les modules (fort couplage = risque élevé)
- Identifier les composants isolés comme candidats sûrs à la modernisation
- Repérer la logique dupliquée et le code mort
- Signaler l'état partagé comme les zones à risque le plus élevé
Modèle 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?"
É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 avec les 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 fonction pour la validation avant le début de la migration
Cette phase n’est pas entièrement automatisable — le contexte métier requiert le jugement humain.
Les workflows hybrides humain-IA affichent des taux de complétion dans les délais initiaux supérieurs de 31 %
par rapport aux approches purement automatisées (WJAETS 2025).
Étape 4 — Implémentation incrémentale
Ne jamais migrer l'ensemble du système d'un coup :
- Traduire la logique composant par composant
- Créer des wrappers API pour les composants hérités encore utilisés
- Faire tourner l'ancien et le nouveau code en parallèle en production
- Valider chaque composant indépendamment avant de passer au suivant
Modèle 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."
« Des années ramenées à des trimestres » est réel — mais c’est le scénario optimiste, pas la moyenne :
Scénario
Réduction du délai
Source
Estimation conservatrice
-25 à -30 %
Revue académique WJAETS 2025
Phases à forte automatisation
-40 à -50 %
Synthèse industrielle 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 de référence nécessitent des conditions favorables : une bonne couverture de tests, des modules isolés et une équipe qui comprend à la fois le système hérité et la pile cible.
❌ Migration big bang — Tout réécrire d’un coup. Aucune entreprise n’a survécu à cela à grande échelle.
❌ Pas d’exécution en parallèle — Basculer sans solution de repli. Un seul 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.
Temps de lecture : 7 minutes
Niveau de compétence : Semaine 2+
Statut : Research Preview (à partir de février 2026)
Disponibilité : Plans Pro et Max uniquement — non disponible sur les plans Team, Enterprise ou les clés API
Remote Control vous permet de surveiller et de contrôler une session Claude Code locale depuis un téléphone, une tablette ou un navigateur web — sans rien migrer 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 visualisateur distant. L’exécution reste toujours sur votre machine locale.
~10 min avant expiration de la session lors d’une déconnexion
Les slash commands ne fonctionnent pas à distance
/new, /compact, etc. sont traités comme du texte brut dans l’interface distante
Pro/Max uniquement
Non disponible sur les plans Team, Enterprise ou les clés API
⚠️ Limitation des slash commands : Lorsque vous tapez /new, /compact ou toute slash command dans l’interface distante (application mobile ou navigateur), elles sont traitées comme des messages texte ordinaires — et non transmises comme des commandes au CLI local. Utilisez les slash commands depuis votre terminal local à la place.
# Pane 1: claude → run /rc → share URL with your phone
# Pane 2: claude (local only)
# Pane 3: claude (local only)
# To switch which session you're controlling remotely:
# → Go to pane 2, run /rc (disconnects pane 1's remote, connects pane 2)
Chaque volet 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 volets.
Remote Control fonctionne sur des machines distantes (VMs, serveurs cloud) tournant dans tmux :
Terminal window
# On your cloud server (e.g., Clever Cloud, AWS, etc.):
tmuxnew-session-sclaude-server
clauderemote-control
# → Scan QR code from your phone
# → Control a cloud-hosted Claude session from mobile
# → Sessions survive laptop reboots (tmux keeps them alive)
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.
La session n’apparaît pas dans l’application Claude
Bug connu (Research Preview) — utilisez 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 — scannez avec l’appareil photo natif, ouvrez dans Safari plutôt que dans l’application Claude
Le QR code ne s’affiche pas
Appuyez sur la barre d’espace après le démarrage du contrôle à distance
Les slash commands ne fonctionnent pas
Tapez-les dans votre terminal local à la place
Session expirée
Reconnectez-vous : exécutez /rc à nouveau
Pare-feu d’entreprise bloquant
HTTPS sortant (port 443) doit être autorisé
Erreur « Not available »
Vérifiez l’abonnement Pro ou Max (pas Team/Enterprise)
Bug connu (Research Preview, 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 : ouvrez 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. Ces deux approches contournent entièrement le bug de synchronisation de l’application.
Temps de lecture : 8 minutes
Niveau de compétence : Mois 1+
Voir aussi : §9.10 État d’esprit d’amélioration continue — le fondement conceptuel de cette section. §9.23 est la couche opérationnelle : détecter le moment d’agir, et comment le faire.
À mesure que votre configuration Claude Code mûrit — skills, agents, rules, CLAUDE.md — un mode de défaillance silencieux émerge : votre configuration dérive par rapport à 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 rules couvrent des cas limites 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 se produit 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 du contexte vieux de 6 mois — l’agent raisonne à partir d’un modèle mental de la base de code qui n’existe plus
Une rule a été ajoutée pour un cas limite qui est maintenant le pattern par défaut — elle se déclenche constamment et vous avez arrêté de lire sa sortie
Vous avez corrigé la même erreur sur 5 sessions — mais rien n’a jamais capturé cette correction comme rule
Le signal est toujours là : vous continuez à faire les mêmes corrections manuelles. Le travail consiste à identifier lesquelles 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 mérite d’être encodée comme skill quand vous l’avez effectuée manuellement 3 fois ou plus 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 du skill échoue parce qu’une API ou un chemin a changé
La sortie nécessite une petite clarification que vous continuez à ajouter manuellement
Vous avez ajouté une convention que le skill ne reflète pas encore
Quand versionner un skill (mineur/majeur) :
Ajoutez un champ version et une date updated dans le frontmatter de votre skill :
minor (x.Y.z) : nouvelles instructions, portée étendue, nouveau comportement opt-in
major (X.y.z) : le comportement par défaut change — annotez ce qui a changé et quand dans votre CHANGELOG
Quand déprécier un skill :
Ajoutez un flag deprecated: true et une note expliquant ce qui le remplace. 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 façon informelle : quelque chose ne fonctionne pas bien → vous le remarquez → vous le corrigez. La différence, c’est de rendre l’étape « remarquer » systématique plutôt qu’accidentelle.
┌──────────────────────────────────────────────┐
│ LA BOUCLE DE MISE À JOUR │
│ │
│ Session → Observer les frictions │
│ (corrections répétées, │
│ échecs d'outils) │
│ ↓ │
│ Analyser la cause racine │
│ (quel skill/rule manque ?) │
│ ↓ │
│ Mise à jour delta │
│ (modification ciblée, │
│ pas réécriture) │
│ ↓ │
│ Test canary │
│ (vérifier que le fix tient) │
│ ↓ │
│ Session suivante → répéter │
└──────────────────────────────────────────────┘
Le principe de mise à jour delta : lors de la mise à jour d’un skill ou d’une rule, faites la modification ciblée la plus petite possible qui résout le problème observé. Ne réécrivez pas l’intégralité du skill — vous perdriez 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 :
# Ajouter à votre prompt de commande handoff
Avant de sauvegarder le contexte, répondez à :
- Quelles rules ou skills manquaient pour le travail d'aujourd'hui ?
- Quelles corrections avez-vous faites plus d'une fois ?
- Quelle est la modification la plus petite qui permettrait d'éviter le plus de frictions répétées ?
Sauvegardez les conclusions via : write_memory("retro_[date]", vos réponses)
Test canary d’un skill après mise à jour :
Avant de valider un changement de skill, vérifiez qu’il produit toujours la sortie attendue 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 façon programmatique en fonction d’une métrique et d’un ensemble d’exemples. Nécessite 20+ exemples étiquetés par skill pour des résultats fiables. Utile quand vous avez une tâche bien définie et suffisamment d’historique de sessions pour constituer un jeu de données. dspy.ai
TextGrad — traite les prompts comme des paramètres différentiables et itère en utilisant les retours générés par un LLM comme « gradients ». Plus 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 ni l’un ni l’autre 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 plupart de la valeur avec une fraction de la complexité.
Temps de lecture : 6 minutes
Niveau de compétence : Mois 2+
Relation avec §9.23 : L’Update Loop gère la maintenance délibérée de la configuration — vous détectez une dérive, vous la corrigez. L’apprentissage basé sur les instincts gère la capture incidente — des observations utiles que vous auriez autrement oubliées avant la fin de la session.
Les invites de fin de session standard (« qu’avez-vous appris lors de cette session ? ») produisent des résumés verbeux sur lesquels on agit rarement. La friction entre « observation » et « règle encodée » est suffisamment élevée pour que la plupart des corrections ne soient jamais réintégrées dans votre configuration.
Ce qui se retrouve réellement encodé : les corrections que vous faites deux fois, puis une troisième, jusqu’à ce que la répétition vous force à é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 du 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ée explicitement
Skill ou règle CLAUDE.md (haute confiance, 0.8+)
Chaque instinct suit : le contenu (l’observation), la confiance (0.0–1.0, commence bas et croît avec la confirmation), la source (quelle session/contexte), et la décroissance (la confiance baisse si non confirmée avec le temps).
Le choix de conception clé : capturer au hook Stop, pas à UserPromptSubmit.
Pourquoi Stop et non 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 — aucun impact sur la vitesse de session, et l’intégralité du contexte de 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 à la confirmation 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 manuelle par conception — c’est vous qui décidez ce qui est encodé. Le pipeline réduit la friction de la capture des observations, pas la friction de leur validation.
Ajoutez capture-instincts.sh comme hook Stop dans settings.json
Relisez chaque semaine — 5 minutes maximum
Promouvez 0 à 2 instincts à haute confiance par semaine ; supprimez le reste
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 le skill directement), les contournements ponctuels (laissez-les partir).
Crédit : Le pipeline d’apprentissage basé sur les instincts et le schéma de capture par 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.
Afficher les informations de session (contexte, coût)
Info
/usage
Vérifier les limites de débit et l’allocation de tokens
Info
/stats
Consulter les statistiques d’utilisation avec graphiques d’activité
Info
/output-style
Modifier le format de réponse (concis/détaillé/code)
Affichage
/feedback
Signaler des bugs ou envoyer des retours à Anthropic
Support
/chrome
Vérifier la connexion Chrome, gérer les permissions
Mode
/config
Consulter et modifier les paramètres globaux
Config
/copy
Copier la dernière réponse dans le presse-papiers — sélecteur interactif pour choisir des blocs de code spécifiques, ou option « Toujours copier la réponse complète » (v2.1.59+)
Session
/debug
Dépannage systématique et investigation des erreurs
Debug
/doctor
Lancer des diagnostics et vérifications de dépannage
Debug
/execute
Quitter le Plan Mode
Mode
/exit
Quitter Claude Code
Session
/fast
Activer/désactiver le mode rapide (Opus 4.6, 2.5x plus rapide, 6x le prix)
Mode
/hooks
Configuration interactive des hooks
Config
/init
Générer un CLAUDE.md de départ basé sur la structure du projet — ⚠️ la sortie est générée par LLM ; relisez et élagez avant de committer (la recherche de l’ETH Zürich montre que les fichiers de contexte auto-générés réduisent le taux de succès des tâches agents d’environ 3 % et augmentent le coût d’inférence de plus de 20 %)
Config
/login
Se connecter au compte Claude
Auth
/logout
Se déconnecter et se ré-authentifier
Auth
/loop [interval] [prompt]
Exécuter une invite ou une slash command à intervalle régulier (ex. /loop 5m check the deploy) — v2.1.71+
Automatisation
/mcp
Gérer les serveurs Model Context Protocol
Config
/memory
Consulter et modifier la mémoire automatique (contexte que Claude a automatiquement sauvegardé entre les sessions via MEMORY.md) — v2.1.59+
Config
/mobile
Afficher les liens de téléchargement App Store et Google Play
Info
/model
Changer de modèle (avec les flèches gauche/droite pour le curseur d’effort)
Mode
/permissions
Configurer les listes d’autorisation des permissions
Config
/plan
Entrer en Plan Mode
Mode
/plugin
Parcourir et installer des plugins Claude Code
Config
/remote-control (/rc)
Démarrer une session de contrôle à distance (Pro/Max uniquement)
Mode
/rename
Donner un nom descriptif à la session actuelle
Session
/resume
Reprendre une session précédente (depuis une session en cours)
Session
/rewind
Ouvrir le menu de retour en arrière pour annuler les modifications récentes
Édition
/sandbox
Activer l’isolation au niveau du système d’exploitation
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 ne s’active que lorsque le mode vocal est actif.
Définissez-les 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
Remplacer 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 built-in (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
Pour les variables configurables via la clé "env" dans settings.json (notamment MAX_THINKING_TOKENS, CLAUDE_CODE_SHELL, CLAUDE_CODE_ENABLE_TASKS, ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL et d’autres), voir la section 10.3 Référence de configuration.
Combinaisons courantes :
Terminal window
# Mode CI/CD - non interactif avec acceptation automatique
Dépannage interactif : Utilisez la commande /diagnose pour une résolution de problèmes guidée et interactive. Elle analyse automatiquement votre environnement et fournit des solutions ciblées. Voir examples/commands/diagnose.md.