Skip to content
jamylPublic

About

A project template for Claude Code. The working method ships with it; your domain gets filled in by an interview the first time you run it. Template de projet Claude Code : cycle de livraison, contre-épreuves, revue en fan-out. Le domaine se remplit à l'amorçage.

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

socle

Un template de projet pour Claude Code : la méthode de travail est déjà en place, ton domaine se remplit par une interview au premier lancement. Le socle s'installe aussi dans un projet déjà commencé.

A project template for Claude Code. The working method ships with it; your domain gets filled in by an interview the first time you run it — and it can be adopted by a project that already has code.

license Claude Code

socle en 24 secondes — le problème, le cycle de livraison, et le script qui refuse un troisième essai

24 secondes, sans commentaire audio — le problème, le cycle de livraison, et le script qui refuse un troisième essai. Tout le texte à l'écran est réel : extrait de ce README ou de la sortie du scorer. Version 1080p avec le son.

24 seconds, no narration — the problem, the delivery cycle, and the script that refuses a third attempt. Every line on screen is real, taken from this README or from the scorer's output. 1080p version, with sound.

Français · English


Français

Ce que c'est

Développer avec un agent de code pose deux problèmes qui reviennent. Tu réexpliques tes règles à chaque session, et tu dois croire l'agent sur parole quand il dit que les tests passent.

Ce template règle les deux. La méthode vit dans des fichiers que Claude Code lit de lui-même, donc les règles survivent d'une session à l'autre. Et chaque rapport que l'agent écrit finit par une commande que tu lances pour constater le résultat toi-même, ce qui t'évite de croire une affirmation que tu ne peux pas reproduire.

Tu obtiens un dépôt où une commande livre une user story de la branche à la pull request mergée, une revue de code où quatre relecteurs indépendants examinent le même changement sans voir les remarques des autres, et une règle ferme : un test n'est une preuve qu'une fois qu'on l'a vu échouer.

Le template n'apporte ni code applicatif ni règles métier. Il demande les tiennes.

Tu débutes avec Claude Code ? Chaque terme de cette page est défini dans Les mots employés ici. Commence par cette section si skill, sous-agent, story ou epic ne te sont pas déjà familiers.

Prérequis

À vérifier une fois par poste, avant de commencer :

Outil Comment vérifier S'il manque
Claude Code 2.1.154 ou plus claude --version Mets à jour. En dessous, l'outil Workflow n'existe pas et la revue à quatre relecteurs ne tourne pas, sans le dire
GitHub CLI, connecté gh auth status gh auth login
Node.js node --version Requis : c'est lui qui note les essais d'une story pendant la livraison. Aussi requis par le serveur de documentation context7 du module Laravel
Python 3 python3 --version Requis par le module dejavu. Ses scripts n'utilisent que la bibliothèque standard, il n'y a rien à installer avec pip
Un runtime de conteneurs docker compose version Docker Desktop, ou OrbStack sur macOS. Requis par le module stack-laravel

Python et Docker sont chacun liés à un module optionnel : ignore ceux dont tu n'activeras pas le module. Node, lui, sert au cœur de la méthode.

Démarrage rapide

Trois étapes t'amènent de rien à un projet dont le premier epic est écrit.

  1. Crée ton dépôt depuis ce template :

    gh repo create mon-projet --template jamyl/socle --private --clone
    cd mon-projet

    Tu dois maintenant voir CLAUDE.md, GETTING-STARTED.md, modules/ et scripts/bootstrap.sh. Si modules/ est absent, la copie est incomplète : recommence.

  2. Ouvre une session et amorce le projet :

    claude

    Puis, dans la session, lance /bootstrap-project. C'est un skill : un jeu d'instructions nommé que Claude Code charge à la demande, invoqué par une barre oblique suivie de son nom. L'amorçage tourne une seule fois, t'interviewe, rédige ta documentation, puis se supprime.

  3. Livre la première story :

    /deliver-story
    

Lis GETTING-STARTED.md en entier avant l'étape 2. Il couvre les prérequis, chaque étape en détail, ce qu'il faut vérifier, et quoi faire quand ça ne va pas. L'amorçage supprime ce fichier aussi, parce qu'il parle du template et non de ton projet.

Adopter la méthode dans un projet existant

Le démarrage rapide ci-dessus suppose un dépôt neuf. Si ton projet a déjà du code, un historique et sa propre documentation, c'est un autre chemin — et il ne touche à rien de ce que tu as écrit.

Trois commandes, depuis ton projet :

git clone --depth 1 https://github.com/jamyl/socle /tmp/socle
cd mon-projet-existant
/tmp/socle/scripts/adopt.sh

Puis, dans une session Claude Code ouverte sur ton projet : /adopter-socle.

Ce que le script fait. Il vérifie que ton arbre de travail est propre, crée une branche adopter-socle, et copie la méthode : les skills, les trois relecteurs, les règles, le workflow de revue et les squelettes de documentation.

Ce qu'il ne fait jamais. Il n'écrase aucun fichier. Ton README.md, ta LICENSE et ton .claude/settings.json ne sont pas touchés du tout. Si tu as déjà un CLAUDE.md, la version du socle atterrit à côté en CLAUDE.socle.md et c'est le skill qui te proposera la fusion, section par section. Ton .gitignore reçoit seulement les lignes qui lui manquent, ajoutées à la fin. Tout ce qui a été sauté est listé en clair à la fin du script : c'est la liste de ce qu'il te reste à rapprocher.

Ce que le skill fait de différent. Là où /bootstrap-project interviewe pour connaître la stack, /adopter-socle lit ton dépôt : les manifestes et leurs verrous pour les versions exactes, les scripts et cibles de build pour les commandes réelles, la CI existante pour les gates déjà en place. Une stack ne se redemande pas quand le code fait autorité.

