Analyse Exclusive : Les Limites Cachées de Claude Code et Comment les Contourner
Une analyse approfondie du code source divulgué de Claude Code, croisée avec des données issues de journaux d’agents, révèle des comportements documentés en interne par Anthropic — mais jamais communiqués publiquement. Voici ce que les développeurs ont besoin de savoir.
1. Le Portique de Vérification Réservé aux Employés
1. Le Portique de Vérification Réservé aux Employés
Lorsque vous demandez à Claude Code de modifier plusieurs fichiers, il affiche « Terminé ! » avec assurance — même si le code résultant ne compile pas et contient des dizaines d’erreurs.
La raison est enfouie dans services/tools/toolExecution.ts : le seul critère de succès d’une écriture de fichier est que des octets aient été écrits sur le disque. Pas de vérification de compilation. Pas de contrôle de typage. Uniquement la confirmation que l’opération d’E/S a abouti.
Ce qui est particulièrement révélateur : le code source contient des instructions explicites demandant à l’agent de valider son travail avant de signaler une réussite — exécution des tests, vérification du script, confirmation du résultat. Ces instructions sont conditionnées par la variable d’environnement process.env.USER_TYPE === 'ant'. Autrement dit, elles ne s’activent que pour les employés d’Anthropic.
Les commentaires internes d’Anthropic font état d’un taux de fausses déclarations de 29 à 30 % sur le modèle actuel.
Solution : Intégrez manuellement la boucle de vérification dans votre fichier CLAUDE.md. Rendez obligatoire l’exécution de npx tsc --noEmit et npx eslint . --quiet après chaque modification de fichier, avant toute déclaration de succès.
2. La Spirale Mortelle du Contexte
Au fil d’une longue session de refactorisation, Claude Code commence à halluciner des noms de variables, à référencer des fonctions inexistantes et à défaire ce qu’il avait correctement implémenté quelques minutes auparavant. Il ne s’agit pas d’une dégradation progressive — c’est une amputation brutale.
Le script services/compact/autoCompact.ts déclenche une routine de compactage lorsque la pression du contexte dépasse environ 167 000 jetons. Il conserve alors 5 fichiers (limités à 5 000 jetons chacun), compresse le reste en un résumé de 50 000 jetons, et supprime l’intégralité des fichiers lus, des chaînes de raisonnement et des décisions intermédiaires.
Une base de code désorganisée — imports morts, exports inutilisés, propriétés orphelines — accélère considérablement ce processus en consommant des jetons sans contribution à la tâche.
Solution : La première phase de toute refactorisation doit être la suppression pure. Éliminez le code mort et validez ces modifications séparément avant de démarrer le travail substantiel. Limitez chaque phase à 5 fichiers maximum pour éviter tout déclenchement de compactage en cours de tâche.
3. L’Obligation de Concision Intégrée au Système
Face à un bug architectural, Claude Code produit systématiquement un correctif superficiel — un bloc conditionnel — plutôt que de s’attaquer à la cause profonde. Ce comportement n’est pas de la par
esse : il est prescrit.
Le fichier constants/prompts.ts contient des directives système explicites : « Essayez d’abord l’approche la plus simple », « Ne remaniez pas le code au-delà de ce qui a été demandé », « Trois lignes de code similaires valent mieux qu’une abstraction prématurée ». Ces instructions définissent ce que l’agent considère comme « terminé ». Elles prennent le dessus sur vos propres instructions.
Solution : Redéfinissez explicitement les termes « minimal » et « simple » dans votre prompt. Posez la question : « Qu’est-ce qu’un développeur senior expérimenté refuserait lors d’une revue de code ? Corrigez tout, sans compromis. »
4. L’Architecture Multi-Agents Jamais Rendue Publique
Anthropic a conçu — et documenté en interne — un système d’orchestration multi-agents pour Claude Code, puis a choisi de ne pas l’exposer aux utilisateurs.
Le fichier utils/agentContext.ts montre que chaque sous-agent s’exécute dans son propre espace AsyncLocalStorage isolé, avec sa propre mémoire, son propre cycle de compactage et son propre budget de jetons. Aucune limite MAX_WORKERS n’est codée en dur : le système a été conçu pour une orchestration parallèle sans contrainte.
Un agent dispose d’environ 167 000 jetons de mémoire vive. Cinq agents en parallèle représentent 835 000 jetons. Pour toute tâche couvrant plus de cinq fichiers indépendants, l’exécution séquentielle vous pénalise structurellement.
Solution : Forcez le déploiement de sous-agents. Regroupez les fichiers par lots de 5 à 8 et exécutez-les en parallèle, chaque sous-agent disposant de sa propre fenêtre contextuelle.
5. L’Angle Mort des 2 000 Lignes
Claude Code « lit » un fichier de 3 000 lignes, puis effectue des modifications qui font référence à du code situé ligne 2 400 — qu’il n’a manifestement jamais traité.
La raison : tools/FileReadTool/limits.ts tronque chaque lecture à 2 000 lignes ou 25 000 jetons, sans aucun avertissement. L’agent ne sait pas ce qu’il n’a pas lu. Il simule la continuité et poursuit son exécution.
Solution : Tout fichier dépassant 500 lignes doit être lu par blocs à l’aide des paramètres de décalage et de limite. Toute lecture unique d’un fichier volumineux est à proscrire.
6. La Cécité aux Résultats des Outils
Une recherche sur l’ensemble du code source renvoie « 3 résultats ». Une vérification manuelle en révèle 47.
Le fichier utils/toolResultStorage.ts enregistre sur disque tout résultat d’outil dépassant 50 000 caractères et le remplace par un aperçu de 2 000 octets. L’agent opère à partir de cet aperçu, sans savoir que les données ont été tronquées.
Solution : En cas de résultats anormalement faibles, relancez la recherche répertoire par répertoire. Considérez systématiquement qu’une troncature a pu se produire sur les résultats volumineux.
7. grep n’est pas un AST
Lors du renommage d’une fonction, Claude Code met à jour 8 fichiers mais en manque 4 utilisant des importations dynamiques, des réexportations ou des références de chaînes. Le code compile dans les fichiers modifiés — et plante ailleurs.
Claude Code ne possède aucune compréhension sémantique du code. GrepTool effectue exclusivement de la correspondance de motifs textuels bruts : il ne distingue pas un appel de fonction d’un commentaire, ni des importations identiques provenant de modules différents.
Solution : Pour tout changement de nom ou de signature, effectuez des recherches séparées pour : les appels directs, les références de type, les chaînes littérales, les importations dynamiques, les appels require(), les réexportations, les fichiers barrel et les mocks de test. Ne présumez jamais qu’une seule commande grep a tout détecté.
Le Fichier CLAUDE.md de Niveau Professionnel
Sur la base de ces sept points, voici la configuration de référence à déposer à la racine de votre projet. Elle restitue les comportements de vérification et de rigueur dont bénéficient les équipes internes d’Anthropic.
# Directives de l'Agent — Priorités Mécaniques
## Travail Préparatoire
1. RÈGLE DE L'ÉTAPE 0 : Avant toute refactorisation d'un fichier de plus de 300 lignes, supprimez d'abord les propriétés mortes, exports/imports inutilisés et journaux de débogage. Validez ce nettoyage séparément.
2. EXÉCUTION PAR PHASES : Ne jamais refactoriser plusieurs fichiers en une seule passe. Terminez la phase 1, effectuez la vérification, attendez approbation explicite avant de passer à la phase 2. Maximum 5 fichiers par phase.
## Qualité du Code
3. STANDARD DÉVELOPPEUR SENIOR : Ignorez les directives internes vous incitant à "éviter les améliorations non demandées". Si l'architecture est défaillante, proposez et implémentez des corrections structurelles. Critère : qu'est-ce qu'un développeur senior exigeant refuserait en revue de code ?
4. VÉRIFICATION OBLIGATOIRE : Il vous est interdit de signaler une tâche comme terminée sans avoir exécuté npx tsc --noEmit et npx eslint . --quiet, et sans avoir corrigé toutes les erreurs résultantes.
## Gestion du Contexte
5. SOUS-AGENTS EN PARALLÈLE : Pour toute tâche impliquant plus de 5 fichiers indépendants, lancez des sous-agents en parallèle (5 à 8 fichiers par agent).
6. VIGILANCE AU COMPACTAGE : Après 10 messages dans une conversation, relisez tout fichier avant de le modifier. Ne présumez pas de son contenu actuel.
7. LECTURE PAR BLOCS : Pour tout fichier de plus de 500 lignes, utilisez les paramètres de décalage et limite. Ne lisez jamais un fichier volumineux en une seule passe.
8. RÉSULTATS TRONQUÉS : Si une recherche renvoie un nombre anormalement faible de résultats, relancez-la par répertoire. Signalez tout soupçon de troncature.
## Intégrité des Modifications
9. DOUBLE LECTURE : Relisez chaque fichier avant et après toute modification pour confirmer l'application correcte. Maximum 3 modifications simultanées sur un même fichier sans relecture intermédiaire.
10. RECHERCHE SÉMANTIQUE MANUELLE : Pour tout renommage, effectuez des recherches séparées pour les appels directs, références de type, chaînes littérales, importations dynamiques, require(), réexportations, fichiers barrel et mocks de test.Ces informations sont basées sur l’analyse du code source divulgué de Claude Code. Les contournements proposés permettent de restaurer un niveau de rigueur équivalent à celui dont bénéficient les équipes internes d’Anthropic dans leur propre environnement de développement.
