Piloter un agent IA par le spec : guide pratique

Taille de la plume pour l'écriture — planche de l'Encyclopédie de Diderot et d'Alembert

Planche de l’Encyclopédie de Diderot et d’Alembert — Art de l’écriture, par Charles Paillasson. Source : Wikimedia Commons.

/sdd-init

Une commande, et le repo est prêt. On décrit le changement en une phrase, l’agent route vers SDD quand ça vaut le coup, sinon il code en ligne. On valide chaque phase par un mot — continue — et à la fin on a du code testé, un spec figé, et un PR propre. Cet article est le mode d’emploi pratique, du démarrage à froid jusqu’au change livré. Pas de théorie.

Le concept — SDD et OpenSpec

SDD : figer le spec avant le code, surtout avec un agent

Le Spec-Driven Development, c’est une discipline vieille comme l’ingénierie : on fige le quoi (les spécifications) avant d’attaquer le comment (le code). RFC, design docs, cahier des charges — un développeur humain en a toujours tiré profit. Avec un agent IA, ça passe de « profitable » à « critique ».

La raison est mécanique. Un développeur humain face à une instruction floue demande : « tu veux dire X ou Y ? ». Un agent, lui, devine — vite, avec assurance, et à grande échelle. Trois cents lignes plus tard, tu relis du code qui ne correspond pas à ce que tu avais en tête, et le fix coûte un refactor. Le spec n’est pas de la bureaucratie : c’est l’ancrage qui force l’ambiguïté à surgir au moment où la corriger coûte une phrase, pas une refonte.

OpenSpec : le spec comme artefact, pas comme message de chat

OpenSpec est le magasin d’artefacts qui porte cette discipline. Les specs vivent dans openspec/, versionnés avec le code — pas dans l’historique de chat, pas dans un Confluence oublié, pas dans la tête de quelqu’un.

Deux répertoires font tout le système :

openspec/specs/ — la vérité canonique. Ce que le système est aujourd’hui, mergé et courant.
openspec/changes/{change}/ — les deltas proposés. proposal.md, spec.md, design.md, tasks.md y naissent, puis sont archivés une fois mergés.

Pourquoi ça compte : un spec qui vit dans le chat est invisible à la prochaine session, non versionné, invérifiable. Un spec qui vit dans openspec/ est lu par l’agent à chaque session, diffable contre le code, et checkable mécaniquement lors du verify. Le spec devient un artefact de build, pas une conversation oubliée.

Le flow en une phrase

Les phases ci-dessous — explore → proposal → spec → design → tasks → apply → verify → sync → archive — déplacent un change de l’idée jusqu’au spec canonique mergé + code livré. Chaque phase produit un artefact à relire. L’humain valide chaque transition.

explore → proposal → spec → design → tasks → apply → verify → sync → archive

Chaque phase écrit un fichier. On le lit, on approuve, on avance. Le fix le moins cher se fait à proposal, pas à apply.

1. Quand utiliser SDD — et quand faire l’impasse

La règle : si le changement est petit + clair + local, on le fait en ligne. SDD est de la cérémonie anti-chaos, pas une taxe sur tout.

Utiliser SDD	Faire en ligne (inline)
Nouvelle feature, multi-fichiers	Coquille, rename
Requirements flous	Bug connu, localisation claire
Changement d’architecture	Édit mécanique sur un fichier
Refactor transverse	`git status` / check d’état rapide
L’utilisateur dit « use SDD » / `/sdd-*`	Lecture de 1–3 fichiers pour vérifier

Le seuil de déclenchement est brutal et volontaire : au-delà de ~400 lignes de diff ou sur un hot path (auth/, security/, update/, payments/), on bascule en SDD + revue forcée. En dessous, on code.

2. Initialisation — une fois par projet

Dans le repo :

/sdd-init

Ça crée openspec/config.yaml. La même commande déclenche le preflight de session : on choisit le mode de store (interactif / OpenSpec / auto), la stratégie de chaînage des PR, et le budget de lignes (par défaut 400). Ces choix sont mémorisés pour la session.

Vérifier l’état à tout moment :

/gentle:status    # snapshot assets + config
/gentle:doctor    # diagnostics en lecture seule

3. Démarrer un change — deux portes d’entrée

En langage naturel (el Gentleman décide si SDD est justifié) :

« Je veux ajouter X au projet. Ça doit faire Y, pas Z. »

