Exercices d'échafaudage

Créez des structures de répertoires d'exercices qui passent pnpm ai-hero-cli internal lint, puis validez avec git commit.

Nommage des répertoires

Sections : XX-section-name/ dans exercises/ (ex. 01-retrieval-skill-building)
Exercices : XX.YY-exercise-name/ dans une section (ex. 01.03-retrieval-with-bm25)
Numéro de section = XX, numéro d'exercice = XX.YY
Les noms utilisent le format dash-case (minuscules, tirets)

Variantes d'exercices

Chaque exercice a besoin d'au moins un de ces sous-répertoires :

problem/ - espace de travail étudiant avec TODOs
solution/ - implémentation de référence
explainer/ - matériel conceptuel, pas de TODOs

Lors de l'ébauche, utiliser par défaut explainer/ sauf si le plan spécifie autre chose.

Fichiers obligatoires

Chaque sous-répertoire (problem/, solution/, explainer/) a besoin d'un readme.md qui :

N'est pas vide (doit avoir du vrai contenu, même une simple ligne de titre suffit)
N'a pas de liens cassés

Lors de l'ébauche, créer un readme minimal avec un titre et une description :

# Titre de l'exercice

Description ici

Si le sous-répertoire contient du code, il a aussi besoin d'un main.ts (>1 ligne). Mais pour les ébauchés, un exercice readme uniquement est acceptable.

Flux de travail

Parser le plan - extraire les noms de sections, noms d'exercices et types de variantes
Créer les répertoires - mkdir -p pour chaque chemin
Créer des readmes d'ébauche - un readme.md par dossier de variante avec un titre
Lancer le lint - pnpm ai-hero-cli internal lint pour valider
Corriger les erreurs - itérer jusqu'à ce que le lint passe

Résumé des règles du linter

Le linter (pnpm ai-hero-cli internal lint) vérifie :

Chaque exercice a des sous-répertoires (problem/, solution/, explainer/)
Au moins un de problem/, explainer/ ou explainer.1/ existe
readme.md existe et est non-vide dans le sous-répertoire principal
Pas de fichiers .gitkeep
Pas de fichiers speaker-notes.md
Pas de liens cassés dans les readmes
Pas de commandes pnpm run exercise dans les readmes
main.ts requis par sous-répertoire sauf s'il est readme uniquement

Déplacer/renommer des exercices

Lors de la renumérotation ou du déplacement d'exercices :

Utiliser git mv (pas mv) pour renommer les répertoires - préserve l'historique git
Mettre à jour le préfixe numérique pour maintenir l'ordre
Relancer le lint après les déplacements

Exemple :

git mv exercises/01-retrieval/01.03-embeddings exercises/01-retrieval/01.04-embeddings

Exemple : ébauche à partir d'un plan

Donné un plan comme :

Section 05: Memory Skill Building
- 05.01 Introduction to Memory
- 05.02 Short-term Memory (explainer + problem + solution)
- 05.03 Long-term Memory

Créer :

mkdir -p exercises/05-memory-skill-building/05.01-introduction-to-memory/explainer
mkdir -p exercises/05-memory-skill-building/05.02-short-term-memory/{explainer,problem,solution}
mkdir -p exercises/05-memory-skill-building/05.03-long-term-memory/explainer

Puis créer des readmes d'ébauche :

exercises/05-memory-skill-building/05.01-introduction-to-memory/explainer/readme.md -> "# Introduction to Memory"
exercises/05-memory-skill-building/05.02-short-term-memory/explainer/readme.md -> "# Short-term Memory"
exercises/05-memory-skill-building/05.02-short-term-memory/problem/readme.md -> "# Short-term Memory"
exercises/05-memory-skill-building/05.02-short-term-memory/solution/readme.md -> "# Short-term Memory"
exercises/05-memory-skill-building/05.03-long-term-memory/explainer/readme.md -> "# Long-term Memory"

scaffold-exercises