CLAUDE.md : pensez RAM, pas disque dur

Si vous utilisez Claude Code au quotidien, vous avez probablement déjà vécu ce scénario : un fichier CLAUDE.md qui grossit de semaine en semaine, passant de 50 lignes à 150, puis à 300. Et paradoxalement, plus il grandit, moins l'assistant semble efficace. Ce n'est pas une coïncidence.

Alberto Arena a publié un article éclairant sur ce sujet (CLAUDE.md is RAM, not disk), et la métaphore qu'il propose mérite d'être adoptée par tout développeur PHP/Symfony qui intègre des outils IA dans son workflow.

La métaphore qui change tout

La distinction est simple mais fondamentale : CLAUDE.md, c'est de la RAM. Vos autres fichiers de documentation, c'est le disque.

Comme la RAM dans un ordinateur, CLAUDE.md est chargé en mémoire à chaque démarrage de session et reste présent en permanence pendant toute la durée de la conversation. Chaque ligne que vous y ajoutez est une ligne que le modèle doit lire et traiter avant même de commencer à répondre à votre question.

Comme un disque dur, votre dossier docs/ contient des informations de référence — volumineuses, précises, structurées — qui ne sont consultées que lorsqu'on en a besoin, via un pointeur explicite.

Cette distinction, une fois intégrée, répond à elle seule à la question « où dois-je mettre cette information ? ».

Pourquoi un CLAUDE.md trop long nuit à la qualité

Claude Code charge CLAUDE.md automatiquement à chaque session et le conserve dans le contexte tout au long de l'échange. C'est exactement ce que vous voulez pour un petit nombre d'informations critiques :

• La stack technique du projet (PHP 8.3, Symfony 7, PostgreSQL…)
• Les commandes essentielles (composer install, bin/console cache:clear…)
• Les conventions incontournables (nommage, structure des entités, règles de PR)

En revanche, c'est précisément ce que vous ne voulez pas pour des informations occasionnelles : une description détaillée du domaine métier, un schéma d'architecture complet, la documentation d'une API tierce. Ces éléments consomment des tokens à chaque échange, diluent le contexte utile, et peuvent même dégrader la qualité des réponses en noyant les instructions importantes dans du bruit.

Autour de la ligne 200 d'un CLAUDE.md trop chargé, l'assistant commence à perdre en précision — non pas parce que le modèle est limité, mais parce que la fenêtre de contexte est encombrée de détails sans rapport avec la tâche en cours.

La bonne architecture : RAM + Disque

L'approche recommandée repose sur une séparation claire des responsabilités.

Dans CLAUDE.md (RAM — toujours chargé) :

## Stack
- PHP 8.3 / Symfony 7.2
- PostgreSQL 16
- Docker Compose pour l'environnement local

## Commandes fréquentes
- `composer install`
- `bin/console doctrine:migrations:migrate`
- `bin/phpunit`

## Conventions
- Entités dans `src/Entity/`, repositories dans `src/Repository/`
- Tests unitaires obligatoires pour les services métier
- Pas de logique métier dans les contrôleurs

Dans docs/ (Disque — chargé à la demande) :

docs/
  architecture.md       # Schéma et décisions d'architecture
  domaine-metier.md     # Glossaire et règles métier détaillées
  api-paiement.md       # Documentation de l'intégration Stripe
  onboarding.md         # Guide pour les nouveaux développeurs

Le CLAUDE.md peut alors simplement référencer ces fichiers : Pour l'architecture du projet, voir docs/architecture.md. Claude ira les consulter quand la tâche le nécessite — et seulement à ce moment-là.

Appliquer ce principe dans un projet Symfony

Concrètement, voici comment traduire cette approche dans un projet PHP/Symfony typique chez MulerTech.

Gardez dans CLAUDE.md :

• La version de PHP et de Symfony
• Les commandes Composer et Console les plus utilisées
• Les règles PSR et les standards de code du projet
• Les variables d'environnement critiques et leur rôle
• Les interdictions absolues (ne jamais commit de credentials, toujours valider avec les Value Objects, etc.)

Déplacez dans docs/ :

• Le schéma de base de données et les relations entre entités
• Les flux métier complexes (workflow de commande, cycle de vie d'un abonnement…)
• La documentation des services tiers intégrés (APIs, webhooks)
• Les décisions d'architecture et leurs justifications (ADR)
• Les guides de contribution et de déploiement

Le résultat : un CLAUDE.md de 30 à 50 lignes maximum, dense et pertinent, qui donne à l'assistant exactement ce dont il a besoin — ni plus, ni moins.

Conclusion

La métaphore RAM/disque d'Alberto Arena est l'une de ces idées simples qui restructurent immédiatement la façon dont on travaille. Elle rappelle que les outils IA ne sont pas des boîtes noires magiques : ils obéissent à des contraintes techniques précises, au premier rang desquelles la gestion du contexte.

En tant que développeurs PHP/Symfony, nous savons depuis longtemps qu'un cache mal configuré dégrade les performances. Le principe est identique ici : un contexte mal structuré dégrade la qualité de l'IA. Gardez votre CLAUDE.md court, précis, et traité comme une ressource précieuse — parce que c'en est une.

Source originale : CLAUDE.md is RAM, not disk par Alberto Arena.