ml-project-template

Gabarit copier d'un projet de machine learning tel qu'AFIB-Predict l'a stabilisé : reproductible par pixi, piloté par spec-kit, exécuté par Claude Code, documenté dans un vault Obsidian (docs/) que des scripts tiennent en ordre (Markdown déplié, wikilinks audités, cartes et index complétés seuls), avec l'observabilité des traitements longs livrée dès le premier jour. Son compagnon, le plugin de skills project-kit, s'installe une fois par machine.

Ce README est écrit pour être suivi de haut en bas, depuis une machine vierge, sans rien connaître de ce qui précède. Chaque étape dit ce qu'elle fait, comment vérifier qu'elle a marché, et quoi faire sinon.

---

0. Ce que vous obtenez à la fin

Un dossier mon-projet/, déjà un dépôt git avec un premier commit, dans lequel :

• pixi run test passe (53 tests livrés avec le gabarit) ;
• claude s'ouvre avec un contrat (CLAUDE.md) qui connaît les conventions du vault, des données, des runs longs et du workflow spec-kit ;
• docs/ est un vault Obsidian prêt (index, gabarits, cartes), tenu par trois hooks ;
• spec-kit est initialisé (/speckit-specify → /speckit-plan → /speckit-tasks → /speckit-implement) avec sa constitution déjà en place ;
• pixi run progress sait suivre vos traitements longs dès que vous les instrumentez.

Temps : dix minutes si les prérequis sont là, trente sinon.

---

1. Prérequis (une fois par machine)

Vérifiez chacun avec la commande de contrôle ; installez seulement ce qui manque. Aucune de ces installations ne demande sudo.

Outil	Rôle	Contrôle	Installation
git	versionnage	git --version	fourni avec les outils Xcode sur macOS (xcode-select --install), sinon votre gestionnaire de paquets
pixi	environnement Python reproductible (remplace conda, pip, venv)	pixi --version	curl -fsSL https://pixi.sh/install.sh | bash puis rouvrir le terminal
copier	instancie ce gabarit	copier --version	pixi global install copier
uv	installe spec-kit	uv --version	pixi global install uv
Claude Code	l'agent qui exécute	claude --version	curl -fsSL claude.ai/install.sh | bash, puis claude une première fois (connexion OAuth ; plan payant requis)
Obsidian	l'éditeur du vault	l'application s'ouvre	https://obsidian.md — installer l'application, rien d'autre
spec-kit	cadre specify → plan → tasks → implement	specify --version	facultatif : l'instanciation l'installe elle-même si uv est présent

Contrôle global, à copier-coller :

git --version && pixi --version && copier --version && uv --version && claude --version && echo "prérequis OK"

Si une ligne échoue, revenez au tableau.

---

2. Décider trois choses avant de taper la commande

1. Le nom du projet : minuscules, chiffres, tirets (mon-projet). Il devient le nom du dossier, du dépôt et du paquet pixi. On ne le change pas ensuite.
2. Le nom du paquet Python : minuscules sans tiret (monprojet). Proposé automatiquement à partir du nom du projet ; acceptez sauf raison précise.
3. Où vivent les données : un chemin hors du dépôt (disque externe, volume chiffré), par exemple /Volumes/DATA/mon-projet. Il sera écrit dans .env sous le nom DATA_ROOT, jamais commité. Créez le dossier avant ou après, peu importe : sans lui, rien ne casse tant que vous ne lancez pas de traitement.

Les autres questions (version de Python, plateforme, extensions de fichiers de données à ignorer, auteur) ont des valeurs par défaut raisonnables ; Entrée les accepte.

---

3. Instancier

Placez-vous dans le dossier parent où le projet doit naître, puis :

copier copy --trust gh:remicastaing/ml-project-template mon-projet

Copier pose ses questions, copie les fichiers, puis exécute sept tâches de mise en place dans mon-projet/, dans cet ordre : git init · .env créé depuis .env.example · hooks rendus exécutables · pixi install (une à deux minutes la première fois) · specify init (installe spec-kit via uv si besoin) · constitution copiée dans .specify/memory/constitution.md · premier commit.

Pourquoi --trust ? Parce que ces tâches exécutent du code sur votre machine ; copier exige que vous l'autorisiez explicitement. Sans --trust, les fichiers sont copiés mais aucune tâche ne tourne, et copier vous le dit.

Contrôle :

cd mon-projet && git log --oneline && pixi run test

Attendu : une ligne chore: projet instancié depuis ml-project-template vX.Y.Z et 53 passed.

Si une tâche a échoué, copier l'a affiché en clair pendant l'instanciation, préfixé de >>>, avec la commande à relancer. Les cas connus :

