# La gestion des spécifications : stocker, versionner et réviser les spécifications comme du code

Canonical: https://specscore.md/fr/articles/spec-management/

Dernière mise à jour : 9 novembre 2026

La gestion des spécifications est la façon dont une équipe stocke une spécification logicielle, enregistre chaque changement, révise ce changement et tient la spécification à jour. La gestion de la spécification est le même travail : une spécification est le document qui dit ce que le logiciel doit faire, et la gérer est ce qui garde le document trouvable et fiable. Gérer les spécifications comme du code signifie que ces documents sont des fichiers dans le système de contrôle de version, de sorte qu’un changement de spécification est un commit dont un relecteur peut lire le diff. Le versionnage des spécifications est l’historique de ces commits, avec le statut écrit sur chaque document. Garder les spécifications synchronisées avec le code signifie qu’un changement proposé qui casse la structure de la spécification échoue au même contrôle automatique que traverse le changement de code. Le [développement piloté par les spécifications](https://specscore.md/fr/spec-driven-development/) (SDD, spec-driven development) est la pratique d’écrire la spécification avant le code et de traiter la spécification comme la source de vérité. L’[intégration continue](https://specscore.md/fr/validators/) (CI, continuous integration) est un contrôle automatique à chaque changement proposé. Un document d’exigences produit (PRD, product requirements document) est la prose qui énonce le problème et le périmètre ; le [modèle de PRD en Markdown](https://specscore.md/fr/articles/feature-spec-template/) est un fichier de fonctionnalité SpecScore de cette forme. [Easy Approach to Requirements Syntax](https://specscore.md/fr/articles/ears-requirements/) (EARS) est un patron de phrase pour une exigence. Dans [SpecScore](https://specscore.md/), une exigence (REQ) est une règle nommée dans une fonctionnalité, et un [critère d’acceptation](https://specscore.md/fr/articles/acceptance-criteria/) (AC, acceptance criterion) est une condition abstraite facultative qui pointe vers une ou plusieurs de ces règles. Le contrôle est une commande de l’[interface en ligne de commande](https://specscore.md/fr/cli/) (CLI, command-line interface), `specscore spec lint`, documentée dans [linter des spécifications en CI](https://specscore.md/fr/articles/lint-specs-in-ci/). Le format vit dans le dépôt public [specscore/specscore](https://github.com/specscore/specscore) ([CC BY 4.0](https://github.com/specscore/specscore/blob/main/LICENSE)). La CLI vit dans [specscore/specscore-cli](https://github.com/specscore/specscore-cli) ([Apache-2.0](https://github.com/specscore/specscore-cli/blob/main/LICENSE)).

## Où la spécification est stockée

La gestion des spécifications commence par un endroit où les fichiers peuvent vivre. Dans ce dépôt la spécification est en Markdown sous `spec/`. Le [README de spec](https://github.com/specscore/specscore/blob/main/spec/README.md) liste les répertoires : features, plans, ideas, decisions et lessons. Une fonctionnalité est un répertoire avec un `README.md`. La [spécification de fonctionnalité](https://specscore.md/feature-specification) est le contrat de ce fichier, et le [modèle de PRD](https://specscore.md/fr/articles/feature-spec-template/) est un exemple rempli qu’un linter a accepté.

`specscore spec lint` ne devine pas quel arbre lire. [internal/cli/spec.go](https://github.com/specscore/specscore-cli/blob/v0.55.1/internal/cli/spec.go) à l’étiquette v0.55.1, et la même fonction à l’[étiquette v0.39.1](https://github.com/specscore/specscore-cli/blob/v0.39.1/internal/cli/spec.go), remonte depuis le répertoire de travail jusqu’à trouver `specscore.yaml`. Le commentaire de cette fonction dit que la commande exige le fichier, renvoie le code de sortie 3 lorsqu’il manque, et vous dit d’exécuter `specscore init`. Le [workflow dogfood](https://github.com/specscore/specscore/blob/main/.github/workflows/dogfood.yml) de ce dépôt installe la CLI v0.39.1 puis exécute `specscore spec lint`, donc le checkout qu’il linte a ce fichier de configuration.

Un index est à côté des fichiers de fonctionnalité. La règle `feature-index-row-sync` est une erreur dans le catalogue de lint de [v0.39.1](https://github.com/specscore/specscore-cli/blob/v0.39.1/docs/lint-rules.md) et de [v0.55.1](https://github.com/specscore/specscore-cli/blob/v0.55.1/docs/lint-rules.md). La ligne du catalogue dit qu’elle exige que chaque ligne de l’index des fonctionnalités corresponde à son fichier de fonctionnalité. C’est l’index qui reste aligné avec le document qu’il désigne. Ce n’est pas une comparaison de la formulation de l’exigence avec un fichier source.

## Versionnage des spécifications

Le versionnage des spécifications, pour les fichiers commités dans git, est l’historique des commits de ces fichiers. SpecScore n’ajoute pas un second numéro de version sur une fonctionnalité. La révision qu’un relecteur regarde est le commit sur la branche. La ligne de statut du document dit où cette fonctionnalité en est dans son cycle de vie, ce qui est un fait distinct du hash git.

La [spécification de fonctionnalité dans le dépôt](https://github.com/specscore/specscore/blob/main/spec/features/feature/README.md) est elle-même `**Status:** Stable`. Elle exige une ligne `**Status:**` immédiatement après le titre, et la valeur doit être l’une de `Draft`, `In Review`, `Approved`, `Implementing`, `Stable`, `Amending`, `Rejected` ou `Deprecated`. La règle `status-mirror`, dans les deux catalogues nommés plus haut, exige que le `status:` du frontmatter d’un artefact qui porte un statut corresponde à cette ligne du corps, et interdit `status:` sur un type qui n’a pas de statut. Faire correspondre les deux copies n’est pas la même chose que rejeter un mot hors des huit valeurs. Aucune des deux lignes du catalogue ne décrit une règle qui rejette un statut de fonctionnalité hors de cet ensemble, donc cette page n’en affirme pas l’existence.

Les plans utilisent un autre ensemble. La règle `P-006`, dans les deux catalogues, exige que le `**Status:**` du corps d’un plan en un seul fichier soit l’un de `Draft`, `In Review`, `Approved`, `Executing`, `Blocked`, `Implemented`, `Failed`, `Rejected`, `Withdrawn`, `Superseded` ou `Deprecated`. La règle `idea-status-values` rejette un statut d’idée hors de l’ensemble que cette règle permet. Le catalogue est la liste. Cette page ne répète pas les mots des idées.

La [spécification de plan](https://github.com/specscore/specscore/blob/main/spec/features/plan/README.md) décrit aussi une table facultative `## Snapshots` avec les colonnes Date, Git Hash, Action et Comment. Elle dit que chaque instantané référence un hash de commit git de l’état du plan à ce moment. Les deux catalogues de lint vérifiés pour cette page ne nomment pas de règle qui résout ce hash, donc cette page n’affirme pas que le linter vérifie que le commit existe. Le hash est un pointeur qu’une personne peut suivre dans git. La [spécification de plan](https://specscore.md/plan-specification) publiée est la page de format de ce document.

## Réviser une spécification

La révision d’une spécification en Markdown est la pull request qui la change. [dogfood.yml](https://github.com/specscore/specscore/blob/main/.github/workflows/dogfood.yml) s’exécute sur `pull_request` et sur un push vers `main`. Le job fait le checkout du dépôt, installe la CLI avec `SPECSCORE_VERSION` fixé à `v0.39.1`, et exécute `specscore spec lint` sans flags supplémentaires. GitHub Actions fait échouer l’étape lorsque ce processus se termine avec un code différent de zéro. Les permissions du workflow sont `contents: read`.

Le statut de fonctionnalité `In Review` signifie que la fonctionnalité est présentée pour révision. Écrire ce mot est une modification du fichier Markdown. La pull request est l’endroit où une personne lit le diff. `status-mirror` vérifie que le frontmatter et le corps nomment le même statut. Cela n’enregistre pas qu’un relecteur a été d’accord avec la prose. La [page des validateurs](https://specscore.md/fr/validators/) sépare ce contrôle structurel d’une lecture qu’une personne doit encore faire. Le récit règle par règle de ce que signale `specscore spec lint` est dans [linter des spécifications en CI](https://specscore.md/fr/articles/lint-specs-in-ci/).

## Garder les spécifications synchronisées avec le code

Garder les spécifications synchronisées avec le code, sur ce site, signifie que la spécification est dans le dépôt avec le projet, et que la CI fait échouer la pull request lorsque l’arbre de la spécification viole le format. Une pull request peut changer un fichier de fonctionnalité et le code dans le même diff. La règle `feature-index-row-sync` garde une ligne d’index alignée avec le fichier de fonctionnalité qu’elle nomme. Elle ne lit pas un fichier source pour décider si le code implémente l’exigence.

L’extrait ci-dessous reprend les étapes d’installation et de lint de [dogfood.yml](https://github.com/specscore/specscore/blob/main/.github/workflows/dogfood.yml). Le fichier de workflow fixe aussi les permissions, un groupe de concurrence et un commentaire sur la raison pour laquelle le pin n’est pas `latest`. Ces lignes sont omises ici. Les commandes sont celles que ce fichier exécute.

### Étapes d’installation et de lint de dogfood.yml

```yaml
name: Dogfood lint

on:
  push:
    branches: [main]
  pull_request:

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
      - name: Install specscore CLI (pinned)
        env:
          SPECSCORE_VERSION: v0.39.1
        run: |
          curl -fsSL https://specscore.md/install/get-cli | \
            SPECSCORE_INSTALL_DIR="$HOME/.local/bin" sh
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
          specscore --version
      - name: Lint spec tree
        run: specscore spec lint
```

Le commentaire de ce fichier dit qu’un pin flottant `latest` change la barrière sous le dépôt : une pull request et la branche main qu’elle vise peuvent voir des règles différentes. Le pin est `v0.39.1`. Le job ne passe pas `--fix`. Une exécution propre et une exécution qui échoue, y compris la ligne `file:line [severity] rule: message`, sont montrées dans [linter des spécifications en CI](https://specscore.md/fr/articles/lint-specs-in-ci/).

Une phrase de la spécification qui ne décrit plus le code n’est pas l’un de ces constats. `specscore spec lint` valide la structure : fichiers et sections obligatoires, lignes d’index, forme des titres, et les références que nomment les règles. Il ne note pas si l’implémentation correspond à l’exigence. Cette limite est le sens de la [page des validateurs](https://specscore.md/fr/validators/). Garder la prose vraie reste une révision du diff.

## Comment d’autres outils de développement piloté par les spécifications vérifient une spécification

Les paragraphes ci-dessous utilisent les pages récupérées le 9 novembre 2026. Ils décrivent les contrôles propres de ces outils. Ils ne disent pas combien de produits existent, et ils ne classent pas un marché. La [revue des outils](https://specscore.md/fr/spec-driven-development/tools/) est la comparaison plus longue.

La [référence de SDD agentique de GitHub Spec Kit](https://github.github.io/spec-kit/reference/agentic-sdd.html) décrit `/speckit.analyze` comme un contrôle en lecture seule sur `spec.md`, `plan.md` et `tasks.md`. Il signale les conflits, les lacunes et les ambiguïtés, il ne modifie jamais les fichiers, et vous l’exécutez dans l’agent avant l’implémentation. La liste de commandes de cette même page ne décrit pas un job de CI qui exécute `specscore spec lint` contre un arbre SpecScore.

[OpenSpec](https://github.com/Fission-AI/OpenSpec) stocke un changement comme un répertoire directement sous `openspec/changes/`. [openspec validate](https://openspec.dev/docs/cli) vérifie les changements et les spécifications à la recherche de problèmes de structure. La référence dit que le code de sortie 0 signifie que chaque élément validé a réussi, et que le code 1 signifie qu’un élément a échoué, que la demande de rapport n’est pas valide, que la configuration ne peut pas être lue, ou que l’exécution a échoué. Ce contrôle est la forme d’OpenSpec, y compris ses blocs d’exigence et de scénario, pas un titre `### AC:` de SpecScore. Sur une autre commande, `openspec status`, la même référence dit qu’un lot qui ne peut pas charger un changement se termine quand même par 1, « so CI doesn’t accept an incomplete report as successful. ». Cette phrase porte sur `openspec status`, pas sur `openspec validate`.

## Questions fréquentes

### Qu’est-ce que la gestion des spécifications ?

La gestion des spécifications est stocker une spécification logicielle, enregistrer chaque changement, réviser ce changement et tenir la spécification à jour. Dans SpecScore les fichiers sont en Markdown dans le dépôt git, et `specscore spec lint` est le contrôle structurel qu’un job de CI peut faire échouer.

### Qu’est-ce que la gestion de la spécification ?

La gestion de la spécification est la même pratique. La spécification est le document qui dit ce que le logiciel doit faire. La gérer signifie que le document a un endroit connu, un historique, une révision, et un contrôle que sa structure correspond encore au format.

### Comment gérer les spécifications comme du code ?

La spécification est un arbre de fichiers Markdown sous `spec/`, plus `specscore.yaml` à la racine du dépôt. Un changement est un commit. Une pull request révise le diff. [dogfood.yml](https://github.com/specscore/specscore/blob/main/.github/workflows/dogfood.yml) exécute `specscore spec lint` sur cette pull request.

### Comment fonctionne le versionnage des spécifications ?

L’historique git est l’historique de version des fichiers. Une fonctionnalité porte aussi `**Status:**` avec l’une des huit valeurs qu’exige la spécification de fonctionnalité. Un plan peut enregistrer une ligne `## Snapshots` dont le Git Hash est un commit de l’état du plan. Les catalogues du linter cités ici ne décrivent pas de règle qui résout ce hash.

### Comment garder les spécifications synchronisées avec le code ?

Mettez la spécification dans le dépôt et faites échouer la pull request lorsque `specscore spec lint` signale une violation structurelle, y compris une ligne d’index qui ne correspond pas à son fichier de fonctionnalité. La commande ne décide pas si le code implémente l’exigence. Une phrase qui s’est écartée du code a encore besoin qu’une personne lise le diff.

## Sources

Fichiers de la CLI et catalogues de lint lus le 9 novembre 2026 aux étiquettes v0.39.1 de specscore-cli (la version que dogfood.yml installe) et v0.55.1. Les exigences de fonctionnalité et de plan sont les fichiers liés ci-dessous dans specscore/specscore. Les pages concurrentes ont été récupérées le même jour.

- [specscore/specscore — spec/README.md](https://github.com/specscore/specscore/blob/main/spec/README.md)
- [specscore/specscore — valeurs de statut de la fonctionnalité](https://github.com/specscore/specscore/blob/main/spec/features/feature/README.md)
- [specscore/specscore — instantanés du plan](https://github.com/specscore/specscore/blob/main/spec/features/plan/README.md)
- [specscore/specscore](https://github.com/specscore/specscore)
- [specscore/specscore — licence CC BY 4.0](https://github.com/specscore/specscore/blob/main/LICENSE)
- [specscore/specscore-cli](https://github.com/specscore/specscore-cli)
- [specscore-cli — licence Apache-2.0](https://github.com/specscore/specscore-cli/blob/main/LICENSE)
- [specscore-cli v0.39.1 — internal/cli/spec.go](https://github.com/specscore/specscore-cli/blob/v0.39.1/internal/cli/spec.go)
- [specscore-cli v0.55.1 — internal/cli/spec.go](https://github.com/specscore/specscore-cli/blob/v0.55.1/internal/cli/spec.go)
- [specscore-cli v0.39.1 — catalogue des règles de lint](https://github.com/specscore/specscore-cli/blob/v0.39.1/docs/lint-rules.md)
- [specscore-cli v0.55.1 — catalogue des règles de lint](https://github.com/specscore/specscore-cli/blob/v0.55.1/docs/lint-rules.md)
- [specscore/specscore — dogfood.yml (CLI v0.39.1)](https://github.com/specscore/specscore/blob/main/.github/workflows/dogfood.yml)
- [Ce que SpecScore valide](https://specscore.md/fr/validators/)
- [Linter des spécifications en CI avec un linter de spécifications](https://specscore.md/fr/articles/lint-specs-in-ci/)
- [Syntaxe des exigences EARS expliquée, avec exemples](https://specscore.md/fr/articles/ears-requirements/)
- [Comment écrire des critères d'acceptation qu'un agent d'IA peut vérifier](https://specscore.md/fr/articles/acceptance-criteria/)
- [Modèle de PRD en Markdown pour coder avec l’IA](https://specscore.md/fr/articles/feature-spec-template/)
- [Spécification de fonctionnalité](https://specscore.md/feature-specification)
- [Spécification de plan](https://specscore.md/plan-specification)
- [GitHub Spec Kit — référence de SDD agentique (/speckit.analyze)](https://github.github.io/spec-kit/reference/agentic-sdd.html)
- [Référence de la CLI OpenSpec — openspec validate et openspec status](https://openspec.dev/docs/cli)
- [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec)
- [Outils de développement piloté par les spécifications](https://specscore.md/fr/spec-driven-development/tools/)

## En lien

- [Linter des spécifications en CI avec un linter de spécifications](https://specscore.md/fr/articles/lint-specs-in-ci/)
- [Modèle de PRD en Markdown pour coder avec l’IA](https://specscore.md/fr/articles/feature-spec-template/)
- [Comment écrire des critères d'acceptation qu'un agent d'IA peut vérifier](https://specscore.md/fr/articles/acceptance-criteria/)
- [Syntaxe des exigences EARS expliquée, avec exemples](https://specscore.md/fr/articles/ears-requirements/)
- [Développement piloté par les spécifications](https://specscore.md/fr/spec-driven-development/)
- [Outils de développement piloté par les spécifications](https://specscore.md/fr/spec-driven-development/tools/)
- [Spécification de fonctionnalité](https://specscore.md/feature-specification)
- [Spécification de plan](https://specscore.md/plan-specification)
- [CLI](https://specscore.md/fr/cli/)
- [Ce que SpecScore valide](https://specscore.md/fr/validators/)
