On ne peut pas mettre le développement sur pause. C'est la première chose à accepter. Les tickets continuent d'arriver, les clients attendent les livraisons, et votre code existant ne s'arrête pas de tourner simplement parce que vous avez décidé de le documenter. Aucun responsable ingénierie ne donnera son feu vert pour un gel de développement d'un mois afin que l'équipe puisse écrire la spécification qui aurait dû exister dès le premier jour. OpenSpec a été conçu pour la réalité, pas pour les fantasmes de projets partant de zéro. Il fonctionne mieux lorsqu'on l'ajoute par-dessus ce que l'on possède déjà, clients compris.
L'objectif ici n'est pas une réécriture. C'est de l'archéologie honnête. Vous déterrez ce qui tourne réellement en production, vous le décrivez avec précision, et vous laissez cette description évoluer au rythme de votre code. Lorsque votre spécification correspond à votre système, vous facilitez la tâche des ingénieurs qui rejoindront l'équipe au prochain trimestre et des outils d'IA qui résident désormais dans votre IDE. Voici comment procéder sans manquer une seule mise en production.
Commencez par ce que vous faites réellement
Ouvrez votre dépôt et vous verrez des dossiers nommés controllers, models, services et utils. Ce sont des couches techniques, et elles vous mentent. Elles ne décrivent pas ce que votre système fait pour l'entreprise. Un dossier rempli de fichiers JavaScript n'explique pas comment une commande devient une expédition. Pour adapter OpenSpec, vous devez penser en termes de capacités.
Recherchez les opérations métier stables qui survivraient même si vous réécriviez toute la pile dans un autre langage. Dans la plupart des entreprises de produits, elles reviennent sans cesse : Commandes, Facturation, Inventaire, Clients et Notifications. Nommez cinq à huit de ces capacités fondamentales.
Pour chacune d'elles, forcez-vous à répondre à cinq questions spécifiques. Quel problème du monde réel cette capacité résout-elle ? Où le code se trouve-t-il réellement — dans un seul service, trois microservices, ou un module hérité que personne ne veut toucher ? Qu'est-ce qui la déclenche : un clic utilisateur, une tâche cron planifiée, un webhook entrant ? Quelles données entrent et quelles données sortent ? Et enfin, de quels autres systèmes dépend-elle, c'est-à-dire qu'est-ce qui casse si cette pièce s'arrête de fonctionner ?
Soyez d'une honnêteté brutale. Si votre capacité « Clients » est éparpillée sur un monolithe Rails, une API Node et un CRM externe, écrivez-le exactement ainsi. Votre carte doit ressembler au territoire, pas au rêve d'un architecte.
Écrivez la vérité, pas une liste de souhaits
La phrase la plus dangereuse dans tout effort de documentation est : « Puisque nous sommes en train de l'écrire, autant en profiter pour le corriger. » Arrêtez-vous. Vous n'êtes pas en train de redessiner le flux de paiement. Vous décrivez le flux de paiement qui encaisse de vraies cartes de crédit en ce moment même.
Si la passation d'une commande déclenche un prélèvement immédiat puis envoie un e-mail via un worker en arrière-plan, documentez cette séquence exacte. N'insérez pas une file d'attente d'événements que vous prévoyez d'ajouter au prochain trimestre. Ne prétendez pas que la validation se produit à la périphérie de l'API si elle réside en réalité profondément à l'intérieur d'une classe de service. La précision importe bien plus que l'aspiration.
Une documentation incorrecte est pire que l'absence de documentation. Elle apprend aux nouvelles recrues à s'attendre à un comportement qui n'existe pas. Elle envoie les assistants de codage IA sur des chemins imaginaires basés sur des souhaits infondés. Lorsque votre spécification correspond à la production, vous créez une base fiable. Le débogage devient plus rapide car vous arrêtez de deviner le flux « prévu ». La refactorisation devient plus sûre car vous savez que le point de départ est réel.
Extrayez les contrats de vos API
Vos points de terminaison d'API imposent déjà des règles. Elles sont simplement implicites. Adapter OpenSpec signifie rendre ces règles explicites.
Commencez par les entrées et la validation. Qu'est-ce que le point de terminaison accepte réellement ? Documentez les types, les champs obligatoires, les longueurs maximales et les dépendances entre les champs. Ensuite, décrivez le comportement métier. Cet appel crée-t-il un enregistrement, déclenche-t-il un effet de bord ou valide-t-il simplement un état par rapport à un autre service ? Soyez spécifique.
Enfin, répertoriez les réponses. Que renvoie un succès ? Quels sont les codes d'erreur exacts et dans quelles conditions apparaissent-ils ? N'écrivez pas « renvoie une erreur ». Écrivez « renvoie 422 lorsque l'adresse de facturation est manquante et 409 lorsque l'inventaire a déjà été réservé par un autre processus ». Ce niveau de précision transforme une route vague en un contrat en lequel les équipes frontend, les ingénieurs QA et les outils automatisés peuvent avoir confiance.
Traquez les règles cachées
Une partie des connaissances les plus précieuses de votre système se cache dans les interstices. Elles sont enfouies dans des blocs conditionnels au sein de classes de service, nichées dans des déclencheurs de base de données, ou