Aller au contenu

ADR-048 : Parcours d'accueil « welcome-projet » dans le squelette

Statut

Accepté, bêta publique 1.0 (1.0.0-beta.x).
Mise en œuvre par les tickets WELCOME-PROJET-*.

Date

2026-06-24

Contexte

forge new produit un projet nu (ADR-024), accompagné d'une page d'accueil web
(mvc/views/home/index.html) et, depuis l'ADR-047, d'une couche de guidance pour
les agents IA (CLAUDE.md, AGENTS.md, ADR-001).

Il manque un onboarding pédagogique humain, local au projet : un fil
conducteur qui guide les premiers gestes dans ce projet précis.
Le tutoriel welcome-forge (publié sur forgemvc.com) enseigne le framework, mais
il est exhaustif et en ligne, pas un point de départ local et court.

Décision

forge new embarque un parcours d'accueil docs/welcome/ dans le projet généré.

  1. Local et orienté « ton projet » : le parcours fait faire les premiers
    gestes dans l'application qu'on vient de créer (première entité, CRUD, page,
    opt-in, validation), pas un cours abstrait.
  2. Court, anti-duplication : chaque page reste brève et renvoie à
    forgemvc.com pour approfondir, plutôt que de recopier la documentation
    exhaustive. On évite de dupliquer welcome-forge.
  3. Multi-paliers : installation.md, puis trois niveaux (débutant,
    intermédiaire, avancé) de deux étapes chacun, chaînés par un bilan.md, et un
    recapitulatif.md.
  4. Source : contenu statique sous cli/skeleton/data/docs/welcome/, copié
    tel quel par forge new (couvert par le package-data skeleton/data/**).
  5. Propriété du projet : le développeur peut adapter ou supprimer ce parcours.

Conséquences

Positives :

  • un développeur dispose d'un fil conducteur local dès la création du projet ;
  • le parcours utilise les commandes réelles du projet, pas des exemples hors sol.

Coûts et limites :

  • déviation assumée d'ADR-024 : le projet généré gagne un onboarding (comme la
    config VS Code, les schémas JSON et la couche agent) ;
  • contenu à maintenir distillé et aligné avec le CLI ;
  • pas de version de Forge codée en dur dans les pages (pour ne pas dater le
    squelette ni déclencher les garde-fous de version).

Relation avec ADR-024 et ADR-047

Trois couches « expérience » accompagnent désormais un projet nu, sans générer de
code métier :

  • ADR-024 : le projet reste nu côté code applicatif ;
  • ADR-047 : guidance pour les agents IA (CLAUDE.md, AGENTS.md, ADR-001) ;
  • ADR-048 : onboarding humain (docs/welcome/).

Alternatives écartées

  • Un simple README d'onboarding : utile mais moins guidé qu'un parcours ;
    pourra coexister, mais ne remplace pas le fil conducteur multi-paliers.
  • Dupliquer intégralement welcome-forge dans le projet : redondant et lourd à
    maintenir.
  • Ne rien fournir : le développeur démarre sans fil conducteur local.

Mise en œuvre (tickets WELCOME-PROJET-*)

  • WELCOME-PROJET-CONTENT-001 : rédiger le parcours dans
    cli/skeleton/data/docs/welcome/ (installation + 3 niveaux + bilans +
    récapitulatif), court et renvoyant à forgemvc.com.
  • WELCOME-PROJET-NAV-001 : garde-fou de chaînage du parcours.

Liens