Leçon 10-1 — Choisir et cadrer un projet

1. Objectif

À la fin de cette leçon tu sauras : choisir un sujet de projet réaliste (utile pour toi, livrable en trois semaines, couvert par les niveaux 00–09), écrire un cahier des charges (SPECS.md) avec des exigences testables et une section « hors périmètre », découper une roadmap en jalons v0.1 → v1.0, transformer ces jalons en issues d'une session chacune, et définir « fini » AVANT d'écrire la première ligne de code.

2. Pourquoi c'est important

La cause n°1 de mort d'un projet d'apprentissage n'est ni un bug ni une notion manquante : c'est l'excès d'ambition non cadré. On démarre « une app de gestion complète », on avance à 30 %, on ne sait plus quoi faire ensuite, on abandonne. Le cadrage est la compétence qui sépare « j'ai commencé plein de trucs » de « j'ai livré un outil qui marche ». C'est aussi une compétence professionnelle centrale : dans une équipe, les specs, la roadmap et les tickets existent avant le code — tu apprends ici, en petit, le processus réel. Et c'est la première phase de TON projet final (leçon 10-P) : ce que tu produis dans cette leçon sera directement réutilisé.

3. Explication simple

Cadrer un projet, c'est répondre à quatre questions par écrit, dans cet ordre, avant de coder :

  1. Quoi et pour qui ? Quel problème concret l'outil résout, et pour quel utilisateur (ici : toi). Une phrase.
  2. Qu'est-ce qu'il fait exactement — et qu'est-ce qu'il ne fera PAS ? C'est le cahier des charges : une liste courte d'exigences vérifiables, plus une liste « hors périmètre » (aussi importante que la première).
  3. Dans quel ordre ? La roadmap : d'abord un cœur minuscule qui rend déjà service (v0.1), puis le confort (v0.2), puis la finition (v1.0).
  4. Quelle est la prochaine tâche ? Le découpage en issues : chaque jalon devient une liste de tâches d'une session chacune. À tout moment du projet, la réponse à « par quoi je continue ? » est écrite quelque part.

Analogie : tu ne construis pas une cabane en commençant par clouer des planches. Tu décides d'abord cabane ou château (le sujet), tu dessines un plan (les specs), tu listes les étapes — fondations, murs, toit (la roadmap), et chaque étape tient dans un week-end (les issues). Le château, ce sera la V2 — si la cabane tient debout.

4. Explication approfondie

a) Les quatre critères d'un bon sujet. Un sujet de projet final se juge contre quatre critères, tous obligatoires :

  1. Utile pour toi : un outil que tu as réellement envie d'utiliser. C'est ton carburant pour les semaines 2 et 3, quand la nouveauté est retombée.
  2. Périmètre trois semaines : la V1 doit être livrable en ~3 semaines de sessions courtes. Pas le projet de tes rêves — sa première brique.
  3. Techniquement couvert par 00–09 : fichiers, exceptions, modules, éventuellement classes, pytest, CSV/JSON, peut-être une API HTTP. Si le sujet exige une interface graphique, du temps réel ou une base de données, il est hors calibre (ou sa V1 doit s'en passer).
  4. Il te fait un peu peur : si tu sais déjà exactement comment tout faire, tu ne vas rien apprendre. Un bon sujet contient une ou deux zones de brume.

b) Une exigence est testable ou elle n'existe pas. « L'outil gère les dépenses » n'est pas une exigence : impossible de dire si c'est fait. « La commande add refuse un montant négatif et affiche un message clair » est une exigence : tu peux la vérifier — et même en faire un test pytest (⏩ discipline du niveau 08). Règle pratique : chaque exigence doit pouvoir commencer par « quand je fais X, il se passe Y ».

c) Le hors-périmètre est la moitié du cadrage. La section « la v1 ne fera PAS » est ta défense contre toi-même. Chaque idée séduisante qui arrive en cours de route (« et si j'ajoutais des graphiques ? ») a deux destinations possibles : la liste hors-périmètre (avec mention « V2 ? »), ou la poubelle. Jamais le code de la V1.

d) La règle de calibrage ×2. Estimation honnête : ce que tu penses faire en 3 jours en prendra 6. Ce n'est pas du pessimisme, c'est une constante observée chez tous les développeurs, débutants comme confirmés. Dimensionne la roadmap avec cette règle, et tu finiras dans les temps — ce qui est une sensation rare et excellente.

