docs/, Astro Starlight, OpenDesigner : comment je partage toute la mémoire d'un projet avec mes clients

Pendant des années, mes specs ont vécu à côté du code. PDF Word ici, Figma là, un Notion partagé avec le client, trois threads d'emails, un Loom enregistré et oublié. Chaque modification produisait du drift. À la troisième itération, plus personne ne savait quelle version faisait foi — ni moi, ni le client, ni l'équipe de dev.

Depuis trois mois, j'ai progressivement basculé tout ça dans un workflow unique, et je crois que c'est l'un des changements de méthode les plus impactants que j'ai faits depuis dix ans. Il s'articule autour d'une idée simple : la mémoire d'un projet doit vivre dans le repo, et chaque acteur — client compris — doit pouvoir y accéder directement, sans intermédiaire humain.

La mémoire en markdown, dans le repo

Première brique, déjà beaucoup couverte dans Le monorepo-mémoire : le vrai levier n'est pas le prompt : tout ce qui décrit le projet — vision, user journeys, data model, ADR, FAQ commerciale, dossier de financement — vit en .md dans un dossier docs/ à la racine. Versionné avec le code. Diff lisible. Pull-requestable.

Sur les projets Coopo (plateforme SaaS de suivi des Protocoles de Coopération HAS) et UNQ (un projet dans le domaine des IA conversationnelles), j'ai aujourd'hui plus de 80 documents markdown dans docs/. C'est la source unique de vérité. Quand un dev (humain ou IA) a une question, il lit le markdown. Quand je me pose une question, je lis le markdown. Quand le client se pose une question, jusqu'ici… il m'envoyait un message Slack et j'allais chercher pour lui.

C'est exactement ce qui a changé.

docs.client.com, déployé avec Astro Starlight

Je passe désormais ces fichiers markdown à travers Astro Starlight, le starter officiel d'Astro spécialisé pour la documentation. J'ai choisi Starlight plutôt qu'un Astro vide parce qu'il câble tout ce qui fait la différence sur un site de doc : nav latérale auto-générée depuis l'arborescence docs/, recherche full-text via Pagefind, callouts, tabs, thème lisible. Le minute zéro de mon site de doc est déjà à 80 % de ce dont j'ai besoin. Et le tout est servi sur un sous-domaine dédié — un docs. chez le client — protégé par un challenge HTTP.

Concrètement, le client accède à 100% de la mémoire du projet, 24/7, sans m'envoyer de mail. Il navigue par chapitre, recherche, copie. Et c'est exactement le point que je cherchais à débloquer en mettant ce pipeline en place : il peut donner l'URL à sa propre instance de Claude. Le client lance une session Claude, lui dit "voici l'URL de la doc du projet, va lire ça avant qu'on parle", et Claude crawle le site en quelques secondes. Au RDV suivant, le client arrive avec des questions structurées que Claude lui a aidé à formuler. La conversation démarre vingt minutes plus loin que d'habitude.

C'est sans doute le détail le plus frappant pour mes clients : ils n'ont jamais eu un accès aussi direct à la cuisine technique d'un projet. La transparence devient une question d'infrastructure, pas de bonne volonté.

OpenDesigner pour les maquettes (et le storybook qui suit)

Deuxième brique, plus récente. Les maquettes, je les faisais sur Figma. Avec Claude Design, j'avais déjà commencé à les générer depuis le PRD — mais les crédits Claude Design partent vite quand on itère.

Je suis donc passé à OpenDesigner, qui fait à peu près la même chose mais en s'appuyant sur ma session Claude Code locale. Sur mon plan Max x20, je peux pilonner sans compter. La seule contrainte que j'ai dû intégrer : OpenDesigner aime les prompts courts. Quelques centaines de mots maximum. J'ai dû réapprendre à briefer compact, ce qui est probablement un bénéfice collatéral en lui-même — la concision force la clarté.

Les maquettes sortent en HTML/CSS/JS, le storybook qui les accompagne aussi. Je déploie le tout sur le même sous-domaine docs., sous /maquettes/... et /storybook/.... Plus de duplication Figma → code, plus de "ah mais sur la maquette tu avais mis 16px de padding". Si c'est dans le storybook, c'est ce qui sera en prod.

Le pattern de Thariq : annoter en HTML, coller dans Claude Code

Troisième brique, importée récemment d'un des core devs de Claude Code, Thariq. La doc purement technique — un data model complexe par exemple — gagne énormément à être structurée en fichiers HTML simples, navigables, plutôt qu'en markdown brut.

Concrètement, je demande à Claude Code de me générer une page HTML qui rend le data model avec ses relations, ses contraintes, ses exemples. Sur chaque entité, un petit champ pour saisir mes commentaires en cours de lecture. Et un bouton "Copy to Claude Code" tout en haut, qui prend tous mes commentaires non vides et les met dans le presse-papier sous une forme directement exploitable.

