Structurer le contexte d’un projet

Un agent IA ne lit pas votre projet, il lit ce que vous lui mettez sous les yeux. Sans contexte structuré, il invente des conventions plausibles, voire des hallucinations qui contredisent ce qui tourne réellement.

Structurer le contexte, c’est :

• Cesser de re-prompter les mêmes règles : ce qui vit dans CLAUDE.md n’a plus à être dit.
• Préserver la fenêtre : le contexte est une ressource finie et coûteuse. Plus on l’occupe avec du bruit, moins il en reste pour la tâche.
• Aligner humains et agents sur une seule source : les conventions vivent au même endroit, lues par les deux. La doc cesse de diverger du code.
• Rendre l’agent prévisible : une bonne structure réduit le non-déterminisme ; l’agent retombe sur les mêmes décisions parce qu’il lit les mêmes règles.
• Capitaliser sur l’acquis : un contexte bien posé se réutilise d’un dev à l’autre, d’un projet à l’autre.

Mal le faire coûte cher dans les deux sens :

• peu de contexte → l’agent improvise et hallucine ;
• trop de contexte → tokens dépensés en pure perte, modèle distrait, qualité qui chute.

Progressive disclosure

Charger tout le contexte à chaque session distrait l’agent : trop de contenu à la sémantique différente sont présents, certaines instructions sont ignorées. La solution est de révéler progressivement le contexte suivant l’endroit où l’agent se trouve dans la codebase (progressive disclosure).

Pour chaque nouvelle session, un agent ira lire systématiquement :

• l’entièreté du fichier CLAUDE.md (ou AGENT.md) sur le poste du développeur (~/.claude/CLAUDE.md) puis celui à la racine du projet qui sont concaténés;
• les en-têtes des skills / commands / MCP déclarés dans le dossier .claude à la racine du projet.

Il y a deux comportements différents suivant le type de fichiers présent dans la “hiérarchie de contexte” :

• CLAUDE.md tous les fichiers présents sont concaténés (~/.claude/CLAUDE.md + <project_root>/CLAUDE.md + <project_root>/sub1/sub2/CLAUDE.md lorsque Claude charge des fichiers de ce dernier répertoire). Plus de détails dans la documentation Claude Code sur le chargement des fichier CLAUDE.md.
• settings.json ici pas de concaténation juste de la priorisation entre les fichiers, certaines clès json sont surchargés par le dernier fichier trouvé et d’autres, notamment les permissions et claudeMdExcludes sont fusionnées. Plus de détails sur le comportement du settings.json dans la documentation Claude Code.

Deux techniques pour bénéficier de la capacité de révélation progressive du contexte :

• Créer des fichiers CLAUDE.md dans la structure du projet : de sorte à ce que l’agent charge progressivement ces fichiers à mesure qu’il parcourt la structure du projet pour une tâche précise.
• Créer une chaîne de référence (des liens vers certains fichiers) dans le fichier racine CLAUDE.md du projet : pour qu’en fonction de la tâche à accomplir, l’agent puisse charger à la volée du contexte si la tâche le requiert.

Isolation des contextes

• Mettre dans le CLAUDE.md ce qui reste vrai pour toutes nouvelles sessions sur le projet : description du projet, structure des fichiers, commandes de démarrage/test/lint.
• Garder le fichier racine < 100 lignes.
• Ne mettre dans le contexte que ce que le code ne dit pas. Au lieu de ré-écrire un exemple, privilégier un lien vers le code.

Plusieurs stratégies possibles pour séparer le contexte au sein d’un projet.

File Structure-driven disclosure

• Répartition de CLAUDE.md dans les sous-dossiers du projet.
• Convient aux architectures qui autorisent le raisonnement local (clean archi, architecture hexagonale, vertical slicing architecture).

Avantages

• Built-in Claude.
• Adapté au monorepo où chaque module porte son contexte propre.
• Maintenance automatisable. Heuristique : si un dossier change, le CLAUDE.md le plus proche est potentiellement à mettre à jour.

Inconvénients

• Doit être paramétré pour des agents autres que ceux fournis par Anthropic.
• Profusion de CLAUDE.md dans la structure du projet.
• Couplage de la composition de contexte à la structure du projet.

projet
  module1/
    src/
      infrastructure/
        kafka/
          CLAUDE.md   <--- Conventions producteurs/consommateurs, topics, sérialisation
        postgres/
          CLAUDE.md   <--- Schéma, migrations, accès aux repositories
        CLAUDE.md     <--- Règles d'adaptation domaine ↔ infra
      domain/
        entity/
        value/
        repository/
        CLAUDE.md     <--- Langage métier, invariants, règles de modélisation
      feature/
        feature1/
          f1.controller.ts
          f1.use-case.ts
          CLAUDE.md   <--- Contrat d'API, cas d'usage, dépendances
    package.json
    CLAUDE.md <--- Périmètre du module, dépendances, commandes locales
  README.md   <--- Description du projet pour les humains
  CLAUDE.md   <--- Contexte toujours valide pour chaque session
  .claude/rules <--- Garde-fous appliqués globalement

Index driven disclosure

• Référencer les sous-contextes par une chaîne de référence depuis le CLAUDE.md.
• Les sous-contextes sont centralisés dans un dossier unique (/docs par exemple) à la racine du projet.
• Dans le cas d’un mono-repo, un dossier de docs dans chaque module.
• Chaque sous-contexte est orienté tâche pour que l’agent puisse les charger à la volée en fonction de la tâche.
• Adapté pour une maintenance et un onboarding humain car centralisé.

Avantages

• Un développeur découvre le projet plus naturellement.
• Orienté tâche, ce qui sert de tutoriel pour un nouvel arrivant.
• L’agent se sert des mêmes artefacts que les humains. On se découple d’un agent.

Inconvénients

• Maintenance plus complexe à automatiser car non locale aux changements. Mise à jour qui repose sur le jugement du développeur.
• Maintenance de la chaîne de référence pour tout nouveau sous-contexte.
• Peu adapté lorsque les pratiques divergent entre modules.

projet
  docs/                        <- tous référencés par le CLAUDE.md racine
    ubiquitous-domain-language.md
    create-controller.md
    create-entity.md
    create-value-type.md
    create-code-using-fonctional-style.md
    testing-code.md
    validate-project.md
    build-project.md
    do-commit.md
    migrate-database.md
    add-new-topic.md
  module1/
    src/
      infrastructure/
      domain/
      feature/
    package.json
  README.md   <--- Description du projet pour les humains
  CLAUDE.md   <--- Contexte toujours valide + index vers les sous-contextes

Comment choisir ?

File-structure si votre architecture porte déjà le raisonnement local et que chaque module mérite ses propres règles. Index si vous voulez un point d’entrée unique, partagé avec les humains, et découplé de l’arborescence. Dans les deux cas, la règle tient : le contexte qu’on ne range pas, on le re-prompte.