e) Une issue se formule par son résultat observable, pas par son implémentation. « Écrire la fonction parse_amount() » est une mauvaise issue : le jour venu tu ne sauras plus pourquoi. « add 12.50 courses enregistre la dépense et l'affiche » est une bonne issue : tu sais quand c'est fini, et le COMMENT reste libre. Une issue = une session de travail maximum. Si elle déborde, c'étaient deux issues.

f) « Fini » se définit au début. Sans définition écrite de « fini », un projet ne finit jamais : on polit indéfiniment. « Fini » = toutes les exigences v1.0 implémentées ou explicitement coupées + pytest vert + README à jour + tag v1.0. Cette définition se fige AVANT de coder, dans SPECS.md.

Difficulté honnête : cette leçon ne contient presque pas de code, et c'est précisément ce qui la rend inconfortable. Écrire un cadrage paraît « perdre du temps » quand on a envie de coder — la tentation de sauter cette étape est énorme. Résiste : chaque projet abandonné de l'histoire de l'apprentissage de la programmation a sauté cette étape. Prévois deux ou trois sessions rien que pour le cadrage de ton projet final.

5. Exemples commentés

Exemple 1 — dégonfler un sujet trop gros

Sujet brut : « une app de gestion de budget avec interface graphique, synchronisation bancaire et graphiques ».

Passage au crible des quatre critères :

Utile pour moi ?          OUI — je veux suivre mes dépenses
Trois semaines ?          NON — interface graphique + synchro = plusieurs mois
Couvert par 00–09 ?       NON — GUI et API bancaire jamais vues
Me fait un peu peur ?     OUI (mais pour de mauvaises raisons)

Version dégonflée qui passe les quatre critères : « un outil en ligne de commande de suivi de dépenses : ajouter une dépense, lister, total par mois, données dans un CSV ». La GUI, la synchro et les graphiques vont dans la section hors-périmètre, étiquetés « V2 ? ». Le sujet n'est pas abandonné — il est ordonné.

Exemple 2 — rendre une exigence testable

FLOU  : « l'outil gère les erreurs »
TESTABLE : « une date invalide passée à `add` affiche
            "date invalide (attendu AAAA-MM-JJ)" et ne modifie pas le CSV »

FLOU  : « le rapport est clair »
TESTABLE : « `report 2026-07` affiche le total du mois et le nombre
            de dépenses, aligné en colonnes »

Le test : peux-tu imaginer le test pytest correspondant ? Si oui, l'exigence est bonne. Si non, reformule.

Exemple 3 — un SPECS.md minimal mais complet (extrait — le modèle intégral rempli est dans les solutions)

# SPECS — spendlog v1

## Problème
Je note mes dépenses nulle part ; fin de mois, aucune idée d'où part l'argent.

## Utilisateur
Moi, dans un terminal, 1 à 2 minutes par jour.

## Exigences v1 (testables)
1. `add <montant> <catégorie> [note]` enregistre une dépense datée du jour.
2. `add` refuse un montant négatif ou non numérique (message clair, CSV intact).
3. `list` affiche les 10 dernières dépenses, plus récentes en premier.
4. `report <AAAA-MM>` affiche le total du mois et le total par catégorie.
5. Les données survivent d'un lancement à l'autre (CSV dans le dossier projet).
6. Aucune entrée utilisateur ne provoque de traceback.

## Hors périmètre v1
- Interface graphique (V2 ? probablement jamais)
- Multi-utilisateurs, synchronisation cloud (non)
- Graphiques (V2 ?)
- Modification/suppression d'une dépense (V2 — noté le 2026-07-05)

## Définition de « fini »
Exigences 1–6 implémentées, pytest vert, README complet, tag v1.0.

Exemple 4 — la roadmap en trois jalons

## Roadmap
- v0.1 — le cœur : `add` + stockage CSV + `list` brut.
         (utilisable dès ce jalon : je peux VRAIMENT noter mes dépenses)
- v0.2 — confort : `report` mensuel, validation des entrées, messages d'erreur.
- v1.0 — fini : totaux par catégorie, README, chasse aux tracebacks, tag.

Remarque le principe : v0.1 rend déjà service. Pas « v0.1 = les fondations techniques » — un jalon dont on ne peut rien faire ne motive personne et ne t'apprend rien sur ton vrai besoin.

Exemple 5 — issues bien et mal formulées

