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.
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.
- Ce que c'est
- Prérequis
- Démarrage rapide
- Adopter la méthode dans un projet existant
- Ce que l'amorçage te demande
- Le cycle quotidien
- Ce qu'il y a dedans
- Modules optionnels
- Ce qu'il n'y a pas dedans, exprès
- Ce qu'un run coûte
- Vérifier que ça a marché
- Configuration locale
- Les mots employés ici
- Quand quelque chose casse
- Contribuer
- Origine et licence
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.
À 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.
Trois étapes t'amènent de rien à un projet dont le premier epic est écrit.
-
Crée ton dépôt depuis ce template :
gh repo create mon-projet --template jamyl/socle --private --clone cd mon-projetTu dois maintenant voir
CLAUDE.md,GETTING-STARTED.md,modules/etscripts/bootstrap.sh. Simodules/est absent, la copie est incomplète : recommence. -
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. -
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.
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.shPuis, 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-laravelLe 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é.
L'interview se fait en quatre lots, et rien n'est écrit avant que tu valides le résultat.
- 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.
- 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.
- 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.
- 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.
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.
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.
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.
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.
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.
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=.gitTu 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 scriptsTu 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 psTous 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.
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.
~/.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.
| 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 |
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.
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 directoryLe CONTRIBUTING.md à la racine appartient au projet engendré, pas à ce
template. C'est l'un des fichiers dont ton projet hérite.
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.
- What this is
- Requirements
- Quickstart
- Adopting the method in an existing project
- What the bootstrap asks you
- The daily cycle
- What's inside
- Optional modules
- What it leaves out, on purpose
- What a run costs
- Check that it worked
- Local configuration
- Words used here
- When something breaks
- Contributing
- Origin and license
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.
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.
Three steps take you from nothing to a project with its first epic written.
-
Create your repository from this template:
gh repo create my-project --template jamyl/socle --private --clone cd my-projectYou should now see
CLAUDE.md,GETTING-STARTED.md,modules/, andscripts/bootstrap.sh. Ifmodules/is absent, the copy was incomplete; start over. -
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. -
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.
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.shThen, 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-laravelThe 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.
The interview comes in four rounds, and you're asked to approve the result before anything gets written.
- Identity — the project name, a slug in kebab-case for container and database names, and the purpose in one sentence.
- 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.
- 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.
- 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.
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.
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.
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.
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.
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.
After the bootstrap, two commands tell you whether it finished. First, look for leftover placeholders:
grep -rn '{{[A-Z_]\+}}' . --exclude-dir=.gitYou 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 scriptsYou 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 psEvery 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.
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.
~/.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.
| 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 |
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.
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 directoryCONTRIBUTING.md at the root belongs to the generated project, not to this
template. It's one of the files your project inherits.
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.