Si c’est substantiel, le preflight tourne et SDD démarre tout seul.

Explicite (forcer SDD quelle que soit la taille) :

/sdd-new <change-name>

Ou simplement : « use SDD for this. »

4. Le flow, concrètement

Chaque phase écrit un fichier. On le lit, on dit continue (ou dale, go on) pour passer à la suivante. En mode interactif, l’agent s’arrête à la fin de chaque phase — jamais d’auto-advance sans oui explicite.

explore      →  mappe le problème (pas d'artefact à relire, juste du contexte)
   ↓
proposal     →  openspec/changes/{change}/proposal.md         ← on lit
   ↓  (continue)
spec         →  openspec/changes/{change}/specs/.../spec.md   ← on lit
   ↓
design       →  design.md                                     ← on lit
   ↓
tasks        →  tasks.md   (forecast diff → peut suggérer une chaîne) ← on lit
   ↓
apply        →  écrit le code + apply-progress.md (preuves TDD RED→GREEN)
   ↓
verify       →  verify-report.md   (check contre le spec)
   ↓
sync         →  merge les deltas dans openspec/specs/   (canonique)
   ↓
archive      →  déplace le change vers openspec/changes/archive/YYYY-MM-DD-{change}/

Comment piloter chaque phase

Phase	Ce qu’on fait
`explore`	Rien — l’agent mappe la zone, pose des questions si besoin.
`proposal`	On lit. On checke les non-goals et les acceptance criteria. Endroit le moins cher pour corriger le cap.
`spec`	On lit les scénarios. « Si X alors Y » — un cas manquant est un bug futur, gratuit maintenant, cher plus tard.
`design`	On lit les décisions. On pousse sur tout ce qui sent le sur-engineering (le mode ponytail aide ici).
`tasks`	On valide le plan + le forecast de taille. Si > 400 lignes, on choisit la stratégie de chaîne ou on accepte un PR unique.
`apply`	L’agent implémente + lance les tests. Les preuves TDD doivent apparaître dans `apply-progress.md`.
`verify`	On lit le rapport. Ça matche le spec ? Non → retour à `apply`.
`sync` + `archive`	Généralement automatiques une fois vérifié.

5. Livrer

Après un verify qui passe :

"open a PR"   ou   /branch-pr

branch-pr impose l’issue-first : il faut une issue status:approved liée et un label type:*.
Si diff > 400 ou touche auth/ / security/ / update/ / payments/ → blocage dur jusqu’à ce que la revue 4R tourne (review-risk + review-resilience + review-readability + review-reliability).
Sous 400, chemin propre → PR unique.

Pour les changes surdimensionnés, le skill chained-pr découpe en PRs empilés (selon le choix auto-forecast de la session).

6. Cheat sheet du quotidien

/sdd-init                 # une fois par projet
/gentle:sdd-preflight     # change les choix de session (store, chaîne, budget)
/gentle:status            # où en suis-je, qu'est-ce qui est installé
/gentle:doctor            # diagnostics
/gentle:models            # assigne modèle + thinking par agent SDD
/gentle:persona           # gentleman ↔ neutral
/sdd-status               # état du change courant (lecture seule)

Reprendre un change en pause à la session suivante :

/sdd-continue

7. Walkthrough concret

On veut : « Add a backup-health check to the NAS dashboard. »

Dans le repo : /sdd-init (une fois).
On dit : « SDD: add backup-health check to dashboard. »
L’agent lance explore → proposal (écrit proposal.md). Il s’arrête.
On lit, on dit continue.
spec → design → tasks. On approuve chaque étape. À tasks, forecast ~180 lignes → PR unique.
apply : l’agent écrit le code + les tests, colle les preuves RED→GREEN dans apply-progress.md.
verify : le rapport confirme que ça matche le spec.
sync : le spec est mergé dans openspec/specs/backup/spec.md. archive.
On dit « open PR » → branch-pr → revue → merge.

TL;DR — les 3 choses à retenir

/sdd-init une fois par projet, puis on décrit le changement naturellement — l’agent route vers SDD quand ça vaut le coup.
On gère chaque phase. On lit l’artefact, on dit continue pour avancer, on pousse pour rediriger. Le fix le moins cher est à proposal.
Budget = 400 lignes. Au-delà (ou sur un hot path), ça chaîne et ça force la revue 4R. L’auto-forecast n’interrompt que quand splitter compte vraiment.