Le dossier de contexte du projet

En chantier Cette section est en cours d'écriture : ce guide est lisible mais pas encore finalisé, son contenu peut évoluer.

Le guide précédent a démonté la machine : un agent ne « connaît » pas votre repo, il l’explore, appel d’outil par appel d’outil. Et les Fondamentaux ont posé que le contexte est sa seule réalité.

La conséquence opérationnelle : tout ce que votre projet ne dit pas par écrit sera redécouvert à grands frais, ou comblé par la moyenne du corpus.

Le dossier de contexte, c’est l’ensemble des documents que l’agent lit avant d’écrire une ligne : fichier d’instructions, décisions archivées, conventions explicites. Ce guide montre comment le construire, et surtout comment le maintenir. Parce que c’est de la documentation qui s’exécute.

À chaque session, un nouveau venu

Chaque session démarre de zéro. L’agent qui ouvre votre repo ce matin n’a aucun souvenir de celui d’hier. Même harnais, même modèle, mémoire vide. Traitez chaque session comme l’onboarding d’un prestataire compétent, rapide et ultra-littéral qui n’a jamais vu le projet.

Sans dossier de contexte, cet onboarding prend l’une de deux formes, toutes deux coûteuses :

L’exploration. L’agent lit, cherche, exécute. Chaque découverte consomme des appels d’outils et remplit la fenêtre avant même que le travail commence.
L’invention. Ce qu’il ne découvre pas, il le comble par la continuation la plus probable. Votre gestionnaire de paquets, votre convention de test, votre découpage en modules deviennent ceux de la moyenne du corpus. Plausibles, et faux chez vous.

Le dossier de contexte convertit l’exploration en lecture et l’invention en consigne. Attention, le but n’est pas de tout documenter : écrivez ce que le code ne dit pas. L’agent lit le code mieux et plus vite que n’importe quel nouveau venu. Ce qui lui manque, ce sont les décisions, les invariants, les pièges connus, et les commandes qui font foi. Paraphraser la structure des fichiers est du gaspillage. Expliquer pourquoi le module de facturation n’importe jamais l’ORM, c’est de l’information introuvable ailleurs.

Le fichier d’instructions : le contrat d’entrée

Tous les harnais convergent vers le même mécanisme : un fichier à la racine du repo, chargé automatiquement à chaque session. CLAUDE.md, AGENTS.md, le nom varie, la pratique est la même. C’est la première chose que l’agent lit, et la seule dont la lecture est garantie. Trois rubriques y travaillent :

La carte : où vivent les choses, en quelques lignes. Pas l’arborescence complète. Les frontières qui comptent et ce qu’elles protègent.
Les commandes qui font foi : comment builder, tester, vérifier. C’est ce qui transforme la boucle agentique en boucle qui converge. Un agent qui connaît npm test se corrige tout seul.
Les conventions normatives : ce qui est obligatoire ou interdit chez vous, formulé en contraintes vérifiables, pas en adjectifs.

Le style est celui que les Fondamentaux exigeaient déjà : court, normatif, vrai. Mais l’agent ajoute une contrainte économique. Ce fichier est rechargé à chaque appel de la boucle, et chaque ligne y dispute le budget d’attention au reste de la session. Mon test d’admission : si une ligne ne change aucun comportement observable de l’agent, elle n’a rien à y faire. Les principes généraux, les vœux pieux, le guide de style recopié d’internet, tout ça dilue les consignes qui, elles, devaient être lues.

Les décisions et leurs raisons

Un agent optimise la plausibilité. Or vos meilleures décisions d’architecture sont précisément celles qui s’écartent de la moyenne : pas d’ORM ici, un thème sombre unique, ce module legacy qu’on ne touche pas avant la migration. Non documentée, chaque déviation délibérée est une anomalie que l’agent (avec l’enthousiasme statistique du corpus) proposera de « corriger ».

D’où la deuxième pièce du dossier : les décisions archivées. Le format ADR fait très bien l’affaire : une décision, son contexte, les options rejetées. Le pourquoi y compte autant que le quoi. Une règle nue s’enfreint dès qu’elle gêne ; une règle motivée ferme l’espace des alternatives, pour l’agent comme pour le collègue qui relira dans deux ans.

Tout n’a pas sa place dans le fichier racine. Le dossier de contexte est un arbre : une racine courte, lue à chaque session, qui pointe vers la profondeur. « Avant de toucher à la persistance, lire docs/adr/0007-pas-d-orm.md ». L’agent suit les pointeurs à la demande, exactement comme il explore le code. Vous payez le détail seulement dans les sessions qui en ont besoin.

De la documentation vivante

La documentation a toujours pourri. Ce qui change, c’est le coût du pourrissement. Une commande de build périmée dans un README trompait un humain par trimestre, qui s’en apercevait et demandait à un collègue. La même ligne dans le dossier de contexte est exécutée à chaque session, sans le réflexe de méfiance. La dérive documentaire n’est plus un défaut cosmétique : c’est un bug en production.

Le tips Craftomancer

Un dossier périmé est pire qu’un dossier vide. Face au vide, l’agent explore : c’est lent, mais ça converge vers l’état réel du repo. Face à une consigne fausse, il obéit, avec le même aplomb statistique que pour une vraie, sans jamais soupçonner vos documents. Chaque ligne que vous n’êtes plus certain de défendre doit être vérifiée ou supprimée, ce jour-là, pas au prochain grand ménage.

L’entretien tient en deux réflexes :

Chaque déviation de l’agent est un rapport de bug contre le dossier. Quand l’agent utilise le mauvais runner de tests ou viole une frontière de module, corriger la session soigne le symptôme. La cause, c’est une ligne manquante, vague ou fausse dans le dossier. Corrigez le document : la correction sert toutes les sessions suivantes, et tous les humains aussi.
Le dossier se met à jour dans la même PR que le changement qui le périme. Comme les tests : une migration de tooling, une décision d’architecture, une frontière déplacée ne sont pas terminées tant que le dossier dit encore l’ancien monde.

Et le dossier se teste. Ouvrez une session vierge et confiez une tâche représentative, sans aide. Là où l’agent se trompe, votre dossier a un trou ou un mensonge. C’est le test d’intégration de votre documentation, au prix d’un café.

En pratique

Écrivez ce que le code ne dit pas : décisions, invariants, pièges connus, commandes qui font foi. Ne paraphrasez jamais ce que l’agent lit lui-même.
Gardez la racine courte : chaque ligne est rechargée à chaque appel de la boucle. Si elle ne change aucun comportement, supprimez-la.
Archivez les décisions avec leurs raisons, et pointez-y depuis la racine plutôt que de tout inliner. L’agent suit les pointeurs à la demande.
Traitez chaque déviation de l’agent comme un rapport de bug contre le dossier : corrigez le document, pas seulement la session.
Mettez le dossier à jour dans la même PR que le changement qui le périme, et testez-le sur session vierge de temps en temps.

Le repo sait maintenant se présenter ; reste à présenter le travail. Prochaine étape : spécifier avant de déléguer, ou comment transformer une intention en demande qu’un agent peut exécuter sans la déformer.