Il lance ensuite ta suite de tests et rapporte sa sortie réelle. Trois cas, et aucun n'est un échec de l'adoption :

Ce qu'il trouve Ce qu'il en fait
Suite verte Note le compte, tu as une base de référence
Suite rouge Ne l'écrit pas comme verte. Ça devient la première story du backlog
Pas de suite Le dit franchement. C'est la story la plus importante : « on l'a vu échouer » n'a aucun sens sans tests

Il t'interroge alors sur ce que le code ne peut pas dire — le but du produit, les personas, le jalon en cours — et sur les règles qui coûtent le plus cher à violer, en te proposant celles qu'il a déduites de ton code pour que tu les corriges plutôt que de partir d'une page blanche.

Enfin il écrit un premier epic qui n'est pas « fondations », puisqu'elles existent : c'est l'epic de ce qui manque pour que la méthode puisse tourner — les tests, la CI, le garde-fou qui empêche la suite d'atteindre ta base de développement, et chaque dette que tu as choisi d'assumer.

Si ta stack correspond à un module, reprends aussi ses sous-agents et ses règles — et rien d'autre :

/tmp/socle/scripts/adopt.sh --stack stack-laravel

Le drapeau ne copie que le .claude/ du module. Ni docker-compose.yml, ni CI, ni Dockerfile : l'infrastructure d'un projet qui tourne ne se remplace pas par celle d'un template.

Ce qui n'est pas repris, exprès : aucun scaffold, aucune story de fondation, aucune spécification rétroactive de ce que tu as déjà livré. Le backlog part de maintenant ; git log porte déjà le passé.

Ce que l'amorçage te demande

L'interview se fait en quatre lots, et rien n'est écrit avant que tu valides le résultat.

  1. Identité — le nom du projet, un slug en kebab-case qui sert aux conteneurs et à la base de données, et le but en une phrase.
  2. Produit — qui l'utilise et pour quoi, ce qui doit marcher pour dire que le produit existe, et ce qui est explicitement hors périmètre.
  3. Contraintes et architecture — obligations légales ou réglementaires, cible d'hébergement, les langages que ton équipe sait déboguer en production, l'échelle à douze mois, les besoins temps réel ou hors-ligne, ton délai, et une stack déjà imposée s'il y en a une.
  4. Les règles qui coûtent le plus cher à violer — trois à cinq invariants de ton domaine, chacun formulé pour qu'un test puisse le vérifier.

Le lot 4 décide de la qualité de tout le reste. Ces règles deviennent la liste que l'un des quatre relecteurs applique à chaque changement, aussi longtemps que le projet vit. « Aucun code hors de X n'écrit dans Y » se vérifie. « Le code doit être propre » ne se vérifie pas. Une réponse molle ici produit une revue molle pendant des mois.

Après l'interview, l'agent nomme le mécanisme dur de ta conception s'il y en a un — concurrence, cohérence, synchronisation hors-ligne — te propose une recherche d'antériorité dessus en annonçant son coût, et attend. Il vérifie dans deux ou trois écosystèmes candidats qu'une implémentation maintenue des briques dont tu as besoin existe, ce qui ne coûte que quelques requêtes HTTP. Puis il propose une stack, une alternative, et la phrase qui écarte l'alternative.

Laravel est une issue possible, pas le choix par défaut. Le module stack-laravel s'active parce que la découverte aboutit à PHP ; toute autre réponse donne un stack.md rédigé depuis l'interview et un sous-agent developer généré pour cette stack.

Rien n'est écrit avant que tu valides.

Le cycle quotidien

Deux commandes portent le travail, et chacune laisse une trace sur le disque :

/cadrer-story "<un requis brut>"
      |
      v   2 à 5 stories écrites dans un fichier d'epic, en Étant donné/Quand/Alors
      |
/deliver-story
      |
      v   branche -> plan -> TDD -> tests verts -> revue à quatre relecteurs
      |   -> pull request -> CI verte -> merge squash
      |
docs/backlog/JOURNAL.md        une ligne par livraison
docs/backlog/DECISIONS.md      une ligne par choix tranché sans te demander

Pour enchaîner plusieurs stories sans retaper, lance /loop 10m /deliver-story E01. La boucle s'arrête d'elle-même quand aucune story du périmètre n'est plus actionnable.

Écrire une story et la livrer sont deux commandes séparées exprès. Une story mal cadrée découverte pendant la livraison coûte une branche déjà ouverte et un plan déjà écrit. Découverte pendant le cadrage, elle coûte une relecture.

Et quand un test ne veut pas passer ? C'est le moment où un assistant coûte le plus cher : il patche, retente, repatche, oublie ce qu'il a déjà essayé. La méthode le borne à deux tentatives par piste.

Ce qui arrive Ce que la méthode impose
Un test rouge résiste à la première correction Nommer deux ou trois pistes, et pour chacune ce qui la réfuterait
La même erreur revient une deuxième fois Annuler les modifications, écrire pourquoi la piste était fausse, passer à la suivante
Une troisième tentative sur la même piste Refusée par un script, avant même de lancer les tests

Chaque tentative est notée sur trois choses mesurables — aucun secret commité, tests verts, analyse statique propre — et gardée dans un dossier local .socle/. Avant d'écrire une correction, l'assistant relit ce dossier : il ne peut pas réessayer une piste déjà morte, parce qu'elle y est écrite.

À la clôture, le journal note combien de tentatives la story a demandé. Un chiffre élevé n'est pas un reproche : c'est le signal qu'une leçon mérite d'être écrite dans DECISIONS.md pendant qu'on s'en souvient.

Ce qu'il y a dedans

