CLAUDE.md minimal & Le context priming (/prime)

CLAUDE.md minimal : la règle universelle, pas le fourre-tout

L’idée en une phrase

Un CLAUDE.md est chargé en entier au démarrage de chaque session : son coût est payé à chaque fois, avant la première question. Le garder minimal — les règles universelles, pas le fourre-tout — c’est Reduce appliqué à la primitive Contexte des Core 4 (chapitre 3) : ne reste que ce qui doit valoir à toutes les sessions ; le reste part vers des mécanismes qui chargent à la demande.

Analogie : les consignes affichées à l’entrée d’un atelier. Chaque personne les lit en franchissant la porte, à chaque fois. Si l’on punaise à la place tout le classeur de procédures, la seule consigne qui compte vraiment se noie dans la masse et plus personne ne lit avec attention. On ne garde à la porte que les règles qui s’appliquent toujours ; le détail vit dans le classeur, consulté seulement quand on en a besoin.

Points clés

• Chargé en entier, à chaque session. Le CLAUDE.md est livré comme un message utilisateur juste après le prompt système, et apparaît sous la rubrique « Memory files » de /context (chapitre 2). Son poids est donc une dépense récurrente : chaque token qu’il contient est rechargé à tous les démarrages.
• Une hiérarchie chargée du plus large au plus précis : politique gérée par l’organisation, puis ~/.claude/CLAUDE.md (personnel, tous projets), puis ./CLAUDE.md ou ./.claude/CLAUDE.md (projet, versionné), puis ./CLAUDE.local.md (privé au projet). Tous sont concaténés, pas substitués : chaque niveau ajoute au coût.
• Viser sous les 200 lignes. Au-delà, la double peine : plus de tokens consommés et une adhérence qui baisse — l’agent suit moins bien des instructions noyées (lois d’échelle inverses, chapitre 2). Une instruction précise et vérifiable (« indentation à 2 espaces ») vaut mieux qu’un paragraphe vague.
• Le levier Reduce, c’est le hors-session. Une procédure multi-étapes ou une convention propre à un seul dossier n’a pas sa place dans le CLAUDE.md : on la déplace vers .claude/rules/ avec un frontmatter paths: (chargée seulement quand l’agent touche les fichiers correspondants) ou vers un skill (chargé à l’invocation).
• Outils pour tenir le fichier propre : /init génère un CLAUDE.md de départ à partir du dépôt, /context confirme ce qui est réellement chargé, /memory ouvre les fichiers mémoire, /doctor propose des coupes. Les commentaires HTML (<!-- ... -->) sont retirés avant injection : ils ne coûtent aucun token.

Exemple concret

