Vous demandez à Cursor Agent de modifier le module paiement dans un monorepo, et il touche aux DTO du centre utilisateur. Claude Code enchaîne vingt tours bash, puis oublie « ne jamais importer directement les packages legacy internes ». Ce n'est pas le modèle qui devient soudain moins intelligent — c'est le mode de défaillance le plus courant dans les grands projets : la perte de contexte.
En 2026, Cursor et Claude Code vantent tous deux un contexte million de tokens, mais sur le terrain « a oublié notre accord » reste fréquent. Cet article livre une méthode de dépannage en cinq étapes reproductible : d'abord classifier comment le contexte a été perdu, puis vérifier budget, index, limites, conventions du dépôt et stratégie de session. Versions des outils au 2026-07-17 (Cursor 1.x, CLI Claude Code récente).
Quick Answer : aperçu en cinq étapes
| Étape | Ce que vous vérifiez | Action typique | Signal que ça marche |
|---|---|---|---|
| 1. Classifier les symptômes | Troncature de session / index manqué / règles non chargées | Tableau ci-dessous — ne changez pas de modèle tout de suite | Vous savez s'il faut corriger « session » ou « dépôt » |
| 2. Vérifier le budget de contexte | Tours d'outils et auto-injection qui remplissent la fenêtre | Fermer les onglets hors sujet, réduire les @ fichiers, modèle plus petit pour l'exploration | Moins de répétitions ; les diffs ne se contredisent plus |
| 3. Reconstruire l'index | .cursorignore, répertoires énormes, index obsolète | Réindexer ; exclure node_modules / DerivedData | L'Agent trouve seul le bon chemin de package |
| 4. Délimiter le périmètre | Périmètre de tâche trop large | Workspace sous-dossier, chaîne d'appels @ explicite, bloc de passation | Les fichiers modifiés restent dans le module attendu |
| 5. Écrire les conventions du dépôt | Règles verbales jamais devenues du texte consultable | AGENTS.md, .cursor/rules, découper les longues sessions | Les nouvelles sessions respectent les mêmes contraintes |
Que signifie « perte de contexte » dans les grands projets ?
Commençons par les termes : une longue fenêtre de contexte répond à « combien de tokens peuvent tenir maintenant ? » Le contexte effectif répond à « quels faits le modèle a-t-il réellement utilisés pour cette décision ? » Dans les grands dépôts, cet écart s'élargit — voir notre article sur persistentem Gedächtnis beim KI-Coding.
Quand les ingénieurs disent que le contexte a été « perdu », cela tombe en général dans trois catégories :
| Type | Ce que vous voyez | Cause typique | Vérifier en priorité |
|---|---|---|---|
| A. Troncature de session | Le même fil dérive ; les contraintes précoces sont annulées | La sortie d'outils multi-tours chasse les instructions initiales ; compact / résumé perd les détails | Étapes 2, 5 |
| B. Index manqué | « Module introuvable » / « la table n'existe pas » | Règles ignore trop agressives, index obsolète, dépôt trop grand avec retrieval bruyant | Étapes 3, 4 |
| C. Règles non chargées | Une nouvelle session oublie le style de nommage et les chemins interdits | Règles seulement dans le chat ; AGENTS.md manquant ou trop long | Étape 5 |
Étape 1 : classifier d'abord — tout « oubli » n'est pas un problème de modèle
En cas d'erreur ou de diff incohérent, parcourez cet arbre de décision en 60 secondes :
- Même session se contredit ? → Probablement A troncature de session — allez à l'étape 2.
- Nouvelle session oublie les accords ? → Probablement C règles non chargées — allez à l'étape 5.
- Le modèle affirme qu'un fichier n'existe pas, mais
greple trouve ? → Probablement B index manqué — allez aux étapes 3–4. - Erreur
context length exceeded/prompt is too long? → Problème de budget clair — allez directement à l'étape 2.
Cursor et Claude Code diffèrent légèrement : Cursor Composer/Agent injecte automatiquement les fichiers ouverts et les extraits d'index — l'IDE peut « faire exploser » la fenêtre en silence. Les agents terminal Claude Code perdent plutôt les décisions au milieu de la chaîne après de longues séquences bash + auto-compact. Comparaison des outils dans le guide de choix 2026.
Étape 2 : vérifier le budget de contexte — une grande fenêtre n'implique pas l'économie
La consommation réelle de tokens dans une tâche Agent vient de : prompt système + fichiers de règles + fichiers @ + sortie d'outils (grep, logs de tests) + résumé d'historique. Dans un monorepo TypeScript de 120k lignes, un run Cursor Agent qui lit automatiquement huit fichiers liés et lance toute la suite de tests peut atteindre 80K–120K tokens d'entrée — avant les retries.
2.1 Côté Cursor
- Fermer les onglets d'éditeur sans lien avec la tâche ; ne pas laisser ouverts d'énormes JSON ou fichiers lock.
- Utiliser un modèle à contexte plus petit ou le chat normal pour explorer ; ouvrir Agent seulement quand le plan est clair.
- Pas de « refactor + tests + CI » dans un seul Composer — trois tâches avec liste de fichiers explicite.
- Surveiller l'indexation de la codebase dans les réglages ; si l'indexation échoue, l'Agent retombe sur grep et la fenêtre gonfle plus vite.
2.2 Côté Claude Code
- Sur les longues tâches, surveiller l'auto-compact ; après compact, coller un bloc fixe « contraintes non négociables ».
- Rediriger la sortie de commande énorme vers un fichier ; l'Agent doit
tailles lignes clés — pas 5 000 lignes de log dans le chat. - Avant
/clearou une nouvelle session, écrire les conclusions dansHANDOFF.mdou un commentaire d'issue.
| Signal | Cause probable | Action immédiate |
|---|---|---|
| Les edits se dégradent vers la fin | Contraintes précoces chassées de la fenêtre | Nouvelle session + bloc de passation + tâche plus courte |
| Facture API par tâche qui explose | Gros fichiers / sortie de tests complète relue | Limiter la portée des tests ; utiliser head/tail |
| Erreur « context exceeded » | Limite dure atteinte | Moins de fichiers @, découper la tâche, modèle d'exploration |
Étape 3 : reconstruire l'index et nettoyer les ignore — aider l'Agent à « trouver » le code
Problème central du type B : le modèle ne refuse pas de chercher — le retrieval ne livre jamais le bon fichier.
3.1 Vérifier .cursorignore / .claudeignore
Des ignores sensés économisent le temps d'index ; un over-ignore crée des angles morts. Continuer à exclure :
node_modules/,.git/,dist/,build/,DerivedData/- Répertoires avec énormément de code généré (si vous devez modifier du code généré, @ des fichiers uniques explicitement)
- Binaires et assets média
Ne pas ignorer à la légère les packages source métier — beaucoup d'équipes excluent tout legacy/ puis s'étonnent que l'Agent ne voie jamais la couche de compatibilité.
3.2 Déclencher la réindexation
Cursor : Settings → Indexing & Docs → Resync Index (libellé selon version). Le premier index complet d'un gros dépôt sur M4 prend souvent 15–40 minutes ; si le portable fait tourner Ollama + Xcode en parallèle, externaliser l'indexation sur un nœud Mac cloud dédié — moins de timeouts swap pour l'IDE et l'Agent. Cohérent avec nos benchmarks M4 programmation IA.
git ls-files | wc -l chaque semaine en CI et comparer aux fichiers indexés. Si la couverture chute fortement, planifier un réindex commun plutôt que de redémarrer Cursor au hasard.Étape 4 : délimiter le périmètre — « tout le dépôt d'un coup » est l'ennemi
Parfois la perte de contexte est vraiment une définition de tâche trop large : vous dites « optimiser les paiements », le modèle touche quarante packages — un peu chacun.
4.1 Rétrécir le workspace
- VS Code / Cursor workspace multi-racine — ouvrir seulement
apps/checkout+packages/payment-sdk. - Démarrer Claude Code dans un sous-répertoire :
cd apps/checkout && claudepour que les chemins non pertinents n'entrent pas dans le retrieval.
4.2 Chaîne d'appels @ explicite
Lors d'un changement d'API, @ au minimum : définition d'interface → implémentation serveur → un vrai appelant → test associé. Dans les dépôts full-stack Vue + Spring Boot, des références @ ciblées sur la chaîne d'appels ont fait passer « frontend oublié » d'environ 40 % à moins de 10 % — approche systématique dans notre étude de cas CodeGraph.
4.3 Modèle de bloc de passation
Avant de changer de session sur une longue tâche, coller une structure fixe :
## Handoff
- Objectif :
- Terminé :
- Restant :
- Non-negotiable: (Pfade / Naming / verbotene Imports)
- Ouvrir ensuite :C'est mieux que « résume ci-dessus », car les entrées sont vérifiables — pas de prose qui perd les contraintes.
Étape 5 : mettre les conventions dans le dépôt et apprendre à découper les sessions
Correctif pour le type C : faire des règles une partie du dépôt, pas du chat.
5.1 AGENTS.md et Cursor Rules
À la racine du dépôt, maintenir des conventions courtes et actionnables (objectif < 200 lignes ; découper si besoin) :
- Frontières de modules et chemins « l'IA ne doit pas éditer » (ex.
generated/,vendor/) - Style de nommage et gestion d'erreurs (un bon et un mauvais exemple chacun)
- Checklist : quelles couches doivent changer lors d'un changement d'API
- Commandes obligatoires :
pnpm test payment --filter=...
Cursor lit .cursor/rules ; Claude Code lit AGENTS.md et CLAUDE.md. Les garder alignés sur le fond — des copies contradictoires embrouillent les deux outils.
5.2 Quand découper les sessions
| Scénario | Recommandation |
|---|---|
| Une fonctionnalité mergée ; on enchaîne la suivante | Nouvelle session + passation |
| L'Agent se trompe trois fois de suite | Arrêter, écrire la passation, rétrécir le scope @ |
| Compact déclenché / barre de contexte au-delà de la moitié | Persister les conventions sur disque, puis continuer |
| Am nächsten Tag weiter | Toujours nouvelle session + lien vers PR/issue |
Si les chaînes d'appels couvrent une douzaine de packages et que les fichiers @ ne suffisent toujours pas, évaluer les outils de graphe de connaissances du code — c'est un renfort après l'étape 5, pas le premier geste.
Étude de cas : 45 minutes sur un monorepo de 120k lignes
Une équipe B2B SaaS (8 backend + 4 frontend) utilise Cursor + Claude Code sur un monorepo pnpm (~118k LOC, 6 apps, 23 packages). Symptôme : quand l'Agent modifie billing-api, il casse à répétition les exports de types depuis auth-middleware — et les nouvelles sessions refont la même chose.
| Ordre | Constat | Action | Résultat |
|---|---|---|---|
| Étape 1 | Les nouvelles sessions oublient les règles → type C | Pas de AGENTS.md confirmé | Cause racine identifiée |
| Étape 3 | .cursorignore excluait à tort packages/auth | Ignore corrigé + réindex | L'Agent pouvait référencer le middleware |
| Étape 4 | Tâche « corriger billing » trop large | Workspace réduit à billing + auth ; @ tests | Fichiers touchés passés de 19 à 6 |
| Étape 5 | Règles verbales jamais documentées | AGENTS.md de 120 lignes + contrôle CI des frontières d'import | Une semaine de PR sans régressions du même type |
Pas de modèle plus cher. Tokens moyens par tâche ~35 % en moins, car l'Agent ne faisait plus de boucles grep sur tout le dépôt. Réindex et tests nocturnes sur un nœud cloud Macstripe 24 Go ; portable en SSH pour coder — plus d'alertes swap à l'indexation.
Auto-vérification : 2 minutes avant de commencer
- ☐ Vous pouvez nommer si cette tâche est de type A, B ou C
- ☐ L'éditeur n'a que les fichiers pertinents ouverts ; pas d'énormes logs
- ☐
.cursorignoren'exclut pas le code source métier - ☐ Index sain, ou réindex planifié
- ☐ Périmètre workspace ≤ 2–3 packages liés
- ☐ Fichiers clés de la chaîne d'appels @ (dont un test)
- ☐
AGENTS.mdliste les non-négociables pour cette tâche - ☐ Modèle de passation prêt pour une longue tâche
FAQ
La fenêtre de contexte est annoncée à 200K — pourquoi perd-on encore du contexte ?
La fenêtre est un plafond de capacité, pas une garantie d'attention. Les appels d'outils Agent multi-tours chassent les instructions précoces de l'attention effective ; les résumés compact perdent des détails. Les conventions du dépôt consultables battent un historique de chat plus long.
Qui perd le plus facilement le contexte — Cursor ou Claude Code ?
Cursor perd plutôt les limites via l'auto-injection IDE et les longues chaînes Composer ; Claude Code plutôt les décisions au milieu après de longs bash et compact. Les deux ont besoin de @ explicites, AGENTS.md et découpage — aucun n'est « plus simple ».
Est-ce que .cursorignore affecte les références @ manuelles ?
Référencer manuellement un fichier @ fonctionne en général ; ce qui casse, c'est l'index global et la recherche auto. Les répertoires ignorés exigent un @ explicite ou l'Agent ne les trouve pas seul.
Faut-il un graphe de connaissances du code ?
Un pilote vaut le coup quand les chaînes traversent beaucoup de packages et que @ fichiers rate encore des edits. Petits dépôts ou frontières claires : AGENTS.md + CI d'abord — meilleur ROI.
Changer de Mac ou passer au cloud aide-t-il ?
N'agrandit pas le contexte du modèle, mais un M4 24 Go dédié réduit le swap à l'indexation et aux tests — moins de timeouts Agent — et peut être l'environnement « tâches lourdes » partagé de l'équipe. Essai à la journée pour valider.
Synthèse
La « perte de contexte » avec Cursor / Claude Code dans les grands projets est surtout un problème d'ingénierie, pas un miracle d'une nouvelle gamme de modèle. Ces cinq étapes — classifier les symptômes → vérifier le budget → reconstruire l'index → délimiter le périmètre → écrire AGENTS.md et découper les sessions — coûtent en général moins et donnent des résultats plus stables que d'activer le mode Max à l'aveugle.
- Dérive dans la même session : réduire l'injection, découper les tâches, utiliser la passation.
- Fichiers introuvables : corriger ignore, réindexer, rétrécir le workspace.
- Nouvelle session oublie : conventions dans le dépôt ; la CI les impose.
Ensuite : mémoire persistante et graphes de connaissances du code pour renforcer après l'étape 5.