MAL  : « créer le module storage »          (implémentation, pas de résultat)
MAL  : « faire la v0.1 »                     (une semaine, pas une session)
BIEN : « #1 `add 12.50 courses` écrit une ligne dans expenses.csv »
BIEN : « #2 `list` affiche les dépenses du CSV, plus récentes en premier »
BIEN : « #3 un montant invalide passé à `add` affiche une erreur sans traceback »

Chaque « BIEN » tient dans une session, se vérifie en lançant le programme, et deviendra une branche Git (⏩ leçon 10-2) puis un ou deux tests pytest.

6. Erreurs fréquentes

1) Le sujet trop ambitieux — le tueur n°1.

Symptôme : la description du projet contient « complet », « plateforme », « avec interface graphique », ou plus de trois « et aussi ». Résultat : abandon à 30 %, sentiment d'échec — alors que c'est le cadrage qui a échoué, pas toi. Correction : passe le sujet au crible des quatre critères (section 4a) et coupe jusqu'à ce que la V1 tienne en trois semaines.

2) Des exigences non testables.

« l'outil doit être simple et robuste »

Personne ne peut dire quand c'est fait. Résultat : tu polis sans fin. Correction : chaque exigence au format « quand je fais X, il se passe Y » (section 4b).

3) Pas de section hors-périmètre. Le document ne dit que ce que le projet fera — donc en cours de route, chaque nouvelle idée semble « dans le sujet ». Le périmètre gonfle silencieusement, semaine après semaine. Correction : la section « la v1 ne fera PAS » est obligatoire, et on y AJOUTE des lignes pendant le projet (avec la date : c'est ton journal de tentations).

4) Des issues formulées par l'implémentation. « Refactorer le parseur », « créer la classe Expense » : trois jours plus tard, impossible de se rappeler pourquoi, ni de savoir quand c'est fini. Correction : formule par le résultat observable (section 4e).

5) v0.1 = « toute l'infrastructure, aucune fonctionnalité ». Tu passes une semaine sur une belle architecture, sans jamais pouvoir utiliser l'outil. Motivation en chute, et l'architecture s'avérera fausse de toute façon (on ne connaît pas les vrais besoins avant d'utiliser). Correction : v0.1 = le plus petit chemin qui rend service, même laid.

6) Ne jamais définir « fini ». Sans définition, deux fins possibles : polissage infini, ou arrêt honteux au milieu. Correction : la définition de « fini » se fige dans SPECS.md au jour 0 — et déclarer fini quand elle est atteinte est une décision de pro, pas un renoncement.

7. Lire les messages d'erreur

Un cadrage raté ne produit pas de traceback — ses erreurs se manifestent des jours plus tard, sous forme de symptômes. Apprends à les lire comme tu lis un traceback : symptôme → cause → correction.

SYMPTÔME (jour 4)  : « je ne sais pas par quoi continuer »
CAUSE              : issues absentes ou trop grosses
CORRECTION         : redécouper le jalon courant en tâches d'une session

SYMPTÔME (jour 8)  : « je code un truc cool mais pas prévu »
CAUSE              : pas de section hors-périmètre (ou pas relue)
CORRECTION         : l'idée va dans hors-périmètre avec la date ; retour à l'issue en cours

SYMPTÔME (jour 12) : « c'est jamais assez bien pour être fini »
CAUSE              : « fini » n'a pas été défini au départ
CORRECTION         : écrire la définition MAINTENANT, et s'y tenir

SYMPTÔME (jour 15) : « j'ai honte, j'ai fait 10 % de ce que je voulais »
CAUSE              : calibrage sans la règle ×2
CORRECTION         : couper le périmètre, pas rallonger le calendrier

La bonne nouvelle : contrairement à un NameError, ces erreurs se corrigent en mettant à jour les documents — un cadrage est vivant. Quand la réalité contredit SPECS.md, c'est SPECS.md qui bouge (avec une ligne datée), pas la réalité qu'on nie.

8. Exercices — faciles

Règles : réponses dans lessons/level-10-autonomie/exercices/mes-reponses/, en fichiers Markdown (ex-10-1-a.md, etc.). Ce sont des travaux d'écriture et de jugement, pas de code — rédige de vraies phrases.