Le cycle de livraison. /deliver-story choisit la prochaine story actionnable en parcourant le graphe des dépendances, pas une liste figée. Une story dont le prérequis vit dans un epic plus loin est sautée, puis redevient candidate quand ce prérequis est livré. Si une story exige un humain — un avis juridique, un compte chez un tiers, une clé d'API — elle passe bloqué avec son motif, et l'agent prend la suivante au lieu de perdre un tour à découvrir le mur.

La discipline de contre-épreuve. Un test n'est une preuve qu'une fois qu'on l'a vu échouer. Avant d'écrire « c'est couvert », l'agent retire le garde que le test prétend protéger, relance, constate le rouge, et restaure. Le skill porte huit façons concrètes dont un test peut rester vert sans rien prouver : la tautologie, la mise en scène absente, une course calée sur un sleep au lieu d'un signal, un garde doublé ailleurs, et quatre autres. Les huit ont été rencontrées en vrai, en deux jours. La question qui les résume : que devrait voir ce test pour devenir rouge ?

La boucle d'exploration bornée. Deux tentatives par piste, puis on change de piste. Chaque tentative est notée par un script sans appel de modèle, gardée dans un dossier local, et relue avant la tentative suivante — un agent ne peut donc pas réessayer ce qu'il a déjà invalidé. La troisième tentative sur la même piste est refusée avant même que les tests se lancent, et c'est la seule économie de ce dépôt qui ne retire aucune capacité. La règle complète tient dans .claude/rules/exploration-policy.md, avec ce qui est formellement interdit : sauter un test, en modifier un pour qu'il passe, baisser un seuil d'analyse statique. Shopify Engineering le résume à propos de Helix : « un essai a le droit d'être faux ; il n'a pas le droit d'être livré tant qu'il l'est ».

La revue à quatre relecteurs. Une fois les tests verts, quatre sous-agents en lecture seule lisent le même diff en parallèle sans se lire entre eux : reviewer pour les conventions et la structure, spec pour l'écart à la story (un critère sans test, un comportement non demandé), security-scanner pour les vulnérabilités, et domain-expert pour tes propres invariants. Leurs remarques sont dédupliquées et triées en code, pas par un modèle. Leurs outils sont limités à la lecture de fichiers : pas d'édition, pas de shell. reviewer et security-scanner n'ont aucun accès réseau, parce que leur entrée est un diff que quelqu'un d'autre a peut-être écrit. domain-expert garde la recherche web, pour pouvoir vérifier un texte réglementaire. C'est structurel, pas une promesse dans un prompt.

Si un relecteur ne rend rien du tout, le workflow le signale. Une couverture incomplète n'est pas « rien à signaler », et confondre les deux est la façon dont une revue cesse discrètement d'être une revue.

La revue est un gate à deux tours, idée reprise de Shopify Helix : chaque remarque grave se corrige, puis les quatre relecteurs relisent le correctif. La PR ne s'ouvre qu'une fois le tour propre. Une remarque grave qui survit au deuxième tour arrête le cycle et revient vers toi.

L'antériorité avant l'architecture. Le module dejavu cherche dans la recherche publiée la partie dure de ta conception, avant que tu la rebâtisses. Il fait lire un article par sous-agent isolé, pour qu'aucune source n'ancre les autres, puis s'engage sur un seul chemin recommandé, cité. Les conclusions se consignent dans docs/engineering/prior-art.md avec leurs identifiants, parce qu'une conclusion que personne ne peut rouvrir est une recherche à refaire à la session suivante.

Onze niveaux de test. docs/engineering/testing-strategy.md définit les niveaux N1 à N11, chacun avec son périmètre et son moment d'exécution en CI. Deux d'entre eux sont ceux que la plupart des projets n'ont pas, et ceux qui trouvent les défauts les plus chers : N4 lance des opérations concurrentes en vrais processus et prouve que les exécutions se sont recouvertes, et N6 fait du mutation testing sur le domaine critique seulement.

Modules optionnels

Tu choisis les modules pendant l'interview. Rien n'est copié sans que tu le demandes.

Module Ce qu'il apporte Quand l'activer
stack-laravel Docker Compose avec PHP 8.4, PostgreSQL 16, Redis, Mailpit et Horizon, toutes les images épinglées par digest. GitHub Actions qui lance Pint, Larastan niveau 8, Pest sur PostgreSQL et un audit des dépendances. Quatre sous-agents Laravel, et un premier epic pré-écrit La découverte d'architecture aboutit à PHP et Laravel
mobile-flutter Un dossier mobile/, des stories de toolchain qui partent bloqué parce que Xcode et Android Studio ne s'automatisent pas, et des niveaux de test de régression visuelle Tu construis une app iOS, Android ou PWA
frontend-web Des gates qui bloquent une interface cassée, quel que soit le framework : accessibilité automatique, captures comparées au pixel, budgets de vitesse, et aucune couleur ni marge en dur hors des tokens de design. Plus un relecteur d'interface et trois skills de direction de design, figés avec leur licence Ton produit a une interface web publique
dejavu Le skill d'antériorité /dejavu embarqué dans ton dépôt et versionné avec lui. Quatre sources académiques, aucune clé d'API, Python en bibliothèque standard Ton architecture porte un mécanisme non trivial. À ignorer si ton poste a déjà /dejavu en global

Les colonnes « quand l'activer » disent où la découverte aboutit, pas ce que tu choisis d'avance.

Sans module de stack, tu as le cœur : la méthode, les skills, quatre relecteurs en lecture seule, le scanner de secrets, le scorer d'essais et des squelettes de documentation. L'amorçage rédige alors stack.md et testing-strategy.md depuis la découverte, et génère un sous-agent developer — plus dba s'il y a une base relationnelle — depuis .claude/templates/.

