Le processus de la skill sdlc

La skill /sdlc applique le playbook « AI-native SDLC » d'Anthropic à un projet : chaque étape du développement devient un fichier versionné, relu avant de passer à la suivante. Elle met la structure en place, puis, en option, installe un cycle de chantiers conduit par un coordinateur, qui lance un agent neuf par phase et ne sollicite l'utilisateur que pour trancher.

L'idée directrice

Écrire du code n'est plus le goulot d'étranglement : ce sont le cadrage, le test et le déploiement. Le playbook transforme donc chaque étape en artefact versionné :

La configuration (CLAUDE.md, skills, hooks, evals) est traitée comme du code : versionnée et relue. Les humains gardent les décisions ; les hooks (déterministes) bloquent, les skills et CLAUDE.md (consultatifs) guident.

La skill travaille à deux niveaux : elle met en place la structure une fois, puis le cycle de chantiers (brique optionnelle) la maintient au quotidien. Deux règles gouvernent toute la skill :

Les questions sont posées par lots de 2 à 4, avec des options concrètes et la recommandation en premier.

Étape 0 : détecter le mode

La skill inspecte le dossier courant en lecture seule : git log, manifestes (pyproject.toml, package.json, go.mod…), code source, CLAUDE.md, .claude/, README, CI.

Le mode détecté est annoncé en une phrase. Si la session est dans un dossier temporaire alors que l'utilisateur parle d'un projet existant, la skill demande ou déplace la session vers le bon dossier avant de lire quoi que ce soit.

Mode existant : auditer puis adopter

1. a1Audit en lecture seule

   Comparaison du dépôt à une checklist : CLAUDE.md, commande unique build+test, dossier d'artefacts, source de vérité des exigences, hooks, permissions, subagent verifier, skills de politiques, REVIEW.md, CI et evals, gate de production, surveillance. Chaque ligne est notée présent, partiel ou absent, avec le chemin comme preuve. Les conventions déjà documentées sont repérées pour être préservées.

2. a2Questions à l'utilisateur

   Ce qui coince aujourd'hui, périmètre d'adoption (tout ou certaines briques), taille d'équipe et hébergement, source de vérité des exigences (dépôt, outil existant type Jira, ou simple lien d'ID), contraintes à respecter, emplacement des artefacts, et le cycle de chantiers : le projet va-t-il évoluer par évolutions successives, qui valide les portes et qui fusionne, quels dossiers non versionnés partager entre worktrees.

