SpecGuard - Plugin CLI/Codex qui vérifie d’abord les spécifications avant le codage par IA

Bonjour. Je développe un outil open source appelé SpecGuard.

Quand on utilise des outils de codage par IA comme Codex ou Claude Code, la vitesse d’implémentation augmente clairement. Mais après plusieurs itérations, le problème auquel je me suis réellement heurté le plus souvent était moins « l’IA ne sait pas coder » que « les spécifications elles-mêmes, fournies à l’IA, sont incomplètes ».

Quand une spécification comporte des défauts, l’IA comble les vides en extrapolant à sa manière. Au début, cela semble plausible, mais à mesure que le développement avance, les problèmes suivants s’aggravent.

• La qualité et la structure du code se dégradent progressivement.
• Les spécifications et le code correspondent de moins en moins.
• Plus tard, il devient difficile de distinguer si le code est faux, si la spécification est obsolète, ou si les exigences initiales étaient ambiguës.

J’en ai donc conclu qu’une simple revue de code après l’implémentation ne suffisait pas. Il fallait une étape permettant de révéler d’abord les lacunes de la spécification elle-même, avant qu’une spécification défectueuse ne soit transmise telle quelle à l’agent d’implémentation.

SpecGuard est un plugin CLI/Codex conçu pour réduire ce problème. Ce n’est pas un outil qui vérifie le résultat après la génération de code, mais un outil qui inspecte d’abord la spécification avant de confier l’implémentation à l’IA.

Le flux de base que j’avais en tête est le suivant.

1. Une personne rédige la spécification produit.
2. La spécification est vérifiée avec SpecGuard.
3. Si le résultat est NOT_READY, la spécification est renforcée.
4. Une fois READY, elle est transmise à un agent d’implémentation comme Codex ou Claude Code.

SpecGuard cherche principalement ce type de lacunes.

• Frontières d’authentification/d’autorisations peu claires
• Portée de propriété tenant/user absente
• Absence de traitement de l’idempotence, du replay ou des race conditions
• Règles ambiguës concernant l’expiration, la révocation ou les transitions d’état
• Absence de politique pour les effets externes, les webhooks ou les retries de background jobs
• Exigences qui se reposent uniquement sur la validation côté client

Les résultats se répartissent en trois grandes catégories.

• READY : peut être transmis à l’agent d’implémentation
• READY_WITH_WARNINGS : peut être transmis, mais avec des points d’attention
• NOT_READY : présence de problèmes Critical/Major, la spécification doit être renforcée

Le chemin par défaut est l’inspection heuristique --no-llm. J’estimais en effet que, dans CI ou en PR Review, il était important d’obtenir des résultats rapides et reproductibles. Il est aussi possible d’ajouter une revue détaillée basée sur OpenAI Platform ou Codex, mais pour l’instant cela reste une voie auxiliaire optionnelle à utiliser quand on veut aller plus en profondeur.

Ce qui a été ajouté dans v0.4.0

Dans cette v0.4.0, j’ai ajouté une MVP de plugin pour l’application Codex.

pip install spec-guard  
specguard --help  
codex plugin marketplace add KoreaNirsa/spec-guard --ref main  

Dans l’application Codex, si vous sélectionnez la source SpecGuard Plugins puis installez le plugin SpecGuard, vous pouvez demander l’exécution de SpecGuard directement depuis Codex. Par exemple, après avoir créé une spécification d’exemple :

specguard example copy specs/your-feature-name --force  

Vous pouvez ouvrir ce dossier dans Codex et faire une requête comme suit.

1. @SpecGuard exécute SpecGuard pour specs/your-feature-name.  
2. @SpecGuard exécute SpecGuard sur le package de spécifications specs/your-feature-name, puis résume l’état READY/NOT_READY et les principaux findings.  
3. @SpecGuard exécute SpecGuard pour specs/your-feature-name. Utilise l’inspection heuristique par défaut, puis résume l’état du résultat et les prochaines actions à entreprendre.  

Le plugin ne réimplémente pas le moteur de SpecGuard. Il appelle le CLI specguard existant, puis lit le résultat généré pour résumer l’état actuel et l’action suivante.

L’idée est que, lorsqu’un état READY est obtenu avec SpecGuard, on puisse produire un document de handoff à transmettre à l’agent d’implémentation, puis laisser Codex démarrer l’implémentation.

PR Review également pris en charge

Un workflow de PR Review SpecGuard basé sur GitHub Actions est également fourni.

Le principe est d’exécuter SpecGuard Review quand un package de spécifications change dans une PR, puis de publier le résultat dans la PR. Cette fonctionnalité s’exécute en appelant OpenAI.

L’objectif n’est pas « une revue du code créé par l’IA », mais « une revue des spécifications en entrée avant de les transmettre à l’IA ».

Cela peut être utile si votre équipe veut définir des règles comme :

• ne pas transmettre à l’implémentation des spécifications NOT_READY
• exposer d’abord dans la PR les findings Critical/Major
• gérer d’abord la qualité des exigences en entrée plutôt que le résultat de l’implémentation

L’installation peut se faire avec specguard actions install-pr-review depuis le CLI, ou en demandant à Codex @specguard configure le workflow SpecGuard PR Review.

Comme il s’agit encore d’une fonctionnalité expérimentale, l’automatisation du paramétrage n’est pas encore prise en charge : il faut donc définir manuellement les éléments suivants dans GitHub Secret.

SPECGUARD_OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxx  
SPECGUARD_PR_REVIEW_MODEL=gpt-5.4-nano  
SPECGUARD_REVIEW_SPEC_PATHS=specs/your-feature-name  

État actuel et limites

Ce n’est encore qu’une version initiale, et l’outil ne permet pas de juger parfaitement toutes les spécifications.

Cela dit, si vous rencontrez, en utilisant le codage par IA, le problème de « spécifications trop faibles qui font dérailler l’implémentation », cela peut servir de garde-fou à appliquer une fois avant de lancer l’implémentation.

J’aimerais beaucoup avoir des retours. En particulier, je me demande :

• sur quels types de spécifications cela fonctionne bien
• quels findings sont excessifs ou insuffisants
• si le flux du plugin Codex est réellement utilisable en pratique
• si le fait de l’imposer via PR Review s’intègre bien au workflow d’équipe

Pour l’instant, on est encore avant même une version bêta, à un stade où le développement vient tout juste de démarrer, mais je veux en faire un projet suffisamment solide pour être réellement utilisable en production à l’avenir.

Les issues/PR de toutes les personnes intéressées sont les bienvenues. Les issues et PR du dépôt sont pour l’instant principalement gérées en anglais, mais vous pouvez aussi les rédiger en coréen si vous préférez.

GitHub : https://github.com/KoreaNirsa/spec-guard

[veltrix]

Vous trouverez plus de détails sur ce projet sur https://nirsa.tistory.com/487.