Le scanner de secrets (.github/scan-secrets.sh) est dans le cœur exprès : une clé commitée coûte la même révocation dans n'importe quelle stack. Il tourne à chaque tentative de livraison, avant les tests.

Ce qu'il n'y a pas dedans, exprès

Aucun scaffold applicatif. Ni composer create-project, ni flutter create. Le scaffold naît de la première itération de livraison, avec les versions du jour. Un scaffold figé dans un template pourrit en quelques mois, et personne ne s'en aperçoit avant d'avoir bâti dessus.

Aucun domaine métier. Le template demande tes invariants au lieu d'en supposer.

Aucun backlog complet. L'amorçage écrit le premier epic et rien d'autre. Les epics rédigés des mois avant qu'on en ait besoin sont des epics à réécrire.

Ce qu'un run coûte

Ces commandes lancent des sous-agents et font de vrais appels réseau. Connais le coût avant de démarrer une boucle.

Action Ce qu'elle dépense
Une revue à quatre relecteurs 4 sous-agents par tour, un ou deux tours par story
Une recherche /dejavu Environ 18 à 26 appels d'agent (1 catégorisation, 12 à 20 lectures isolées en Haiku, notation, regroupement, jusqu'à 3 lectures de texte intégral, 1 convergence), plus du HTTP réel vers quatre APIs
Vérifier les écosystèmes avec codesearch.py Rien. C'est un script Python — aucun modèle dans la boucle
Noter un essai, relire le cache, faire la rétrospective Rien. C'est un script Node — il lance tes commandes de test, il n'en juge rien
/loop Tourne sans surveillance jusqu'à épuisement du backlog. Elle expire après sept jours

Chaque sous-agent déclare Sonnet. Les relecteurs le déclarent par son ID complet, pour qu'une surcharge de l'alias ne les fasse pas tourner sur le modèle de l'auteur. Les lectures isolées d'antériorité tournent en Haiku. Le modèle lourd est réservé à /security-review, le seul gate que le cycle de livraison impose sur le domaine critique. La politique complète, et comment monter un agent d'un cran quand ton domaine le justifie, sont dans docs/engineering/models.md.

Une boucle qui tourne consomme des tokens pendant que tu regardes ailleurs, et elle relance /deliver-story même quand tu croyais avoir fini. Si une livraison démarre sans que tu aies rien tapé, c'est elle : vérifie avec CronList avant de conclure quoi que ce soit, et CronDelete <id> l'arrête plus tôt.

C'est précisément pour cette boucle sans surveillance que les deux tentatives par piste existent. Le poste de dépense le plus lourd n'est pas un modèle trop cher sur un relecteur : c'est un agent qui repatche le même bloc quinze fois, en relisant tout le contexte à chaque passage.

Vérifier que ça a marché

Après l'amorçage, deux commandes te disent s'il est allé au bout. D'abord, cherche les placeholders restants :

grep -rn '{{[A-Z_]\+}}' . --exclude-dir=.git

Tu ne dois rien voir. Chaque placeholder survivant est un endroit où ton projet parle encore du template. Le motif ne cherche que la forme réelle — deux accolades, des majuscules, deux accolades — pour qu'un grep "{{" nu n'attrape pas les accolades légitimes d'un bout de code.

Puis confirme que le template s'est retiré :

ls modules scripts

Tu dois voir « No such file or directory ». Si ces dossiers sont encore là, l'amorçage s'est arrêté en route.

Si tu as activé stack-laravel, vérifie que l'environnement démarre :

docker compose up -d && docker compose ps

Tous les services doivent afficher running, et la base healthy.

Deux projets ayant tous deux activé stack-laravel ne peuvent pas tourner en même temps sans modifier les ports. Les deux publient 8080 pour l'app, 5433 pour PostgreSQL, 6380 pour Redis et 8026 pour Mailpit. Le second docker compose up -d échoue sur un port déjà pris ou, pire, connecte un outil à la base de l'autre projet.

Configuration locale

Certains fichiers de configuration appartiennent au dépôt, d'autres à ton poste. Les mélanger produit deux symptômes désagréables : une permission qui marche chez toi et nulle part ailleurs, ou un chemin de machine commité dans une PR.

Se commite, parce que toute l'équipe doit avoir les mêmes garde-fous : .claude/settings.json (les permissions allow et deny), la méthode entière sous .claude/, CLAUDE.md, et le .mcp.json qu'un module fournit.

Ne se commite jamais, et c'est déjà dans le .gitignore : .claude/settings.local.json (tes surcharges personnelles), .claude/scheduled_tasks.json et son verrou (l'état des boucles /loop, qui appartient à la session qui les a lancées), .socle/ (le cache d'essais : le chemin d'une story, pas son résultat), le bytecode Python, et les *.bak d'un amorçage interrompu.

Ne vit pas dans le dépôt du tout : tes préférences globales dans ~/.claude/, les skills que tu as installés pour toi seul, le cache de /dejavu dans ~/.cache/dejavu — partagé entre tous tes projets — et les variables d'environnement comme DEJAVU_CONTACT.

⚠️ Une variable d'environnement doit être dans ton fichier de profil (~/.zshrc, ~/.bashrc), pas seulement exportée dans un terminal : le processus de Claude Code a démarré avant ton export, il ne le voit pas. Après édition, rouvre le terminal.

🔑 Une liste deny n'est pas un contrôle de sécurité. Elle compare des préfixes littéraux, et les formes équivalentes d'un même push sont innombrables. Les trois règles deny du template attrapent les fautes d'inattention, rien de plus. Ce qui en est un : la protection de branche côté GitHub.

Deux hooks de .claude/hooks/ vont plus loin que la liste : ils lisent la commande entière et refusent un push vers main sous toutes ses formes, un push forcé, --no-verify, et le merge d'une story dont le dernier essai n'est pas vert. Ils rattrapent l'agent qui oublie une règle, pas celui qui la contourne.