a) Passe ces trois sujets au crible des quatre critères (utile pour toi / trois semaines / couvert par 00–09 / un peu peur) et conclus pour chacun : bon calibre, à dégonfler, ou à écarter :

  1. « Un clone de Spotify avec lecture audio et recommandations »
  2. « Un gestionnaire de flashcards à répétition espacée, en CLI »
  3. « Un script qui renomme des fichiers » (⚠️ celui-là a un défaut inverse)

b) Réécris ces exigences floues en exigences testables (format « quand je fais X, il se passe Y ») :

  1. « L'outil doit être facile à utiliser »
  2. « Les données sont sauvegardées »
  3. « Le programme gère les mauvaises entrées »

c) Voici quatre issues. Classe-les bonne/mauvaise et corrige les mauvaises : « améliorer le code », « delete 3 supprime la dépense n°3 et l'affiche », « implémenter la classe Storage », « report sans argument affiche le mois courant ».

9. Exercices — moyens

a) Écris un SPECS.md complet (problème, utilisateur, 5–8 exigences testables, hors-périmètre, définition de « fini ») pour ce sujet imposé : « un outil CLI de suivi d'habitudes : cocher une habitude faite aujourd'hui, voir la série en cours (streak), stockage JSON ». Impose-toi au moins 4 lignes de hors-périmètre. Piège à éviter : au moins une de tes exigences doit couvrir les entrées invalides (section 6, erreur 2).

b) Découpe le sujet de l'exercice a en roadmap v0.1 / v0.2 / v1.0, puis transforme la v0.1 en 3 à 5 issues d'une session chacune, formulées par leur résultat observable. Vérifie chaque issue contre le piège de la section 6 (erreur 4).

10. Exercices — difficiles

a) LE vrai exercice du niveau : cadre ton projet final. Choisis ton sujet (idées de calibre dans projects/mini-projects/12-projet-final-cli.md, ou invente), passe-le au crible des quatre critères, puis écris son SPECS.md complet et sa roadmap. C'est un livrable réel : il partira dans projects/final-projects/<ton-projet>/ au lancement de la leçon 10-P. Compte 2 à 3 sessions, pas une.

11. Mini-projet lié — « le dossier de cadrage »

Assemble le livrable de l'exercice 10-a en dossier propre : exercices/mes-reponses/cadrage-projet-final/ contenant SPECS.md, ROADMAP.md et ISSUES.md (numérotées, formulées par résultat observable, la v0.1 entièrement découpée). Puis fais relire le tout… à toi-même, trois jours plus tard, avec cette grille : chaque exigence est-elle testable ? Le hors-périmètre a-t-il au moins 4 lignes ? Chaque issue tient-elle dans une session ? Durée : 45 min d'assemblage + la relecture différée. Ce dossier sera copié tel quel dans ton projet final en 10-P.

12. Correction / méthode de correction

Les exemples de référence sont dans solutions/serie-10-1-solutions.md : un crible des trois sujets, les exigences réécrites, et surtout un SPECS.md + roadmap + issues entièrement remplis pour le sujet du suivi d'habitudes.

Méthode particulière ici : il n'y a pas UNE bonne réponse — compare la structure de ton cadrage (testabilité, hors-périmètre, taille des issues) plutôt que le contenu. Pour ton propre projet final, personne n'a la solution : utilise la grille de relecture du mini-projet, et note dans ton journal chaque écart entre ta version et les critères.

13. À retenir

14. Questions de révision

  1. Quels sont les quatre critères d'un bon sujet de projet final, et lequel est le plus souvent violé ?
  2. Comment reconnaît-on une exigence testable ? Donne un exemple flou et sa version corrigée.
  3. À quoi sert la section hors-périmètre PENDANT le projet (pas seulement au début) ?
  4. Pourquoi « v0.1 = toute l'infrastructure » est-il un piège ?
  5. Qu'est-ce qu'une bonne issue ? Donne les deux règles (taille et formulation).
  6. Que contient une définition de « fini », et pourquoi doit-elle être écrite avant le code ?
  7. Le jour 8, tu réalises qu'une exigence de SPECS.md est irréaliste. Que fais-tu, concrètement ?

15. Checklist de compréhension

Si une case reste vide : refais les exercices de la section correspondante demain, AVANT d'ouvrir la leçon suivante.

16. Commit conseillé

git add lessons/level-10-autonomie/exercices/mes-reponses/
git commit -m "exercises: complete lesson 10-1 project framing"

Puis, si c'est ta fin de session : entrée de journal + git push.