La gouvernance : une constitution, une mémoire, des reviews

Ce dépôt est édité par des humains et par des agents IA. Pour que les deux travaillent sans se marcher dessus, la gouvernance ne repose pas sur la mémoire des personnes : elle est écrite, versionnée, et organisée en trois couches.

CLAUDE.md : la constitution

À la racine du dépôt, CLAUDE.md fixe ce qui ne se négocie pas : la mission du projet, la stack, les principes (une page n’est jamais du HTML libre, seul le contenu publié est rendu en production, pas de JavaScript client sans justification écrite), les commandes, et la liste des actions interdites. Tout contributeur — humain ou agent — le lit avant de toucher au code. C’est court, exigeant, et c’est voulu : une constitution de quarante pages ne serait lue par personne.

PROJECT_DECISIONS.md : la mémoire

Chaque décision d’architecture durable est consignée dans PROJECT_DECISIONS.md avec son contexte, les alternatives écartées et ses conséquences. La règle d’usage est simple : on ne re-litige jamais une décision sans écrire une nouvelle entrée. Envie de revenir sur le choix de Cloudflare Pages ou sur la convention des liens ? Très bien — mais cela passe par une entrée datée qui remplace l’ancienne, pas par un changement silencieux. Ce fichier évite le pire ennemi des projets longs : redébattre tous les trois mois des mêmes sujets, avec à chaque fois un peu moins de contexte.

Les docs spécialisées

Six documents couvrent chacun un domaine : ARCHITECTURE.md (comment le site est construit), DESIGN_SYSTEM.md (les règles visuelles), SECURITY.md (le modèle de menace), TESTING.md (la stratégie de test), OPERATIONS.md (l’exploitation au quotidien) et LAUNCH.md (le lancement d’un nouveau site). La règle : si un changement modifie l’architecture, la doc correspondante est mise à jour dans le même commit.

Les skills de review

Trois reviewers spécialisés, exécutables à la demande, encadrent les changements :

• project-guardian classe chaque changement par niveau de risque — Low (contenu, typo), Medium (nouveau bloc, dépendance), High (architecture, sécurité, URLs publiées) — et adapte l’exigence de review en conséquence ;
• architecture-review vérifie qu’un changement respecte les décisions actées et les patterns existants ;
• security-review traque secrets, surfaces d’attaque et scripts tiers.

Un risque Low passe vite ; un risque High exige plan, justification et rollback documenté. L’énergie de review va là où le danger est réel.

Le principe directeur

Tout cela sert une seule idée : préserver l’architecture existante, par petits changements réversibles. Ce dépôt est un template — chaque raccourci pris ici sera hérité par tous les sites clonés. Un petit changement propre et annulable vaut toujours mieux qu’une refonte brillante et risquée.

La gouvernance dit qui décide quoi et comment ; la vérification mécanique de ces règles, elle, est confiée au tribunal qualité : audits, tests et CI bloquante. Les deux couches sont complémentaires — la gouvernance pense, le tribunal exécute.