AIDive

Pack vidéo

Gouverner les specs et plans IA dans Git : cinq règles, drift gate, sources et checklist

11 min de lecture

TL;DR

  • Commitez les specs et les plans écrits par l'IA. Tous les outils le font déjà par défaut ; la vraie question, c'est la gouvernance.
  • Donnez à chaque squad un dossier avec une ligne CODEOWNERS, pour qu'un changement de spec demande une revue aux propriétaires du code.
  • Mettez un en-tête de type ADR sur chaque spec partagée : status, superseded-by, owner, paths touchés, date de revue. Ne réécrivez jamais une spec acceptée pour en faire une nouvelle décision.
  • Lancez un drift gate en CI : pour chaque spec acceptée, faites échouer le build quand un chemin qu'elle cite n'existe plus.
  • Redirigez le chemin de sortie avec une ligne impérative en gras dans CLAUDE.md, gardez les plans personnels dans CLAUDE.local.md et .git/info/exclude, et écrivez sur une branche, jamais sur main.
  • Ne spécifiez que le travail qui franchit une frontière de squad ou qui sera relu dans 90 jours. Les runs pilotés par les specs coûtent environ deux fois plus de temps et trois fois plus de tokens.

Ce que disent les sources

Les défauts : tout le monde commite

Le skill writing-plans de Superpowers enregistre les plans dans docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md, avec une ligne en dessous précisant que les préférences de l'utilisateur sur l'emplacement des plans l'emportent sur ce défaut s1. Le skill brainstorming écrit le design validé dans docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md et finit par « Commit the design document to git » s2. Spec Kit organise specs/[branch-name]/ avec spec.md, plan.md et tasks.md, numérotés 001, 002, plus une constitution dans memory/constitution.md s6. Kiro garde .kiro/specs/ avec un dossier par feature et invite les équipes à « collaborate with team members on different features simultaneously » s8. Le playbook d'Anthropic est explicite : « Every stage commits an artifact the next stage can read », « Commit the approved plan as plan.md », et « When implementation departs from the plan, update plan.md in the same commit » s5.

Aucun de ces documents ne dit qui possède une spec commitée ni quand elle cesse d'être vraie. Les trois échecs documentés se logent dans ce vide.

Échec 1 : la fuite publique

L'issue 1690, ouverte le 2026-06-05, signale que l'emplacement par défaut docs/superpowers/ peut faire fuiter des plans internes dans la documentation publiée via Sphinx et Read the Docs s15. Le projet touché était okama, une bibliothèque Python de 273 stars. Son commit de correction a remis 5 plans et 3 specs, supprimé une ligne de .gitignore et s'intitule « track superpowers plans/specs in git, excluded from the Sphinx build » s21. La ligne 84 de docs/conf.py contient désormais exclude_patterns = ["_build", "Thumbs.db", "superpowers"] s22. Aujourd'hui le dossier contient 8 plans et 6 specs s15. L'équipe a gardé la pratique et corrigé le build.

Échec 2 : des plans sur main

L'issue 1246, ouverte le 2026-04-22 et toujours ouverte, demande pourquoi le plan est commité avant qu'une branche de développement existe. Un utilisateur rapporte « I'm getting 10 to 15 commits » ; un autre : « Yes please, no plans and specs on main branch! » s16. Le plugin n'impose aucune règle de branche ; la checklist ci-dessous le fait.

Échec 3 : des overrides que le modèle ignore

L'issue 337, fermée le 2026-03-10, se conclut par la note du mainteneur : depuis la v5.0, le plugin donne priorité au CLAUDE.md de votre projet sur ses propres défauts, avec cette ligne d'exemple : « Save plans to ~/.superpowers/plans/ instead of docs/plans/ » s17. L'issue 939, sur la v5.0.6, montre la limite : un tableau « Output Paths » dans CLAUDE.md a été ignoré et les specs continuaient d'atterrir dans docs/superpowers/specs/. Le contournement qui a marché est une ligne impérative en gras sous le tableau : les design specs MUST be saved to docs/design-docs/, NOT docs/superpowers/specs/ s18. La pull request 1020, qui réordonnait l'instruction, a été fermée sans merge s19. L'override est un prompt, pas un réglage : revérifiez-le après chaque release du plugin. Pour les fichiers de travail du plugin, l'issue 1780 a été fermée par la v6.0.3 avec un dossier .superpowers/sdd/ qui s'auto-ignore en déposant son propre .gitignore contenant * s20.

Personnel contre partagé

Claude Code documente la séparation : « For private per-project preferences that shouldn't be checked into version control, create a CLAUDE.local.md at the project root. It loads alongside CLAUDE.md and is treated the same way. Add CLAUDE.local.md to your .gitignore so it isn't committed » s3. Les CLAUDE.md par répertoire se chargent à la demande, « Commit these files to the repository so teammates inherit them. Each directory's owner typically maintains its file », et un réglage claudeMdExcludes masque les fichiers des autres équipes dans un monorepo s4. Git offre trois niveaux d'ignore, $XDG_CONFIG_HOME/git/ignore, $GIT_COMMON_DIR/info/exclude et .gitignore s24 ; celui du milieu cache un dossier de plans personnels sans toucher à un fichier partagé. CODEOWNERS couvre la moitié propriété : « Code owners are automatically requested for review when someone opens a pull request that modifies code that they own » s23.

Un cycle de vie, comme les ADR

