La couche manquante : le spec-as-source a besoin d'un steward

Un développeur livre une feature un vendredi après-midi. Le code marche. Les tests passent. La PR est approuvée.

Et la spec — le document qui dit ce que le système est censé faire — décrit encore le comportement de la semaine dernière. Personne ne le remarque pendant trois sprints.

C'est l'échec silencieux de tous les systèmes de specs que j'ai vus. Les specs guident l'implémentation initiale, puis le code se met à évoluer plus vite que la documentation, et la spec devient un mensonge bien présenté. Avec des agents IA qui écrivent une part croissante du code, l'écart se creuse plus vite que jamais.

J'y ai passé cinq jours — et un nombre de tokens franchement gênant. Voici la version honnête de ce parcours : les faux départs, les impasses, et l'idée sur laquelle j'ai atterri et qui, je crois, compte vraiment.

Tout est parti de ce qui ressemblait à une percée. Si les specs sont la source de vérité, il devrait exister un moyen de détecter quand le code s'en écarte. Une détection de drift bidirectionnelle — pas seulement des specs qui pilotent le code, mais des changements de code qui signalent les specs à mettre à jour. Le concept était séduisant, et quand je l'ai décrit à des collègues, ils ont compris instantanément.

L'idée ressemblait à ça : utiliser l'historique git pour relier les commits aux changements de code, puis relier ces commits à une ou plusieurs specs. Élégant sur un tableau blanc. Puis j'ai essayé de l'implémenter, et le vrai problème est apparu.

Comment relier du code à des specs ? Une spec couvre plusieurs fichiers. Un fichier est touché par plusieurs specs. Cette relation many-to-many était le point de rupture. Chaque solution que j'esquissais réclamait un fichier de mapping — un specs/mapping.yaml — qu'il faudrait maintenir. Par les développeurs. À la main.

Je demandais aux développeurs de maintenir un second index de leur propre codebase. Personne ne le ferait. Et si personne ne le maintient, la détection de drift devient une production de drift : un fichier périmé de plus dans le repo.

Mon premier vrai enseignement a donc été négatif. Je m'écartais moi-même des specs, en recopiant le modèle de données de git au lieu de résoudre le problème de gouvernance. L'idée était bonne. L'implémentation était une impasse.

Puis ça m'a frappé, et j'avoue que c'était presque gênant tant c'était évident avec le recul.

Le mapping entre les specs et le code existe déjà. Ça s'appelle la suite de tests.

BDD, TDD, Gherkin — ces traditions résolvent le même problème depuis des années. Un test est une assertion lisible par une machine qui vérifie qu'une exigence de la spec tient. Le mapping est inscrit dans la structure : un scénario Given/When/Then dans un fichier de spec correspond à un cas de test dans la codebase. Pas besoin d'un index séparé. Il faut une convention.

Voici où j'ai atterri. Prends les identifiants d'exigence de la spec (disons REQ-005-07) et mets les mêmes identifiants en commentaire au-dessus des tests correspondants. C'est tout. La spec dit ce que le système doit faire. Le test prouve qu'il le fait. L'identifiant les relie. Pas de fichier de mapping. Pas de YAML. Aucune charge de maintenance supplémentaire.

À partir de là, une couche d'application basique — que j'ai commencé à appeler Drift Guard — se met naturellement en place. Une exigence de spec sans test correspondant bloque le commit. Un test sans identifiant d'exigence bloque. Un changement de code qui touche des fichiers liés à une exigence sans mettre à jour le changelog est signalé. L'outillage est familier : hooks de pre-commit, linters, checks de CI. Rien d'exotique.

Mais j'ai alors heurté le mur suivant. Les tests unitaires correspondent à de petits détails d'implémentation. Les tests end-to-end correspondent à des comportements produit. Une spec qui marche pour les parties prenantes — lisible, objectifs de haut niveau — est inutilisable pour un linter. Une spec qui marche pour un linter — identifiants structurés, contraintes parsables par une machine — est illisible pour un product owner.

Il faut une spec hybride. Et c'est là que ça devient vraiment difficile.

J'ai fait une pause. J'ai parlé à des gens. J'ai lu ce qui avait déjà été fait. Et j'ai réalisé que je pensais les specs comme un artefact unique, alors qu'en réalité elles couvrent tout le cycle de développement — d'une vision produit floue jusqu'à une assertion à la ligne près.

Une spec répond à trois questions, et chacune s'adresse à un public différent, à une étape différente.

Pourquoi — l'objectif business, le besoin utilisateur, la raison de construire. Territoire du product owner : PRD, parcours utilisateurs, critères de succès. Ça se fige après validation et change rarement.

Quoi — les exigences fonctionnelles, les scénarios d'acceptation, les contrats d'API. Territoire du développeur : markdown structuré avec Given/When/Then, identifiants d'exigence, schémas de données. Ça évolue avec le code.

Comment — les garde-fous d'implémentation, les changelogs, les métadonnées de mapping. Territoire du système : suivi automatique, éphémère, lisible par une machine. Ça change à chaque commit.

Et les specs sont partout. Ce ne sont pas seulement tes fichiers 005-ideation-brief.md — ceux-là n'en sont que la forme la plus visible. Une spec, c'est tout artefact qui capture une décision que le code doit respecter.

Une fois cela vu, j'ai creusé le paysage existant — BMAD Method, Kiro, OpenSpec, GitHub Spec Kit. Ce que j'y ai trouvé était éclairant, et frustrant. Deux catégories distinctes existent, et elles sont presque totalement orthogonales.

