Le développement piloté par spec avec Claude Code

Problème : Le taux de réussite au premier essai de Claude Code sur les PR petites à moyennes sans guidance détaillée tourne autour d'un tiers, selon l'équipe RL Engineering d'Anthropic elle-même. Les deux tiers du temps, il rate des exigences, interprète le périmètre trop largement, ou choisit le mauvais chemin d'implémentation. Le correctif n'est pas de prompter davantage en cours de session. C'est d'écrire une spec avant que la session commence.

Le calcul est brutal. Suppose que Claude prend la bonne décision 80 % du temps sur n'importe quelle décision individuelle. Une fonctionnalité typique implique 20 décisions. Probabilité d'avoir les 20 bonnes sans guidance : 0,8^20, soit environ 1 %. Une spec revue amène chaque décision près de la certitude parce que tu as déjà fait le choix. La spec ne guide pas Claude. Elle retire les décisions que Claude ne devrait pas prendre en premier lieu.

Le pattern en quatre phases

Le développement piloté par spec (SDD) tourne en quatre phases : Exigences, Design, Tâches, et Exécution. Les trois premières se passent dans une session. La quatrième dans une nouvelle session.

Exigences capture ce que la fonctionnalité doit faire du point de vue de l'utilisateur. User stories, critères d'acceptation, cas limites. Pas comment. Quoi.

Design capture l'architecture : modèles de données, contrats API, quels fichiers changent, lesquels restent, quelle décision de stack technique pour cette fonctionnalité.

Tâches est le plan d'implémentation ordonné avec des dépendances explicites. L'étape 3 ne peut pas commencer avant que l'étape 2 soit terminée. Cet ordre compte quand Claude est en plein dans une chaîne d'appels d'outils.

Exécution se déroule dans une session entièrement séparée. Ce n'est pas optionnel.

Pourquoi la session fraîche compte

Claude s'attache à son propre plan dans la même session. Il a déjà raisonné sur les exigences et le design, donc il porte ces hypothèses implicitement plutôt que de lire la spec telle qu'elle est écrite. Une session fraîche force Claude à lire la spec comme un nouvel ingénieur le ferait : depuis le début, littéralement.

Le consensus de la communauté là-dessus est unanime. Pimzino, dont le package claude-code-spec-workflow (3 700+ étoiles, 258 forks) a formalisé cette approche après avoir étudié l'IDE spec-driven d'Amazon Kiro, décrit le split de session comme non négociable. La session spec utilise Claude Opus pour un raisonnement profond sur les exigences. La session d'implémentation utilise Claude Sonnet pour exécuter un plan clair. Des jobs différents, des modèles différents, des sessions différentes.

Le workflow d'interview recommandé par Anthropic

La doc officielle d'Anthropic décrit la façon la plus rapide de produire une bonne spec : le mode interview. Lance une session fraîche et exécute :

I want to build [brief description]. Interview me in detail using 
the AskUserQuestion tool.

Ask about technical implementation, UI/UX, edge cases, concerns, 
and tradeoffs. Don't ask obvious questions, dig into the hard parts 
I might not have considered.

Keep interviewing until we've covered everything, then write a 
complete spec to SPEC.md.

Claude pose des questions jusqu'à avoir couvert l'implémentation, l'UX, les cas limites, et les compromis. Quand il est satisfait, il écrit la spec dans SPEC.md. Ensuite tu fermes la session. La session suivante ouvre la spec et construit.

C'est ce transfert qui concentre la plupart de la valeur.

La structure de dossiers

Pour les petites fonctionnalités ou les projets solos, un seul SPEC.md suffit. Pour les fonctionnalités plus larges avec plusieurs parties mobiles, la communauté a convergé sur trois fichiers dans un dossier nommé :

.claude/
├── commands/       # 14 slash commands
├── steering/       # product.md, tech.md, structure.md
├── specs/
│   └── {feature-name}/
│       ├── requirements.md
│       ├── design.md
│       └── tasks.md
├── bugs/           # bug fix workflows
└── agents/

Le dossier steering/ sert de mémoire projet entre les sessions. product.md contient la vision. tech.md contient les décisions de stack. structure.md contient les conventions de fichiers. Toute session qui ouvre ces trois fichiers commence avec le contexte qu'il aurait fallu des dizaines de messages aller-retour pour établir.

