Codebase Context Docs

Que fait Codebase Context Docs ?

Génère un CLAUDE.md compact à la racine du dépôt ainsi qu'un ensemble de fiches d'approfondissement dans .claude/docs/.

L'objectif n'est pas de « documenter le projet ». Il est : rendre un futur agent efficace dès son premier tour tout en dépensant le moins de tokens possible. CLAUDE.md est chargé dans le contexte à chaque tour, pour toujours. Chaque ligne qui s'y trouve est une taxe. Une ligne ne mérite sa place que si elle change ce qu'un agent fait sur une tâche qu'il n'a pas encore vue. Tout le reste appartient à .claude/docs/, chargé uniquement lorsque c'est pertinent.

Ce compromis dicte toutes les règles ci-dessous.

Flux de travail

Suivez cet ordre. Écrire CLAUDE.md en premier est l'échec le plus courant — cela produit un fichier plausible rempli de suppositions, et les fiches sont ensuite écrites pour correspondre aux suppositions plutôt qu'au code.

1. Sonder le dépôt de manière mécanique (commandes ci-dessous).
2. Lire les points d'entrée, la configuration et une portion représentative du code source.
3. Écrire .claude/docs/*.md — les détails se trouvent ici.
4. Écrire CLAUDE.md en dernier — c'est un index sur ce que vous venez d'apprendre.
5. Vérifier — nombre de lignes, chaque commande, chaque file:line.

Étape 1 — Sondage

Exécutez ces commandes avant toute lecture. Elles coûtent peu et évitent des suppositions erronées sur la taille, le mélange de langages et les outils.

# Forme et échelle
git ls-files | wc -l
git ls-files | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -40
git ls-files | grep -oE '\. [a-z0-9]+$' | sort | uniq -c | sort -rn | head -20

# Outils et points d'entrée (lire chaque fichier trouvé)
ls -a
git ls-files | grep -iE '(package\.json|pyproject\.toml|setup\.py|requirements.*\.txt|Cargo\.toml|go\.mod|pom\.xml|build\.gradle|Gemfile|composer\.json|pubspec\.yaml|Makefile|justfile|Taskfile|docker-compose|Dockerfile)'
git ls-files '.github/workflows/*' '.gitlab-ci.yml' '.circleci/*'

# Documentation existante — les lire, elles contiennent des intentions que vous ne pouvez pas déduire du code
git ls-files | grep -iE '(readme|contributing|architecture|adr|docs/)' | head -30

# L'activité récente montre quelles parties du dépôt sont réellement actives
git log --oneline -15
git log --pretty=format: --name-only -n 200 | sort | uniq -c | sort -rn | head -20

Notez tout ce que le sondage ne parvient pas à trouver. Un dépôt sans configuration CI ni répertoire de tests est une découverte réelle, pas une lacune à masquer.

Étape 2 — Lecture

Lisez, dans cet ordre :

• Les fichiers manifestes (package.json, pyproject.toml, …) — en entier, y compris la section scripts/tâches. C'est là que se trouvent les vraies commandes.
• Les fichiers de workflow CI — les commandes exécutées par la CI sont les commandes qui fonctionnent réellement.
• README.md et tout CONTRIBUTING.md / docs/ — pour le pourquoi, que le code ne peut pas vous dire.
• Le(s) point(s) d'entrée de l'application, puis 5 à 15 fichiers source représentatifs répartis dans les principaux répertoires.

Utilisez des sous-agents parallèles pour la phase de lecture du code source lorsque le dépôt est volumineux et que des sous-agents sont disponibles — un par répertoire principal, chacun rapportant ce que fait ce répertoire, quels motifs il utilise, et les ancres file:line pour ces motifs. C'est plus rapide et évite de charger des extraits de fichiers bruts dans le contexte principal.

Pendant la lecture, maintenez une liste courante des motifs candidats avec le chemin/vers/fichier.ts:142 exact où vous les avez vus. Vous aurez besoin de ces ancres plus tard, et revenir pour les trouver coûte cher.

Étape 3 — Écrire .claude/docs/

Créez uniquement les fichiers que le codebase supporte réellement. Une fiche vide ou gonflée est pire qu'une fiche absente, car elle apprend à l'agent à se méfier de l'ensemble.

Fichier	Créer quand	Contient
architectural_patterns.md	Toujours (sauf si le dépôt est trivialement petit)	Décisions structurelles récurrentes : injection de dépendances, gestion d'état, gestion d'erreurs, limites de modules, conventions de conception d'API, règles de couches
testing_strategy.md	Des tests existent	Frameworks, emplacement des tests, conventions de fixtures/fabriques, comment exécuter un test vs. la suite, ce qui est mocké vs. réel
build_and_deploy.md	Les outils de build ou la CI ne sont pas évidents	Pipeline de build, variables d'environnement et leur déclaration, artefacts, flux de release/déploiement, astuces de configuration locale
data_model.md	Des données persistantes, des schémas ou des migrations existent	Entités principales et relations, emplacement et workflow des schémas/migrations, couche de validation
api_reference.md	Le projet expose ou consomme une API significative	Organisation des routes/points de terminaison, conventions requête/réponse, authentification, versionnage, format des erreurs

Vous pouvez ajouter un fichier spécifique au domaine lorsqu'un codebase possède un sous-système volumineux qui ne correspond pas à ces catégories (realtime_sync.md, billing.md). Préférez un petit nombre de fichiers substantiels à de nombreux fichiers légers.

La règle de preuve multi-fichiers

C'est la règle qui sépare un document de motifs utile d'un document halluciné.

Ne documentez un motif que si vous l'avez vu dans au moins trois fichiers distincts, et citez au moins deux d'entre eux. Une seule abstraction astucieuse n'est qu'un détail anecdotique. Une convention répétée dans tout le codebase est ce qu'un nouvel agent doit suivre pour écrire un code qui s'intègre.

Lorsque vous trouvez quelque chose qui ressemble à un motif mais n'apparaît qu'une fois, soit abandonnez-le, soit utilisez une recherche pour confirmer qu'il se généralise :

rg -n 'useAppDispatch' --stats           # quelle est sa diffusion ?
rg -l 'implements Repository' | head     # quels fichiers partagent cette forme ?

Si une convention est appliquée de manière incohérente — la moitié du codebase fait d'une façon, l'autre moitié d'une autre — dites-le explicitement et notez laquelle est la plus récente (git log sur les fichiers vous le dira). Un agent qui sait qu'un codebase est en cours de migration écrit un meilleur code qu'un agent qui suppose l'uniformité.

Référencez par ancre, pas par extrait

Écrivez Voir src/services/base.py:34 plutôt que de coller la classe. Les extraits deviennent obsolètes dès que quelqu'un modifie le fichier, et un extrait obsolète induit activement en erreur — alors qu'un numéro de ligne obsolète mérite manifestement d'être revérifié. Cela permet également de garder les fiches suffisamment courtes pour être lues.

Incluez le nom du symbole à côté de la ligne afin que l'ancre survive à de petites modifications : PaymentProcessor.execute — src/billing/processor.py:88.

Laissez le style de code tranquille

L'utilisateur exécute des linters et des formateurs. Ne documentez pas l'indentation, le style de guillemets, la longueur des lignes, l'ordre des imports ou la casse des noms. Ceux-ci sont appliqués mécaniquement ; les répéter dans un fichier toujours chargé consomme du contexte pour dupliquer un outil. Documentez les conventions qu'un linter ne peut pas appliquer — quelle couche peut importer quoi, quand ajouter une migration, où une nouvelle route s'enregistre.

Étape 4 — Écrire CLAUDE.md

Moins de 150 lignes, impératif. Utilisez cette structure :

# <Nom du Projet>

<2 à 4 phrases : ce qu'est ce projet et à qui/quoi il sert. Le POURQUOI —
le problème qu'il résout. C'est la partie qui ne peut pas être déduite du code,
donc c'est la partie qui vaut le plus la peine d'être écrite avec soin.>

## Stack Technique

<Liste compacte : langage + version, framework, base de données, infrastructure clé.
Seulement ce qui change la façon dont le code est écrit. Ne faites pas un dump des dépendances transitives.>

## Structure du Projet

<Tableau ou liste des répertoires de premier niveau, une ligne chacun, indiquant ce qui
y appartient et — lorsque ce n'est pas évident — ce qui n'y appartient pas.>

## Commandes

<Seulement les commandes vérifiées et universellement utiles : install, dev, build, test,
test-un-seul-fichier, lint, typecheck. Notez le gestionnaire de paquets s'il n'est pas
celui par défaut pour l'écosystème.>

## Conventions

<3 à 8 lignes, uniquement des règles qui s'appliquent à l'ensemble du dépôt et qu'un
linter ne peut pas détecter. Si une règle est spécifique à un sous-système, elle doit
se trouver dans un fichier de documentation à la place.>

## Documentation Additionnelle

Lisez ces fichiers lorsque la tâche l'exige — ne les chargez pas de manière préventive.

- `.claude/docs/architectural_patterns.md` — <quand le lire>
- `.claude/docs/testing_strategy.md` — <quand le lire>

Deux choses font que la section « Documentation Additionnelle » fonctionne ou échoue :

• Chaque entrée indique quand la lire, pas ce qu'elle contient. « À lire avant d'ajouter un point de terminaison ou de modifier une forme de réponse » oriente correctement un agent ; « documente l'API » ne le fait pas.
• La liste est le seul endroit où les détails spécialisés sont référencés. Si vous vous surprenez à expliquer la configuration des tests dans CLAUDE.md et dans testing_strategy.md, supprimez-la de CLAUDE.md.

Voir references/templates.md pour un exemple rempli de CLAUDE.md et de chaque fichier de documentation.

Étape 5 — Vérification

Ne sautez pas cette étape. Chaque mode d'échec de cette tâche est une contre-vérité énoncée avec assurance, et chacun est bon marché à détecter.

wc -l CLAUDE.md                          # doit être < 150

Ensuite :

• Exécutez chaque commande que vous avez écrite, ou au minimum confirmez qu'elle existe dans le manifeste / la configuration CI. Un npm test dans CLAUDE.md qui n'est pas dans package.json fera perdre du temps à un agent à chaque session future. Si vous ne pouvez pas exécuter une commande, marquez-la comme lue depuis la source plutôt que vérifiée.
• Vérifiez ponctuellement chaque file:line — ouvrez-en quelques-uns et confirmez que le symbole cité s'y trouve.
• Relisez CLAUDE.md à froid, en tant qu'agent voyant ce dépôt pour la première fois. Supprimez toute ligne qui ne change pas ce que vous feriez. Les conseils génériques (« écrivez un code propre », « gérez les erreurs correctement ») sont les coupables habituels.
• Signalez le nombre final de lignes et la liste des fichiers créés.

Si CLAUDE.md dépasse 150 lignes, coupez plutôt que de compresser — déplacez une section entière dans un fichier de documentation et laissez une ligne d'index derrière vous. Compresser le texte pour le faire tenir produit un fichier dense que personne ne parse.

Travailler avec un CLAUDE.md existant

S'il en existe déjà un, ne l'écrasez pas aveuglément. Lisez-le d'abord, puis vérifiez-le par rapport au code actuel : commandes qui n'existent plus, répertoires qui ont été renommés, motifs qui ont été abandonnés. Préservez toute instruction manuscrite qui encode une préférence humaine que vous ne pouvez pas déduire du code (« ne touchez jamais au SDK vendorisé », « demandez avant d'ajouter une dépendance ») — ce sont les lignes les plus précieuses du fichier et les plus faciles à détruire. Montrez à l'utilisateur ce que vous supprimez et pourquoi avant de couper quoi que ce soit de substantiel.