5 règles pour arrêter de faire pourrir vos specs IA

Superpowers est un plugin Claude Code (286 000 étoiles GitHub) dont les skills écrivent des specs et des plans d'implémentation sous forme de fichiers markdown et les commitent dans le dépôt. Par défaut, chacun de ces fichiers atterrit dans un seul dossier, docs/superpowers/. En juin, les mainteneurs d'Okama, une librairie Python de finance, ont découvert que huit plans d'implémentation écrits là par un agent, commités exactement comme le plugin le prévoit, avaient été rendus en pages web publiques sur Read the Docs. Ils l'ont remarqué après la publication.

Maintenant, changez d'échelle : une équipe front-end de dix développeurs, quatre squads, un seul dépôt, et chaque développeur qui génère ces fichiers. Trois questions atterrissent sur le bureau du lead. Que versionne-t-on exactement ? Le drift est-il un problème quand une spec cite un chemin supprimé deux sprints plus tôt ? Et qui gouverne le dossier ? La fuite d'Okama n'a pas été causée par le fait de commiter. Elle a été causée par le fait de commiter sans règle. Cet article vous en donne cinq.

Superpowers ne demande jamais s'il faut commiter. La ligne 18 de son skill de planning sauvegarde chaque plan sous docs/superpowers/plans/, daté, un fichier par feature. Le skill de brainstorming écrit le document de design et le commite dans la même étape, avant même que vous ayez vu le plan.

Ce n'est pas une bizarrerie de Superpowers. Tous les grands outils spec-driven font le même choix :

Tool	Publisher	Where specs live
Superpowers (286 000 étoiles)	obra	docs/superpowers/, un seul dossier pour tout
Spec Kit (136 000 étoiles)	GitHub	un dossier numéroté par feature, sur la branche de cette feature
Kiro	Amazon	.kiro/specs/, un dossier par feature
AI-native SDLC playbook	Anthropic	un artefact commité par étape : intent, spec, plan, diff, review findings, incident record

Kiro vend les dossiers par feature comme un moyen pour les équipiers de collaborer sur des features différentes en même temps. Le playbook d'Anthropic, publié en août, va plus loin : chaque étape commite un artefact que l'étape suivante peut lire. Donc la question n'a jamais été de savoir s'il faut commiter, et où est répondu par tous les outils. Qui possède le fichier, et quand il est mort, ne le sont pas. C'est cet écart que couvrent les cinq règles.

Les plans commités échouent de trois façons distinctes.

Échec 1 : le générateur de docs. Un build de documentation qui rend tout fichier markdown sous docs/, qu'une table des matières le liste ou non, expédie le dossier des plans avec le manuel. C'est exactement ce qui est arrivé à Okama.

Échec 2 : la branche. L'issue 1246 de Superpowers rapporte que le brainstorm commite le plan directement sur main. Un utilisateur compte 10 à 15 commits par session, un nouveau toutes les quelques modifications. La demande du thread tient en une ligne : pas de plans et de specs sur la branche main.

Échec 3 : le drift. Le spec drift est l'échec silencieux : le code évolue et la spec non. Birgitta Böckeler, chez Thoughtworks, nomme trois niveaux de spec-driven development :

Level	Meaning
Spec-first	Écrite, utilisée une fois
Spec-anchored	Conservée et maintenue pendant toute la vie de la feature
Spec-as-source	L'humain n'édite plus jamais que la spec

Superpowers écrit des documents spec-first et les garde pour toujours. Par défaut, vous obtenez donc un stockage spec-anchored avec une maintenance de premier jet : personne ne met à jour le fichier, et un agent le lit le trimestre suivant comme s'il était vrai. TrueFoundry le dit sans détour : le drift est inévitable en pratique spec-first et gérable en pratique spec-anchored, mais seulement si la divergence est détectable.

Un dépôt qui contient 41 specs et 9 fichiers d'agents n'a pas un problème de rangement. Il a 41 entrées de comportement non versionnées. La réaction de Böckeler elle-même : elle préférerait relire du code que tous ces fichiers markdown. Un plan que personne ne recharge jamais est un déchet. Un plan qu'un agent recharge est une instruction, et une instruction obsolète est une instruction fausse.

Règle 1 : le dossier a un propriétaire, et le propriétaire est un squad, pas le plugin. Depuis la version 5, Superpowers respecte les instructions du CLAUDE.md de votre projet plutôt que ses propres valeurs par défaut. Dites où vont les plans, et ils y vont.