Les frameworks SDD — Spec Kit, OpenSpec, Kiro, Tessl — répondent à « comment écrire et maintenir des specs qui pilotent le code ? » Ils traitent de rédaction, de format et de workflow. La spec est le produit. OpenSpec offre une itération par deltas et le support du brownfield. Tessl pousse vers le spec-as-source complet, où le code est généré et jamais édité à la main. Spec Kit fournit des workflows par phases avec des points de contrôle. Ils sont tous utiles. Aucun ne résout ce qui se passe après l'écriture de la spec, quand le code se met à évoluer.

Les frameworks agentiques — BMAD, Xebia ACE — répondent à « comment organiser des agents IA pour simuler une équipe de dev ? » Ils traitent d'orchestration, de rôles et de process. BMAD propose des personas spécialisés qui se passent des artefacts structurés. ACE embarque l'IA sur tout le cycle de vie. Ils produisent des specs comme artefacts, mais ne gouvernent pas leur intégrité dans le temps.

L'article fondateur sur le SDD publié sur arXiv (Piskala et al., 2026) pose trois niveaux de rigueur : spec-first, spec-anchored, spec-as-source. L'analyse de Birgitta Böckeler sur le blog de Martin Fowler décrit le même gradient en comparant Kiro, Spec Kit et Tessl côte à côte. Mais même au niveau le plus ambitieux, aucun des outils existants ne répond à la question qui a lancé tout ce parcours : quand le code et la spec divergent, qui le voit ?

BMAD produit des specs mais ne les surveille pas après l'implémentation. OpenSpec archive des deltas mais ne vérifie pas si le delta correspond au diff réel.

La pièce manquante n'est pas un outil. C'est une couche.

Voici où j'ai fini, et ce n'est pas là où je m'attendais à arriver.

Le problème n'est pas qu'il nous manque des frameworks pour écrire des specs — il y en a plein. Ce n'est pas non plus qu'il nous manque des frameworks pour orchestrer des agents — ils existent aussi. Le problème, c'est que personne ne gouverne la spec sur tout le cycle de vie : build, deploy, run.

Chaque phase a ses rôles. Les product owners écrivent le pourquoi. Les développeurs écrivent le quoi. Les systèmes de CI suivent le comment. Mais aucun rôle unique, humain ou automatisé, ne porte la question qui les relie tous :

Le système fait-il ce dont nous étions convenus, et pouvons-nous le prouver ?

À chaque commit, chaque merge, chaque deploy et chaque incident, la réponse devrait être oui — sinon ça bloque. C'est la fonction que j'appelle le Spec Steward : un rôle de gouvernance qui couvre les trois phases, s'assure que les règles sont appliquées, collecte les retours du processus de collaboration, et utilise l'IA générative pour faciliter ce qui ne demande pas de jugement humain.

Benoît Lamouche décrit un profil de « Spec Curator » proche dans son analyse des rôles émergents à l'ère de l'IA — quelqu'un qui structure et gouverne un savoir réutilisable d'un projet à l'autre. Je pousse l'idée plus loin. Le Steward ne se contente pas de curer les specs comme des artefacts. Il les fait respecter comme des contrats vivants sur tout le cycle de vie.

Le Drift Guard est l'outillage qui rend le travail du Steward possible. Ce n'est pas un outil, c'est une couche. Des hooks de pre-commit qui vérifient la couverture des identifiants d'exigence. Des jobs de CI qui donnent les diffs et les specs à un LLM pour validation sémantique. Des skills développeur à la demande qui proposent des entrées de changelog. Chaque couche a un déclencheur différent, un poids de décision différent — bloquer, avertir, suggérer — et un public différent.

Le cycle de vie a été conçu pour des humains. Nous sommes désormais dans quelque chose qui ressemble davantage à un cycle augmenté par les agents, où des agents IA écrivent du code, proposent des specs, lancent des revues et itèrent en autonomie. Kief Morris, sur le blog de Martin Fowler, présente ce basculement comme le passage de humans in the loop à humans on the loop : au lieu d'inspecter chaque ligne de code, on construit et on maintient le harnais qui façonne ce que les agents produisent. Le Spec Steward est le rôle qui porte ce harnais pour la gouvernance des specs.

Le Steward ne remplace ni le product owner, ni le développeur, ni l'ingénieur QA. Il se place en travers de tous, et fait le travail qu'aucun d'eux ne peut faire seul : garder la spec vivante, comme un contrat opposable.

Ce que je ne construis pas, c'est un énième framework SDD ou un énième orchestrateur agentique. Tout existe déjà. Mais la colle entre « gouverner les specs » et « orchestrer les agents », elle, n'existe pas.

Pas une nouvelle façon d'écrire des specs — Tessl, OpenSpec et Spec Kit s'en chargent. Pas une nouvelle façon de faire tourner des agents — BMAD et ACE s'en chargent. La couche de validation et d'application qui les complète. Un système qui collecte les retours du processus de collaboration, s'assure que les règles sont bien appliquées, et utilise l'IA générative pour ce qui ne demande pas de jugement humain.

Les conventions de rédaction, c'est ce que les frameworks SDD résolvent déjà. L'orchestration, c'est ce que les frameworks agentiques résolvent déjà. Ce qui reste, c'est la gouvernance : prouver, à chaque point de contrôle, que le système fait ce dont nous étions convenus.

C'est un problème plus petit que construire un framework entier. Mais c'est peut-être celui qui compte vraiment.

Cet article est né de notes de réflexion prises lors de sessions de brainstorming avec Claude, via une skill /thought maison qui synthétise les réponses surprenantes du modèle en fichiers granulaires. Discussion, plan, revue — chaque phase confiée à un agent différent. Cela reflète le workflow que je cherche à gouverner. L'ironie ne m'échappe pas.