Symptôme	Cause	Réparation
>>> spec-kit non installé	uv absent ou pas de réseau	uv tool install specify-cli --from git+https://github.com/github/spec-kit.git && specify init --here --force --integration claude --script sh
>>> constitution : copier …	specify init n'a pas tourné (cas précédent)	après la réparation ci-dessus : cp .claude/constitution-seed.md .specify/memory/constitution.md
pixi: command not found	pixi installé mais terminal pas rouvert	rouvrir le terminal, puis dans le projet : pixi install && git add -A && git commit -m "chore: projet instancié"
pas de commit dans git log	une tâche antérieure a échoué et interrompu la chaîne	réparer la cause, puis git add -A && git commit -m "chore: projet instancié depuis ml-project-template"

---

4. Finir la mise en place (cinq minutes)

4.1 Vérifier .env

cat .env

La ligne DATA_ROOT=… doit pointer sur le chemin décidé au §2. Corrigez-la si besoin, puis créez le dossier et ses deux sous-dossiers :

mkdir -p "$(grep '^DATA_ROOT=' .env | cut -d= -f2)"/{raw,derived}

raw/ reçoit les sources (jamais partagées), derived/ les artefacts calculés. .env est dans .gitignore et ne sera jamais commité — vérifiez-le une fois pour toutes : git check-ignore .env doit afficher .env.

4.2 Ouvrir le vault dans Obsidian

Dans Obsidian : Ouvrir un dossier comme coffre → choisir mon-projet/docs. Pas mon-projet : le vault, c'est docs/. La note d'entrée est index.md ; les cartes sont les _MOC.md de chaque dossier. Obsidian créera docs/.obsidian/ ; seuls ses fichiers d'espace de travail sont ignorés par git, la configuration (thème, plugins) est versionnée — c'est voulu.

4.3 Installer le plugin de skills (une fois par machine, pas par projet)

Dans une session claude, tapez :

/plugin marketplace add remicastaing/project-kit
/plugin install vaultkit@project-kit

