Démarrer un projet — Guide & Templates

Protocole interne MJY Holding. À suivre à la création de chaque nouveau repo Git et à chaque session de travail avec Claude Code.

1. Création du repo — checklist obligatoire

Avant d'écrire la première ligne de code, le repo doit être configuré. Claude Code ne peut pas travailler correctement sans ce contexte.

✅ À faire sur GitHub

• Créer le repo sous ENGWE-FRANCE/ (pas sous un compte perso)
• Renseigner la description du repo (1 phrase claire, ex: "Plateforme RH interne — planning, paie, alertes. React/Vite/Supabase.")
• Ajouter les topics GitHub (ex: react, supabase, internal, engwe)
• Choisir la visibilité : Private par défaut
• Initialiser avec un README.md
• Ajouter un .gitignore adapté au stack

✅ À créer dans le repo (à faire avec Claude Code au démarrage)

README.md              ← description, stack, lancer en local
CLAUDE.md              ← contexte permanent pour Claude (voir template ci-dessous)
docs/
  product_backlog.md   ← toutes les fonctionnalités planifiées
  sprints/
    sprint_01/
      sprint_backlog.md
      tasks.md

2. Template CLAUDE.md — à créer dans chaque nouveau repo

Ce fichier est lu automatiquement par Claude Code à chaque session. Il donne le contexte permanent du projet. Sans lui, Claude repart de zéro à chaque fois.

Copie ce template et remplis chaque section :

# Contexte projet — [NOM DU PROJET]

