Écrire une spec qui décuple Claude Code en 2026

En 2026, le bottleneck n'est plus le code. C'est la clarté. Tu peux avoir Claude Opus 4.7 entre les mains : si ta spec ressemble à un nuage, tu vas obtenir du nuage. C'est exactement ce que je vois chez 80% des founders accompagnés : ils se plaignent que "Claude Code a pas compris", alors qu'en relisant leur prompt, moi non plus je n'aurais pas compris.

Si tu n'es pas encore sûr de l'idée à spec, commence par valider une idée de SaaS rentable en 7 jours. Une spec impeccable sur une mauvaise idée, c'est juste perdre du temps plus efficacement.

Spec ou prompt : quelle est la différence pour Claude Code ?

Un prompt est une demande ad hoc d'1 à 5 lignes pour une modification isolée. Une spec est un document structuré de 25 à 50 lignes qui décrit une feature complète, ses contraintes, ses cas limites et ses critères de succès. Dès qu'une feature touche plus de 3 fichiers, il faut une spec. Sans elle, Claude Code va deviner, et 70% du temps il devine mal.

Pour décider quoi utiliser, regarde le scope. Le tableau ci-dessous résume les 4 formats que tu vas croiser et quand chacun est pertinent :

Voici le contraste concret. D'abord le prompt vague qu'on voit chez 80% des founders. Ensuite la spec courte (30 lignes) qui donne le bon résultat sur la même feature.

Prompt vague, 80% des cas

Ajoute un système de relance
d'impayés WhatsApp avec
templates personnalisables,
opt-out, etc.

→ Claude devine.
→ 4h d'allers-retours.
→ Code à jeter à 60%.

Spec structurée, 30 lignes (11 fichiers livrés en 1h32)

# Objectif
Relancer auto J+3, J+7, J+14
les factures impayées via WhatsApp.

# Contexte technique
WhatsApp Business API, table invoices.

# Critères d'acceptation
1. Un seul message par stade
2. Stop si payé entre temps
3. Log de tous les envois

# Out of scope
- Templates personnalisés (V2)
- A/B test (V2)

L'anatomie d'une spec Claude Code en 7 sections

Une spec efficace tient en 7 sections : objectif, user story, contexte technique, critères d'acceptation, edge cases, out of scope, definition of done. Chacune fait maximum 1 paragraphe, sauf la 4 qui peut être plus longue. Le but est d'orchestrer plutôt que coder : décrire l'intention, pas l'implémentation.

1. Objectif — 1 phrase. Verbe + sujet + bénéfice mesurable.
2. User story — En tant que [persona], je veux [action], pour que [bénéfice].
3. Contexte technique — Stack, fichiers concernés, dépendances. 5 lignes max.
4. Critères d'acceptation — Liste numérotée, chaque item testable, chaque item commençant par un verbe.
5. Edge cases — 3-5 cas limites précis, avec le comportement attendu.
6. Out of scope — Ce qu'on ne fait PAS dans cette feature.
7. Definition of done — Checklist finale : tests, déploiement, doc.

Et concrètement, voilà le template à copier-coller dans ton SPEC.md :

# SPEC — [Nom de la feature]

## 1. Objectif (1 phrase)
Ce qu'on veut résoudre. Verbe + sujet + bénéfice mesurable.

## 2. User story
En tant que [persona], je veux [action], pour que [bénéfice].

## 3. Contexte technique
Stack, fichiers concernés, dépendances. Pas plus de 5 lignes.

## 4. Critères d'acceptation
Liste numérotée, chaque item testable, chaque item commençant par un verbe.

## 5. Edge cases
3-5 cas limites précis, avec le comportement attendu.

## 6. Out of scope
Ce qu'on ne fait PAS dans cette feature.

## 7. Definition of done
Checklist finale. Tests, déploiement, doc.

C'est tout. Pas plus. Au-delà de cette structure, tu over-spécifies et tu perds Claude Code dans le bruit.

Exemple complet : relances d'impayés WhatsApp en 30 lignes

Voici la spec exacte que j'ai donnée à Claude Code la semaine dernière. Résultat : 11 fichiers fonctionnels livrés en 1h30, sur la stack qu'on utilise chez WhatSetter. La section "Out of scope" est ce qui empêche Claude de partir construire un onboarding qui évite 70% du churn alors qu'on lui demande juste des relances.

# SPEC — Relance d'impayés via WhatsApp

## 1. Objectif
Permettre à un coach WhatSetter de déclencher une séquence
de 3 relances WhatsApp automatiques à un client en retard
de paiement, en respectant le ton de la marque.

## 2. User story
En tant que coach, je veux qu'à J+3 / J+7 / J+14 d'impayé,
WhatSetter envoie automatiquement 3 messages WhatsApp
personnalisés, pour que je récupère 60% des impayés sans
intervention manuelle.

## 3. Contexte technique
- Stack : Next.js 15, Appwrite, orchestrateur de workflows
- Fichiers à toucher : `app/api/dunning/`, `lib/whatsapp.ts`,
  collection Appwrite `invoices`, workflow `dunning-flow`
- Déjà en place : webhook Stripe sur invoice.payment_failed

## 4. Critères d'acceptation
1. Quand Stripe envoie un webhook payment_failed, créer
   une row dans `dunning_sequences` avec `status=scheduled`.
2. Un cron d'orchestration s'exécute toutes les heures et traite les
   séquences arrivées à échéance.
3. Les messages utilisent les templates dans `lib/templates/dunning/`
   (3 templates : dunning_3d, dunning_7d, dunning_14d).
4. Si le paiement est régularisé (webhook payment_succeeded),
   la séquence passe à `status=cancelled` et plus aucun
   message n'est envoyé.
