Je committe des spécifications en coréen à la place du code — une app PWA + serveur avec 3 pages de specs

Il y a une chose sur laquelle je butais sans arrêt en faisant coder l’IA. Le code produit reste, mais la conversation et l’intention qui ont permis de le générer disparaissent. Trois mois plus tard, il n’y a plus personne à qui demander : « Pourquoi ce code est-il comme ça ? »

J’ai donc inversé l’approche. Je committe dans git des spécifications qui portent l’intention, et je traite le code comme un artefact de build. Pour vérifier l’idée, j’ai créé puis publié de bout en bout une petite application.

C’est une PWA appelée Rimlog : pour les notes de lecture et d’apprentissage, l’IA rattache d’anciennes notes au fil du temps. Pas de serveur, pas d’inscription, et les données restent uniquement dans le navigateur.

L’app est assez ordinaire. Ce que je veux partager, c’est la manière dont elle a été construite.

Méthode

Dans le dossier eux/ du dépôt, il y a 3 pages de spécifications en coréen. L’ossature complète de l’app tient en 40 lignes, le widget de cartes IA en 25 lignes, et le serveur d’insights en une page. On y trouve des phrases comme celle-ci.

saveCapture : enregistrer le formulaire de capture (nom de la source · citation · ma réflexion · tags) — insertion en tête de captures + répercussion dans le local storage + toast « Enregistré » + bascule vers l’onglet historique.

Si on donne ces fichiers à un outil nommé EstreUX, il génère du code (j’appelle ça brew). Le code généré embarque le hash de la spécification, et si l’on modifie uniquement la spec ou uniquement le code, le commit est bloqué au pre-commit. L’idée est de bloquer, via un garde-fou, le moment où la spec devient obsolète et commence à mentir.

J’ai aussi mesuré l’effet. En reprenant par exemple un pavé numérique de 152 lignes déjà présent dans le framework et en le ramenant à une spec de 28 lignes, les mesures montrent que le nombre de lignes maintenues par un humain baisse de 60 à 82 %. Le code généré lui-même peut devenir plus long que l’original. Ce qui diminue, c’est la partie que les humains doivent lire et modifier. Le journal de mesure est dans le dépôt.

Le serveur aussi tient sur une page de spec

La démo Pages étant serverless, l’IA n’y aide qu’avec un fallback par recouvrement de tags. Pour faire tourner le tout correctement, j’ai ajouté un serveur auto-hébergé ; lui aussi est un unique fichier Node sans dépendance, brewé à partir d’une seule page de spec. Le backend se choisit à la carte.

• nvidia (par défaut) : l’API gratuite de build.nvidia.com. Elle fournit une clé sans carte bancaire, est compatible OpenAI et permet environ 40 requêtes par minute, ce qui est largement suffisant pour un journal personnel
• claude-cli / codex-cli : à chaque requête, le serveur appelle claude -p / codex exec comme processus enfant. C’est une façon de réutiliser un abonnement Claude/ChatGPT déjà payé, sans clé API
• openai / google : simple proxy de clé

Les clés et l’authentification restent uniquement côté serveur et ne sortent jamais vers le navigateur.

Les points sur lesquels je ne suis pas encore sûr

Je suis en train d’étendre le jugement de conformité spec↔code, au-delà d’un diff statique, vers une vérification dynamique basée sur les propriétés, mais le calibrage des pondérations n’est pas encore au point. J’ai aussi découvert une classe de faux positifs où le rendu du framework en environnement DOM headless se comporte différemment du vrai navigateur ; faire monter l’environnement de validation vers un vrai navigateur fait donc aussi partie des chantiers. Si vous regardez l’historique des commits depuis le début, vous verrez dans l’ordre le processus scaffold → spec → génération → affinage.

• Live : https://soliestre.github.io/Rimlog/
• Dépôt : https://github.com/SoliEstre/Rimlog
• Journal de build (détaillé) : https://estreui.tistory.com/5

J’ai deux questions. Quels pièges voyez-vous dans une approche où la spec devient la SSoT ? En particulier, à quel moment avez-vous rencontré des limites où le pouvoir d’expression de la spec n’arrivait plus à suivre le code ? Et concernant cette voie de réutilisation d’abonnement qui consiste à utiliser claude -p comme backend d’application, voyez-vous des points bloquants en usage réel (du point de vue du débit, des conditions d’utilisation ou de la latence) ?