## Identité du projet
- **Nom** : [Nom complet]
- **Slug** : [kebab-case, ex: mjy-task-platform]
- **Repo** : ENGWE-FRANCE/[nom-repo]
- **Marque** : [ENGWE / KOBIKE / Miyan / MJY Holding]
- **Statut** : [en construction / actif / maintenance]
- **Déployé sur** : [Netlify / VPS Hostinger / local / ...]
- **URL prod** : [https://...]
- **URL staging** : [si applicable]

## Stack technique
- **Frontend** : [React 18 + Vite / Next.js / ...]
- **Backend** : [Supabase / Express / n8n / ...]
- **Base de données** : [PostgreSQL via Supabase / SQLite / ...]
- **Auth** : [Supabase Auth / JWT / ...]
- **Déploiement** : [Netlify / GitHub Pages / Docker + Coolify]
- **CI/CD** : [GitHub Actions / Manuel]

## Objectif du projet
[2-3 phrases : quel problème ça résout, pour qui, quelle valeur ça apporte]

## Utilisateurs cibles
- **[Rôle 1]** : [ce qu'il fait, ce dont il a besoin]
- **[Rôle 2]** : [idem]

## Fonctionnalités principales (résumé)
1. [Feature 1]
2. [Feature 2]
3. [Feature 3]
(voir `docs/product_backlog.md` pour le détail complet)

## Règles de travail — RESPECTER ABSOLUMENT

### Branches Git
- **Ne jamais travailler directement sur `main`**
- Créer une branche à chaque session ou chaque jour : `feat/[date]-[sujet]` ou `fix/[date]-[sujet]`
  - Exemple : `feat/2026-07-15-auth-pin` ou `session/2026-07-15-sprint-02`
- Merger sur `main` uniquement quand la fonctionnalité est stable et testée
- **Toujours vérifier sur quelle branche on est avant de commencer**

### Sprints
- Chaque sprint dure [1 semaine / 2 semaines]
- À chaque début de sprint : créer `docs/sprints/sprint_XX/sprint_backlog.md` et `tasks.md`
- À chaque fin de sprint : créer `docs/sprints/sprint_XX/sprint_review.md` avec ce qui a été fait, ce qui ne l'a pas été, et pourquoi
- Les numéros de sprint sont séquentiels : sprint_01, sprint_02, ...

### Recap quotidien
- En fin de journée (ou session), créer / mettre à jour `docs/sprints/sprint_XX/rapport_[DATE].md`
- Le rapport contient : ce qui a été fait, les décisions prises, les blocages, la prochaine étape

### Documentation
- Toute décision d'architecture importante → créer un ADR dans `docs/ADR/ADR_XXXX_sujet.md`
- Format ADR : contexte, décision, conséquences, alternatives rejetées

## État actuel (à mettre à jour à chaque session)
- **Sprint en cours** : sprint_01
- **Dernière mise à jour** : [DATE]
- **Prochaine étape** : [en une phrase]

## Accès & secrets
- Variables d'environnement dans `.env.local` (jamais committé)
- Clés Supabase : voir `.env.local` → `VITE_SUPABASE_URL` et `VITE_SUPABASE_ANON_KEY`
- [Autres secrets si applicable]

## Notes importantes
[Tout ce que Claude doit savoir et qui n'entre pas dans les catégories ci-dessus :
contraintes métier, décisions passées, choses à ne PAS faire, etc.]

3. Template docs/product_backlog.md

# Product Backlog — [NOM DU PROJET]

> Source de vérité pour toutes les fonctionnalités planifiées.
> Mise à jour à chaque sprint planning ou quand une nouvelle idée est validée.
> **Format** : chaque user story = une ligne avec priorité, statut et sprint cible.

---

## Épiques

### Épique 1 — [Nom de l'épique]
*[Description courte de l'objectif]*

| # | User Story | Priorité | Statut | Sprint |
|---|-----------|----------|--------|--------|
| US-001 | En tant que [rôle], je veux [action] afin de [bénéfice] | 🔴 Haute | 🔲 À faire | Sprint 01 |
| US-002 | En tant que [rôle], je veux [action] afin de [bénéfice] | 🟡 Moyenne | 🔲 À faire | Sprint 02 |

### Épique 2 — [Nom de l'épique]
*[Description courte]*

| # | User Story | Priorité | Statut | Sprint |
|---|-----------|----------|--------|--------|
| US-010 | En tant que [rôle], je veux [action] afin de [bénéfice] | 🔴 Haute | ✅ Fait | Sprint 01 |

---

## Légende
- 🔴 Haute — bloque d'autres fonctionnalités ou demande forte
- 🟡 Moyenne — important mais pas urgent
- 🟢 Basse — nice-to-have
- 🔲 À faire | 🔄 En cours | ✅ Fait | ❌ Annulé

4. Prompt de démarrage — Coller dans Claude Code à J+1 d'un nouveau repo

Utilise ce prompt une seule fois, au tout début du projet, après avoir créé le repo et le CLAUDE.md vide. Claude va poser les questions pour tout remplir.

Tu vas m'aider à démarrer un nouveau projet de zéro.

Je viens de créer le repo [NOM_DU_REPO] sur GitHub (ENGWE-FRANCE/[NOM_DU_REPO]).

**Ton rôle** : agir comme un product owner / tech lead qui pose les bonnes questions pour cadrer le projet avant d'écrire la première ligne de code.

**Ce que tu dois faire, dans l'ordre** :

1. Pose-moi des questions pour comprendre le projet :
   - Quel problème ce projet résout-il ?
   - Qui sont les utilisateurs (rôles, besoins) ?
   - Quel est le stack technique choisi (ou à choisir) ?
   - Quelle est la fonctionnalité #1 à livrer en premier ?
   - Y a-t-il des contraintes (délai, budget, intégrations existantes) ?
   - Comment sera déployé le projet ?

2. Sur la base de mes réponses, génère et crée ces fichiers directement dans le repo :
   - `CLAUDE.md` : rempli avec tout le contexte (utilise le template du hub de doc)
   - `README.md` : description claire, stack, comment lancer en local (même si vide pour l'instant)
   - `docs/product_backlog.md` : les premières user stories organisées en épiques, issues de notre échange
   - `docs/sprints/sprint_01/sprint_backlog.md` : les stories sélectionnées pour le sprint 1 (les plus prioritaires)
   - `docs/sprints/sprint_01/tasks.md` : les tâches techniques découpées depuis les stories du sprint 1

3. Crée la structure de dossiers du projet selon le stack choisi.

4. Crée la première branche de travail :

git checkout -b feat/[DATE_AUJOURDHUI]-setup-initial

5. Résume ce qu'on a décidé et ce qu'on va faire en premier.

Commence par poser tes questions — une par une ou groupées par thème, comme tu préfères.

5. Prompt quotidien — Coller chaque matin dans Claude Code

Utilise ce prompt au début de chaque session de travail. Il force Claude à reconsulter le backlog, à recadrer sur les priorités, et à organiser la journée.

Bonjour. Nouvelle session de travail sur [NOM_DU_PROJET].

**Avant de commencer, fais les vérifications suivantes :**

1. **Lis `CLAUDE.md`** pour te remettre dans le contexte du projet.

2. **Vérifie la branche Git actuelle** :

git branch --show-current git status

- Si on est sur `main` → crée une nouvelle branche pour aujourd'hui :
  `git checkout -b session/[DATE_AUJOURDHUI]-[sujet-court]`
- Si on est déjà sur une branche de feature → dis-moi laquelle et ce qu'il reste à faire.

3. **Lis le rapport de la dernière session** (cherche le fichier le plus récent dans `docs/sprints/sprint_XX/rapport_*.md`) et fais-m'en un résumé en 3 points :
- Ce qui a été fait
- Les décisions prises
- Ce qui était prévu pour aujourd'hui

4. **Lis `docs/product_backlog.md`** et identifie :
- Les stories "En cours" ou "À faire" pour le sprint actuel
- Les 3 éléments les plus prioritaires non encore faits

5. **Propose-moi un plan pour aujourd'hui** :
- Demande-moi sur quoi je veux me concentrer (ou propose-moi les priorités logiques)
- Découpe en blocs de travail (ex: matin / après-midi, ou bloc 1 / bloc 2 / bloc 3)
- Mets en évidence les dépendances (ex: "il faut finir X avant de pouvoir faire Y")

6. **En fin de session** (quand je te dis "fin de session" ou "recap"), tu devras :
- Créer ou mettre à jour `docs/sprints/sprint_XX/rapport_[DATE].md` avec :
  - Ce qu'on a fait aujourd'hui
  - Les décisions prises et pourquoi
  - Les blocages rencontrés
  - Ce qui est prévu pour la prochaine session
- Mettre à jour les statuts dans `docs/product_backlog.md` (🔄 → ✅ si terminé)
- Mettre à jour `CLAUDE.md` section "État actuel"
- Proposer le commit final avec un message clair

Commence par la vérification #1 et dis-moi où on en est.

6. Prompt "fin de session" — Recap rapide

Si tu es pressé et que tu veux juste faire le recap sans relire tout le contexte :

Fin de session. Fais le recap de ce qu'on a fait aujourd'hui :

1. Liste tout ce qu'on a réalisé (fichiers créés/modifiés, fonctionnalités implémentées, bugs corrigés)
2. Note les décisions importantes prises
3. Identifie ce qui est resté en suspens
4. Mets à jour `docs/product_backlog.md` (change les statuts)
5. Crée `docs/sprints/sprint_XX/rapport_[DATE_AUJOURD'HUI].md` avec un résumé structuré
6. Propose le commit Git avec un message conventionnel (feat/fix/docs/refactor...)
7. Dis-moi si je dois merger sur main ou garder la branche pour demain

7. Convention de nommage des branches

8. Convention de nommage des fichiers docs

9. À retenir — Les 5 règles d'or

1. CLAUDE.md toujours à jour — c'est la mémoire de Claude entre les sessions.

2. Jamais travailler sur main — une branche par jour minimum.

3. Un sprint = des documents — sprint_backlog + tasks au début, sprint_review à la fin.

4. Recap en fin de session — même 3 lignes valent mieux que rien.

5. Le backlog est vivant — le mettre à jour dès qu'une décision change les priorités.