Un CLAUDE.md devenu fourre-tout — arborescence complète du dépôt, liste des dépendances, conventions détaillées de l’API, procédure de tests — pèse vite ~32 000 caractères, soit ≈ 8 000 tokens (heuristique ~1 token pour 4 caractères, chapitre 2) chargés à chaque session. On le reconstruit : on garde ~60 lignes de règles universelles (commandes de build, conventions globales, « toujours faire X »), soit ~1 000 tokens ; les conventions d’API partent dans .claude/rules/api.md avec paths: src/api/** (chargées ~600 tokens seulement quand l’agent touche l’API), la procédure de tests devient un skill (chargé à l’invocation). Chaque session paie désormais ~1 000 tokens au lieu de ~8 000 : ~7 000 tokens (~3,5 % d’une fenêtre de 200k) rendus à chaque démarrage — et l’adhérence progresse, car les rares règles restantes ne sont plus diluées.

Où placer chaque instruction

Config — un CLAUDE.md qui tient en une page

# Projet — regles permanentes (chargees a CHAQUE session)

## Commandes
- Build : `npm run build`
- Tests : `npm test` avant chaque commit

## Conventions
- Indentation 2 espaces ; imports absolus depuis `src/`
- Les handlers d'API vivent dans `src/api/handlers/`

<!-- Note mainteneur : garder sous ~150 lignes. Detail par dossier -> .claude/rules/. -->

Commande — inspecter et tailler

# Generer un CLAUDE.md de depart : Claude lit le repo et propose (ne pas tout garder) :
/init

# Verifier ce qui est REELLEMENT charge (rubrique « Memory files ») :
/context

# Ouvrir / editer les fichiers memoire :
/memory

# Proposer des coupes dans un CLAUDE.md versionne (garde pieges et conventions, coupe l'evident) :
/doctor

Piège courant : croire que « découper un gros CLAUDE.md en @imports allège le contexte » est inexact. Les fichiers importés via @chemin sont dépliés et chargés en entier au démarrage, exactement comme du contenu en ligne : le découpage améliore la lisibilité, pas le coût en tokens. Pour vraiment réduire, on déplace les instructions vers .claude/rules/ avec un frontmatter paths: (chargées seulement quand l’agent touche les fichiers concernés) ou vers un skill (chargé à l’invocation).

Le context priming : des commandes /prime sur-mesure

L’idée en une phrase

Le context priming (amorçage), c’est démarrer une session en chargeant exactement l’instantané dont la tâche a besoin — l’arborescence utile, les quelques fichiers clés, l’objectif — via une commande /prime sur-mesure, au lieu de laisser l’agent découvrir le dépôt en lisant des dizaines de fichiers. C’est Reduce rendu délibéré et rejouable : un petit chargement choisi plutôt qu’un gros chargement subi.

Analogie : un itinéraire enregistré dans un GPS. On saisit la destination et l’appareil ne charge que le tracé et les tuiles de carte utiles — pas l’atlas du monde entier. Enregistré une fois, il se rejoue à chaque trajet. Une commande /prime, c’est cet itinéraire pour une tâche : elle amène la poignée de fichiers qui comptent, pas le dépôt entier, et se réutilise d’une session à l’autre.

Points clés

• Une commande sur-mesure est un simple fichier Markdown : .claude/commands/prime.md devient /prime (scope projet ; ~/.claude/commands/ pour le scope personnel, présent dans tous les projets). Les commandes sur-mesure sont désormais unifiées avec les skills — .claude/commands/prime.md et .claude/skills/prime/SKILL.md créent tous deux /prime ; les fichiers .claude/commands/ existants continuent de fonctionner.
• L’injection dynamique. Une ligne commençant par ! suivie d’une commande entre backticks est exécutée avant que le contenu n’atteigne l’agent, et sa sortie remplace la ligne. L’agent reçoit donc des données réelles — un instantané choisi — et non l’ordre de partir explorer.
• Références et arguments : @chemin insère un fichier ; $ARGUMENTS (ou $0, $1) injecte les arguments passés à la commande. Un même /prime devient ainsi paramétrable par objectif ou par zone.
• Priming vs découverte. L’amorçage remplace le « lire tout pour comprendre » (des dizaines d’appels d’outils, des dizaines de milliers de tokens bruités) par un chargement choisi, en une fois. C’est le complément du CLAUDE.md : celui-ci porte les règles permanentes, le /prime amène le contexte spécifique à la tâche, à la demande.
• Frontmatter utile : description, argument-hint, et allowed-tools pour pré-autoriser les commandes de lecture (aucune invite de permission). disable-model-invocation: true réserve le déclenchement au seul appel manuel.

Exemple concret

Sans amorçage, sur « ajoute un endpoint à l’API de paiement », l’agent part explorer : il liste le dépôt, ouvre quinze fichiers, lit un README, cherche au grep — ~25 appels d’outils et ~30 000 tokens en grande partie hors sujet (le run « tout charger » du chapitre 1) avant d’écrire une ligne. Une commande /prime insère à la place un instantané choisi : l’arborescence de la zone (git ls-files src/api, ~300 tokens), le handler concerné (@src/api/handlers/payment.ts, ~500 tokens), la vue d’ensemble (@README.md, ~400 tokens) — soit ~1 500 tokens choisis, chargés en une fois. L’agent démarre focalisé, à ~1 500 tokens au lieu de ~30 000 : ~28 500 tokens (~14 % d’une fenêtre de 200k) de bruit évités, et une attention qui reste dense (chapitre 2).

Choisir ce qui entre au démarrage

Config — l’injection dynamique en quelques lignes

---
description: Amorce le contexte d'une tache API
allowed-tools: Bash(git ls-files:*), Read
---
# Snapshot injecte AVANT toute lecture de l'agent
Structure de la zone : !`git ls-files src/api`
Fichier cle : @src/api/handlers/payment.ts

Objectif : $ARGUMENTS

Invoquée par /prime "ajoute un remboursement partiel", la ligne ! s’exécute d’abord et insère la liste des fichiers, @ insère le handler, $ARGUMENTS injecte l’objectif : un snapshot d’environ 1 500 tokens choisi, contre ~30 000 explorés à l’aveugle.

Piège courant : croire que /prime est une commande intégrée de Claude Code est faux — il n’existe aucun /prime natif. C’est une commande sur-mesure que l’on écrit soi-même (un fichier Markdown dans .claude/commands/, désormais unifiable avec les skills). À ne pas confondre avec /context, qui est native et mesure la fenêtre (chapitre 2) : /prime la remplit délibérément. L’une lit la jauge, l’autre choisit le carburant.

Fil rouge — Reduce ou Delegate ?

Ce chapitre est entièrement du côté Reduce, sur la primitive Contexte des Core 4 (chapitre 3) — précisément sur ce qui est chargé sans qu’on l’ait demandé. Deux temporalités s’y complètent. Le CLAUDE.md règle le coût permanent payé à chaque session : un fourre-tout à ~8 000 tokens ramené à ~1 000, soit ~3,5 % d’une fenêtre de 200k rendus à chaque démarrage. Le context priming règle le coût initial d’une tâche : une exploration à l’aveugle de ~30 000 tokens remplacée par un snapshot choisi de ~1 500, soit ~14 % de fenêtre épargnés. Aucun des deux ne délègue — le traitement reste dans l’agent principal ; tous deux réduisent à la source ce qui entre, pour que l’attention reste dense (chapitre 2). Un agent qui démarre sous les quelques pour-cent d’occupation « voit » net. Delegate viendra au tier suivant, avec les sub-agents.

Travaux pratiques

À chaque leçon, un petit artefact à déposer dans ton .claude/ — commande, sous-agent, hook, mémo… — pour te bâtir, au fil du livre, une boîte à outils de context engineering réutilisable.

Commande slash maison — /prime

Ce chapitre donne un levier majeur : autant en faire une commande prête à dégainer. Ce /prime injecte, avant toute lecture de l’agent, un instantané choisi du dépôt — arborescence versionnée, historique récent, README — puis cadre l’objectif passé en argument. L’agent démarre donc focalisé au lieu d’explorer à l’aveugle : c’est Reduce sur la primitive Contexte, un chargement initial choisi (~1 500 tokens) à la place d’un chargement subi (~30 000 tokens d’exploration).

---
description: Amorce la session avec un snapshot choisi du depot, puis cadre l'objectif
argument-hint: [objectif de la tache]
allowed-tools: Bash(git ls-files:*), Bash(git log:*), Read
---

# /prime — amorcage de contexte

## Snapshot du depot (injecte AVANT toute lecture de l'agent)

Arborescence versionnee (bornee pour rester legere) :
!`git ls-files | head -40`

Dix derniers changements :
!`git log --oneline -10`

Vue d'ensemble :
@README.md

## Objectif

$ARGUMENTS

## Consigne

Le contexte ci-dessus est un instantane choisi : arborescence, historique recent, README.
N'ouvre QUE les fichiers necessaires a l'objectif — ne relis pas tout le depot, l'utile est
deja amorce. Annonce ton plan avant d'editer.

Invoque-la par /prime "ajoute un remboursement partiel à l'API" : les lignes ! et @ s’exécutent d’abord et insèrent un snapshot d’environ 1 500 tokens choisis au lieu de ~30 000 tokens d’exploration à l’aveugle — soit ~14 % d’une fenêtre de 200k gardés libres, et une attention dense dès le premier tour. Les commandes sur-mesure étant désormais unifiées avec les skills, le même contenu peut vivre en .claude/skills/prime/SKILL.md ; .claude/commands/prime.md continue de fonctionner.