3. a3Plan d'adoption à valider

   Pour chaque brique : créer, fusionner ou ignorer, avec fichiers touchés, risque et ordre. Trois niveaux : gains rapides sans risque, garde-fous (hooks, permissions), optionnel et coûteux (CI d'evals, REVIEW.md, monitoring, cycle de chantiers avec son coordinateur, ses agents de phase, ses hooks et ses scripts de worktree). La skill attend un « oui » explicite.

4. a4Application brique par brique

   Petits changements relisibles, sans jamais écraser un fichier existant (fusion, diff montré), sans toucher au code applicatif. Les commandes de vérification sont lancées après chaque brique et leur sortie réelle est rapportée. Aucun commit sans permission.

Mode nouveau : cadrer puis construire

1. b1Découverte du besoin

   Brainstorming par questions : problème et public, critères de réussite, systèmes concernés, contraintes (stack, hébergement, budget, délais, conformité, données personnelles), hors périmètre, questions ouvertes. Le besoin est reformulé pour faire corriger les malentendus avant d'écrire.

2. b2Évaluer la complexité

   Simple (script, un seul flux, peu d'inconnues) : intent.md seul et CLAUDE.md. Complexe (plusieurs composants, intégrations, données sensibles, choix d'architecture, jalons) : chaîne complète intent.md → spec.md → plan.md avec validation à chaque étape.

3. b3Artefacts

   Dans docs/sdlc/, ou dans docs/chantiers/<AAAA-MM>-<slug>/ si le cycle de chantiers est adopté. intent.md (statut ouvert, validé par l'utilisateur, qui joue le product owner). spec.md dérivée de l'intent, politiques appliquées pendant la rédaction, contradictions signalées plutôt que tranchées en silence. plan.md établi en lecture seule : fichiers à créer, ordre, risques, preuves.

4. b4Squelette du projet

   Version minimale après validation : stack choisie avec l'utilisateur, CLAUDE.md d'une page, une commande unique de vérification et un premier test qui passe (pytest via uv, vitest en JS/TS), hooks essentiels si pertinent. Le subagent verifier, REVIEW.md, les evals en CI et le cycle de chantiers restent optionnels. git init et premier commit seulement avec permission.

Les six phases du playbook

Le cycle de chantiers

Une fois la structure posée, le projet évolue par chantiers : un par évolution, avec ses propres intent.md, spec.md et plan.md, sa branche chantier/<slug> et son worktree. La brique ne convient pas à un script ni à un projet sans évolution prévue.

Le cycle est conduit par un coordinateur : le skill /chantier, qui tourne dans la session de l'utilisateur. Il n'écrit ni document, ni test, ni code. Il lance un agent neuf par phase, trie ses questions, commite et tient un journal. L'utilisateur n'est sollicité que pour trancher : valider l'intention, valider la conception (spec et plan ensemble), merger. Des hooks tiennent chaque agent dans son rôle et réservent le merge à l'utilisateur.

Les phases et les trois portes

Le statut vit dans l'en-tête d'intent.md : ouvert, puis clos (avec la date) ou abandonné (avec une ligne de raison). La phase en cours vit dans journal.md. Chaque phase est commitée avant la suivante, ce que le coordinateur vérifie avec git log et git status dans le worktree.

Graphe animé d'un chantier

Le graphe montre qui parle à qui pendant un chantier complet : la session de l'utilisateur, le coordinateur, les six agents, les documents qu'ils ont le droit d'écrire, le hook garde.py qui filtre chaque écriture, et la branche du chantier qui reçoit un commit par porte franchie.

Règles qui valent à toute phase

• Un agent neuf par phase. Le coordinateur ne lui passe que le chemin absolu du dossier du chantier, ce qu'il doit produire et, en relance, la critique ou les réponses à intégrer. Jamais un résumé de la conversation : l'agent ne s'appuie que sur les fichiers amont, CLAUDE.md et le code. Une information qui lui manque est un défaut de ces fichiers.
• Dans une phase, on continue les mêmes agents. Une relance passe par SendMessage à l'agent déjà lancé, qui reprend depuis sa transcription. La relecture qui suit est faite par le même relecteur. À la phase suivante, des agents neufs.
• Un relecteur distinct par phase relue. Conception, plan et tests ont chacun leur chantier-relecteur, lancé neuf : une seule définition d'agent, trois instances qui ne se connaissent pas. Celui de la conception n'est pas repris pour relire plan.md, même si spec et plan passent la même porte. Intention et code n'ont pas de relecteur ; en phase Code, c'est le coordinateur qui vérifie la suite et la mesure.
• Deux relances par agent et par phase. Au-delà, escalade : le blocage, ce qui a été tenté, les options.
• Un aval ne modifie jamais un amont. Un agent qui signale amont_a_rouvrir déclenche une escalade si l'amont est intent.md ou si la correction change ce que l'utilisateur a validé ; sinon le coordinateur relance l'agent de l'amont puis le relecteur, et le note au journal.
• Commits délégués par chantier. La permission est donnée une fois à l'ouverture, pour la branche du chantier seulement. Messages d'une ligne, sans attribution à une IA.
• CLAUDE.md ne change pas pendant un chantier. Les décisions qui valent pour tout le projet vont dans « Décisions à reporter » de plan.md et passent dans CLAUDE.md au merge, un chantier à la fois.
• Données partagées. Les dossiers non versionnés reliés entre worktrees sont communs : une commande qui y écrit ne se lance qu'avec l'accord de l'utilisateur, si aucune autre session n'en lance une.
• Écrire par Edit et Write, par chemin absolu dans le worktree : c'est ainsi que le hook juge l'écriture dans le bon worktree.

Trancher, régler ou informer

Chaque agent termine par un rapport YAML (questions, decisions_prises, amont_a_rouvrir, verification). Le coordinateur trie chaque question et chaque remarque bloquante :

Les questions pour l'utilisateur sont groupées, une fois par phase au plus, chacune avec deux à quatre options, la recommandation en premier et la raison pour laquelle elle lui revient.

Le journal

journal.md, dans le dossier du chantier, est tenu par le coordinateur seul et commité avec chaque phase. Il sert à reprendre après un /clear ou dans une autre session, et à contester une décision.

permission_commits: accordée AAAA-MM-JJ, branche chantier/<slug>
phase: intention | conception | plan | tests | code | pret-a-merger | clos | abandonne
relances: <phase> <n>/2
agents: <phase> — <agent> <identifiant>, chantier-relecteur <identifiant>

## En attente de l'utilisateur
## Décisions prises seul        décision — source : fichier §section
## À signaler (relecteur)
## Déroulé                      agent lancé, relance, commit, escalade

Les commandes

Le circuit bogue n'a qu'une porte, le merge. chantier-intention écrit un intent.md minimal (symptôme, commande qui le reproduit, résultat attendu) portant circuit: bogue ; pour ce circuit, le hook n'exige que cet intent.md commité avant le code. Pas de spec ni de plan si la correction est locale ; sinon le circuit complet reprend. chantier-tests écrit le test qui reproduit le bogue et le voit échouer, puis chantier-code corrige sans toucher au test.

Un worktree par chantier

ouvrir.py, lancé depuis le dossier principal, crée la branche chantier/<slug> et le worktree .claude/worktrees/<slug>/, relie les dossiers non versionnés partagés et installe l'environnement (par exemple uv sync, car le .venv n'est pas versionné et les hooks l'appellent). Le coordinateur reste dans la session de l'utilisateur, dans le dossier principal : ce sont les agents qui partent de zéro. Ce sont donc les hooks du dossier principal qui tournent ; garde.py juge une écriture par chemin absolu dans le worktree qui contient ce chemin. lister.py liste les chantiers ouverts de tous les worktrees, avec leur branche et les portes franchies.

Verrous par agent

Pour un appel fait par un sous-agent, Claude Code transmet au hook le champ agent_type (le nom de sa définition, par exemple chantier-tests) ; il est absent pour la session principale, qui partage le même session_id. garde.py fonde ses verrous sur ce champ :

Seule l'approbation de merge reste une commande au quotidien. Le hook commande.py se déclenche à l'envoi d'un message de l'utilisateur (UserPromptSubmit), avant que Claude le voie : /chantier merge pose un marqueur dans .claude/etat/, lié à la session et purgé après deux jours. garde.py interdit à Claude d'écrire dans ce dossier, ce qui garantit que seul l'utilisateur l'ouvre. La commande ne compte qu'au tout début du message, une fois retiré le contexte <ide_…> de l'extension VS Code ; un message venu d'une autre session (enveloppe <cross-session-message>) n'ouvre jamais rien.

Si agent_type n'arrive pas (version de Claude Code qui ne l'envoie pas), le coordinateur passe en repli : il demande à l'utilisateur de taper /chantier tests, puis /chantier code en fin de phase Tests, et dit toujours pourquoi.

Ce que fait garde.py

La garde est stricte pour Edit et Write, heuristique pour le shell : un script qui écrit hors de la vue du hook passe, et la relecture reste le filet. L'heuristique refuse parfois à tort (comparaison par sous-chaîne d'un chemin gardé, texte d'un heredoc pris pour des commandes). Les sources d'une copie ne sont que lues : seule la destination est contrôlée. Hors branche de chantier, la garde sur le code ne bloque rien.

Le merge

L'utilisateur seul, en tapant /chantier merge. Aucun agent ne fusionne ; c'est le coordinateur, depuis le dossier principal :

• Vérification : intent.md à statut: clos, worktree propre, suite complète verte, mesure de la spec atteinte, artefact déployé vérifié s'il en existe un.
• Dans la même question que la confirmation : garder ou supprimer le worktree et la branche après le merge.
• Fusion qui conserve l'historique des phases : git merge --no-ff chantier/<slug>, sans squash.
• Report des décisions de plan.md dans la section « Décisions » de CLAUDE.md, dans un commit à part.
• En cas de conflit : arrêt, fichiers en cause montrés, rien n'est résolu sans l'utilisateur.

Arborescence

projet/
├─ CLAUDE.md                  commandes, conventions, invariants, décisions
├─ REVIEW.md                  passes de relecture avant commit
├─ docs/
│  └─ chantiers/
│     └─ AAAA-MM-slug/        un dossier par chantier
│        ├─ intent.md          le besoin, sans solution
│        ├─ spec.md            la conception
│        ├─ plan.md            l'exécution et les tests nommés
│        └─ journal.md         tenu par le coordinateur
├─ tests/                    écrits par chantier-tests seul
└─ .claude/
   ├─ settings.json          permissions et hooks
   ├─ skills/chantier/       SKILL.md : le coordinateur
   ├─ agents/                chantier-intention, -conception, -plan,
   │                         -relecteur, -tests, -code
   ├─ hooks/                 garde.py, commande.py
   ├─ chantier/              ouvrir.py, lister.py
   ├─ etat/                  approbations liées à la session, non versionné
   └─ worktrees/             un worktree par chantier en cours, non versionné

Contenu des trois fichiers

Un seul jeu de sections pour intent.md, spec.md et plan.md, avec ou sans le cycle de chantiers. Avec le cycle, les mêmes sections figurent dans les agents de phase.

---
statut: ouvert
ouvert: AAAA-MM-JJ
---
# Titre

## Besoin
Le problème, tel qu'observé, pour qui ; un exemple concret.

## Pourquoi maintenant
Ce qui le rend utile ou urgent.

## Critère de réussite
Observable et vérifiable : un temps, un résultat de commande, une mesure.

## Hors périmètre
Ce qu'on ne fait pas.

## Contraintes
Stack, délais, conformité, données, budget : si elles comptent.

## Questions ouvertes
À trancher avant la spec.

## Pistes notées en passant
Solutions évoquées, non retenues ; la spec les examinera.

# Spec : titre

## Approche retenue
En quelques paragraphes : comportement, flux, interfaces, modèle de données.

## Invariants de CLAUDE.md touchés
Pour chacun, comment il est respecté. « Aucun » se justifie en une ligne.

## Options écartées
Une phrase chacune, avec la raison.

## Comportement qui change
Ce que l'utilisateur verra de différent : cela décide des tests à modifier.

## Exigences transverses
Sécurité, vie privée, accessibilité, performance, journalisation, politiques appliquées.

## Contradictions et points signalés
Conflits entre exigences ou politiques, non tranchés silencieusement.

## Critères d'acceptation
Liste testable.

## Mesure qui tranchera
La mesure et son seuil, fixés avant d'écrire le code.

# Plan : titre

## Étapes et fichiers touchés
Chemins, création ou modification, ordre ; réutiliser l'existant.

## Tests
Liste nominative des tests à ajouter, modifier ou supprimer, avec la raison
de chacun et le critère d'acceptation couvert. Liste vide possible, à justifier.

## Mise à jour de ce qui est visible
Artefact déployé, documentation : si le comportement visible change.

## Risques
Ce qui pourrait casser, dépendances, migrations, retour arrière.

## Vérification
Commandes de CLAUDE.md et mesure de la spec.

## Décisions à reporter
Décisions valables pour tout le projet, reportées dans CLAUDE.md au merge.

Installer la brique

1. 1Questions

   Décideur des portes (seul ou équipe), délégation des commits de chaque chantier au coordinateur, branche principale, chemins protégés, dossiers de tests et de code, dossiers à partager, commande d'installation, commande de vérification complète, artefact « déployé » éventuel.

2. 2Adapter les modèles

   Constantes « À ADAPTER » de garde.py et ouvrir.py, champs du skill et des six agents, copiés dans .claude/agents/. Les hooks ne sont pas élargis au-delà de ce que le projet demande.

3. 3Brancher les hooks

   Fusion dans .claude/settings.json : commande.py sur UserPromptSubmit (sans matcher), garde.py sur PreToolUse pour Edit, Write, NotebookEdit, Bash et PowerShell. .gitignore : /.claude/etat/ et /.claude/worktrees/.

4. 4Copier et lancer les tests

   Pour chaque hook, un cas qui doit bloquer, un cas qui doit passer et une entrée illisible, plus la création de worktree et la liste des chantiers. Tous doivent passer ; la sortie réelle est montrée.

5. 5Vérifier en séance réelle

   Les hooks ne se chargent que dans une nouvelle session. Taper /chantier tests et contrôler qu'un marqueur apparaît dans .claude/etat/, avec un fichier ouvert dans l'éditeur : seul le marqueur fait foi, pas ce que répond Claude. Puis, sur une branche de chantier au plan commité, faire écrire un test par chantier-tests (accepté) et par chantier-code (refusé). Un refus pour chantier-tests signifie que agent_type n'arrive pas : rester en repli.

6. 6Documenter

   Une section « Cycle de développement » d'une demi-page dans CLAUDE.md. Aucun commit sans permission.

Principes appliqués partout

• Vérifier avant de dire « fini » : build, test et lint exécutés, sortie réelle collée, objectif quantifiable, aucun test supprimé pour passer au vert.
• Bug fix = test qui échoue d'abord, puis correction.
• Règle des deux erreurs : une erreur répétée entre dans « Things Claude gets wrong ».
• Config = code : versionnée et relue.
• Séparation des tâches : l'agent qui code n'approuve pas ; approbation de PR, merge et déploiement en production restent humains.
• Le merge est humain, sur la commande de l'utilisateur, posée par un hook à l'envoi de son message, jamais par Claude. Avec le cycle de chantiers, le verrou des tests suit l'agent qui écrit (agent_type), pas une commande.
• Hooks pour le déterministe, skills pour le consultatif ; sous Windows, pas de hooks supposant bash.
• Ne rien inventer : chiffres, URLs, API, commandes viennent du dépôt ou de l'utilisateur.

Sortie finale

Un résumé court : mode retenu, décisions prises, fichiers créés ou modifiés, commandes de vérification lancées et leur résultat, points en suspens, prochaine étape suggérée : un premier chantier (/chantier nouveau <idée>) si le cycle est installé, sinon un premier intent.md, ou l'activation de la revue automatique des PR.