Un tableau de chemins ne suffit pas, cependant. Dans l'issue 939, un utilisateur avait écrit un tableau des chemins de sortie, et le modèle a suivi le chemin concret présent dans le skill en ignorant le tableau. La note de dérogation du skill lui-même n'est qu'une parenthèse. Une seule ligne, en gras et à l'impératif, a corrigé le problème du premier coup : les specs doivent être sauvegardées ici, pas là, avec le chemin par défaut nommé comme ce qu'il faut éviter.

L'agencement, c'est un dossier par squad (checkout, search, accounts, design-system), chacun avec ses propres specs et plans. Dans un monorepo, mettez la ligne dans le CLAUDE.md propre au package. Claude Code charge le fichier d'un sous-dossier à la demande, quand il y lit, et la documentation dit que le propriétaire de chaque dossier maintient généralement son fichier. Les ingénieurs qui n'ont jamais installé le plugin ne sont pas affectés : la ligne ne se déclenche que quand un skill demande où sauvegarder.

Ensuite, laissez la plateforme faire respecter la propriété. Une ligne CODEOWNERS par dossier de squad, et chaque review de spec atterrit chez les gens qui devront vivre avec. Une mise en garde : la dérogation est un prompt, pas un paramètre. Vérifiez la première spec après chaque sortie du plugin.

Règle 2 : tous les plans ne sont pas des artefacts d'équipe. La première personne à avoir demandé à Superpowers un emplacement configurable (issue 337) l'a dit le mieux : les fichiers de plan peuvent être des documents de travail personnels plutôt que des artefacts de projet.

Le côté personnel a un fichier fait pour ça. CLAUDE.local.md se place à côté du fichier partagé, se charge après lui, et la documentation vous dit de le git-ignorer vous-même. Votre redirection vers un dossier privé vit là, et personne d'autre ne la voit. Pour le dossier lui-même, Git a un fichier d'exclusion qui ne touche jamais l'arbre partagé : .git/info/exclude est propre à chaque clone, jamais commité, et ne nécessite aucune pull request. Le plugin fait déjà ça pour son propre espace de brouillon : depuis la version 6.0.3, son dossier de travail dépose un .gitignore contenant * en son propre sein, donc il s'auto-ignore sans toucher à un fichier suivi.

Le côté partagé, c'est tout ce qui a passé la porte de review que le brainstorm exécute déjà : spec écrite, review demandée, approuvée par une deuxième personne. Approuvé, ça part dans le dossier du squad. Pas approuvé, ça reste local. Les deux sont écrits sur une branche, jamais sur main. Deux lignes dans le CLAUDE.md partagé suffisent : traiter les specs et les plans comme le point de départ d'une feature, et créer le worktree avant de les écrire.

Une limite : un plan git-ignoré ne voyage pas. Les mainteneurs d'Okama ont d'abord essayé d'ignorer le dossier, puis ont fait marche arrière, parce que les plans ne se synchronisaient plus entre machines et entre agents. Perso veut dire perso.

Règle 3 : une spec a un statut, et une spec morte le dit. L'idée a 15 ans. Michael Nygard, en 2011, a proposé de garder les architecture decision records (ADR) dans le dépôt, un fichier numéroté chacun. Une décision est proposée, puis acceptée. Quand un enregistrement ultérieur la modifie, l'ancien est marqué deprecated ou superseded, avec une référence vers son remplaçant. Si une décision est annulée, l'ancien enregistrement est conservé mais marqué superseded.

Appliqué aux specs, chaque spec partagée s'ouvre sur un en-tête de cinq lignes que l'agent lit déjà :

Field	Purpose
status	proposed, accepted, superseded
superseded-by	la spec qui la remplace
owner	le squad
touches	les chemins sur lesquels la spec fait des affirmations
review date	la dernière date de vérification

Ne jamais éditer une spec accepted pour en faire une décision différente. Écrivez la suivante, faites-la pointer vers l'ancienne, et l'historique reste honnête. Une exception, énoncée dans le playbook d'Anthropic : quand l'implémentation s'écarte du plan, mettez à jour le plan dans le même commit. Le plan voyage avec le diff qui l'a rendu faux, et un hook peut l'imposer.

Spec Kit nomme trois façons dont une spec peut vivre. Flow-forward : un nouveau dossier par feature, les anciens conservés comme historique. Living spec : la spec est le contrat, et le reste se régénère. Flow-back : le build reformule la spec. Leur règle : ne jamais laisser un changement dans les tasks ou le code si la spec dit encore autre chose. C'est choisir spec-anchored délibérément.

