0001 Doc de référence vs artefacts de travail

• Statut : Accepté
• Date : 2026-10-12
• Décideurs : Mickaël Lambert

Contexte

Le dossier docs/ mélangeait deux natures de contenu : de la doc de référence vivante (architecture, modèle de données, modélisation, runbooks) et des artefacts de travail (plans de design, exports générés). Conséquences observées : un plan de design avait fuité dans le versioning, un export PDF du matching de 2026-04 traînait, périmé et redondant avec les .md, et du savoir réel (modeling.md, la spec d'onboarding) n'était même pas publié dans la nav mkdocs.

La question posée : faut-il versionner tout docs/ ou rien, et comment ne pas perdre de connaissance ?

Décision

docs/ est une base de connaissance docs-as-code, versionnée et publiée via mkdocs (public interne). On sépare strictement deux natures :

• Doc de référence : versionnée, relue en PR, présente dans la nav mkdocs.
• Artefacts de travail : non versionnés. Les plans vivent dans docs/plans/ (gitignoré), les exports générés dans docs/generated/ (gitignoré). On versionne la source, jamais le binaire généré. Un généré sans source est un orphelin à retirer.

Alternatives considérées

• Tout versionner, y compris plans et exports. Compromis : préserve l'historique mais pollue la base de référence et expose des docs périmées ou trompeuses sur le site.
• Ne rien versionner, externaliser la doc dans un wiki. Compromis : allège le repo mais détache la doc du code, elle drift et n'est plus relue en PR.

La frontière retenue garde l'avantage du docs-as-code (relecture, proximité du code) sans le bruit des artefacts jetables.

Conséquences

• docs/plans/ et docs/generated/ sont dans .gitignore.
• La règle opérationnelle est reportée dans le CLAUDE.md racine (section Documentation).
• La CI docs tourne en mkdocs build --strict, et exclude_docs sort les dossiers d'artefacts locaux du build, pour garantir qu'aucun orphelin ni artefact ne soit publié.
• L'export PDF/HTML périmé du matching a été retiré du versioning.