5. Tous les envois sont loggés dans `dunning_logs`.

## 5. Edge cases
- Numéro WhatsApp invalide → log error, mark `status=failed`.
- Coach pas en plan Pro → abort la séquence, envoyer un email
  d'alerte au coach.
- Plus de 3 séquences en parallèle pour le même client →
  ignorer (dedup par client_id).

## 6. Out of scope
- Pas de relance email (autre feature).
- Pas de gestion du recouvrement légal > J+14.
- Pas de personnalisation du contenu via IA pour le moment
  (templates fixes en V1).

## 7. Definition of done
- [ ] Tests unitaires sur la logique de scheduling
- [ ] Test e2e sur 1 séquence complète en staging
- [ ] Documentation dans `/docs/features/dunning.md`
- [ ] Déployé en staging, validé sur 3 cas réels
- [ ] PR ouverte et mergée sur `main`

Cette spec fait 30 lignes. Claude Code l'a lue, a posé 2 questions de clarification, puis a livré l'implémentation complète en 1h30. Sans ça, j'aurais passé 4-5 heures en allers-retours.

Les 5 erreurs qui ruinent une spec (et comment les éviter)

Sur les 200+ specs que j'ai vues passer via VibesMoney, ce sont les 5 erreurs récurrentes, celles qui transforment Claude Code de turbo en mou. Apprends à les repérer et tu doubles ton ratio "ce qu'il livre / ce que tu voulais" du jour au lendemain.

1. Le "etc." caché

"Ajoute un système d'authentification avec login, signup, reset password, etc." Le "etc." est un trou noir. Claude va combler avec ce qu'il pense, et tu vas découvrir 3 jours plus tard qu'il a mis une 2FA dont tu ne voulais pas. Pas d'etc. Liste tout, ou marque "out of scope".

2. Demander 3 features en une

Une spec = une feature. Si tu veux ajouter le login + le profil user + la migration DB, fais 3 specs. Claude Code fait beaucoup mieux quand le scope est étroit.

3. Décrire le "comment" plutôt que le "quoi"

Erreur de junior : "Crée un fichier auth.ts qui exporte une fonction login() avec ces 14 paramètres précis…". Tu es en train de coder à sa place. Décris l'intention, pas l'implémentation. Claude Code choisit mieux que toi pour 80% des décisions techniques.

4. Pas de critères d'acceptation testables

"Le système doit être fiable" → impossible à valider. "Le système doit gérer 1000 req/sec sans erreur" → testable. Toujours mesurable.

5. Pas d'out of scope

Le piège classique : Claude Code, par excès de zèle, ajoute des features que tu ne lui as pas demandées. La section "Out of scope" l'empêche de divaguer. Toujours la remplir.

Cycle d'itération : 30 minutes de spec = 4 heures gagnées

Le ratio est constant : 30 minutes investies en amont, 4 heures économisées sur l'implémentation. Sur 12 semaines de build, c'est littéralement des semaines récupérées. Plus la feature touche de fichiers, plus l'écart se creuse — c'est là que la spec rapporte le plus.

Voici le workflow type qu'on enseigne dans le programme VibesMoney.

1. Brouillon spec — 15 min. Tu écris la spec à la main, en mode "vraiment ce que je veux", sans filtre.
2. Review IA — 5 min. Tu donnes la spec à Claude en mode chat avec : "Critique cette spec. Ambigus ? Edge cases manquants ?" Tu récupères 5-10 questions.
3. Itération — 10 min. Tu intègres les retours. La spec passe de "à peu près" à "exécutable".
4. Lancement Claude Code — 2 min. Tu pointes vers SPEC.md avec : "Implémente cette spec, propose un plan d'attaque avant de toucher au code".
5. Validation du plan. Claude répond avec un plan en 5-10 étapes. Tu valides ou ajustes, c'est là que tu rattrapes les dernières ambiguïtés.
6. Implémentation supervisée. Tu surveilles, tu review chaque diff, tu testes en local avant merge. La feature est shippée.

Une fois la feature livrée, prochaine question : combien tu la fais payer ? On a couvert ça dans comment pricer la feature que Claude Code vient de livrer, incluant le piège du free trial qui tue 60% des conversions.

CLAUDE.md : le meta-spec qui vit dans ton repo

CLAUDE.md est un fichier à la racine du repo, lu automatiquement par Claude Code à chaque session. Il contient le stack, les conventions de code, les règles métier non-évidentes, les commandes courantes et les pièges connus. Il sert de meta-spec : il rend chaque spec feature 30% plus courte, parce que tu n'as pas à répéter le contexte à chaque fois.

• Ton stack technique (versions, patterns)
• Tes conventions de code (naming, structure de dossiers)
• Tes règles métier non-évidentes
• Les commandes courantes (test, build, deploy)
• Les pièges connus du projet

Concrètement : si tu installes CLAUDE.md dès le jour 1 d'un projet, tu n'auras plus jamais à expliquer à Claude que tu utilises Next.js 15 App Router, que tes routes API sont en app/api/*/route.ts, et que ton ESLint impose des semicolons. Une fois pour toutes.

La spec, skill #1 du founder solo en 2026

Écrire de bonnes specs, c'est devenu la skill #1 du founder solo en 2026. Plus que d'écrire du code. Plus que d'utiliser tel ou tel outil. Si tu maîtrises la spec, n'importe quel agent IA devient 10× plus efficace.

Le moyen le plus rapide de s'améliorer : écris la spec, lance Claude Code, mesure le ratio "ce qu'il a fait" vs "ce que tu voulais". Plus le ratio est haut, meilleure était ta spec. Itère.

Pour aller plus loin : la méthode complète en 12 semaines avec Claude Code, où la spec est l'étape 1 de chaque feature.