Le détail — ce qui manque exprès à la liste allow, et pourquoi il ne faut pas l'élargir à l'avance — est dans docs/engineering/config-locale.md.

Les mots employés ici

Terme Ce que ça veut dire
Claude Code L'agent de code d'Anthropic, utilisable depuis un terminal, un IDE ou un navigateur
Skill Un jeu d'instructions nommé que l'agent charge à la demande. On l'invoque en tapant une barre oblique et son nom, comme /deliver-story
Sous-agent Un agent lancé à part, avec sa propre liste d'outils et son propre contexte. Les quatre relecteurs sont des sous-agents
Workflow Un fichier JavaScript dans .claude/workflows/ qui orchestre plusieurs sous-agents de façon déterministe. review-story en est un
Story Une unité de travail avec ses critères d'acceptation, numérotée US-XYZ. Aussi appelée user story
Epic Un fichier qui regroupe des stories liées, numéroté E01, E02, et ainsi de suite
Backlog Tout ce qui vit dans docs/backlog/ : les epics, le journal des livraisons et le journal des décisions
TDD Développement piloté par les tests. Écrire le test qui échoue, puis le code qui le fait passer
Contre-épreuve Casser volontairement le code qu'un test protège, pour confirmer que le test devient rouge
Strike Une tentative dont l'erreur est identique à la précédente. Au deuxième, la piste est abandonnée et l'agent en change
Merge squash Fusionner une branche en un seul commit, pour qu'une story se lise comme un commit sur main
Amorçage Le run unique qui transforme ce template en ton projet

Quand quelque chose casse

GETTING-STARTED.md finit par un tableau symptôme-cause-remède couvrant les pannes qu'on rencontre vraiment : l'amorçage qui refuse de démarrer, des placeholders qui survivent, un relecteur qui reste muet, et un domain-expert qui ne trouve jamais rien parce qu'il n'a jamais été spécialisé.

Deux règles méritent d'être répétées ici. Ne merge jamais sur une CI rouge. Et si un relecteur ne rend pas de rapport, c'est une couverture incomplète, pas un quitus.

Un message qui ressemble à une panne mais n'en est pas : ⛔ … a 2 strikes — rien n'a été exécuté. C'est le garde de la boucle d'exploration qui refuse une troisième tentative sur une piste morte. La sortie est écrite juste en dessous.

Contribuer

Les issues et les pull requests sont bienvenues. Deux choses à savoir avant d'en ouvrir une.

.github/workflows/template.yml amorce une copie jetable dans cinq combinaisons de modules à chaque pull request, et vérifie que rien du template ne survit, qu'aucune sauvegarde ne traîne, et que seuls les placeholders de rédaction restent. Lance le même contrôle en local avant d'ouvrir une PR :

node --test .claude/skills/deliver-story/scripts/eval-run.test.mjs   # le scorer d'essais
./.github/scan-secrets.sh                                           # aucun secret ici
cp -R . /tmp/socle-check && cd /tmp/socle-check
./scripts/bootstrap.sh test-slug stack-laravel
grep -rn '{{[A-Z_]\+}}' . --exclude-dir=.git   # seulement les placeholders de rédaction
ls modules scripts                              # No such file or directory

Le CONTRIBUTING.md à la racine appartient au projet engendré, pas à ce template. C'est l'un des fichiers dont ton projet hérite.

Origine et licence

Ce template est extrait d'un projet réel livré avec cette méthode. Ce qui a survécu à l'extraction, c'est ce qui avait déjà attrapé un défaut : la discipline de contre-épreuve, la revue à quatre relecteurs, la section « comment tu peux le vérifier toi-même » qui clôt chaque rapport, et la liste blanche qui empêche l'agent d'installer un outil que personne n'a approuvé.

Sous licence MIT.


English

What this is

Building software with an AI coding agent has two recurring problems. You re-explain your rules every session, and you have to take the agent's word that the tests pass.

This template removes both. The method lives in files that Claude Code reads on its own, so the rules survive between sessions. And every report the agent writes ends with a command you run to check the result yourself, so you never have to believe a claim you can't reproduce.

What you get is a repository where one command delivers a user story from branch to merged pull request, a code review where three independent readers examine the same change without seeing each other's findings, and one firm rule: a test only counts as proof once somebody has watched it fail.

The template ships no application code and no business rules. It asks for yours.

New to Claude Code? Every term on this page is defined in Words used here. Read that section first if skill, subagent, story, or epic isn't already familiar.

Requirements

Check these once per machine, before you start:

Tool Check it with If it's missing
Claude Code 2.1.154 or later claude --version Update. Below that version the Workflow tool doesn't exist, and the four-reader review silently doesn't run
GitHub CLI, signed in gh auth status gh auth login
Node.js node --version Required: it scores a story's attempts during delivery. Also needed by the context7 documentation server in the Laravel module
Python 3 python3 --version Needed by the dejavu module. Its scripts use the standard library only, so there's nothing to install with pip
A container runtime docker compose version Install Docker Desktop, or OrbStack on macOS. Needed by the stack-laravel module

Python and Docker are each tied to one optional module, so skip the ones whose module you don't activate. Node is used by the method itself.

Quickstart

Three steps take you from nothing to a project with its first epic written.

  1. Create your repository from this template:

    gh repo create my-project --template jamyl/socle --private --clone
    cd my-project

    You should now see CLAUDE.md, GETTING-STARTED.md, modules/, and scripts/bootstrap.sh. If modules/ is absent, the copy was incomplete; start over.

  2. Open a session and bootstrap the project:

    claude

    Then, inside the session, run /bootstrap-project. This is a skill — a named instruction set that Claude Code loads on demand, invoked with a leading slash. The bootstrap runs once, interviews you, writes your documentation, and then deletes itself.

  3. Deliver the first story:

    /deliver-story
    

