Modèle de spécification produit en Markdown

Un fichier .md prêt à remplir : problème, objectif, hors périmètre, parcours, critères d’acceptation, questions ouvertes et décisions. Il s’ouvre dans n’importe quel éditeur et s’affiche mis en forme dans Marko.

Télécharger le modèle (.md) ↓

Pourquoi une spec en Markdown

Une spécification sert à décrire ce qu’on va construire avant d’écrire du code. En Markdown, c’est un fichier texte simple : il s’ouvre partout, sur n’importe quel Mac, sans logiciel propriétaire. Vous le rangez à côté du dépôt, vous suivez ses versions avec Git, et chaque relecture montre noir sur blanc ce qui a changé depuis la précédente.

À quoi sert chaque rubrique

Sept rubriques, dans l’ordre où une équipe lit une spec.

• Problème : qui rencontre quoi, et pourquoi c’est un problème aujourd’hui.
• Objectif : le résultat attendu, en une phrase mesurable.
• Hors périmètre : ce que la spec ne couvre pas, pour couper court aux attentes.
• Parcours proposé : les étapes que traverse la personne concernée.
• Critères d’acceptation : des conditions vérifiables, en cases à cocher.
• Questions ouvertes : ce qui reste à trancher.
• Décisions : ce qui a été tranché, par qui, quand.

Comment le remplir

1. Téléchargez le modèle, puis ouvrez-le dans Marko (clic droit, « Ouvrir avec », « Marko ») ou dans l’éditeur de votre choix.
2. Remplacez chaque ligne d’exemple. Supprimez les rubriques inutiles : une spec courte se relit mieux.
3. Si vous avez déjà une réponse d’IA, collez-la en mode Source, puis remettez chaque idée dans sa rubrique.
4. Pour l’envoyer à quelqu’un qui n’a pas Marko, utilisez « Exporter en PDF… » dans le menu Fichier.

Écrire des critères d’acceptation vérifiables

C’est la rubrique qui fait la différence entre une intention et une spec. Un critère vérifiable se coche ou ne se coche pas, sans débat. Comparez « le formulaire doit être rapide » et « le formulaire s’envoie en moins de deux secondes sur une connexion normale ». Le premier se discute sans fin ; le second se teste. Reprenez chaque ligne de la rubrique jusqu’à pouvoir répondre par oui ou par non.

Si vous partez d’une réponse d’IA, collez-la en mode Source, puis remettez chaque idée dans sa rubrique. Ce qui tenait du résumé devient une suite de critères et de décisions que l’équipe peut suivre. Marko affiche le résultat mis en forme pendant que vous réorganisez.

Aperçu du fichier

# Spécification : [nom de la fonctionnalité]

- **Auteur :** Prénom Nom
- **Statut :** brouillon / en revue / validé
- **Dernière mise à jour :** JJ/MM/AAAA

## Problème

Qui rencontre quoi, et pourquoi c'est un problème aujourd'hui.

## Objectif

Le résultat attendu, en une phrase mesurable.

## Hors périmètre

- Ce que cette spec ne couvre pas

## Parcours proposé

1. Première étape du parcours
2. Deuxième étape

## Critères d'acceptation

- [ ] Condition vérifiable 1
- [ ] Condition vérifiable 2

## Questions ouvertes

1. Première question à trancher

## Décisions

> Décision : ce qui a été tranché, par qui, quand.

Les cases à cocher et la citation s’affichent dans Marko et dans la plupart des éditeurs Markdown. Un éditeur de texte simple montre les symboles tels quels.