La limite : un statut est une métadonnée qu'un humain fixe. L'agent ne marquera pas sa propre spec superseded à moins que votre CLAUDE.md ne le lui dise, et même alors, la review doit s'en rendre compte.

Règle 4 : une spec qui ment sur l'arbre fait échouer le build. Le papier qui a nommé le problème, publié en juin, l'appelle silent spec-code drift : le code évolue, la spécification non, et la divergence reste invisible jusqu'à ce qu'elle coûte cher à réparer. Sa réponse est un drift gate, une condition de merge bloquante.

Le check est plus petit qu'il n'y paraît. Pour chaque spec dont l'en-tête dit accepted, extrayez les chemins qu'elle cite, entre backticks ou dans la ligne touches, et testez que chacun existe. Chemin manquant, build en échec, avec le nom de la spec dans le log. Les fichiers superseded et proposed sont ignorés : seules les specs accepted font des affirmations sur l'arbre, donc seules les specs accepted sont vérifiées. TrueFoundry présente ça comme un diff planifié plutôt qu'une archéologie post-incident : une spec est un échafaudage, et un changement de spec est un changement de politique.

Les gens font déjà la version manuelle. Un commentateur fait comparer par Claude les fichiers de specs au code, et ouvre des tickets pour ce qui manque. Le script fait ça sur chaque pull request, gratuitement.

Le second garde-fou est celui qu'Okama a livré : exclure le dossier du build de docs. Une ligne dans la configuration Sphinx garde les fichiers dans Git, mais hors du HTML.

La limite : un check de chemins attrape les fichiers supprimés, pas les comportements changés. Une spec peut nommer chaque fichier existant et décrire quand même une API qui a disparu. C'est le rôle de la review et de la règle du même commit.

Règle 5 : la plupart du travail ne mérite pas de spec. Les preuves sur le coût du spec-driven sont cohérentes :

Experiment	Result
Marmelab, Spec Kit sur une feature qui affiche la date du jour	8 fichiers, 1 300 lignes de texte de spécification
Bake-off OpenSpec, mêmes besoins avec un outil de spec vs Claude Code seul	50 % de code en plus, 50 % de complexité cyclomatique en plus, deux fois plus long, trois fois plus cher
Une équipe qui a fait du spec-driven development pendant des mois	2 à 3 fois plus de tokens, environ deux fois plus long, un gros coût de coordination pour des changements qui n'en avaient pas besoin ; aucune preuve que le code s'en soit trouvé meilleur

Le bake-off est une expérience, pas un benchmark, et son auteur le dit lui-même. Mais la tendance tient. D'où la règle : écrivez une spec quand le travail traverse une frontière de squad ou sera relu dans 90 jours. Tout le reste est un prompt.

Superpowers trie déjà chaque demande selon trois chemins : spike, bounded, architectural. Seul le chemin architectural écrit une spec. Gardez le chemin bounded bounded, et gardez la spec près de 300 lignes. Les praticiens ajoutent deux lignes : ne spec pas trop gros, et lisez les specs générées.

La limite joue dans les deux sens. Le même bake-off a trouvé trois trous que le run simple avait manqués. La spec achète de la couverture, pas de la vitesse. Payez-la là où la couverture compte.

Retour aux trois questions du lead. Que versionne-t-on : les specs et plans approuvés, sur une branche, dans le dossier du squad. Le drift : un en-tête de statut et un gate CI. La gouvernance : des owners et une règle de taille.

Cinq règles, et aucune n'est imposée par un outil aujourd'hui. L'issue de dérogation est ouverte. L'issue de la branche main est ouverte. La pull request qui réordonnait l'instruction a été fermée sans être mergée. L'équipe qui s'est fait brûler a gardé la pratique : 8 plans et 6 specs, commités, exclus du build de docs.

L'objection de Böckeler tient toujours. Avec un en-tête de statut et un budget de taille, vous ne lisez que les specs accepted, et moins d'entre elles. Ce que vous récupérez, c'est ce que le playbook d'Anthropic appelle l'audit trail : qui a demandé quoi, ce que l'agent a produit, et qui l'a approuvé.

C'est du process, pas de l'outillage : un fichier CLAUDE.md, un fichier CODEOWNERS, un en-tête, et un script de quinze lignes. Et si l'équipe ne veut pas relire une demande CODEOWNERS, elle ne relira pas une spec non plus. Dans ce cas, le .gitignore était le choix honnête.