Read GETTING-STARTED.md in full before step 2. It covers prerequisites, each step in detail, what to check, and what to do when something goes wrong. The bootstrap deletes that file too, because it describes the template rather than your project.

Adopting the method in an existing project

The quickstart above assumes a fresh repository. If your project already has code, a history, and documentation of its own, that's a different path — and it touches none of what you wrote.

Three commands, from inside your project:

git clone --depth 1 https://github.com/jamyl/socle /tmp/socle
cd my-existing-project
/tmp/socle/scripts/adopt.sh

Then, in a Claude Code session open on your project: /adopter-socle.

What the script does. It checks that your working tree is clean, creates an adopter-socle branch, and copies the method: the skills, the four reviewers, the rules, the review workflow, and the documentation skeletons.

What it never does. It overwrites nothing. Your README.md, your LICENSE, and your .claude/settings.json are left alone entirely. If you already have a CLAUDE.md, the template's version lands beside it as CLAUDE.socle.md, and the skill walks you through the merge section by section. Your .gitignore gets only the lines it's missing, appended at the end. Everything skipped is listed in plain text when the script finishes: that list is what's left for you to reconcile.

What the skill does differently. Where /bootstrap-project interviews you about the stack, /adopter-socle reads your repository: the manifests and their lock files for exact versions, the build scripts and targets for the real commands, the existing CI for the gates already in place. A stack isn't worth asking about when the code is authoritative.

It then runs your test suite and reports the real output. Three cases, none of which is a failed adoption:

What it finds What it does
Green suite Records the count — you have a baseline
Red suite Doesn't write it up as green. It becomes the first story in the backlog
No suite Says so plainly. That's the most important story: "we watched it fail" is meaningless without tests

It asks you only what the code cannot tell — the product's purpose, the personas, the milestone in progress — and about the rules that cost the most to break, proposing the ones it inferred from your code so you correct them rather than start from a blank page.

Finally it writes a first epic that isn't "foundations", since those exist: it's the epic of what's missing for the method to run — the tests, the CI, the guard that keeps the suite away from your development database, and each piece of debt you chose to accept.

If your stack matches a module, pick up its subagents and rules too — and nothing else:

/tmp/socle/scripts/adopt.sh --stack stack-laravel

The flag copies only the module's .claude/ directory. No docker-compose.yml, no CI, no Dockerfile: a running project's infrastructure doesn't get replaced by a template's.

What isn't brought over, on purpose: no scaffold, no foundation stories, no retroactive specification of what you already shipped. The backlog starts now; git log already carries the past.

What the bootstrap asks you

The interview comes in four rounds, and you're asked to approve the result before anything gets written.

  1. Identity — the project name, a slug in kebab-case for container and database names, and the purpose in one sentence.
  2. Product — who uses it and for what, what has to work before you can say the product exists, and what is explicitly out of scope.
  3. Constraints and architecture — legal or regulatory obligations, hosting target, the languages your team debugs in production, scale at twelve months, realtime or offline needs, your deadline, and any stack you've already been handed.
  4. The rules that cost the most to break — three to five invariants of your domain, each phrased so a test can check it.

Round 4 decides the quality of everything that follows. Those rules become the checklist that one of the four reviewers applies to every change, for as long as the project lives. "No code outside X writes to Y" can be checked. "The code should be clean" cannot. A vague answer here produces a vague review for months.

After the interview, the agent names the hard mechanism in your design, if there is one — concurrency, consistency, offline sync — and offers a prior-art search on it, with the cost stated, then waits. It checks two or three candidate ecosystems for maintained implementations of the building blocks you need, which costs nothing but a few HTTP requests. Then it proposes one stack, one alternative, and the sentence that rules the alternative out.

Laravel is one possible outcome, not the default. The stack-laravel module activates because the discovery lands on PHP; any other answer gets a stack written from the interview and a developer subagent generated for it.

Nothing is written before you approve.

The daily cycle

Two commands carry the work, and each leaves a trace on disk:

/cadrer-story "<a raw requirement>"
      |
      v   2 to 5 stories written to an epic file, in Given/When/Then form
      |
/deliver-story
      |
      v   branch -> plan -> TDD -> tests green -> four-reader review
      |   -> pull request -> CI green -> squash merge
      |
docs/backlog/JOURNAL.md        one line per delivery
docs/backlog/DECISIONS.md      one line per call made without asking you

To chain several stories without retyping, run /loop 10m /deliver-story E01. The loop stops on its own when no story in scope is still actionable.

Writing a story and delivering it are separate commands on purpose. A badly framed story discovered during delivery costs a branch that's already open and a plan that's already written. Discovered during framing, it costs a re-read.

And when a test won't go green? That's where an assistant gets expensive: it patches, retries, re-patches, and forgets what it already tried. The method caps it at two attempts per idea.

What happens What the method requires
A red test survives the first fix Name two or three ideas, and for each one what would disprove it
The same error comes back a second time Roll the changes back, write down why the idea was wrong, move to the next one
A third attempt on the same idea Refused by a script, before the tests even run

Every attempt is scored on three measurable things — no secret committed, tests green, static analysis clean — and kept in a local .socle/ folder. Before writing a fix, the assistant re-reads that folder: it can't retry a dead idea, because the idea is written there.

At closing time, the journal records how many attempts the story took. A high number isn't a reproach: it's the signal that a lesson is worth writing into DECISIONS.md while it's still fresh.

What's inside

The delivery cycle. /deliver-story picks the next actionable story by walking the dependency graph, not a fixed list. A story whose prerequisite lives in a later epic gets skipped, then becomes a candidate again once that prerequisite ships. If a story needs a human — a legal opinion, an account with a third party, an API key — it's marked blocked with the reason, and the agent moves to the next one instead of losing a turn discovering the wall.

