Claude Code sans magie : Habr analyse l’architecture, le bruit de contexte et les pratiques d’ingénierie

Sur Habr, une traduction d'un grand texte pratique sur Claude Code a été publiée, basée sur six mois de travail intensif avec l'agent. Ce n'est pas un récapitulatif des fonctionnalités, mais une analyse de la raison pour laquelle un outil d'IA pour le développement commence à mal fonctionner quand on lui donne trop de contexte, de règles et de liberté simultanément.

Où le Contexte se Perd

L'idée principale de l'article est simple : Claude Code ne se casse pas parce que le modèle « n'est pas assez intelligent », mais parce que l'environnement d'ingénierie qui l'entoure est mal structuré. L'auteur décrit l'agent comme un cycle de collecte de contexte, d'action et de vérification des résultats. Si même une couche dans ce cycle est surchargée, la qualité chute drastiquement : un long CLAUDE.md génère du bruit, des dizaines d'outils compliquent la prise de décision, et l'absence de vérification rapide transforme chaque modification en pari. Dans un tel mode, le développeur commence à ajuster sans fin les prompts, bien que le problème soit plus profond.

Le coût du contexte est discuté séparément. Formellement, Claude Code a une grande fenêtre, mais une portion importante de tokens est dépensée avant même que le travail ne commence : sur les instructions système, les descripteurs de skills, les descriptions des outils MCP, l'état LSP, la mémoire et le CLAUDE.md du projet. L'auteur fournit un calcul révélateur : un seul serveur MCP typique peut occuper des milliers de tokens juste pour les schémas d'outils, et quelques serveurs connectés consomment facilement une portion notable de la fenêtre disponible. Ajoutez à cela les longs résultats de tests, grep et logs—et l'historique de dialogue utile commence à être déplacé de lui-même.

• Instructions système et règles de base
• Descriptions de skills et outils MCP
• Mémoire du projet et contenu de CLAUDE.md
• Résultats des appels shell, tests et recherches
• Historique de session compressé, mais pas toujours exact

De cela découle une conclusion pratique : les connaissances rarement utilisées ne devraient pas vivre dans un contexte constamment chargé. Quand on change de tâche, il est préférable d'utiliser plus souvent le nettoyage de session ; pour continuer dans une direction—compression gérée. Un autre conseil de l'article : demander à l'agent avant une nouvelle session de rassembler HANDOFF.md avec la progression, les impasses et l'état de vérification. C'est moins cher et plus fiable que d'espérer que la compaction automatique préservera véritablement les décisions architecturales importantes.

Skills, Hooks et Agents

La deuxième section importante est consacrée à la séparation des rôles. L'auteur suggère de ne pas mélanger MCP, outils, skills, hooks, plugins et subagents en un seul tas. La logique est : un outil fournit une nouvelle capacité, un skill établit le flux de travail, un hook incorpore une vérification automatique obligatoire, et un subagent isole une tâche séparée dans un contexte isolé. C'est une clarification utile car de nombreuses équipes tentent de corriger toute défaillance avec un nouveau prompt ou un autre outil, alors que le problème pourrait être résolu à un niveau complètement différent.

L'article explique séparément ce qu'un bon skill devrait être. Il a un descripteur court et précis, un déclencheur d'utilisation compréhensible, des entrées documentées, des sorties et une condition d'arrêt. Tout ce qui est lourd—exemples, runbooks, fichiers auxiliaires—doit être tiré à la demande, pas suspendu dans le SKILL.md principal. Pour les actions avec des effets secondaires, l'auteur conseille de désactiver explicitement l'exécution automatique par le modèle. L'idée est que l'agent voie d'abord l'index et la route, puis charge les détails seulement quand ils sont vraiment nécessaires.

Les subagents dans cette analyse sont présentés non pas comme un moyen d'« accélérer tout en parallèle », mais comme un moyen d'isolation. La recherche de la base de code, l'examen, l'exécution de tests et autres opérations bruyantes sont mieux envoyés aux threads enfants avec des permissions limitées, un modèle séparé et un format de réponse fixe. Les hooks, en revanche, doivent capturer les choses déterministes dès que possible : exécuter une vérification rapide après l'édition de fichier, bloquer les modifications dangereuses, mélanger le contexte technique au démarrage de la session. Plus tôt le système attrape une erreur, moins de tokens, de temps et de modifications inutiles sont gaspillés.

Cache, Vérification et Contrat

L'une des parties les plus intéressantes du texte est l'explication de la dépendance de l'architecture de Claude Code au prompt caching. L'auteur écrit qu'un préfixe de prompt stable économise non seulement de l'argent, mais réduit également les frictions avec les limites. De là viennent plusieurs règles non évidentes : ne pas insérer de données dynamiques dans le prompt système, ne pas brasser l'ordre des instructions, ne pas changer de modèle au milieu d'une longue session sans nécessité, et autant que possible, différer le chargement complet des schémas d'outils rares. Même Plan Mode, comme noté dans l'article, est plus pratique à implémenter sans changer l'ensemble complet des outils, pour éviter de casser le cache.

L'accent final est mis sur la vérification et le rôle de CLAUDE.md. L'auteur appelle ce fichier non pas une base de connaissances, mais un contrat entre le projet et l'agent : comment collecter, comment tester, quelles limites ne peuvent pas être violées, ce qui doit être préservé lors de la compression, quelles interdictions s'appliquent toujours. CLAUDE.md n'a pas besoin d'apporter des références API et de longues introductions ; seules les règles critiques dans chaque session devraient y vivre. Un conseil séparé : après chaque erreur répétée, demander à l'agent de mettre à jour son contrat pour que les erreurs types ne reviennent pas.

«

Si vous ne pouvez pas expliquer comment savoir que Claude l'a bien fait, la tâche n'est probablement pas appropriée pour une exécution totalement automatique. »

Ce que Cela Signifie

Ce matériel est important non seulement pour les utilisateurs de Claude Code. Essentiellement, c'est une instruction pour la maturation de tout agent d'IA pour le développement : moins de magie, plus d'isolement, de vérification explicite et de contrôle du contexte. Plus activement les équipes passent de « chatbot de code » à ingénieur semi-autonome, plus précieuses deviennent exactement ces pratiques, plutôt qu'une autre collection de prompts.