CLAUDE.md : le manifeste qui fait loi

Le problème : l'agent arrive amnésique

Chaque session d'agent démarre de zéro : il ne connaît ni vos conventions, ni vos pièges, ni vos raisons. Sans contexte, il produira du code générique — correct en apparence, faux dans votre cadre (le WHERE tenant_id qu'il ajoutera avec les meilleures intentions du monde est précisément interdit chez vous).

La réponse : un manifeste à la racine du repo (CLAUDE.md chez Claude Code, AGENTS.md en standard émergent), chargé automatiquement à chaque session. C'est le document le plus lu de votre équipe — par les agents à chaque tâche, par les humains à l'onboarding.

L'anatomie d'un bon manifeste (celui du projet étudié)

1. Ce qu'est le projet en dix lignes : le produit, l'architecture, où vivent les choses ;
2. Les invariants non négociables, formulés en interdits vérifiables : « jamais de WHERE tenant_id manuel (RLS) », « jamais de schéma en dur », « fail loud : raise plutôt que return None », « pas de feature flag, pas de futurisme » ;
3. Les règles de style structurantes : composition > héritage, un fichier = une chose (> 600 lignes = signal d'alerte), tout SDK en version async ;
4. Les pointeurs : où sont les ADRs, les docs par module, les commandes (just lint, just test) — le manifeste route, il ne duplique pas.

Les règles d'écriture qui font la différence

• Des interdits testables, pas des vœux : « privilégier la simplicité » ne guide rien ; « fichier > 600 lignes = alerte » se vérifie. Un agent applique ce qui est falsifiable ;
• Le POURQUOI en une ligne : « jamais de WHERE tenant_id — il masquerait une régression RLS » : l'agent (comme l'humain) généralise correctement quand il comprend la raison ;
• Court et dense : le manifeste est injecté dans chaque contexte — chaque ligne inutile coûte de l'attention (et des tokens). Le détail vit dans les ADRs et les docs, référencés ;
• Maintenu comme du code : une règle violée en revue = une règle à reformuler ; un piège découvert = une ligne ajoutée. Le manifeste du projet étudié porte des numéros de section cités dans les MRs (« CLAUDE.md §B.11 ») — c'est devenu la jurisprudence de l'équipe.