Counter-proof discipline. A test is proof only once you've seen it fail. Before writing "this is covered", the agent removes the guard the test claims to protect, re-runs it, confirms red, and restores. The skill carries eight concrete ways a test can stay green while proving nothing: tautology, missing setup, a race timed with sleep instead of a signal, a guard that's duplicated elsewhere, and four more. All eight were met in practice, within two days. The question that summarizes them: what would this test have to see to turn red?

The bounded exploration loop. Two attempts per idea, then the idea changes. Every attempt is scored by a script with no model call, kept in a local folder, and re-read before the next attempt — so an agent cannot retry what it has already disproved. The third attempt on the same idea is refused before the tests even start, and it's the only saving in this repo that removes no capability. The full rule lives in .claude/rules/exploration-policy.md, along with what's flatly forbidden: skipping a test, editing one so it passes, lowering a static-analysis threshold. Shopify Engineering puts it this way about Helix: "An attempt is allowed to be wrong. It is not allowed to ship until it isn't."

The four-reader review. After the tests pass, four read-only subagents read the same diff in parallel without seeing each other's findings: reviewer for conventions and structure, spec for the gap with the story (a criterion with no test, behavior nobody asked for), security-scanner for vulnerabilities, and domain-expert for your own invariants. Their findings are deduplicated and sorted in code, not by a model. Their tools are limited to reading files: no editing, no shell. reviewer and security-scanner have no network access at all, because their input is a diff someone else may have written. domain-expert keeps web search, so it can check a regulatory text. That's structural, not a promise in a prompt.

If one reader returns nothing at all, the workflow says so. Incomplete coverage is not the same as "nothing to report", and treating the two alike is how a review quietly stops being a review.

The review is a two-round gate, an idea taken from Shopify Helix: every serious finding gets fixed, then the four readers read the fix. The PR opens only after a clean round. A serious finding that survives the second round stops the cycle and comes back to you.

Prior art before architecture. The dejavu module searches published research for the hard part of your design before you rebuild it. It reads one paper per isolated subagent, so no source anchors another, then commits to a single recommended path with citations. Conclusions get recorded in docs/engineering/prior-art.md with their identifiers, because a conclusion nobody can reopen gets re-researched next session.

Eleven test levels. docs/engineering/testing-strategy.md defines levels N1 to N11, each with its scope and the moment it runs in CI. Two of them are the ones most projects skip and the ones that find the expensive defects: N4 runs concurrent operations as real processes and proves the executions actually overlapped, and N6 runs mutation testing on the critical domain only.

Optional modules

You choose modules during the interview. Nothing is copied unless you ask for it.

Module What it adds Activate it when
stack-laravel Docker Compose with PHP 8.4, PostgreSQL 16, Redis, Mailpit, and Horizon, all images pinned by digest. GitHub Actions running Pint, Larastan level 8, Pest on PostgreSQL, and a dependency audit. Four Laravel subagents, and a pre-written first epic The architecture discovery lands on PHP and Laravel
mobile-flutter A mobile/ directory, toolchain stories that start out blocked because Xcode and Android Studio can't be automated, and visual regression test levels You're building an iOS, Android, or PWA app
frontend-web Gates that block a broken interface, whatever the framework: automated accessibility, pixel-compared screenshots, speed budgets, and no color or spacing hard-coded outside the design tokens. Plus an interface reviewer and three design-direction skills, pinned with their licenses Your product has a public web interface
dejavu The /dejavu prior-art skill embedded in your repository and versioned with it. Four academic sources, no API keys, standard-library Python Your architecture has a non-trivial mechanism. Skip it if your machine already has /dejavu installed globally

The module rows say when the discovery lands there, not what you pick up front.

With no stack module you get the core: the method, the skills, three read-only reviewers, the secret scanner, the attempt scorer, and documentation skeletons. The bootstrap then writes stack.md and testing-strategy.md from the discovery, and generates a developer subagent — plus dba when there's a relational database — from .claude/templates/.

The secret scanner (.github/scan-secrets.sh) sits in the core on purpose: a committed key costs the same revocation in any stack. It runs on every delivery attempt, before the tests.

What it leaves out, on purpose

No application scaffold. Neither composer create-project nor flutter create ships here. The scaffold is born in the first delivery iteration, with that day's versions. A scaffold frozen inside a template rots within months, and nobody notices before they've built on top of it.

No business domain. The template asks for your invariants rather than assuming any.

No complete backlog. The bootstrap writes the first epic and nothing else. Epics written months before they're needed are epics you rewrite.

What a run costs

These commands spawn subagents and make real network calls. Know the cost before you start a loop.

Action What it spends
One four-reader review 4 subagents per round, one or two rounds per story
One /dejavu search Roughly 18 to 26 agent-shaped calls (1 categorize, 12 to 20 isolated reads on Haiku, scoring, clustering, up to 3 full-text reads, 1 convergence), plus real HTTP to four APIs
Checking ecosystems with codesearch.py Nothing. It's a Python script — no model in the loop
Scoring an attempt, re-reading the cache, running the retrospective Nothing. It's a Node script — it runs your test commands, it judges nothing
/loop Runs unattended until the backlog is exhausted. It expires after seven days

Every subagent declares Sonnet. The reviewers use its full ID, so that an alias override can't run them on the author's model. The isolated prior-art reads run on Haiku. The heavy model is reserved for /security-review, the one gate the delivery cycle imposes on the critical domain. The full policy, and how to move one agent up when your domain warrants it, is in docs/engineering/models.md.

