194 lines
9.8 KiB
Markdown
194 lines
9.8 KiB
Markdown
# Méthode — démarrer un projet école
|
||
|
||
Consigne à donner à Cursor au **premier message** d’un nouveau projet 42.
|
||
Elle reprend la méthode déjà utilisée sur la piscine mobile, Swifty Companion et Tokenizer.
|
||
|
||
Copier ce fichier dans `docs/` du nouveau dépôt, ou l’ouvrir dans le chat et demander : « mets en place la structure décrite dans ce document, sans coder la fonctionnalité ».
|
||
|
||
---
|
||
|
||
## 1. Deux espaces, un seul dossier de travail
|
||
|
||
Tout vit dans **un dépôt perso** (Gitea / Git privé). Le correcteur ne voit **jamais** ce dépôt entier.
|
||
|
||
| Espace | Chemin | Qui le lit | Git école |
|
||
|--------|--------|------------|-----------|
|
||
| **Travail** | racine du dépôt : `README.md`, `docs/` | Toi + Cursor | Non |
|
||
| **Rendu** | un sous-dossier dédié, ex. `swiftyCompanion/`, `tokenizerRendu/`, `mobileModule01/` | Le correcteur, une fois copié à la racine Intra | Oui — **ce contenu devient la racine** du dépôt Vogosphere |
|
||
|
||
Règle : on **code dans le paquet de rendu**. On **explique dans `docs/`**.
|
||
|
||
Le README à la racine du dépôt de travail dit en une page : où est le sujet, où est la pédagogie, où est le paquet école, et comment pousser plus tard. Il ne remplace pas le README du rendu.
|
||
|
||
---
|
||
|
||
## 2. Ordre de démarrage (avant le code métier)
|
||
|
||
Cursor crée l’arborescence, extrait le sujet, rédige le cadrage. Il n’implémente pas l’app tant que le cadrage (section 4) n’est pas relu.
|
||
|
||
```text
|
||
<projet>/
|
||
README.md # dépôt de travail
|
||
.gitignore # .env, builds, .git imbriqué du rendu
|
||
docs/
|
||
README.md # index
|
||
methode-demarrage-projet-ecole.md # cette consigne, recopiée
|
||
sujets/
|
||
README.md
|
||
<slug>.md # traduction FR fidèle + visuels décrits
|
||
originaux/
|
||
<slug>_subject.pdf # PDF Intra, renommé (pas en.subject.pdf)
|
||
captures/ # images extraites du PDF s’il y en a
|
||
pedagogie/
|
||
README.md # feuille de route (table des étapes)
|
||
00-reprise-et-etat.md # où on en est, prochaine action
|
||
cahier-des-charges.md # exigences du sujet → critère testable
|
||
architecture.md # modules, flux, données — calé sur le sujet
|
||
ui.md # seulement si le sujet a des écrans ou maquettes
|
||
protocole-test-manuel.md # checklist device / démo, cases vides
|
||
fiche-depot.md # plus tard : comment pousser le rendu
|
||
fiche-soutenance-orale.md # plus tard : déroulé oral, reste dans docs/
|
||
<paquetRendu>/
|
||
README.md # doc école (voir section 6)
|
||
.gitignore
|
||
.env.example # seulement si le sujet a des secrets
|
||
… code …
|
||
```
|
||
|
||
Nom du paquet de rendu : celui du sujet, ou un nom explicite défendable à l’oral. Pas de deuxième copie du code à la racine du dépôt de travail.
|
||
|
||
---
|
||
|
||
## 3. Extraction du sujet (première tâche)
|
||
|
||
1. Déposer le PDF Intra dans `docs/sujets/originaux/`, renommé (`swifty_companion_subject.pdf`, pas `en.subject.pdf`).
|
||
2. Extraire le texte **et** les figures (maquettes, schémas, arborescence imposée) dans `docs/sujets/captures/` quand le PDF en contient.
|
||
3. Rédiger `docs/sujets/<slug>.md` :
|
||
- traduction française **fidèle** (le PDF reste la source si un doute apparaît) ;
|
||
- obligatoire / bonus / interdit, chacun dans sa section ;
|
||
- arborescence de rendu si le sujet en impose une ;
|
||
- messages, noms de champs, libellés : **recopiés tels quels** (souvent en anglais).
|
||
4. `docs/sujets/README.md` pointe le markdown et le PDF.
|
||
|
||
Interdit d’inventer une fonctionnalité, un écran ou une techno absents du sujet pour « améliorer » le projet. Un bonus du PDF se fait après la partie obligatoire, et se note comme bonus dans le cahier des charges.
|
||
|
||
---
|
||
|
||
## 4. Doc de dev (cadrage)
|
||
|
||
Tout ceci reste dans `docs/pedagogie/`. Aucun de ces fichiers ne part sur Vogosphere.
|
||
|
||
### `cahier-des-charges.md`
|
||
|
||
Grille de conformité. Une ligne par exigence du PDF :
|
||
|
||
| # | Exigence (citation courte ou renvoi §) | Critère de validation | Hors scope | Statut |
|
||
|---|----------------------------------------|------------------------|------------|--------|
|
||
|
||
La colonne **Hors scope** sert à figer ce qu’on ne fera pas (ex. « pas d’API météo au module 1 », « pas de mainnet »). En cas de doute, on relit le sujet ; on n’élargit pas le périmètre.
|
||
|
||
### `architecture.md`
|
||
|
||
Découpage réel du code à venir : entrée, écrans ou commandes, services (API, auth, base), où vivent les secrets, ce qui est partagé entre exercices. Schéma simple (liste ou mermaid) suffit. Chaque bloc renvoie à une exigence du cahier des charges.
|
||
|
||
### `ui.md` (si le sujet a une interface)
|
||
|
||
Un écran = une section : ce que montre la maquette, les libellés exacts, navigation, états vides / erreur / chargement **déjà décrits par le sujet**. Les captures vivent dans `docs/sujets/captures/`. On ne redessine pas.
|
||
|
||
### Feuille de route
|
||
|
||
`docs/pedagogie/README.md` est la table des étapes. Une étape = un objectif vérifiable (ex. « OAuth + `/v2/me` », « ex00 géoloc »). Statut : à faire / en cours / fait.
|
||
|
||
`00-reprise-et-etat.md` tient en une page : ce qui est fait, la prochaine étape, les commandes pour relancer. C’est le fichier à ouvrir en reprenant le projet.
|
||
|
||
Les guides détaillés (`etape-02-….md`, `module-01/ex00-guide.md`) s’écrivent **quand l’étape démarre**, pas tous d’avance.
|
||
|
||
### Rituel de lot
|
||
|
||
Pour chaque lot (cadrage, README école, fiche orale, commentaires) : Cursor décrit ce qu’il va faire → tu valides → il exécute → la case est cochée dans `00-plan` ou la feuille de route. Pas de gros chantier non relu.
|
||
|
||
---
|
||
|
||
## 5. Où coder
|
||
|
||
- Uniquement dans `<paquetRendu>/`.
|
||
- Commentaires de code en **français**. Les chaînes imposées par le sujet restent dans la langue du PDF.
|
||
- Secrets : `.env` local, listé dans `.gitignore`, jamais commité. `.env.example` versionné, sans valeur réelle. Le sujet qui punit un secret public (OAuth, clé API) est rappelé dans le README école.
|
||
- Pas de lien « pour aller plus vite » vers un autre dépôt école. La piscine peut servir de **référence perso** dans `docs/`, pas dans le paquet rendu.
|
||
|
||
---
|
||
|
||
## 6. Doc école — indépendante en fin de projet
|
||
|
||
Le README de `<paquetRendu>/` est le seul mode d’emploi du correcteur. Il contient : prérequis, installation, variables (via `.env.example`), commandes `analyze` / `test` / `run`, ce qu’il faut montrer (exercices ou écrans), et les messages d’erreur attendus s’ils sont au sujet.
|
||
|
||
**Pendant la construction**, un lien vers `docs/pedagogie/` est toléré le temps de rédiger le README (pour ne pas réécrire deux fois). **Dès que le comportement est stable**, ces liens sont retirés.
|
||
|
||
Clôture, avant branche ou push école :
|
||
|
||
```bash
|
||
# depuis le paquet de rendu — doit rester vide
|
||
grep -RIn --include='*.md' -E 'docs/pedagogie|/home/|piscine_mobile|tokenizer/docs' .
|
||
```
|
||
|
||
Le correcteur clone le dépôt école, ouvre le README à **sa** racine, et lance les commandes **depuis ce dossier**. On vérifie la même chose en local :
|
||
|
||
```bash
|
||
cd <paquetRendu>
|
||
# commandes du README, sans sortir vers la racine du dépôt de travail
|
||
```
|
||
|
||
Checklist device : `docs/pedagogie/protocole-test-manuel.md` (cases à cocher). Le README école reprend les critères utiles au correcteur, sans renvoyer vers ce protocole.
|
||
|
||
---
|
||
|
||
## 7. Git — travail et rendu
|
||
|
||
Développer sur **`main`** du dépôt perso. La doc `docs/` se commit **là**. La perdre sur une branche de rendu, c’est la perdre au checkout.
|
||
|
||
Deux formes déjà utilisées ; en choisir **une** au cadrage et l’écrire dans `fiche-depot.md`.
|
||
|
||
**A — Paquet imbriqué** (Swifty, Tokenizer). Quand le rendu est prêt : `git init` dans `<paquetRendu>/` (ou copie vers un clone Vogosphere vide). Le `.git` imbriqué est ignoré par le dépôt de travail. On ne pousse pas `docs/`.
|
||
|
||
**B — Branche snapshot** (piscine, un module = un dépôt). Quand le module est validé sur `main`, créer `rendu-…` qui ne garde que le `.gitignore` racine et le dossier du module. Si `main` change ensuite : **supprimer et recréer** la branche. Pas de merge de `main` dedans.
|
||
|
||
Dans les deux cas, la fiche orale et les guides restent sur `main` / `docs/`.
|
||
|
||
---
|
||
|
||
## 8. Préparation soutenance (après le code)
|
||
|
||
Dans l’ordre, chacun validé avant le suivant :
|
||
|
||
| Lot | Livrable | Où |
|
||
|-----|----------|----|
|
||
| README autonome | plus aucun lien vers `docs/` | `<paquetRendu>/README.md` |
|
||
| Fiche orale | déroulé, commandes, démo, questions probables, renvois au code | `docs/pedagogie/` seulement |
|
||
| Commentaires | français, sur le code du rendu | `<paquetRendu>/` |
|
||
| Dépôt école | `fiche-depot.md` exécuté ; re-test **depuis** le paquet rendu | Vogosphere |
|
||
|
||
`analyze` et `test` doivent passer sur cette copie « comme à l’école » avant le push.
|
||
|
||
---
|
||
|
||
## 9. Consigne courte à coller dans Cursor
|
||
|
||
```text
|
||
Lis docs/methode-demarrage-projet-ecole.md et applique-la à ce dépôt.
|
||
|
||
1. Range le PDF dans docs/sujets/originaux/ et produis la traduction fidèle
|
||
docs/sujets/<slug>.md (obligatoire, bonus, interdit, libellés exacts,
|
||
captures si le PDF a des visuels).
|
||
2. Crée le cadrage dans docs/pedagogie/ : reprise, cahier des charges
|
||
(une exigence = une ligne testable + hors scope), architecture,
|
||
feuille de route, ui.md seulement si le sujet a une interface,
|
||
protocole de test manuel vide.
|
||
3. Crée le paquet de rendu avec README, .gitignore et .env.example
|
||
si des secrets existent. Le README école peut linker docs/ le temps
|
||
du développement ; il sera nettoyé avant le push école.
|
||
4. Ne code pas la fonctionnalité tant que je n’ai pas validé le cadrage.
|
||
5. Ensuite, une étape de la feuille de route à la fois, code uniquement
|
||
dans le paquet de rendu, commentaires en français, aucun ajout hors sujet.
|
||
6. Réponds en français. Décris le lot, attends ma validation, puis exécute.
|
||
```
|