Le specs.md n'est pas un cahier des charges rigide. C'est un document vivant.

10 Septembre 2026

Cet article est un retour d'expérience sur la façon dont j'ai géré la documentation du projet Diet App, l'application de tracking nutritionnel que j'ai construite avec Claude Code (voir l'étude de cas complète pour le contexte du projet).

Tout est parti de specs.md, le tout premier fichier, né d'un brainstorming avec Claude AI avant même d'avoir une app vide sur ma machine. Ce que je n'avais pas anticipé à ce moment-là, c'est qu'il allait en entraîner une dizaine d'autres derrière lui. Ils ne sont pas arrivés d'un coup, selon un plan de documentation posé à l'avance. Chacun est apparu au moment précis où j'en avais réellement besoin, quand continuer sans lui commençait à coûter cher en confusion ou en allers-retours inutiles avec Claude Code.

Ce texte n'essaie pas de vendre une architecture documentaire idéale à copier avant de se lancer. C'est un retour d'expérience sur ce qui est apparu, quand, et pourquoi, et sur ce que ça a changé dans ma façon de piloter Claude Code au fil des lots.

Le premier fichier : specs.md, avant même le code

Le premier fichier du projet, specs.md, n'existait pas avant une session de brainstorming avec Claude AI. L'idée de départ était simple. Transformer le Google Sheets que j'utilisais depuis des années pour suivre ma nutrition en une vraie application mobile. J'ai partagé les CSV extraits du fichier, décrit les fonctionnalités attendues et les comportements UX que je voulais retrouver, et Claude AI m'a aidé à arbitrer les priorités et à fixer le périmètre du MVP.

Cette session a produit deux livrables. Un flowchart FigJam avec les écrans principaux, les enchaînements de navigation et les comportements clés de chaque vue. Et specs.md, pensé dès le départ pour devenir la source de vérité du projet.

Sa première section ne s'adresse pas à moi. Elle s'adresse à Claude Code directement. Langue à utiliser, conventions de naming, et la règle qui fait autorité en cas de divergence avec les autres documents du projet. Placer ces consignes en premier cadre tout le reste avant même d'entrer dans le contenu produit.

Suivent l'architecture globale de l'app, stack technique et structure de fichiers cible, puis chaque écran du MVP détaillé un par un. Démarrage, setup profil, diary, food, recipes, profil. Pour chacun, le layout attendu, les blocs, les comportements, jusqu'aux cas limites. Le schéma data Supabase et les règles de calcul viennent ensuite, avec une première version du design system. Le fichier se termine par une section de notes adressées à Claude Code, pour cadrer ce qui restait ouvert au moment de lancer le premier lot.

Cette structure n'avait rien d'accessoire. Elle donnait à Claude Code un contexte complet avant d'écrire la moindre ligne de code. C'est ce qui a rendu possible le découpage en douze lots séquencés qui a suivi.

Mais specs.md n'est pas resté figé à cet état de départ. Au fil des douze lots, il s'est enrichi, précisé, corrigé, à mesure que des décisions se prenaient pendant le build. Ce qui avait commencé comme un brief de lancement est devenu, avec le temps, une vraie documentation technique de fond, la source de vérité du projet et le fichier qui concentre le contexte le plus riche que Claude Code consulte.

Le premier lot passe, la stack devient dense : documentation.md

documentation.md est arrivé plus tard, une fois les fondations du projet posées. Dépendances installées, Tailwind configuré, tokens en place, premières migrations Supabase jouées. Le jour où j'ai eu besoin de clarifier le rôle de chaque outil et framework de la stack, plutôt que de les garder éparpillés dans ma tête : React, React Native, NativeWind, Metro, Expo, expo-router, TanStack Query, Zustand, Supabase. La structure du projet dossier par dossier, les procédures de build et de test sur mon iPhone. Le fichier s'est construit au fur et à mesure, au fil des besoins de clarification qui se présentaient pendant le build.

Ce contenu n'avait pas sa place dans specs.md, resté concentré sur la vision produit, les écrans et les comportements attendus. Rien à voir avec le fonctionnement interne de la stack ou les conventions de code.

Une fois posé, il est devenu la référence que je consulte encore aujourd'hui pour retrouver une procédure de build ou vérifier une convention, et celle que Claude Code consulte pour comprendre comment le projet est organisé.

Le chantier design system fait naître trois fichiers d'un coup

Le chantier design system a fait naître trois fichiers d'un coup : design-tokens-architecture.md, design-system-rules.md, component-map.md.

Contrairement à specs.md et documentation.md, qui couvrent chacun un domaine large, un seul fichier n'aurait pas suffi ici. Chacun de ces trois-là répond à une question différente.

design-tokens-architecture.md documente l'architecture des tokens en trois couches, primitives, alias sémantiques, tokens composant, et la règle de circulation à sens unique entre elles.

design-system-rules.md condense les règles concrètes de styling, les valeurs de couleurs, de typographie, d'espacement, et les règles critiques à respecter dans chaque composant.

component-map.md fait le lien entre Figma et le code, quel composant Figma correspond à quel fichier source, quelles props, quels usages. Ce fichier a une histoire à part. Figma propose Code Connect pour lier automatiquement les composants Figma au code, mais l'outil n'est disponible qu'à partir du plan Organization, hors de portée pour un projet solo. component-map.md est le substitut que j'ai construit à la main pour compenser cette absence, un mapping exhaustif entretenu manuellement plutôt qu'automatisé.

Séparer ces trois fichiers plutôt que de tout regrouper dans un seul évite qu'il devienne un fourre-tout. L'architecture des tokens, les règles de styling, le mapping Figma, ce sont trois natures de contenu différentes, avec des rythmes de mise à jour différents. Les tokens bougent rarement une fois posés. Les règles de styling évoluent avec chaque nouveau composant. Le mapping Figma se met à jour à chaque session de génération ou de correction dans Figma.

Le workflow Figma MCP impose ses propres fichiers

Le workflow Figma MCP a fait naître deux fichiers supplémentaires, figma-prompt-template.md et figma-etats-manquants.md. Ils sont apparus quand les allers-retours entre Figma et le code sont devenus un usage régulier plutôt qu'une opération ponctuelle.

figma-prompt-template.md répond à un besoin précis, un format de prompt reproductible pour chaque update UI depuis Figma. La frame Figma précise à cibler, le fichier à modifier, les changements à implémenter, les contraintes à respecter, lier une variable existante plutôt que poser une valeur brute, joindre un screenshot en complément du lien. Un format standardisé, pour ne rien oublier d'une session à l'autre et garder la même rigueur à chaque update. Selon l'usage, ce fichier pourrait à terme devenir un skill à part entière plutôt qu'un simple template à copier-coller.

figma-etats-manquants.md répond à un besoin différent, garder une vision claire de ce qui existe des deux côtés, dans la lib Figma et dans le code. Un inventaire des écrans, des états, des interactions, avec les écarts entre les deux. Un audit croisé qui sert de point de départ dès qu'un besoin d'itérer sur un état précis se fait sentir, dans un sens ou dans l'autre.

Ces deux fichiers n'ont pas la même nature que specs.md, documentation.md ou les fichiers du design system. Ce ne sont pas des specs. Ce sont des fichiers de suivi. Ils ne fixent rien de définitif, ils décrivent un état à un instant donné, avec un rythme de mise à jour propre, à chaque session Figma plutôt qu'à chaque décision structurante.

Clôturer une version : audit.md, backlog.md et les ADR

audit.md, backlog.md et les ADR ne sont pas arrivés au même moment.

La pratique de l'audit a commencé tôt, dès la fin des premiers lots. Pas encore de skill à ce stade, je demandais directement à Claude Code de faire un audit en précisant à chaque fois ce qu'il fallait vérifier. Ce n'est qu'après la v0.1, une fois les douze lots terminés, que cette pratique s'est transformée en skill à part entière, /audit, capable de régénérer audit.md sans que j'aie à reformuler la demande à chaque fois.

Une fois le skill en place, audit.md devient un instantané jamais modifié à la main. Points forts, faiblesses classées par sévérité, table de priorité, problèmes résolus depuis le dernier passage. Une photo de l'état réel du code à un instant T, écrasée et remplacée à chaque nouvel audit.

backlog.md et les ADR, eux, sont arrivés au même moment, celui du passage en v0.1. À ce stade, je me suis renseigné sur les bonnes pratiques de documentation, au-delà des fichiers README.md et CHANGELOG.md que je connaissais déjà. C'est cette recherche qui a amené les ADR dans le projet.

backlog.md capture ce qui est reporté. Les tâches classées par priorité, les points de vigilance à vérifier lors des prochaines montées de version, les décisions différées. La façon de clôturer proprement une version sans perdre le fil de ce qui attend.

Les ADR journalisent autre chose, le pourquoi des décisions déjà prises. Comme par exemple pourquoi le projet est mono-utilisateur, sans authentification. Ou pourquoi les macros ne sont jamais stockées mais toujours recalculées. Chaque entrée fixe le contexte, la décision, et ce qui a été écarté. Sans ces fichiers, le risque est de remettre en question plus tard une décision déjà tranchée, faute de trace du raisonnement qui l'avait motivée.

Cette recherche m'a appris quelque chose au-delà des ADR eux-mêmes. Documenter la technique et les états d'un projet ne suffit pas. Documenter les choix, le pourquoi derrière chaque décision, compte tout autant.

Le nombre de fichiers grandit, il faut pouvoir les maintenir

À ce stade du projet, la question n'était plus seulement d'écrire de la documentation. C'était de la garder à jour et cohérente avec l'état réel du code, sans tout repasser à la main à chaque fois. Le dossier docs/ couvrait déjà les spécifications, la stack technique, le design system, le suivi Figma, l'audit, le backlog, les ADR. Vérifier manuellement que chacun de ces fichiers reflétait encore la réalité du projet devenait intenable.

Deux réponses concrètes à ce problème. Le skill /docs-update, une passe systématique qui repasse document par document sur tout le dossier docs/ pour vérifier que chaque fichier est encore à jour. Et la cadence d'audit régulière, portée par le skill /audit, qui régénère audit.md à chaque run sans intervention manuelle.

Ces deux skills ne serviraient à rien sans un mécanisme qui rend les fichiers consultables sans effort. CLAUDE.md, à la racine du projet, déclare les fichiers de référence que Claude Code doit consulter. Une fois ces fichiers déclarés, ils sont pris en compte automatiquement à chaque session, sans avoir à les rementionner dans chaque prompt. D'autres skills viennent s'ajouter à ce socle au fil du temps, /lot pour générer un plan de lot structuré, /debug-error pour structurer le process de debug.

Retours, limites, axes d'amélioration

Avec le recul, plusieurs limites se dégagent.

La première est déjà identifiée dans mon propre backlog. design-system-rules.md grossit avec le projet, un fichier de plus en plus long à mesure que de nouveaux composants et de nouvelles règles s'y ajoutent. La piste envisagée est de basculer vers des .claude/rules/ path-scoped si le fichier devient trop lourd à consulter en entier. Pas encore actée, mais le signal est là.

La seconde touche à la discipline elle-même. Tous les fichiers ne sont pas régénérés automatiquement comme audit.md. component-map.md, figma-etats-manquants.md, et d'autres, dépendent de moi pour rester synchronisés avec la réalité du code ou de la lib Figma. Et ça m'est arrivé concrètement, sur plusieurs fichiers, pas seulement ceux-là. Le skill /docs-update a amélioré les choses, une passe systématique vaut mieux qu'une vérification au hasard. Mais il y a sûrement encore de la marge pour fiabiliser l'ensemble, plutôt que de compter sur ma vigilance seule pour repérer les dérives.

La troisième concerne backlog.md lui-même. Le fichier mélange plusieurs natures de contenu sous un même toit. Des tâches priorisées, une section de surveillance liée à des événements futurs comme les montées de version, et des notes techniques ponctuelles remontées par /audit. C'est exactement le genre de situation qui a fait naître trois fichiers séparés pour le design system. backlog.md n'a jamais été scindé de la même façon, alors qu'il porte plusieurs rôles différents.

Ce dernier point en ouvre un autre. /audit se contente aujourd'hui de régénérer audit.md. Une piste d'amélioration concrète serait qu'il aille plus loin, proposer un échange, quelques questions pour prioriser les tâches détectées, et les intégrer directement dans backlog.md plutôt que de me laisser faire ce classement à la main à chaque fois.

Plus largement, à force d'accumuler ces fichiers et ces skills, une question commence à se poser. Celle d'une vraie architecture documentaire plutôt qu'une accumulation de fichiers ajoutés un par un. On entrevoit l'intérêt d'une documentation plus holistique, qui relierait le technique, le fonctionnel et le design plutôt que de les garder dans des fichiers séparés qui ne se parlent qu'à travers moi. Une idée à plus long terme. Pas encore un chantier, mais elle commence à prendre forme.

Conclusion

Autant de fichiers que de moments différents dans le projet. Aucun n'existait avant que j'en aie besoin, et aucun n'est arrivé selon un plan que j'aurais pu écrire à l'avance. Les skills, eux, ne sont venus qu'une fois la charge de maintenance devenue trop lourde pour rester manuelle.

Ce que je retiens de cette construction, c'est moins la liste des fichiers que le rythme dans lequel ils sont apparus. specs.md a posé la vision avant le code. documentation.md a posé la stack une fois qu'elle existait vraiment. Le design system a demandé trois fichiers distincts le jour où une cohérence stricte est devenue nécessaire. Le workflow Figma a demandé les siens le jour où les allers-retours sont devenus réguliers. audit.md, backlog.md et les ADR ont fermé le premier cycle en documentant non seulement l'état du projet, mais aussi les choix qui y ont mené.

Et la dernière partie de cet article le montre bien, cette construction n'est pas terminée. Certains fichiers grossissent, d'autres dépendent encore trop de ma seule vigilance, et la question d'une vraie architecture documentaire, plutôt qu'un empilement de fichiers ajoutés un par un, commence tout juste à se poser.

Si ce texte doit servir à quelque chose au-delà de mon propre projet, c'est probablement ça. Laisser la documentation naître du besoin réel plutôt que de la designer à l'avance dans le vide, tout en acceptant qu'elle va continuer à demander du travail à mesure qu'elle grandit.