A loop that's running consumes tokens while you're looking elsewhere, and it re-launches /deliver-story even when you thought you were done. If a delivery starts without you typing anything, that's the loop: check CronList before concluding anything, and CronDelete <id> stops it early.

The two-attempts-per-idea cap exists for exactly this unattended loop. The heaviest cost isn't an over-priced model on a reviewer: it's an agent re-patching the same block fifteen times, re-reading the whole context on each pass.

Check that it worked

After the bootstrap, two commands tell you whether it finished. First, look for leftover placeholders:

grep -rn '{{[A-Z_]\+}}' . --exclude-dir=.git

You should see nothing. Every surviving placeholder is a spot where your project still talks about the template. The pattern matches only the real shape — two braces, uppercase letters, two braces — so a bare grep "{{" doesn't drag in legitimate braces from code.

Then confirm the template removed itself:

ls modules scripts

You should see "No such file or directory". If those directories are still there, the bootstrap stopped partway.

If you activated stack-laravel, check that the environment starts:

docker compose up -d && docker compose ps

Every service should read running, and the database should read healthy.

Two projects that both activated stack-laravel can't run at the same time without editing ports. Both publish 8080 for the app, 5433 for PostgreSQL, 6380 for Redis, and 8026 for Mailpit. The second docker compose up -d either fails on a taken port or, worse, connects a tool to the other project's database.

Local configuration

Some configuration files belong to the repository, others to your machine. Mixing them produces two unpleasant symptoms: a permission that works for you and nowhere else, or a machine path committed in a pull request.

Committed, because the whole team needs the same guardrails: .claude/settings.json (the allow and deny permissions), the entire method under .claude/, CLAUDE.md, and the .mcp.json a module provides.

Never committed, and already in .gitignore: .claude/settings.local.json (your personal overrides), .claude/scheduled_tasks.json and its lock (the state of /loop runs, which belongs to the session that started them), .socle/ (the attempt cache: a story's path, not its result), Python bytecode, and the *.bak files an interrupted bootstrap leaves behind.

Doesn't live in the repository at all: your global preferences in ~/.claude/, skills you installed for yourself, the /dejavu cache in ~/.cache/dejavu — shared across all your projects — and environment variables such as DEJAVU_CONTACT.

⚠️ An environment variable has to be in your shell profile (~/.zshrc, ~/.bashrc), not just exported in a terminal: the Claude Code process started before your export, so it doesn't see it. Reopen the terminal after editing.

🔑 A deny list is not a security control. It compares literal prefixes, and the equivalent forms of the same push are countless. The template's three deny rules catch slips of attention, nothing more. What is a control: branch protection on the GitHub side.

Two hooks in .claude/hooks/ go further than the list: they read the whole command and refuse a push to main in any form, a force push, --no-verify, and merging a story whose last attempt isn't green. They catch an agent that forgets a rule, not one that works around it.

The details — what's deliberately missing from the allow list, and why you shouldn't widen it in advance — are in docs/engineering/config-locale.md.

Words used here

Term What it means
Claude Code Anthropic's coding agent, run from a terminal, an IDE, or a browser
Skill A named instruction set that the agent loads on demand. You invoke one by typing a slash and its name, like /deliver-story
Subagent A separate agent run with its own tool list and its own context. The four reviewers are subagents
Workflow A JavaScript file in .claude/workflows/ that orchestrates several subagents deterministically. review-story is one
Story One unit of work with acceptance criteria, numbered US-XYZ. Also called a user story
Epic A file grouping related stories, numbered E01, E02, and so on
Backlog Everything in docs/backlog/: the epics, the delivery journal, and the decision log
TDD Test-driven development. Write the failing test, then the code that makes it pass
Counter-proof Deliberately breaking the code a test protects, to confirm the test turns red
Strike An attempt whose error is identical to the previous one. On the second, the idea is abandoned and the agent switches
Squash merge Merging a branch as a single commit, so one story reads as one commit on main
Bootstrap The one-time run that turns this template into your project

When something breaks

GETTING-STARTED.md ends with a symptom-cause-fix table covering the failures people actually hit: the bootstrap refusing to start, placeholders surviving, a reviewer staying silent, and a domain-expert that never finds anything because it was never specialized.

Two rules are worth repeating here. Never merge on a red CI. And if a reviewer returns no report, that's incomplete coverage, not a clean bill of health.

One message looks like a failure and isn't: ⛔ … a 2 strikes — rien n'a été exécuté. That's the exploration guard refusing a third attempt on a dead idea. The way out is printed right below it.

Contributing

Issues and pull requests are welcome. Two things to know before you open one.

.github/workflows/template.yml bootstraps a throwaway copy in five module combinations on every pull request, and checks that nothing of the template survives, that no backup file is left behind, and that only the writing placeholders remain. Run the same check locally before opening a pull request:

node --test .claude/skills/deliver-story/scripts/eval-run.test.mjs   # the attempt scorer
./.github/scan-secrets.sh                                           # no secret in here
cp -R . /tmp/socle-check && cd /tmp/socle-check
./scripts/bootstrap.sh test-slug stack-laravel
grep -rn '{{[A-Z_]\+}}' . --exclude-dir=.git   # only the writing placeholders
ls modules scripts                              # No such file or directory

CONTRIBUTING.md at the root belongs to the generated project, not to this template. It's one of the files your project inherits.

Origin and license

This template was extracted from a real project delivered with this method. What survived the extraction is what had already caught a defect: the counter-proof discipline, the four-reader review, the "here's how to check it yourself" section that closes every report, and the whitelist that keeps the agent from installing tools nobody approved.

Licensed under MIT.

About

A project template for Claude Code. The working method ships with it; your domain gets filled in by an interview the first time you run it. Template de projet Claude Code : cycle de livraison, contre-épreuves, revue en fan-out. Le domaine se remplit à l'amorçage.

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages