17 juin 2026Mis à jour le Fathy Shalaby13 min de lecture
Modèle de spécification technique : écrire une spec que les ingénieurs lisent vraiment
Un modèle de spécification technique à copier, les pratiques de design docs et de RFC dont il s’inspire, et une méthode pas à pas pour écrire une spec que les ingénieurs lisent jusqu’au bout.
Un modèle de spécification technique doit placer les décisions risquées en première page : le problème et ses contraintes, la conception proposée, les alternatives écartées et ce qui pourrait mal tourner, sur une à trois pages pour la plupart des changements. Les design docs de Google et les RFC d’Uber suivent cette forme. Le modèle à copier ci-dessous y ajoute un résumé en une phrase et un tableau de décisions, pour que les relecteurs repèrent les choix difficiles en moins d’une minute.
À retenir
Les design docs de Google comptent cinq sections essentielles et font de 10 à 20 pages pour les grands projets, mais de 1 à 3 pages pour un travail incrémental (Malte Ubl, 2020).
Les lecteurs parcourent environ 20 % des mots d’une page web moyenne, 28 % au maximum (Nielsen Norman Group, 2008). Les specs sont lues de la même façon : on les balaie à la recherche des passages qui pourraient être faux.
61 % des développeurs passent plus de 30 minutes par jour à chercher des réponses (Stack Overflow, 2024). Une spec qui consigne les décisions répond à ces questions une fois pour toutes.
Les équipes dotées d’une documentation de qualité ont 3,8 fois plus de chances d’appliquer les bonnes pratiques de sécurité (DORA, 2021).
« Alternatives envisagées » est la section à laquelle les relecteurs se fient le plus, car elle montre que vous avez cherché une raison de ne pas construire la chose ainsi.
Qu’est-ce qu’une spécification technique, et en quoi diffère-t-elle d’un PRD ?
Une spécification technique (aussi appelée design doc ou document de conception technique) explique comment une équipe va construire quelque chose et quels compromis elle accepte. Un PRD explique quel problème mérite d’être résolu, pour qui, et comment on mesurera le succès. Le PRD vient en premier ; la spécification technique y répond.
Les équipes utilisent quatre documents voisins. Les confondre est la raison la plus fréquente pour laquelle une spec atteint 15 pages que personne ne finit.
Quel problème, pour qui, et comment saurons-nous que ça a marché ?
Product manager
2–5 pages
Spécification technique / design doc
Comment allons-nous le construire, et quels compromis acceptons-nous ?
Tech lead ou ingénieur
1–3 pages (10–20 pour les grands systèmes)
RFC (request for comments)
L’organisation au sens large approuve-t-elle ce plan avant le début du travail ?
Auteur et approbateurs nommés
Comme une spec, avec une date limite de relecture
ADR (architecture decision record)
Pourquoi avons-nous pris cette décision précise, et qu’en découle-t-il ?
L’ingénieur qui a tranché
1–2 pages
Les consignes de Google décrivent le design doc comme le lieu où documenter la stratégie d’implémentation de haut niveau et les décisions de conception clés, en insistant sur les compromis. Le format d’ADR de Michael Nygard, publié en 2011, le réduit à une seule décision en cinq parties : titre, contexte, décision, statut et conséquences (Michael Nygard, 2011). Si vous voulez commencer par le côté produit, lisez d’abord le guide pour rédiger un PRD.
Pourquoi les ingénieurs ignorent-ils la plupart des spécifications techniques ?
Les ingénieurs ignorent les specs qui répondent à des questions que personne n’a posées et qui cachent celles qui comptent. Trois travers expliquent l’essentiel.
Elles sont écrites pour être complètes, pas pour trancher. L’analyse de Jakob Nielsen en 2008 a montré que, sur une page moyenne de 593 mots, les lecteurs avaient le temps de lire 28 % des mots au plus, et plus probablement 20 %. Ils ne venaient à bout que de la moitié du contenu sur les pages de 111 mots ou moins. Un relecteur qui a six specs dans sa file lit de la même manière : le résumé, le schéma, le texte en gras, puis la section avec laquelle il n’est pas d’accord.
Elles noient le choix risqué dans de la prose uniforme. Si la décision irréversible se trouve au neuvième paragraphe, chaque relecteur doit la redéduire. C’est précisément le gaspillage qu’une spec est censée éviter.
Elles deviennent obsolètes. L’enquête Stack Overflow Developer Survey 2024 a constaté que 61 % des répondants passent plus de 30 minutes par jour à chercher des réponses, et que 30 % disent que les silos de connaissances nuisent à leur productivité 10 fois ou plus par semaine. Une spec qui ne correspond plus au code devient une source de plus de mauvaises réponses.
Le bénéfice d’une bonne pratique est mesurable. Les recherches DORA de 2021 ont montré que les équipes disposant d’une documentation de qualité avaient 3,8 fois plus de chances d’appliquer les bonnes pratiques de sécurité et 2,5 fois plus de chances d’exploiter pleinement le cloud.
Que doit contenir une spécification technique ?
N’incluez que ce qui change la façon dont quelqu’un construirait ou relirait le travail. Deux pratiques publiées donnent une bonne base.
Les sections du design doc de Google
Le texte de Malte Ubl de 2020 sur les design docs chez Google énumère les sections que la plupart des documents partagent :
Contexte et périmètre : l’environnement dans lequel vit le système, en quelques paragraphes.
Objectifs et non-objectifs : ce que le système doit faire, et ce qu’il ne fera explicitement pas.
La conception proprement dite : schéma du système, API, stockage des données, et code ou pseudo-code uniquement lorsqu’il éclaire un algorithme inédit.
Alternatives envisagées : les autres conceptions et pourquoi elles ont perdu.
Préoccupations transverses : sécurité, confidentialité et observabilité.
Les sections des RFC d’Uber
Le processus de RFC d’Uber a grandi avec l’entreprise, de quelques dizaines d’ingénieurs à environ deux mille, selon Gergely Orosz, qui y a travaillé (The Pragmatic Engineer, 2018). Son modèle backend s’ouvrait sur une liste d’approbateurs, puis couvrait les changements d’architecture, les SLA des services, les dépendances, les tests de charge, les enjeux multi-datacenters, la sécurité, les tests et le déploiement, les métriques et la supervision, ainsi que le support client. Le modèle mobile y ajoutait l’interface et l’accessibilité. Des sections ont été ajoutées à mesure que l’entreprise découvrait ce qu’elle oubliait sans cesse.
La leçon commune : un modèle de spécification technique est une liste de contrôle des erreurs passées. Commencez petit et n’ajoutez une section que lorsque son absence a causé un vrai problème.
Modèle de spécification technique (à copier et adapter)
Ce modèle de spécification technique combine les sections de Google, l’habitude d’Uber de placer les approbateurs en tête et le format de décision de Nygard. Supprimez toute section qui dirait « sans objet ».
# [Nom de la fonctionnalité ou du système] : spécification technique
**Résumé :** Nous faisons [X] pour atteindre [Y], en acceptant le compromis de [Z].
**Auteur :** [nom] · **Approbateurs :** [2–3 noms] · **Relecture avant le :** [date]
**Statut :** Brouillon | En relecture | Approuvée | Remplacée par [lien]
**PRD / ticket associé :** [lien]
## 1. Problème et contraintes
- Ce qui ne fonctionne pas, qui en souffre, et ce qui devient possible une fois
le problème réglé.
- Contraintes strictes : budget de latence, résidence des données, rétro-
compatibilité, le SLA que vous ne pouvez pas enfreindre.
## 2. Objectifs et non-objectifs
- Objectifs (mesurables si possible).
- Non-objectifs : ce qu’un lecteur raisonnable pourrait attendre et que nous ne ferons pas.
## 3. Décisions clés (à lire en premier)
| # | Décision | Réversible ? | Risque si elle est mauvaise | Confiance |
|---|----------|-------------|---------------|------------|
| 1 | | Porte à sens unique / à double sens | | Haute / Moyenne / Faible |
## 4. Conception proposée
- Un seul schéma. Changements d’API et de modèle de données. Pseudo-code
uniquement pour ce qui est inédit.
## 5. Alternatives envisagées
- Option A : pourquoi elle a perdu.
- Option B : pourquoi elle a perdu.
- Ne rien faire : ce qui se passe si nous ne construisons pas cela.
## 6. Risques et questions ouvertes
- Hypothèses porteuses et comment nous les vérifierons.
- Questions à trancher avant ou pendant la construction.
## 7. Préoccupations transverses
- Sécurité et confidentialité · Observabilité · Accessibilité · Coût.
## 8. Déploiement, validation et retour arrière
- Feature flag / plan de déploiement progressif.
- Métriques qui prouvent que ça marche, et seuil qui déclenche le retour arrière.
## 9. Journal des décisions
- [date] [Décision] modifiée parce que [raison]. (À mettre à jour ici, pas dans un commentaire de PR.)
Le tableau de décisions de la section 3 est ce qui donne sa valeur au modèle. Marquer chaque décision comme porte à sens unique ou à double sens indique aux relecteurs où concentrer leur attention. Le cadre des décisions réversibles et irréversibles explique comment juger laquelle est laquelle.
Quelle longueur pour une spécification technique ?
Aussi courte que la décision la plus risquée le permet. Les consignes de Google situent les design docs de grands projets autour de 10 à 20 pages et jugent acceptables des « mini design docs » de 1 à 3 pages pour un travail incrémental. Les ADR de Nygard font une ou deux pages. Amazon remplace les diapositives par des « mémos de six pages à structure narrative », lus en silence au début de chaque réunion, et Jeff Bezos a écrit qu’un bon mémo demande probablement une semaine ou plus de rédaction (Amazon, 2018).
Une règle pratique, selon l’ampleur du changement :
Changement
Format
Longueur
Relecture
Correction de bug, changement de texte, ajustement de config
Description du ticket
Un paragraphe
Revue de code uniquement
Nouvel endpoint ou composant au sein d’un service
Mini-spec
1 page
Un approbateur, en asynchrone
Fonctionnalité touchant 2–3 services ou une API publique
Spécification technique (modèle ci-dessus)
2–3 pages
2–3 approbateurs, fenêtre de 2–3 jours
Nouveau système, migration de données ou frontière de sécurité
Design doc complet ou RFC
5–20 pages
Réunion de relecture formelle
Les consignes de Google précisent aussi quand ne pas en écrire : lorsque la solution est sans ambiguïté et que le document ne serait qu’un mode d’emploi d’implémentation sans compromis à discuter.
Comment écrire une spec que les ingénieurs lisent vraiment ?
Rédigez-la dans cet ordre. L’essentiel du travail consiste à décider ce qu’il faut omettre.
Écrivez d’abord le résumé en une phrase. « Nous faisons X pour atteindre Y, en acceptant le compromis de Z. » Si vous n’y arrivez pas, vous n’êtes pas prêt à écrire la spec, et vos relecteurs ne pourront pas la résumer non plus.
Ouvrez avec le problème, pas avec la solution. Les ingénieurs ne peuvent juger une conception avant de connaître les contraintes qu’elle sert. Énoncez les points non négociables avant le schéma d’architecture.
Remplissez le tableau de décisions. Listez chaque décision qu’un relecteur pourrait raisonnablement contester. Mettez en gras les portes à sens unique.
Rédigez les alternatives honnêtement. Incluez « ne rien faire ». Une spec sans option écartée donne l’impression d’une décision déjà prise.
Nommez deux ou trois approbateurs et une date limite de relecture. Uber listait les approbateurs en tête de chaque RFC. Une spec sans décideur ni date a tendance à rester indéfiniment en relecture.
Relisez en asynchrone, ne vous réunissez que pour les désaccords. Les commentaires dans le document couvrent l’essentiel des retours. Si vous vous réunissez, faites comme Amazon et consacrez les dix premières minutes à la lecture silencieuse.
Mettez la spec à jour quand la construction la modifie. Dans le cycle de vie décrit par Google, le document se révise pendant l’implémentation. Consignez les changements dans le journal des décisions, pas dans un commentaire de pull request que personne ne retrouvera.
Orosz note qu’une fois qu’une équipe s’accorde sur un plan, l’écrire prend généralement quelques heures. Si cela prend des jours, le désaccord est la vraie découverte.
Exemple détaillé (à titre d’illustration)
Supposons qu’une équipe de six personnes doive empêcher les webhooks lents de clients de faire expirer le paiement. Leur phrase de résumé : « Nous déplaçons l’envoi des webhooks vers une file d’attente pour que le paiement n’attende jamais le serveur d’un client, en acceptant jusqu’à 60 secondes de retard de livraison. »
#
Décision
Réversible ?
Risque si elle est mauvaise
Confiance
1
Passer à une livraison au moins une fois ; les clients doivent dédoublonner par ID d’événement
Porte à sens unique (contrat public)
Commandes en double dans les systèmes des clients
Moyenne
2
Utiliser la base Postgres existante comme file d’attente plutôt qu’un nouveau broker
Porte à double sens
Plafond de débit en pic ; migrer plus tard
Haute
3
Réessayer cinq fois sur 24 heures, puis marquer comme échoué
Porte à double sens
Certains clients manquent des événements lors de longues pannes
Haute
Les relecteurs voient en 30 secondes que la décision 1 mérite le débat : elle modifie un contrat d’API public, exige une note de migration pour les clients et ne peut pas être annulée discrètement. Les décisions 2 et 3 peuvent être approuvées dans un commentaire.
Quelles sont les erreurs courantes avec les spécifications techniques ?
Écrire la spec après le code. Une spec rédigée pour justifier une pull request terminée n’a pas d’alternatives et ne détecte rien.
Cinq schémas au lieu d’un. Un seul schéma du système avec le changement mis en évidence vaut mieux que cinq qui montrent tout.
Traiter le modèle comme un formulaire. Les sections « sans objet » vides apprennent aux lecteurs à survoler. Supprimez-les.
Aucun responsable pour les questions ouvertes. Chaque question ouverte a besoin d’un nom et d’une date, faute de quoi elle devient un incident de production.
Figer le document. Une spec qui ne correspond plus à la réalisation est pire que pas de spec, parce que les gens lui font confiance.
Utiliser une spec là où un prototype répondrait plus vite. Si la question risquée est « cette bibliothèque tiendra-t-elle notre charge ? », un spike d’une journée vaut mieux qu’un argumentaire de cinq pages.
Comment les spécifications techniques évoluent-elles avec les agents de code IA ?
Les agents de code lisent les specs au pied de la lettre. L’ambiguïté qu’un ingénieur humain lèverait sur Slack devient du code qu’un agent écrit de travers avec assurance. Les parties du modèle qui comptent le plus pour un agent sont les non-objectifs, les contraintes et des critères d’acceptation testables. Le modèle de PRD pour agents de code IA montre comment les expliciter. Une fois la spec approuvée, découper le PRD en user stories est l’étape suivante, et un pre-mortem de lancement met le plan de déploiement à l’épreuve avant la mise en production.
Où Specky s’intègre-t-il ?
L’écart entre l’intention documentée et la réalité livrée s’ouvre généralement lorsque exigences, décisions et tickets vivent dans des outils différents. Specky rédige des PRD dans un éditeur avec des citations en ligne renvoyant aux preuves clients, génère des tickets avec des critères d’acceptation testables et consigne les décisions dans un Product Graph pour que le « pourquoi » reste attaché au travail. Les agents de code peuvent lire ce contexte via un serveur MCP. C’est toujours l’ingénieur qui écrit la conception technique ; le contexte produit qui l’entoure reste à jour. Si trouver du temps pour écrire est le goulot d’étranglement, l’exemple d’emploi du temps hebdomadaire d’un PM protège un créneau de concentration pour cela.
Questions fréquentes
Quelle est la différence entre un PRD et une spécification technique ?
Un PRD définit le problème, les utilisateurs et la manière de mesurer le succès ; une spécification technique définit comment l’équipe va construire la solution et quels compromis elle accepte. Le product manager est généralement responsable du PRD et le tech lead de la spec. Rédigez d’abord le PRD, puis liez-le depuis la spec pour que les relecteurs puissent confronter la conception à l’objectif initial.
Qui doit écrire la spécification technique ?
L’ingénieur ou le tech lead qui sera responsable de la construction doit écrire la spécification technique, et le product manager la relit au regard du PRD. L’auteur répond des décisions, pas du fait de taper chaque section. Dans une petite équipe, le PM peut rédiger les sections problème, objectifs et non-objectifs, et l’ingénieur complète la conception, les alternatives et le plan de déploiement.
Quelle longueur pour un document de conception technique ?
La plupart des documents de conception technique devraient faire une à trois pages. La pratique de Google juge normaux les mini design docs de 1 à 3 pages pour les changements incrémentaux et réserve 10 à 20 pages aux grands systèmes nouveaux. Si votre spec dépasse trois pages pour une fonctionnalité au sein de services existants, elle mélange probablement plusieurs décisions qui devraient être des ADR distincts.
Qu’est-ce qu’une RFC en ingénierie logicielle ?
Une RFC (request for comments) est un plan écrit partagé avec l’ensemble de l’organisation d’ingénierie avant le début du travail, afin que d’autres puissent signaler des risques. Uber a utilisé les RFC en passant de quelques dizaines à environ deux mille ingénieurs, en listant des approbateurs nommés en tête de chacune. Une RFC, c’est une spécification technique plus un processus de relecture, une échéance et un décideur.
Quand ne faut-il pas écrire de spécification technique ?
Passez la spec lorsque la solution est sans ambiguïté et qu’il n’y a pas de compromis significatif à discuter, ce qui est la limite que tracent les consignes de Google. Les corrections de bugs, les petits changements d’interface et les mises à jour de configuration relèvent d’un ticket. Si la principale incertitude porte sur la faisabilité technique, lancez d’abord un spike limité dans le temps et écrivez la spec une fois que vous savez ce qui fonctionne.
Qu’est-ce qu’un architecture decision record (ADR) ?
Un ADR est une fiche d’une ou deux pages sur une seule décision d’architecture. Le format de Michael Nygard, datant de 2011, comporte cinq parties : titre, contexte, décision, statut et conséquences. Beaucoup d’équipes conservent leurs ADR dans le dépôt de code, afin que les futurs ingénieurs voient pourquoi quelque chose a été construit d’une certaine façon. Utilisez les ADR pour les décisions qui survivent à une spec isolée.
GDPR-aligned. EU workspace data is stored in Frankfurt, Germany. GDPR and EU data Built in Vienna, Austria. A product of influence solutions fm GmbH (FN 675374y). Imprint 14-day trial. Card required, and nothing is charged until day 14. 30-day refund after subscribing. See pricing