Structuré avec Claude

Gros projets

Tout ce qu’on a vu — skills, hooks, agents, CLAUDE.md avec carte du repo — scale sur les petits projets. Sur les gros repos, les mêmes outils s’appliquent, mais la discipline autour du contexte devient critique.

Claude Code n’a pas de notion de “taille de repo”. Ce qu’il a, c’est un context window. Et c’est cette contrainte qui détermine tout quand on travaille sur une large codebase.

Cette page est une synthèse de patterns émergents rapportés par la communauté. Elle sera mise à jour au fil des retours d’XP.

La contrainte réelle : le context window

Claude ne lit pas tout le repo à chaque session. Il lit ce qu’on lui donne. Sur un petit projet, on peut tout mettre dans le contexte sans y penser. Sur un repo de 50k+ lignes, chaque fichier ajouté au contexte est un choix qui a un coût.

Le problème n’est pas que Claude “ne sait pas” ce qui est dans les autres fichiers — c’est que si tu lui en donnes trop, la qualité de raisonnement se dégrade. Il perd le fil, répète des erreurs, ignore des instructions données tôt dans la session.

Ce que la communauté rapporte

Worktrees git pour isoler le travail

Les worktrees permettent de travailler sur une feature dans un répertoire séparé sans toucher à la branche principale. Sur un gros repo, ça a deux avantages :

1. Claude n’a accès qu’au répertoire du worktree — contexte naturellement délimité
2. Les agents parallèles peuvent travailler sur des worktrees différents sans interférer

git worktree add ../mon-projet-feature feature/ma-feature

Décomposition + agents parallèles

Sur un refactor qui touche plusieurs modules indépendants, lancer des agents sur chaque module séparément (et en parallèle) donne de meilleurs résultats qu’une session unique qui tente tout en même temps.

Condition : les modules doivent être vraiment indépendants. Si l’agent du module A a besoin du résultat de l’agent B, ils ne peuvent pas être parallélisés.

CLAUDE.md avec carte du repo

Sur un gros repo, CLAUDE.md peut inclure une carte minimaliste de la structure — les modules principaux, leurs responsabilités, et ce qu’il ne faut pas toucher :

## Structure
src/api/          # Endpoints REST — ne pas modifier les contrats existants
src/domain/       # Logique métier — pas de dépendances vers src/api/
src/infra/        # DB, cache, queues — modifications via migrations uniquement
tests/            # Miroir de src/ — un fichier de test par module

Ça évite que Claude modifie des fichiers hors scope ou ignore des contraintes architecturales.

Sessions courtes et ciblées

Au lieu d’une session “je veux refactorer tout le module auth”, préférer :

• Session 1 : extraire les interfaces
• Session 2 : migrer le service
• Session 3 : mettre à jour les tests

Chaque session repart avec un contexte propre. La qualité reste stable.

/compact régulier

Sur les sessions longues (exploration, debugging), utiliser /compact avant que le contexte sature — pas après. Une fois que Claude commence à dégrader, il est souvent trop tard pour récupérer la session proprement.

Limites réelles

Il faut être honnête sur ce que Claude Code ne gère pas bien aujourd’hui :

Scénario	Fiabilité
Feature isolée, fichiers délimités	✅ Très bonne
Refactor d’un module (5–15 fichiers)	✅ Bonne avec décomposition
Compréhension architecturale globale	⚠️ Fragile — il peut manquer des dépendances implicites
Refactor cross-module (30+ fichiers)	⚠️ Risqué sans supervision étroite
Repo 100k+ lignes, tâche ouverte	❌ Déconseillé sans découpage préalable

Recommandations pratiques

Donner le contexte minimal nécessaire. Pas tout le repo — les fichiers directement liés à la tâche. Claude travaille mieux avec moins, bien ciblé.

Tâches atomiques. Un objectif, un périmètre, un résultat vérifiable. Plus c’est atomique, plus c’est fiable.

Vérifier systématiquement. Sur du code critique dans un gros repo, ne pas supposer que parce que ça compile, c’est correct. Tests, review, lecture humaine.

Documenter l’architecture dans CLAUDE.md. Plus le repo est grand, plus Claude a besoin d’une carte pour naviguer sans faire d’erreurs de scope.

→ Voir aussi : Pièges & limites et Coûts & tokens.