Tu peux installer le scaffold complet de Pimzino avec une commande :

npx @pimzino/claude-code-spec-workflow

La règle de correction du test

Sans spec, Claude a deux chemins vers une suite de tests verte : corriger le code cassé, ou modifier le test qui échoue pour qu'il accepte un mauvais comportement. Il prend parfois le chemin le plus facile. Ce n'est pas un bug. C'est une optimisation locale rationnelle en l'absence de contrainte contre ça.

La contrainte va dans SPEC.md ou CLAUDE.md :

## During Testing

**IMPORTANT!** When you find a failure during testing, **NEVER** ignore or remove 
the test to bypass the failure.

**ALWAYS** identify the root cause first.

If the root cause is in the *application's implementation*, then fix the application.
If the root cause is because the *test* was incorrectly made, then fix the test.

C'est un petit ajout. Il ferme l'un des modes d'échec les plus courants dans les sessions non guidées.

L'angle mort de la cohérence interne

Quand Claude Opus écrit une spec, il ne voit pas ses propres lacunes. Le raisonnement qui a généré les exigences est toujours actif, donc les omissions qui n'ont jamais été considérées restent non considérées lors de la revue.

Faire tourner un modèle différent (GPT ou Codex) pour revoir adversarialement une spec générée par Claude fait remonter des problèmes majeurs dans presque tous les documents. Le pattern qui fonctionne : deux agents séparés, chacun explicitement chargé de trouver des lacunes, des cas limites manquants, et des conflits d'hypothèses. L'un cherche des exigences manquantes. L'autre cherche des hypothèses d'implémentation enfouies dans le design qui n'ont jamais été soumises à l'utilisateur. Les deux tournent avant que l'implémentation commence.

Le problème du document vivant

Au moment où ta spec se désynchronise avec le code, la plupart des bénéfices disparaissent. Les sessions suivantes peuvent silencieusement revenir sur des changements non documentés ou interpréter le périmètre sur la base d'un design obsolète.

Le correctif vient de Sevak Avakians et correspond à ce que les équipes internes d'Anthropic pratiquent : la dernière étape de tout plan de tâches devrait être la mise à jour de la documentation. Demande à Claude de résumer le travail accompli et de suggérer des améliorations à CLAUDE.md à la fin de chaque session. L'équipe Data Science d'Anthropic rapporte des gains de temps de 2 à 4x sur le refactoring routinier. Son équipe Security Engineering a réduit le débogage d'infrastructure de 10-15 minutes à 5 minutes. L'équipe Product Dev a vu 70 % d'une implémentation de mode Vim complétée de façon autonome. Dans tous les cas, un bon contexte au début de la session était la variable.

La documentation de fin de session n'est pas de la surcharge. C'est comment la spec reste utile après le premier build.

Modes d'échec

Six patterns cassent le SDD en pratique :

Périmètre trop large. "Construis un système de gestion d'utilisateurs" sans définir quels utilisateurs, quelles actions, ou quelles permissions signifie que Claude interprète au maximum. La fenêtre de contexte se remplit de travail que tu n'as pas demandé.

Spec obsolète. Quelqu'un prompte un changement directement sans mettre à jour la spec. La session suivante lit la spec et revient silencieusement sur le changement.

Kitchen sink. Deux fonctionnalités non liées dans une même spec. Claude introduit une contamination croisée entre elles. Garde les specs à une seule unité de travail cohérente.

Dérive de contexte. Une spec dans la fenêtre de contexte est effectivement "perdue" au fur et à mesure que la conversation dépasse 15-20 appels d'outils. Les sessions fraîches pour l'implémentation préviennent ça.

Spec générée par LLM substituant la réflexion. Une étude de l'ETH Zurich a trouvé que les fichiers d'agents générés par LLM nuisent aux performances tout en coûtant 20 % de tokens supplémentaires. Les specs écrites par des humains ont aidé à 4 %. La spec ne fonctionne que si un humain l'a revue et a pris de vraies décisions. Une spec entérinée sans réflexion est du bruit.

