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

Habr a publié la traduction d'un long texte pratique sur Claude Code, fondé sur six mois de travail intensif avec l'agent. Il ne s'agit pas d'un récapitulatif de fonctionnalités, mais d'une analyse des raisons pour lesquelles un outil d'IA pour le développement se met à dérailler quand on lui donne trop de contexte, de règles et de liberté à la fois.

Où le contexte se perd

L'idée maîtresse de l'article est simple : Claude Code ne plante pas parce que le modèle serait « pas assez intelligent », mais parce que l'environnement d'ingénierie qui l'entoure est mal conçu. L'auteur décrit l'agent comme une boucle de collecte de contexte, d'action et de vérification du résultat. Si ne serait-ce qu'une couche de cette boucle est surchargée, la qualité chute nettement : un CLAUDE.md trop long fait du bruit, des dizaines d'outils compliquent le choix, et l'absence de vérification rapide transforme chaque modification en loterie. Dans ce régime, le développeur tourne sans fin autour de ses prompts, alors que le problème est plus profond.

Le texte examine aussi le coût du contexte. Sur le papier, Claude Code dispose d'une grande fenêtre, mais une part importante des tokens est dépensée avant même le début du travail : instructions système, descripteurs de skills, descriptions des outils MCP, état LSP, mémoire et CLAUDE.md du projet. L'auteur livre un calcul parlant : un serveur MCP typique peut occuper des milliers de tokens rien qu'en schémas d'outils, et plusieurs serveurs connectés avalent facilement une part notable de la fenêtre disponible. Ajoutez-y les longues sorties de tests, de grep et de logs, et l'historique utile de la conversation se retrouve évincé de lui-même.

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

En découle une conclusion pratique : les connaissances rarement utilisées ne doivent pas vivre dans un contexte chargé en permanence. Pour changer de tâche, mieux vaut nettoyer la session plus souvent ; pour poursuivre dans la même direction, recourir à une compression maîtrisée. Autre conseil de l'article : demander à l'agent, avant une nouvelle session, de produire un HANDOFF.md avec l'avancement, les impasses et l'état de la vérification. C'est moins coûteux et plus fiable que d'espérer que le compaction automatique préserve les décisions d'architecture réellement importantes.

Skills, hooks et agents

Le deuxième grand bloc porte sur la séparation des rôles. L'auteur recommande de ne pas mélanger MCP, tools, skills, hooks, plugins et subagents. La logique : l'outil apporte une nouvelle capacité, le skill définit un flux de travail, le hook intègre une vérification automatique obligatoire, et le subagent déporte une tâche dans un contexte isolé. La précision est utile, car de nombreuses équipes cherchent à soigner chaque défaillance par un nouveau prompt ou un énième tool, alors que le problème peut se résoudre à un tout autre niveau.

L'article détaille aussi les qualités d'un bon skill : un descripteur court et précis, un déclencheur d'usage clair, des entrées, des sorties et une condition d'arrêt explicites. Tout ce qui est lourd — exemples, runbooks, fichiers annexes — doit être chargé à la demande, et non figurer dans le SKILL.md principal. Pour les actions à effets de bord, l'auteur conseille de désactiver explicitement le déclenchement automatique par le modèle. L'idée : l'agent voit d'abord un index et un itinéraire, et ne charge les détails qu'au moment où ils sont réellement nécessaires.

Dans cette analyse, les subagents ne sont pas présentés comme un moyen de « tout accélérer en parallèle », mais comme un outil d'isolation. L'exploration de la base de code, la relecture, l'exécution des tests et les autres opérations bruyantes gagnent à être confiées à des fils enfants aux droits limités, avec un modèle dédié et un format de réponse fixe. Les hooks, à l'inverse, doivent attraper le plus tôt possible tout ce qui est déterministe : lancer une vérification rapide après la modification d'un fichier, bloquer les changements dangereux, injecter du contexte technique au démarrage de la session. Plus tôt le système repère l'erreur, moins de tokens, de temps et de modifications inutiles partent à la poubelle.

Cache, vérification et contrat

L'une des parties les plus intéressantes du texte explique à quel point l'architecture de Claude Code repose sur le prompt caching. L'auteur écrit qu'un préfixe de prompt stable fait économiser non seulement de l'argent, mais réduit aussi la friction avec les limites d'usage. D'où plusieurs règles peu intuitives : ne pas insérer de données dynamiques dans le prompt système, ne pas mélanger l'ordre des outils, ne pas changer de modèle au milieu d'une longue session sans nécessité et, si possible, différer le chargement complet des schémas de tools rares. Même le Plan Mode, note l'article, gagne à être implémenté sans changer tout le jeu d'outils, afin de ne pas casser le cache.

L'accent final porte sur la vérification et le rôle du CLAUDE.md. L'auteur qualifie ce fichier non de base de connaissances, mais de contrat entre le projet et l'agent : comment compiler, comment tester, quelles limites ne pas franchir, ce qu'il faut absolument conserver lors de la compression, quelles interdictions s'appliquent en permanence. Inutile d'y faire entrer des références d'API ni de longues introductions ; n'y vivent que les règles critiques dans chaque session. Autre conseil : après chaque erreur récurrente, demander à l'agent de mettre à jour son contrat, afin que les écarts typiques ne reviennent pas.

«

Si vous ne pouvez pas expliquer comment savoir que Claude a fait le travail correctement, la tâche ne se prête probablement pas à une exécution entièrement automatique ».

Ce que cela signifie

Ce texte importe au-delà des seuls utilisateurs de Claude Code. Il s'agit au fond d'un guide de maturation pour tous les agents d'IA dédiés au développement : moins de magie, plus d'isolation, de vérification explicite et de maîtrise du contexte. Plus les équipes passent du « chatbot pour le code » à un ingénieur semi-autonome, plus ces pratiques prennent de la valeur, bien davantage que de nouvelles collections de prompts.