0. TL;DR
Cet article découle de six mois d'utilisation intensive de Claude Code et des leçons apprises en dépensant 40 $/mois sur deux comptes. J'espère apporter des conseils précieux à tout le monde.
Au début, je l'utilisais comme un chatbot, mais j'ai vite réalisé que les choses tournaient mal : le contexte devenait désordonné, les outils augmentaient mais l'efficacité diminuait, et les règles étaient ignorées malgré leur longueur. Après avoir étudié Claude Code lui-même, j'ai compris que ce n'était pas un problème de prompt, mais un problème de conception système.
Je veux aborder : comment Claude Code fonctionne sous le capot, pourquoi le contexte devient désordonné et comment le gouverner, comment concevoir des Skills et des Hooks, l'utilisation correcte des Subagents, l'impact architectural du Prompt Caching, et comment rédiger un CLAUDE.md vraiment utile.
La façon la plus directe de le comprendre est de décomposer Claude Code en six couches :
Renforcer une seule couche provoque un déséquilibre. Si CLAUDE.md est trop long, il pollue le contexte ; trop d'outils créent de la confusion ; trop de sous-agents entraînent une dérive d'état ; sauter la vérification rend impossible de trouver où les choses ont échoué.
1. Comment ça fonctionne sous le capot
Le cœur de Claude Code n'est pas de « répondre », mais une boucle agentique répétée :
1Collect Context → Take Action → Verify Result → [Finish or Loop]2 ↑ ↓3 CLAUDE.md Hooks / Permissions / Sandbox4 Skills Tools / MCP5 Memory
J'ai réalisé que les goulets d'étranglement sont rarement dus à un modèle pas assez intelligent, mais plutôt au fait de lui donner un mauvais contexte ou de ne pas avoir de moyen de juger si la sortie est correcte ou de revenir en arrière.
Cinq couches sur lesquelles se concentrer :
Examiner ces couches facilite le dépannage. Résultats instables ? Vérifiez l'ordre de chargement du contexte. Automatisation hors de contrôle ? Vérifiez la couche de contrôle. Qualité en baisse dans les longues sessions ? Les produits intermédiaires ont pollué le contexte ; mieux vaut démarrer une nouvelle session que de modifier les prompts.
2. Frontières conceptuelles : MCP / Plugin / Tools / Skills / Hooks / Subagents
Règle simple : utilisez Tools/MCP pour les nouvelles actions, Skills pour les workflows, Subagents pour les environnements isolés, Hooks pour les contraintes/audits obligatoires, et Plugins pour la distribution inter-projets.
3. Ingénierie du contexte : la contrainte système la plus importante
Beaucoup traitent le contexte comme un « problème de capacité », mais le goulot d'étranglement est généralement le bruit. Les informations utiles sont enterrées dans un contenu non pertinent.
Composition du coût réel du contexte
Le contexte 200K de Claude Code n'est pas entièrement disponible :
1200K Total Context2├── Fixed Overhead (~15-20K)3│ ├── System instructions: ~2K4│ ├── Skill descriptors: ~1-5K5│ ├── MCP Server tool definitions: ~10-20K ← The biggest hidden killer6│ └── LSP state: ~2-5K7│8├── Semi-fixed (~5-10K)9│ ├── CLAUDE.md: ~2-5K10│ └── Memory: ~1-2K11│12└── Dynamic Available (~160-180K)13 ├── Chat history14 ├── File content15 └── Tool results
Un serveur MCP typique (comme GitHub) contient 20 à 30 définitions d'outils, chacune ~200 tokens, totalisant 4 000 à 6 000 tokens. Connecter 5 serveurs consomme 25 000 tokens (12,5 %). Ceci est critique lors de la lecture de grandes quantités de code.
Hiérarchisation recommandée du contexte
1Always Resident → CLAUDE.md: Project contract / build commands / prohibitions2Path-based → rules: Language / directory / file-type specific rules3On-demand → Skills: Workflows / domain knowledge4Isolated → Subagents: Large-scale exploration / parallel research5Outside Context → Hooks: Deterministic scripts / auditing / blocking
Ne chargez pas des choses que vous n'utilisez qu'occasionnellement.
Bonnes pratiques du contexte
- Gardez CLAUDE.md court, dur et exécutable. Celui d'Anthropic fait ~2,5K tokens.
- Déplacez les gros documents de référence vers les fichiers de support des Skills.
- Utilisez .claude/rules/ pour les règles de chemin/langue.
- Utilisez /context pour surveiller la consommation.
- Utilisez /clear pour changer de tâche et /compact pour les nouvelles phases.
- Écrivez des instructions compactes dans CLAUDE.md pour contrôler ce qui est préservé.
Bruit de sortie des outils : un autre tueur caché
Les sorties d'outils dynamiques (comme cargo test ou git log) peuvent facilement remplir le contexte. Claude n'a pas besoin de tout voir.
RTK (Rust Token Killer) est une bonne approche : il filtre la sortie des commandes avant qu'elle n'atteigne Claude. Par exemple, il peut condenser des milliers de lignes de sortie de test en un seul message de succès.
Pièges de la compression
La compression par défaut pourrait supprimer les décisions architecturales et les contraintes.
Solution : spécifiez des instructions compactes dans CLAUDE.md pour prioriser les décisions architecturales, les fichiers modifiés, l'état de vérification et les TODO.
Une autre solution proactive : demandez à Claude d'écrire un HANDOFF.md avant de démarrer une nouvelle session pour expliquer la progression et les impasses.
Valeur d'ingénierie du mode Plan
Le mode Plan sépare l'exploration de l'exécution.
Pour un refactoring complexe, c'est mieux que de se précipiter vers le code. Astuce avancée : utilisez un Claude pour rédiger le plan et un autre en tant qu'« ingénieur senior » pour le réviser.
4. Conception des Skills : workflows chargés à la demande
Les Skills sont des connaissances et workflows chargés à la demande.
Ce qui fait un bon Skill
- La description doit dire « quand m'utiliser », pas « ce que je fais ».
- Ayez des étapes, des entrées, des sorties et des conditions d'arrêt complètes.
- Gardez le corps principal pour la navigation et les principales contraintes ; déplacez les détails dans des fichiers de support.
- Définissez disable-model-invocation: true pour les Skills qui ont des effets secondaires.
Divulgation progressive
Claude Code met l'accent sur la « divulgation progressive » : fournissez d'abord des indices et de la navigation, puis tirez les détails selon les besoins.
Trois types de Skills typiques
- Checklist (Porte de qualité) : par ex., release-check.
- Workflow (Ops standardisées) : par ex., config-migration avec rollback.
- Expert domaine (Cadre de décision) : par ex., runtime-diagnosis.
Gardez les descripteurs courts pour économiser de l'espace dans le contexte.
5. Conception des outils : aider Claude à choisir correctement
Les outils pour agents doivent se concentrer sur la facilité d'utilisation correcte plutôt que sur l'exhaustivité des fonctionnalités.
Bons vs mauvais outils
Principes de conception : utilisez des préfixes (github_pr_*), supportez des formats concis, fournissez des messages d'erreur utiles et évitez d'exposer trop d'outils fragmentés.
Évolution des outils internes
L'évolution de l'outil « AskUserQuestion » montre qu'un outil dédié est plus stable que le formatage markdown ou les paramètres de sortie.
Les outils Todo sont devenus une « entrave » à mesure que les modèles se renforçaient. Les outils de recherche ont évolué de RAG à Grep pour une meilleure flexibilité et une « divulgation progressive ».
6. Hooks : logique obligatoire avant/après les opérations
Les Hooks reprennent le contrôle déterministe sur des processus comme le formatage, la protection des fichiers et les notifications.
Adapté aux Hooks
Blocage des fichiers protégés, auto-formatage après modifications, injection de contexte dynamique (branche Git), et notifications.
Détection précoce des erreurs
7. Subagents : instances Claude indépendantes
Les Subagents offrent l'isolement. Des tâches comme scanner des dépôts ou exécuter des tests produisent une sortie massive qui ne devrait pas encombrer le thread principal.
Contraintes explicites
Limitez les outils, choisissez le bon modèle (Haiku pour l'exploration, Opus pour la révision) et définissez maxTurns.
8. Prompt Caching : le cœur de l'architecture de Claude Code
Claude Code est construit autour du Prompt Caching. Des taux de succès élevés économisent de l'argent et augmentent les limites de taux.
Disposition du prompt pour le caching
L'ordre est important pour la correspondance des préfixes : System Prompt → Tool Definitions → Chat History → User Input.
Ne changez pas de modèle en cours de session
Changer de modèle casse le cache. Utilisez plutôt les Subagents pour les transferts.
Implémentation de la compaction
La compaction utilise un fork pour résumer l'historique à 1/10e du coût grâce aux succès de cache.
9. Boucles de vérification : pas de vérificateur, pas d'agent d'ingénierie
« Claude dit que c'est fait » est inutile sans vérification. Définissez la vérification explicitement dans le Prompt, le Skill et CLAUDE.md.
10. Commandes à haute fréquence
Des commandes comme /context, /clear, /compact et /memory aident à gérer le contexte activement.
Gouvernance et parallélisme
Commandes cachées utiles : /simplify (revue de code), /rewind (points de contrôle), /btw (questions secondaires), /insight (analyse de la session pour les mises à jour de CLAUDE.md).
11. Comment rédiger un bon CLAUDE.md
C'est un contrat, pas une base de connaissances.
Incluez les commandes de build/test, les limites d'architecture, les conventions de codage, les garde-fous de sécurité et les instructions compactes. Demandez à Claude de mettre à jour CLAUDE.md après avoir corrigé ses erreurs.
12. Expériences récentes
Leçons de la construction de Kaku (Rust + Lua) : la transparence de l'environnement est vitale (utilisez une commande 'doctor'), et les Hooks sont excellents pour les projets multilingues.
13. Anti-patrons
14. Vérification de santé
Utilisez npx skills add tw93/claude-health pour vérifier votre configuration.
15. Conclusion
L'accent passe de « comment utiliser les fonctionnalités » à « comment laisser l'agent fonctionner sous contraintes ». Si vous ne pouvez pas définir « fait », la tâche n'est pas prête pour un agent.