Le billet de Michael Nygard de 2011 sert de modèle : une décision « may be 'proposed' if the project stakeholders haven't agreed with it yet, or 'accepted' once it is agreed. If a later ADR changes or reverses a decision, it may be marked as 'deprecated' or 'superseded' with a reference to its replacement », et « If a decision is reversed, we will keep the old one around, but mark it as superseded » s9. Thoughtworks distingue trois usages de la spec : spec-first (écrite une fois pour la tâche), spec-anchored (conservée pour faire évoluer la feature) et spec-as-source (seule la spec est modifiée), et son auteur ajoute : « I'd rather review code than all these markdown files » s10. Superpowers écrit des fichiers spec-first et les garde pour toujours : de la dérive par défaut.

La dérive et le gate

L'article arXiv nomme le problème « silent spec-code drift, code evolves, the specification does not, and the divergence becomes invisible until it is costly to repair » et propose « a drift gate that makes spec-code divergence a blocking merge condition » s11. Le guide de Spec Kit prévient : « Do not leave a lower-level change in tasks.md or code if spec.md still says something different » s7. TrueFoundry pose le cas de gouvernance sans détour : « forty-one specs and nine agent files aren't a tidiness problem », ce sont « forty-one unversioned behavior inputs and nine competing standing policies », et la dérive « is unavoidable in spec-first practice and managed in spec-anchored practice, but only if divergence is detectable ». Le même billet suggère environ 300 lignes par spec et un budget de 150 à 200 instructions permanentes s13. Un praticien décrit la version manuelle : « I've had to have Claude compare the spec files to the codebase and see if anything is missing » s26.

Ce que ça coûte

Expérience Résultat Source
Spec Kit sur une feature qui affiche la date du jour 8 fichiers et 1,300 lignes de texte s14
Bake-off OpenSpec, mêmes exigences, outil de spec contre Claude Code seul OpenSpec a fait remonter 3 lacunes de plus ; 50% de code en plus avec 50% de complexité cyclomatique en plus ; deux fois plus long et trois fois le coût s12
Une équipe qui pratique le spec-driven development depuis des mois « two to three times as many tokens and take about twice as long » ; aucune preuve que le code s'est amélioré s25

Le bake-off est une seule expérience et son auteur le dit, mais la direction se retrouve dans les trois. Donc : spécifiez le chemin architectural, gardez le chemin simple borné, et suivez les deux lignes que répètent les praticiens, « don t spec too big / read the generated specs » s26.

À faire lundi

  • Créez docs/specs/<squad>/ par squad et ajoutez une ligne CODEOWNERS par dossier, pointant vers les relecteurs de cette squad.
  • Ajoutez une ligne impérative en gras au CLAUDE.md du projet : les plans et specs MUST be saved under docs/specs/<squad>/, NOT docs/superpowers/. Lancez un brainstorm et vérifiez où le fichier a atterri.
  • Déplacez les plans personnels vers un dossier listé dans .git/info/exclude et gardez les préférences par développeur dans CLAUDE.local.md, lui-même ignoré.
  • Mettez un en-tête sur chaque spec partagée : status (proposed, accepted, superseded), superseded-by, owner, paths, review-by.
  • Écrivez le drift gate : pour chaque spec avec status: accepted, extrayez les chemins qu'elle cite et faites échouer la pull request quand l'un manque. Une quinzaine de lignes de shell ou de Python.
  • Ajoutez une règle de branche : aucun commit de spec ou de plan n'arrive sur main en dehors d'une pull request.
  • Si le dépôt publie sa doc avec Sphinx ou équivalent, ajoutez dès aujourd'hui le dossier des specs à exclude_patterns.
  • Fixez le budget de taille : une spec reste autour de 300 lignes, et seul le travail qui franchit une frontière de squad ou qui sera relu dans 90 jours en reçoit une.

Aller plus loin

  • Lisez les trois catégories d'usage des specs (spec-first, spec-anchored, spec-as-source) avant de choisir un schéma d'en-tête ; le cycle de vie n'a de sens que pour les fichiers spec-anchored s10.
  • L'article arXiv va plus loin que les contrôles de chemins, jusqu'à une architecture complète imposant l'absence de dérive ; utile quand le gate de quinze lignes devient trop grossier s11.
  • Le guide de Spec Kit nomme trois flux d'évolution (Flow-Forward, Living Spec, Flow-Back) qui correspondent à la règle du même commit s7.
  • Le playbook suggère un hook pour imposer la synchronisation du plan et du diff ; le thread Reddit associé compte 43 points et 27 commentaires de retours du terrain s5, s27.
  • L'argument de TrueFoundry, selon lequel un changement de spec est un changement de politique et doit donc passer derrière un eval gate avec métadonnées de run, est l'étape suivante après les contrôles de chemins en CI s13.
  • Suivez les deux issues ouvertes, 1246 (plans sur main) et 939 (overrides ignorés) ; quand l'une se ferme, une règle de ce pack devient un défaut du plugin s16, s18.
  • Le texte complet de Marmelab explique pourquoi les 1,300 lignes sont apparues et où Spec Kit est rentable s14.

Sources

FAQ

Faut-il les cinq règles dès le premier jour ?

Non. La redirection dans CLAUDE.md et l'exclusion Sphinx prennent dix minutes. Ajoutez CODEOWNERS et l'en-tête quand une spec traverse les squads pour la première fois, et le drift gate quand une spec acceptée a vieilli d'un sprint.

Que rate le drift gate ?

Le comportement modifié. Il vérifie seulement qu'un chemin cité existe toujours, donc une condition inversée passe. Associez-le à la règle du même commit et à la revue.

Pourquoi ne pas simplement mettre le dossier dans .gitignore ?

Parce que l'agent qui lira la spec plus tard en a besoin, et que la piste d'audit ne fonctionne que si les pièces intermédiaires sont versionnées. L'équipe okama a essayé le gitignore, puis est revenue au commit avec une exclusion du build.