Chaque ambiguïté dans votre spécification
est un token que votre agent brûle.

Ce qui casse quand il n'est pas là.

• 🌀 Les spécifications se désynchronisent.

  La spécification dans le document, le fil sur Slack et le code dans la PR divergent en silence pendant des semaines. Personne ne sait quelle version de la discussion fait foi.

  Le remède

  Une seule spécification canonique, dans le dépôt, versionnée avec le code. specscore lint s'exécute en CI à chaque push ; l'historique git constitue la piste d'audit. La spécification, le fil et la PR ne peuvent plus diverger en silence — ils partagent le même fichier sous révision.

• 🌫️ Les critères d'acceptation restent flous.

  « Gérer les erreurs avec élégance » devait signifier« afficher un toast et annuler. » Ou était-ce« enregistrer dans les logs et réessayer ? » L'agent doit deviner.

  Le remède

  Le linter détecte les critères ambigus avant même qu'une seule ligne de code ne soit écrite. Le verbe échoue au lint car il manque d'objet ou de condition concrète. Corriger l'avertissement oblige à expliciter ce que« gérer » veut réellement dire.

• 🤖 Les agents livrent la mauvaise chose.

  Les humains interpolent, posent des questions, précisent. Les agents d'IA, non — ils implémentent le motif le plus fréquent dans leurs données d'entraînement. Le code passe la revue parce qu'il faitquelque chose de sensé. Mais ce n'est pas ce que vous vouliez dire.

  Le remède

  Une entrée structurée. Les agents d'IA analysent les identifiants REQ, AC et les scénarios GIVEN / WHEN / THENde manière déterministe — rien à interpoler. Chaque tâche du Plan doit citer les AC qu'elle satisfait, de sorte que ce qui est construit soit toujours vérifiable par rapport à ce qui a été spécifié.

• 🔁 Vous payez deux fois pour une spécification ambiguë.

  L'agent construit quelque chose à partir d'un brief flou, vous voyez que c'est erroné et vous lui redemandez — de quatre manières différentes. Chaque fonction inachevée et chaque nouvelle tentative se paient en tokens. Plus la spécification est vague, plus les allers-retours s'accumulent avant d'obtenir le bon résultat.

  Le remède

  Passez la spécification au linter avant que l'agent ne commence.specscore lint rejette d'entrée les verbes vagues et les critères d'acceptation manquants, permettant à l'agent d'implémenter un brief précis en une seule passe au lieu de tâtonner entre les essais. L'exécution la moins chère est celle que vous n'avez pas à recommencer.

• 💸 Les agents paient pour relire vos spécifications.

  Un agent d'IA qui répond à « de quoi dépend cette feature ? » lit le README entier de la feature. Puis chaque index parent. Puis les features sœurs au cas où. Chaque requête est une nouvelle analyse syntaxique. Les tokens s'envolent ; la latence grimpe ; la facture avec.

  Le remède

  Des requêtes structurées plutôt que la lecture de fichiers.specscore feature tree renvoie la hiérarchie en YAML ; feature deps parcourt la chaîne transitive de dépendances ; feature infoexpose le statut, le propriétaire et les questions ouvertes — chacun en un seul appel. L'agent navigue dans le graphe, pas dans la prose.

• 🔗 Le code oublie sa spécification.

  Six mois plus tard, vous déboguez une fonction et personne ne se souvient de quelle feature elle découle. Le lien entre code et spécification résidait dans la tête de quelqu'un, et cette personne est partie. La PR qui l'a introduite a disparu dans les archives.

  Le remède

  Des annotations dans le code source. Des commentaires tels que// specscore: features/checkout/apply-discount/R1.AC-2rendent le lien lisible par une machine et résistent aux refactorisations.specscore code deps répond à« quelle spécification ce fichier implémente-t-il ? » en un seul appel ; le linter signale les références pointant vers des spécifications supprimées.

• 🏷️ Les changements de statut s'égarent.

  Vous passez une feature de Draft à Approveddans son README, mais le features-index parent continue de l'afficher comme Draft. Trois semaines plus tard, un agent lisant l'index croit qu'elle est toujours en cours de révision. L'état réside à deux endroits, et ils se contredisent.

  Le remède

  specscore feature change-status réécrit le champ Status de la feature et resynchronise la ligne de l'index en une seule étape atomique — si le lint échoue, la réécriture est annulée. L'état existe en un lieu unique et canonique ; l'index est une vue générée de cet état.

• 📋 Les spécifications oublient ce qu'elles ignorent.

  Une spécification se lit comme si elle était close — jusqu'à ce que vous réalisiez que la question« et que fait-on pour les fuseaux horaires ? » s'est perdue dans un fil Slack il y a deux mois et n'a jamais atteint le document. Vous êtes en pleine implémentation et personne ne sait quelle était la réponse.

  Le remède

  Chaque feature SpecScore comporte une section obligatoireOutstanding Questions. Le linter rejette les features qui l'omettent — vide est accepté ("None at this time."), mais absente ne l'est pas. Les questions non résolues sont visibles dans le document, consultables via le CLI et impossibles à oublier.