Méthode · logiciel avec IA · open source
Urazuke, la méthode de la preuve.
Urazuke (裏付け) est le mot japonais pour l'appui que possède une affirmation : ce qui la soutient par derrière. C'est ma méthode pour construire du logiciel avec l'intelligence artificielle qui sorte robuste et prêt pour la production, sans que le propriétaire du projet n'ait à lire une seule ligne de code. Je l'ai distillée de trois systèmes réels que j'ai aujourd'hui en production, en m'appuyant sur l'ingénierie des systèmes de toujours et sur ce que ces systèmes m'ont appris sur les endroits où les modèles l'appliquent de façon fragile.
Auteur : Pablo Kuschniroff, assisté par Claude Code.
Creative Commons BY-SA 4.0 · Huit langues · Neutre vis-à-vis de l'outil · Trois systèmes en production comme source · Open source et collaboratif
La thèse
L'IA n'interrompt pas la méthode : elle la continue.
Avant la thèse, une précision qui m'importe : cette méthode n'est pas une collection de rustines que j'aurais posées après chaque coup dur. Elle vient de deux facteurs combinés. Le premier est ma propre connaissance de l'ingénierie des systèmes : relevé, exigences, dimensionnement, tests comme preuve, déploiement reproductible, audit ; je l'apporte de bien avant l'existence de ces modèles. Le second est ce que trois systèmes en production m'ont montré, incident après incident : où les modèles appliquent ces principes de façon fragile, et donc où il faut serrer par écrit. Les cicatrices prouvent où la rigueur est nécessaire ; elles ne sont pas l'origine des principes.
L'industrie a cessé de faire confiance à l'auteur du code il y a vingt ans. Quand l'écriture est passée à des équipes juniors, externalisées ou tournantes, la revue ligne par ligne est devenue impossible à tenir, et ce qui a poussé à la place est tout ce que nous tenons aujourd'hui pour acquis : tests automatisés, intégration continue, critères d'acceptation, pipelines qui ne laissent rien passer sans vert. Ce fut la réponse de l'ingénierie des systèmes à « celui qui écrit n'est pas fiable » : ne pas lire son code, exiger des preuves. Le modèle est l'auteur suivant, pas le premier à qui on ne fait pas confiance.
Où va l'effort de l'humain
L'humain ne fait que deux choses : il décide, et il vérifie des artefacts. Rédiger, construire, tester, mesurer et documenter, c'est le modèle qui le fait. Chaque marche se termine par une vérification de complétude sans lire de code.
La preuve se prouve elle-même
Un test que vous n'avez jamais vu échouer, vous ne savez pas s'il prouve quelque chose. Un instrument sans test ment. Un rapport sans angles morts cache. La discipline d'indépendance du contrôle qualité, portée un cran plus loin.
Le coût des artefacts
Avant, la documentation coûtait cher et vieillissait. Maintenant la régénérer est gratuit, donc la règle devient « dans le même commit » et « reproductible à la main, sans IA ». Ce qui était un idéal inatteignable devient une porte.
Ce que c'est et ce que ce n'est pas
L'ingénierie des systèmes appliquée à un constructeur qui ne se fatigue pas et qu'on ne peut pas croire.
Pour ceux qui viennent des systèmes, ça sonne familier : relevé, exigences, dimensionnement, conception, construction, test, déploiement, exploitation, audit. Pour ceux qui viennent du vibecoding, ça leur donne ce qui leur manque, qui est justement le squelette.
Ce que c'est
- Une méthode : quoi faire dans quel ordre, quoi demander au modèle, ce qu'il doit livrer, et comment savoir que c'est complet.
- Vingt-quatre marches en quatre tronçons, chacune avec un contrat : contexte, prompts, résultat attendu, vérification, signaux d'alerte.
- Neutre vis-à-vis de l'outil : Claude Code, Cursor, Codex CLI, Gemini CLI ou Forge. Chaque artefact est un fichier, un test ou un script.
- Distillée de trois systèmes réels en production, chaque règle rattachée au commit et au coup dur qui l'a fait naître.
Ce que ce n'est pas
- Un cours de programmation ni d'un framework.
- Une collection d'astuces de prompts pour que le modèle écrive mieux.
- Une méthode pour le prototype de la démo du vendredi : c'est pour ce qui doit continuer à fonctionner après.
- Une méthode qui convient à n'importe quel projet. La marche 0 définit la frontière par écrit.
L'échelle
Vingt-quatre marches, quatre tronçons, dans l'ordre où on les gravit.
Les marches sont numérotées dans l'ordre chronologique où on les gravit. Celles du démarrage une fois par projet ; celles de la boucle à chaque changement ; celles de la mise en production une fois, avant le premier déploiement ; celles de l'exploitation quand le système est vivant. La 23 ferme le cycle et revient à la 0. Chaque marche a une fiche en huit parties et un contrat avec les prompts. Pas de délais : la méthode est un processus, pas une promesse de vitesse.
Une fois par projet, avant d'écrire des fonctionnalités
Les cinq qu'on est le plus tenté de sauter et qui coûtent le plus cher à sauter.
À chaque changement, pendant tout le projet
Dans l'ordre où elles se font avec chaque élément en attente. On les apprend sur les deux premiers blocs et on les pratique pendant tout le projet.
Une fois, avant le premier déploiement
Elles transforment « ça marche » en « ça tient » : audit, verrous, chaîne vers la production, observabilité, persistance, vulnérabilités, performance et manuels.
Quand le système est déjà vivant
Les deux surveillances avec rapport cyclique, l'agent résident et la rétrospective qui ferme le cycle et revient à 0.
Treize marches non négociables dans tout projet
- Éligibilité (une heure ; économise des mois)
- Contrat de collaboration
- Définition courte, avec « ce que ce N'EST PAS »
- Dimensionner avec les chiffres du métier
- Les éléments en attente comme plan
- Décisions avec propriétaire et date
- Tests vus en rouge
- Rapport vérifié / cru / angles morts
- Rétrospective chiffrée
- Analyse des dépendances et des secrets dans la chaîne
- Capture centralisée des erreurs et rapport
- Qualité du code dans la chaîne, au minimum
- Cas de test manuels exécutés par des personnes
La chronologie
Quand on gravit chaque marche, et ce qui se passe entre-temps.
Une méthode sans ligne du temps est une liste de bonnes intentions. Voici celle de tout projet : cinq phases, dans l'ordre, et dans chacune ce qui se fait en plus des marches : l'ingestion des exigences, l'infrastructure, la chaîne d'intégration et de déploiement, le développement, les tests de bout en bout, le regard humain, les tests humains. Sans délais : chaque phase dure ce que le système demande.
Collecte
Relevé avec le propriétaire, avec les méthodes classiques de l'ingénierie des exigences : entretiens, cas d'utilisation, modèle de domaine avec ses états, prototypes d'écran. En prose, incomplet exprès : l'agent le complète en posant des questions.
Démarrage (marches 0 à 4)
Éligibilité, contrat, définition avec l'arbre sémantique, dimensionnement. Et toute l'infrastructure initiale et la chaîne CI/CD : dépôt, environnement de test, intégration continue, premier déploiement avec le système vide. Le propriétaire ouvre l'URL et voit l'écran vide.
Boucle (marches 5 à 12)
Bloc fonctionnel par bloc. À chaque élément en attente : spécification, décisions, test vu en rouge, test de bout en bout du flux, capture d'écran que regarde le propriétaire. À la clôture de chaque bloc : la suite complète de bout en bout et des tests humains dans l'environnement de test.
Mise en production (13 à 20)
Audit par une autre session. Cadenas avant de construire ce qui facture ou envoie. Clôture de la chaîne vers la production avec retour arrière testé. Les trois manuels. Tests d'acceptation du propriétaire sur tous les flux. Et les quatre échelons de qualité opérationnelle avant le déploiement : observabilité, persistance, vulnérabilités, performance.
Exploitation (21 à 23 et la boucle)
Agent résident au nom d'une personne. Audit périodique. Chaque évolution entre par la boucle complète et sort par la chaîne de déploiement. Rétrospective chiffrée à la clôture de chaque étape. Les deux surveillances, ressources et erreurs, mises en place la semaine du premier déploiement, avec un rapport cyclique que le propriétaire lit.
Les tests de bout en bout ne se font pas une seule fois à la fin
À chaque élément en attente, le flux qu'il a touché. À la clôture de chaque bloc, tous les flux qui existent. Avant la production, tous les flux avec la version exacte qui sera promue. Si vous ne faites que la troisième, vous arrivez à la fin avec des semaines non testées.
Les trois cas d'usage
Dossier vide, système fait avec la méthode, ou système hérité : par où l'on entre.
L'échelle est écrite en regardant un dossier vide, qui est le cas le plus clair pour apprendre et non le plus fréquent. Avant d'ouvrir l'agent, il vaut mieux savoir dans lequel des trois cas vous êtes, parce que cela change par où l'on entre. Et le troisième, le système qui existe déjà et n'est pas né avec la méthode, a un chemin propre : on le normalise sans le réécrire, et seulement ensuite on gravit l'échelle.
Projet nouveau
Un dossier vide et un propriétaire avec une demande. On entre par l'échelon 0 et on gravit les vingt-quatre dans l'ordre : une semaine de démarrage avant la première fonctionnalité. C'est ce que décrivent le document principal, les contrats et le cours.
Évolutif-correctif avec la méthode
Le système a déjà gravi l'échelle : il a un contrat, une carte, des éléments en attente clôturés avec preuve, une batterie, un déploiement et des manuels. On entre par l'échelon 5, en ouvrant un bloc, et on suit la boucle. C'est le 15 qui revient au 0.
Évolutif-correctif sans la méthode
Un système qui tourne, avec des utilisateurs, fait par un autre ou par vous-même sans preuve. Huit stations de normalisation (N0 à N7) : récupérer par autodécouverte les intrants que personne n'a écrits, avec des marques de source ; une ceinture de sécurité comme porte dure ; la dette payée à mesure qu'on touche. Ensuite, la boucle en mode correctif ou évolutif.
Lire le chemin évolutif-correctif → Le cours, partie 2 : le projet hérité →
Le contrat de chaque marche
Comment on demande, ce qui doit revenir, et comment je sais que c'est revenu complet.
Chaque marche s'exécute avec un contrat en cinq sections. Les prompts pour le modèle sont en anglais, une seule pièce identique dans les huit versions du document, et sous chacun l'explication, dans la langue du lecteur, de ce que nous demandons et pourquoi chaque clause est là.
Contexte requis
Nommé de façon générique. Les relevés sont par nature incomplets ; on ne les complète pas avec un formulaire, c'est le modèle qui les complète en posant des questions.
Prompts
Textuels. Tous avec la même clause : le modèle évalue si le contexte suffit, demande ce qui manque avant de continuer, et n'estime ni n'invente une donnée que seul le métier possède.
Résultat attendu
Les caractéristiques détaillées de l'artefact : quel fichier, quelles sections, ce qui ne peut pas manquer.
Vérification de complétude
Ce que le propriétaire vérifie sur l'artefact sans lire de code. Si une réponse est « non », la marche n'est pas gravie.
Signaux d'alerte
Les symptômes que la marche a été mal gravie même si elle semble gravie. Ceux qu'on voit des semaines plus tard, quand ça fait déjà mal.
Un prompt d'exemple · marche 7
docs/PENDING.md ; le changement déjà implémenté ; la commande de la suite de tests dans docs/STATUS.md ; et l’environnement de test en marche, avec des données pour le flux touché. Dans la documentation, chaque prompt est précédé d’un bloc comme celui-ci : quels fichiers tu construis, avec quel contenu, et quel est l’état minimal acceptable.Pourquoi en anglais : le même contenu dans une autre langue occupe entre 30 et 50 % de tokens de plus, les modèles suivent les instructions avec plus de précision en anglais, et le vocabulaire du métier est anglais. Mais je ne veux pas que l'anglais soit une barrière : dans la documentation, chaque prompt vient avec sa traduction dans la langue du document et un bouton comme celui-ci. C'est l'anglais que l'on colle au modèle ; la traduction est là pour que vous compreniez. Tous se terminent par « Reply in my language ».
De l'exigence à l'élément en attente
L'ingénierie des exigences de toujours, décomposée en unités qu'un modèle peut construire et que vous pouvez vérifier.
Une exigence n'est pas une phrase du client dans un chat. C'est cette phrase traitée par des méthodes qui existent depuis des décennies et que le modèle applique très bien si vous le lui demandez et très mal sinon : entretiens, cas d'utilisation, modèle de domaine, critères d'acceptation, prototypes d'écran, traçabilité. Dans la méthode, trois artefacts les portent.
L'arbre sémantique
Le système sous forme d'arbre : les domaines ; en dessous, les acteurs, les processus (les cas d'utilisation), les entités avec leurs états, les écrans et les intégrations ; et de chaque nœud pendent les éléments en attente et les décisions. L'agent le construit, vous le corrigez, et c'est ce que l'agent lit avant de toucher au code. Un élément en attente qui ne pend d'aucun nœud est hors périmètre, et cela se voit en dix secondes.
La spécification détaillée vit dans chaque élément en attente
Le long document de spécification qui vieillissait se décompose : chaque élément en attente porte son nœud de l'arbre, l'histoire d'origine avec les mots du client, la description, les règles métier avec leur décision et leur date, les données, les écrans, les cas limites, les critères d'acceptation et la façon de vérifier. Lire cette spécification est ce qui vous rapprochera le plus de la lecture du code, et c'est la bonne distance.
Les éléments en attente clôturés sont de la documentation
Un élément clôturé ne s'efface pas : il reste avec sa spécification, la décision qui l'a fait naître, la preuve avec laquelle il a été clôturé, le commit et la date. La file des éléments clôturés est l'historique fonctionnel du système ; de là sortent le journal des changements, le manuel utilisateur, et la réponse à « pourquoi le système fait-il cela » six mois plus tard.
Avec n'importe quel outil
Les artefacts sont des fichiers, des tests et des scripts. Ce qui change, c'est où ils vont.
Claude Code
Le contrat et les routines vont dans le CLAUDE.md du projet ; les prompts de marche se collent dans le chat en gravissant chaque marche.
Cursor
Les routines vont dans .cursor/rules/ comme règles toujours actives ; le reste, pareil.
Codex CLI / Gemini CLI
Dans AGENTS.md ou GEMINI.md à la racine du dépôt.
Yujin Forge
Le contrat et les routines sont des doctrines, les prompts s'injectent seuls au passage de chaque porte, et le registre des éléments en attente est natif. C'est la même méthode avec moins de copier-coller. Découvrir Forge →
Le cours
Vingt-quatre leçons avec des tâches pratiques, jusqu'à l'application en production.
Un manuel de type cours, une leçon par marche, pour appliquer la méthode sur un projet personnel ou sur le projet guide (« Turnera », un agenda de rendez-vous avec rappels, acomptes et données personnelles : tout ce qu'il faut pour qu'aucune marche ne soit factice). Il se termine par la liste de mise en production : vingt-quatre conditions que le propriétaire vérifie sans ouvrir le code. La partie 2 du cours reprend le même cabinet avec un système hérité (« Turnera héritée ») et enseigne à le normaliser avant de le corriger et de le faire évoluer.
Ce que vous devez comprendre
Le concept de chaque marche, expliqué comme on l'explique à une personne, avec la défaillance réelle qui l'a fait naître.
La tâche, pas à pas
Avec le prompt exact pour l'agent et quoi faire de ce qu'il renvoie. Elle inclut des tests volontaires : laisser une question sans réponse et voir ce qu'il fait.
La vérification et le livrable
Les questions que vous vous posez sur ce qui a été livré, sans ouvrir le code, et le fichier ou la preuve qui doit exister à la fin.
Erreurs typiques et le projet guide
Ce qui arrive à presque tout le monde la première fois, et à quoi ressemble chaque leçon appliquée à Turnera.
Pour celui qui arrive
Le développeur junior à l'ère d'après la programmation à la main.
Si le modèle écrit le code, comment un junior se forme-t-il, qu'apprend-il, et pour devenir quoi ? Un document à part sur les axes de formation qui perdent du poids, ceux qui en gagnent, l'alphabétisation qui reste obligatoire, l'objectif et un plan de douze semaines avec un mentor. Écrit pour les débutants, comme toute la méthode.
En équipe
Plusieurs développeurs, chacun avec son agent, sur une même branche.
La méthode est écrite au singulier. Ce document dit comment elle s'applique quand on est plusieurs : les sept règles de la branche partagée (l'élément en attente comme unité de propriété, intégrer petit et souvent, l'intégration continue comme arbitre, l'inachevé derrière un interrupteur, la carte comme détecteur de conflits, les décisions nominatives, relire la preuve et non le code), comment se répartissent les marches, et les prompts.
Tout le matériel, en huit langues
Lisez-le dans votre langue.
L'espagnol est la source de vérité ; les sept autres versions sont des traductions et, en cas de divergence, l'espagnol prévaut. Les prompts sont identiques dans toutes. Trois documents par langue : le document principal (la thèse, le relevé des trois systèmes, les vingt-quatre marches, les défaillances réelles et le glossaire), les vingt-quatre contrats, et le manuel-cours. Et depuis la version 5, deux documents de plus par langue : le chemin évolutif-correctif, pour les systèmes qui existent déjà, et la partie 2 du cours avec le projet guide hérité.
La méthode est publiée sous Creative Commons Attribution-Partage dans les mêmes conditions 4.0 : on peut l'utiliser, la traduire et l'adapter, avec attribution et sous la même licence. Le dépôt est public et collaboratif : github.com/pkuschnirof/urazuke. Les améliorations entrent par pull request depuis un fork, avec leurs preuves, et je les fusionne après revue.
Est-ce que cela existe déjà sous un autre nom ? J'ai cherché en profondeur ce qui ressemble à cette méthode jusqu'en octobre 2026 (Uncle Bob et son « gauntlet », Tsumiki, Spec Kit, Consort, IACDM, Osmani et d'autres), ce qu'il vaut mieux citer que revendiquer, ce que je n'ai trouvé nulle part, et l'objection la plus sérieuse avec sa réponse. C'est dans la Partie F du document principal, « Travaux connexes ».
Deux manuels d'exécution dans Forge, pas à pas et avec captures, réalisés sur de vrais projets d'entraînement : nouveau projet (Turnera) et projet existant (Turnera héritée). Avec les preuves collectées à chaque échelon (en espagnol).
Deux documents de plus, hors du corpus traduit : les portes expliquées, en anglais, parce que c’est de la documentation d’outil et qu’elle est générée depuis les données ; et les évaluations de modèles d’IA sur la méthode, en espagnol.
Si vous allez consommer la méthode avec un outil, inutile de lire le dépôt : l’interface de données est à yujin.app/urazuke/api/. Son index liste chaque ressource avec son adresse canonique, sa version et son empreinte : gates.json, la définition mécanique des portes, et prompts.json, les prompts. L’empreinte se recalcule sur le contenu, donc une copie périmée se trahit toute seule.
D'où ça vient
Trois systèmes en production, et quarante-six cas documentés avec date et preuve.
J'ai relevé en lecture seule trois dépôts aujourd'hui en production avec de vraies personnes qui les utilisent : l'outil où la méthode s'est formée (mille quatre-vingt-dix commits en cinq mois), un système d'automatisation pour un organisme de santé avec de l'argent et des données sensibles en jeu (six cent quarante et un éléments en attente, tous clôturés), et un guichet omnicanal pour une association civile (le premier où la mesure précède systématiquement la construction). Chaque cas que je cite dans la méthode est numéroté dans le document de références, pour que les procédures restent propres et que le détail reste à un clic. Les clients sont anonymisés ; les chiffres, les dates et les commits sont réels.
Là où le modèle échoue à appliquer l'évidence
L'instrument qui a menti deux fois. L'erreur d'authentification signalée comme un succès. Les trois affirmations sur quatre qui étaient fausses. Chacun m'a dit où un principe qui m'était évident devait devenir une clause explicite du prompt.
Rétrospective chiffrée
J'ai supprimé une équipe entière d'agents avec soixante dollars et soixante-treize minutes contre quatre-vingt-dix minutes. J'ai scindé le déploiement avec vingt-quatre à vingt-sept minutes contre onze. L'échelle elle-même, c'est cela.
Pablo Kuschniroff, assisté par Claude Code
RPAForce / Yujin. La méthode s'applique à elle-même : ses décisions sont consignées avec date et mots textuels, et le dépôt est public depuis le 18 octobre 2026 sur github.com/pkuschnirof/urazuke.
Questions fréquentes
Questions fréquentes.
- Dois-je savoir programmer ?
- Non. Il vous faut un propriétaire du domaine avec du jugement et du temps pour décider, et des notions minimales de ce qu'est un dépôt, un commit et un push. La méthode existe précisément pour que le propriétaire vérifie des preuves au lieu de lire du code.
- Convient-elle à n'importe quel projet ?
- Non, et ce n'est pas un défaut. Il y a deux conditions excluantes : un dépôt standard où déposer les preuves, et des écrans pilotables par programme pour tester de bout en bout. La marche 0 met la frontière par écrit.
- Ai-je besoin de Forge ou de NAC3 ?
- Non. La méthode est neutre vis-à-vis de l'outil ; chaque artefact est un fichier, un test ou un script. Forge automatise les portes et l'injection des prompts, mais la marche existe sans Forge. NAC3 est le moyen par lequel nous obtenons aujourd'hui la testabilité des écrans, pas une condition.
- Pourquoi les prompts sont-ils en anglais si la documentation est dans ma langue ?
- Parce que les modèles suivent les instructions avec plus de précision et moins de tokens en anglais. Chaque prompt est une seule pièce identique dans les huit versions, expliquée dans votre langue en dessous, et se termine par « Reply in my language ».
- Combien de temps prend un petit projet de bout en bout ?
- Je ne donne pas de délai, exprès. La méthode est un processus pour faire des systèmes exploitables et maintenables sans comprendre un bit de code ; ce n'est pas un processus pour construire plus vite, même si la vitesse apparaît comme conséquence. Ce que la méthode fixe, c'est l'ordre et les portes ; la durée de chaque étape, c'est la taille et la complexité de votre système qui la fixent.
- Comment proposer une amélioration ?
- Avec des preuves : la marche 15 demande que chaque rétrospective se termine par une proposition concrète de changement de l'échelle, avec l'incident qui la justifie. Les propositions entrent par pull request depuis un fork sur github.com/pkuschnirof/urazuke et je les examine avant de les fusionner.
Exigez des preuves. Ne lisez pas son code.
Une méthode pour que le modèle construise et que vous décidiez et vérifiiez. En huit langues, sous licence ouverte, et avec les coups durs de trois systèmes réels pour que vous n'ayez pas à prendre les mêmes.