project-structure-convention

Version : 1.0 — Juin 2026 Scope : Tout projet Gentle Designs (web, desktop, data) Objectif : Fixer l'arborescence documentaire commune — quels fichiers « capitaux » chaque projet maintient, où ils vivent, et comment les reconnaître au premier coup d'œil. Sert autant à démarrer un nouveau projet qu'à mettre à niveau l'existant.

0. Philosophie — Pourquoi ce document existe

De projet en projet, les mêmes documents de pilotage réapparaissent (README, suivi de dev, design system…), mais sous des noms et à des emplacements variables. Cette dérive coûte cher : on ne sait plus où chercher, et chaque nouveau projet réinvente son arborescence. Ce document fige la convention pour qu'elle devienne un repère stable, identique partout.

Principe directeur : un repère ne vaut que s'il est au même endroit, avec le même nom, dans tous les projets.

Pour un petit projet, une partie de ces fichiers est superflue — c'est assumé. La règle n'est pas « tout créer toujours », mais « quand un de ces rôles existe, il porte CE nom, à CET endroit ».

1. Règle de nomenclature — le signe distinctif

Les fichiers capitaux sont TOUJOURS nommés en CAPS (majuscules + underscore) :

README.md   DESIGN_SYSTEM.md   DEVELOPER_GUIDE.md   PROGRESS.md
CHANGELOG.md   ROADMAP.md   PRD.md   CLAUDE.md

La casse majuscule est le repère visuel immédiat dans l'arbre de fichiers : un document en CAPS = un document de pilotage de premier plan, à connaître. Le contexte projet pour agents (docs/claude-mds/) reste lui en minuscules kebab-case (architecture.md, suivi-dev.md → désormais remonté en PROGRESS.md, frontend/design-tokens.md…), précisément pour ne PAS se confondre avec les capitaux.

2. Les fichiers capitaux — rôle & emplacement

Note sur PROGRESS.md (changement v1.0)

Le suivi de dev s'appelle désormais docs/PROGRESS.md (CAPS, à la racine de docs/), et non plus docs/claude-mds/suivi-dev.md. Raison : c'est un document de pilotage de premier plan (on le consulte tous les jours), il mérite donc le statut « capital » et la visibilité d'un nom en CAPS, plutôt que d'être enfoui dans le contexte agent. Migration d'un projet existant : git mv docs/claude-mds/suivi-dev.md docs/PROGRESS.md, puis mettre à jour les références dans CLAUDE.md et docs/README.md.

3. Icônes de fichiers (VS Code) — lisibilité de l'arbre

Pour que chaque capital se distingue visuellement, on mappe une icône dédiée via Material Icon Theme (workbench.iconTheme: "material-icon-theme"). Configuration globale (par nom de fichier, insensible à la casse) dans ~/AppData/Roaming/Code/User/settings.json → un seul mapping profite à tous les projets :

"material-icon-theme.files.associations": {
  "progress.md": "gnuplot",        // courbe d'avancement
  "design_system.md": "palette",   // design / couleurs
  "developer_guide.md": "document", // guide technique
  "roadmap.md": "roadmap"          // vision / étapes
}

README.md et CHANGELOG.md reçoivent déjà une icône distinctive par défaut du thème — inutile de les mapper.

4. Checklist

Démarrer un nouveau projet

• README.md + CLAUDE.md à la racine (CAPS).
• docs/PROGRESS.md dès la première session de dev.
• docs/gentlewits/ en submodule + docs/claude-mds/ pour le contexte agent.
• DESIGN_SYSTEM.md / DEVELOPER_GUIDE.md quand l'UI / l'équipe le justifient.

Mettre à niveau un projet existant

• Renommer suivi-dev.md → docs/PROGRESS.md (+ mettre à jour les références).
• Vérifier que les capitaux présents sont bien en CAPS, au bon emplacement.
• Créer en stub structuré les capitaux manquants (sections réelles + amorce + TODO), sans remplissage générique.

Lien : voir aussi le guide « Getting Started » sur gentledesigns.studio (cycle projet en 4 phases) et keyboard-navigation.md / frontend-anti-slop-playbook.md pour les standards frontend.

Dernière mise à jour : juin 2026