Vous obtenez journal (entrée du jour), ask-vault (réponse citée à une question posée au vault), ingest-lecture (fiche d'un article PDF), coursekit-* (cours du vault), artkit-* et oralkit-* (manuscrit et soutenance) et la commande /checkpoint. Contrôle : claude plugin list affiche vaultkit@project-kit … enabled. Si vous l'avez déjà fait pour un autre projet, rien à refaire.

4.4 Remplir la couche projet de CLAUDE.md

Ouvrez CLAUDE.md. Sa première ligne utile est @.claude/CLAUDE-gestion.md : elle importe la couche générique (environnement, vault, Markdown, runs longs, spec-kit, workflow post-implémentation) — ne la modifiez pas, elle est mise à jour par le gabarit. En dessous, quatre sections projet avec des TODO : Commandes, Architecture, Données, Méthodologie. Remplacez chaque TODO par une phrase vraie ; supprimez ce qui ne s'applique pas. Une règle mal écrite ici sera mal suivie ; une règle absente ne sera pas suivie.

Faites de même dans docs/reference/planification.md (la conception de l'étude : question, données, baseline, évaluation) — c'est ce document, et non la constitution, qui porte la méthode.

4.5 Première session avec Claude Code

claude

Demandez : « Quelles sont les règles sur les runs longs et sur docs/ ? ». La réponse doit venir de CLAUDE.md. Puis lancez le premier tour spec-kit sur votre première brique — la constitution est déjà en place, /speckit-constitution ne sert qu'à l'amender :

/speckit-specify <la première brique, avec ses critères d'acceptation>

Recommandation issue de l'expérience : instrumentez le premier traitement long avec RunState avant de le lancer (src/monprojet/runstate.py, gestionnaire de contexte open(...), tick(), close()), et vérifiez son avancement par pixi run progress plutôt que de le supposer. C'est la brique qu'AFIB-Predict a livrée en spec 021 et qui aurait dû être la spec 002.

4.6 Premier vrai commit

git add -A && git commit -m "docs: CLAUDE.md et planification remplis"

Puis créez le dépôt distant à votre convenance, par exemple gh repo create mon-projet --private --source . --push.

---

5. La journée type

1. claude → « fais l'entrée du jour » (journal) : l'intention en une phrase.
2. /speckit-specify pour la brique visée ; relire spec.md.
3. /speckit-plan ; le revoir — c'est le moment clé ; noter la décision en ADR (docs/decisions/, gabarit docs/templates/decision.md).
4. /speckit-tasks puis /speckit-implement ; pixi run test.
5. Run long : lancer, puis pixi run progress — jamais supposer.
6. Rapport de l'artefact dans docs/experiments/… ou docs/cohorts/… (généré depuis les fichiers, jamais recopié).
7. Une question sur ce que le vault sait déjà : « qu'est-ce qu'on sait sur … ? » (ask-vault).
8. Commit avec le message proposé par l'agent, validé par vous ; git push à la main.

Les hooks travaillent en arrière-plan à chaque note écrite par Claude Code : dépliage du Markdown (md_unwrap), signalement des wikilinks manquants (wikilink), complétion des cartes et de l'index (vault_index). Vous pouvez les lancer vous-même : pixi run md-unwrap, pixi run wikilink, pixi run vault-index (--check pour un audit, code de sortie 1 s'il manque une entrée).

---

6. Faire évoluer

Le projet suit le gabarit

Quand ce gabarit publie une nouvelle version (nouveau script, hook corrigé, couche générique de CLAUDE.md améliorée) :

cd mon-projet && copier update --trust

Copier relit vos réponses dans .copier-answers.yml, applique la différence entre la version que vous aviez et la dernière, et vous montre les conflits éventuels sur les fichiers que vous avez modifiés (à résoudre comme un merge git). Les sept tâches de mise en place ne rejouent pas à l'update. Vérifiez ensuite pixi run test.

Le gabarit lui-même

Le contenu instancié vit sous template/ ; les fichiers .jinja sont rendus (variables {{ project_name }}, {{ package_name }}…), les autres copiés tels quels. Deux pièges connus, appris en le construisant :

• copier lit le dernier tag du dépôt source, pas l'arbre de travail : pour tester une modification, committez puis instanciez avec --vcs-ref HEAD ;
• un : dans une commande de _tasks casse le YAML : écrire ces commandes en bloc >-.

copier copy --trust --defaults --vcs-ref HEAD --data project_name=demo --data package_name=demo . /tmp/demo && (cd /tmp/demo && pixi run test)

Publier une version : git tag vX.Y.Z && git push --tags.

---

7. Ce que contient un projet instancié

Pièce	Rôle
CLAUDE.md + .claude/CLAUDE-gestion.md	le contrat avec Claude Code : couche générique importée (mise à jour par copier update) + couche projet à compléter
.claude/settings.json	trois hooks PostToolUse : md_unwrap, wikilink, vault_index (versionné ; settings.local.json reste local)
.claude/constitution-seed.md	les dix principes d'ingénierie, copiés dans .specify/memory/constitution.md à l'instanciation
.specify/ + .claude/skills/speckit-*	spec-kit, installé par specify init
pixi.toml, pyproject.toml	environnement + tâches nb, test, progress, md-unwrap, wikilink, vault, vault-index ; paquet installé en editable
src/<pkg>/runstate.py, completion.py	avancement persistant des runs longs ; marqueur done.json d'idempotence — avec leurs tests
scripts/	md_unwrap.py, wikilink.py, vault_index.py et leurs hooks — avec leurs tests
docs/	index.md court, templates/ (concept, decision, journal, rapport, exploration), cartes _MOC.md semées, .vault-index.toml, .wikilex.toml, reference/planification.md, reference/commandes-pixi.md, backlog/backlog.md
.gitignore, .env.example, pytest.ini	gouvernance des données hors dépôt
.copier-answers.yml	vos réponses, versionnées : c'est ce qui permet copier update

Le pourquoi de chaque pièce, et le retex du projet dont ce gabarit est l'automatisation : docs/retex-afib-predict.md.

---

8. Questions fréquentes

Puis-je instancier sans réseau ? Oui, si copier, pixi et un clone local du gabarit sont là : copier copy --trust /chemin/vers/ml-project-template mon-projet. La tâche spec-kit échouera proprement (message >>>), à relancer plus tard.

J'ai déjà un dossier de projet : puis-je appliquer le gabarit dessus ? Oui, copier copy --trust gh:remicastaing/ml-project-template . dans le dossier ; copier demande quoi faire fichier par fichier en cas de conflit. Les tâches ne réécrivent pas un .env existant (cp -n) et git init sur un dépôt existant est sans effet.

Le vault doit-il s'appeler docs/ ? Oui : les scripts, les hooks et la couche générique de CLAUDE.md le supposent. Ne créez pas de docs/ dans docs/.

Où mettre les specs ? Dans specs/ à la racine (créé par spec-kit), jamais dans docs/.

Puis-je ne pas utiliser Claude Code ? Les scripts, les tests et le vault fonctionnent sans lui ; vous perdez les hooks (qui sont des hooks Claude Code) — lancez alors pixi run md-unwrap, wikilink, vault-index à la main.

Et OpenKB ? Le retex documente un pilote possible d'OpenKB en couche compilée à côté de docs/ ; il n'est volontairement pas dans le gabarit de base.