Quand j'ai fini ma relecture, je fais Cmd+V dans ma session Claude Code, et il prend en compte tous mes retours en une seule passe. Avant, je devais éditer le markdown, ré-uploader le contexte, expliquer ce que je voulais changer. Trois ou quatre allers-retours pour cinq remarques. Aujourd'hui, je relis pendant 20 minutes en buvant un café, je clique, je colle, Claude bosse pendant que je passe au sujet suivant.

C'est anecdotique sur une fois. Sur cinq projets en parallèle, ça libère plusieurs heures par semaine.

Le double harnais : maquettes validées + data model dérivé

C'est probablement le changement de méthode le plus profond. Sans revenir au cycle en V — pas question de figer une spec sur six mois — je valide systématiquement les maquettes avec le client avant tout dev sérieux.

La raison est bête : un markdown, même bien écrit, laisse toujours des ambiguïtés. Le client lit "l'utilisateur voit la liste de ses devis" et imagine quelque chose. Moi j'imagine autre chose. Et l'IA en imagine encore une troisième. Une maquette, ça tranche.

Je vais même plus loin : je transforme ces maquettes en prototypes navigables. Le client clique d'écran en écran comme dans la vraie app. Quand il a fini, on a tous les trois — lui, moi, l'IA — la même image en tête.

Et là, le mouvement clé : une fois les maquettes validées, je demande à Claude Code de générer le data model depuis les maquettes. Pas l'inverse. Parce qu'une fois que je sais quelles données apparaissent sur chaque écran, je sais exactement quelles entités, quels champs, quelles relations je dois modéliser. Le data model qui en sort colle au besoin réel, pas à ma vue d'architecte d'il y a trois semaines.

Et c'est là que je passe du temps. Pas mal de temps, même. C'est ce qui fait, je crois, la vraie différence entre un dev senior très expérimenté et le reste : un coup d'œil sur un data model, et on voit déjà les bugs qu'on va se prendre dans trois mois. Une relation mal posée, une donnée dénormalisée qu'on aurait dû normaliser, une contrainte d'unicité manquante. Corriger ça ici, avant le premier git commit, c'est cinq minutes. Le corriger six semaines plus tard, après que l'API et le frontend ont été construits dessus, c'est plusieurs jours de tests et de debug, parfois avec un client qui s'agace.

Parce qu'une fois le data model bien posé, l'API se construit toute seule — c'est juste du CRUD avec quelques règles métier autour. Et une fois que le storybook est prêt, le frontend se construit tout seul aussi — c'est de l'assemblage de composants validés contre des données validées.

Couplé à mon harnais de tests sur trois niveaux (unitaires, E2E par story, journey cross-story) — celui que je raconte dans 51 stories, 4 sprints, 0 régression — j'obtiens un double harnais : les maquettes verrouillent la surface utilisateur, le data model verrouille la cohérence interne, les tests vérifient que les deux tiennent ensemble. À aucun moment je ne livre quelque chose qui sort de cette gaine.

Ce que ça change concrètement

Trois mois après avoir mis ce pipeline en place, voici ce que j'observe :

• Les RDV client commencent vingt minutes plus loin parce qu'ils sont arrivés en ayant lu (ou fait lire par leur IA) la doc à jour.
• Mes relectures de specs sont passées d'une heure à vingt minutes, parce que je clique pour annoter au lieu d'éditer du markdown.
• Le drift entre spec et code a quasiment disparu — la spec EST le code, ou en tout cas vit dans le même PR.
• Mes temps de tests ont chuté parce que la majorité des cas sont déjà couverts par le couple maquettes + data model.
• Et le bénéfice le plus inattendu : les clients me parlent de la doc comme d'un livrable à part entière. Pas un sous-produit du dev. Un livrable.

Si je devais résumer en une phrase : j'ai arrêté de produire des artefacts éphémères (PDF, Notion, Figma exports) pour produire de la mémoire vivante. Et cette mémoire, je la rends accessible à tous les acteurs du projet — y compris ceux qui ne sont pas humains.

C'est sans doute le plus gros saut qualitatif que j'ai fait dans ma façon de livrer du logiciel ces dix dernières années. Pas parce que les outils sont magiques — Astro existe depuis longtemps, le markdown est vieux comme le web — mais parce que la combinaison change la nature même de la relation avec le client. Il n'attend plus que je l'informe : il se sert. Et son IA aussi.

Si vous êtes fondateur et que vous démarrez un projet, ou que vous avez déjà un MVP mais que vos specs sont éparpillées entre cinq outils, ce workflow peut sérieusement changer la donne pour vous — pour votre rapidité d'itération, pour la qualité de vos relations avec votre équipe technique, et pour le coût de la prochaine personne qui rejoindra le projet (humaine ou IA). N'hésitez pas à me contacter si vous voulez qu'on mette tout ça en place chez vous.