Session bleed. Lancer la création de la spec et l'implémentation dans la même session. Le problème d'attachement réapparaît. La spec devient une suggestion, pas une contrainte.

Quand utiliser quel pattern

Trois options couvrent toute la gamme de tailles de projets :

Les Architecture Decision Records vont dans docs/adr/ avec un préfixe de numéro séquentiel. Un fichier par décision. Ils capturent ce qui a été décidé, quelles alternatives ont été considérées, et pourquoi cette option a gagné. Ce ne sont pas des fichiers spec. Ce sont des enregistrements permanents de choix qui disparaîtraient sinon dans l'historique de chat.

Pour la plupart des fonctionnalités sur un projet solo, SPEC.md à la racine du dépôt suffit. Utilise la structure à trois fichiers quand une fonctionnalité touche la couche base de données, un contrat API, et un composant UI dans le même build. Utilise les ADRs quand un choix est architectural et conséquent : sélection de file d'événements, stratégie d'authentification, couche de cache, schéma de versioning d'API.

Ce que ça change

Le taux de 33 % au premier essai sans guidance n'est pas une limitation du modèle. Il reflète la taille de l'espace de décision que Claude navigue sans contraintes. Une spec ne rend pas Claude plus intelligent. Elle rend le problème plus petit. Tu prends les 20 décisions à l'avance. Claude exécute contre un plan où les décisions sont déjà réglées.

La spec d'abord. Session fraîche. Document vivant. C'est le pattern.

Questions fréquentes

C'est quoi le développement piloté par spec avec Claude Code ?

Le développement piloté par spec est un workflow en quatre phases où tu écris les exigences, le design, et un plan de tâches ordonné avant que Claude écrive une seule ligne de code. La spec retire les 20 décisions environ que Claude prendrait sinon tout seul. Tu les prends à l'avance. Claude exécute contre un plan déjà réglé.

Comment écrire une spec pour Claude Code ?

Lance une session fraîche et demande à Claude de t'interviewer avec l'outil AskUserQuestion jusqu'à ce qu'il ait couvert l'implémentation, l'UX, les cas limites, et les compromis. Quand l'interview est terminée, demande-lui d'écrire la sortie dans SPEC.md. Ferme cette session. La session suivante ouvre la spec et construit. Le transfert entre sessions concentre la plupart de la valeur.

Pourquoi démarrer une session fraîche après avoir écrit une spec ?

Claude porte le raisonnement de la session d'écriture de spec en avant comme hypothèses implicites. Il arrête de lire la spec littéralement et commence à combler les lacunes depuis la mémoire. Une session fraîche le force à lire la spec comme un nouvel ingénieur le ferait : depuis le début, mot pour mot, sans contexte hérité de la conversation précédente.

Que met-on dans un fichier spec Claude Code ?

Une spec minimale a trois parties : les exigences (ce que la fonctionnalité doit faire, écrites comme user stories et critères d'acceptation), le design (modèles de données, contrats API, quels fichiers changent), et les tâches (un plan d'implémentation ordonné où chaque étape liste ses dépendances). Pour les petites fonctionnalités un seul SPEC.md suffit. Les fonctionnalités plus larges utilisent trois fichiers séparés dans un dossier nommé sous .claude/specs/.

Quelle est la différence entre le développement piloté par spec et le vibe coding ?

Le vibe coding, c'est prompter Claude de façon itérative et accepter où que la conversation mène. C'est rapide pour l'exploration mais imprévisible à grande échelle. Le développement piloté par spec met la prise de décision en amont dans un document écrit avant que du code tourne. La spec échange un peu de temps initial contre une grande réduction de rework, de dérive de périmètre, et de perte de contexte entre sessions.

C'est quoi la règle de correction du test dans le développement piloté par spec ?

Sans contrainte écrite, Claude fait parfois passer un test en échec en changeant le test plutôt qu'en corrigeant le code cassé. La règle de correction du test va dans SPEC.md ou CLAUDE.md : toujours trouver la cause racine d'abord, corriger l'application si l'application est fausse, corriger le test seulement si le test lui-même a été mal écrit. Cette seule règle ferme l'un des modes d'échec les plus courants dans les sessions non guidées.