Un assistant de code montre chaque changement sous la forme d'un diff texte : des lignes rouges, des lignes vertes, et un humain qui approuve ou refuse. Ce mécanisme est ce qui rend Claude Code ou Codex utilisables sur un vrai dépôt. C'est aussi leur limite. On approuve des lignes. On n'approuve pas un comportement.

Le diff texte répond à la question « qu'est-ce qui a changé dans le fichier ». Il ne répond pas à « qui appelle qui, dans quel ordre, et que se passe-t-il quand ça échoue ». Cette question-là, personne ne la pose plus, parce que le code arrive plus vite qu'on ne peut le lire.

Le diagramme est le contrat. Rien ne se code avant validation.

Ce texte propose un déplacement simple : appliquer au design le mécanisme qui marche déjà sur le code. L'assistant propose un diagramme. L'humain voit ce qui change dans ce diagramme, en couleur, comme un diff. Il valide. Alors seulement l'assistant écrit du code, et le diagramme régénéré depuis ce code est comparé, visuellement, à celui qui a été validé. Le nom proposé pour cette pratique est Design-Gated Development (DGD). Le mot important est gated : ce qui compte n'est pas le diagramme, c'est la porte placée devant l'implémentation.

Le problème : la dette de compréhension

Le terme vibe coding vient d'un message d'Andrej Karpathy en février 2025. Il décrit une pratique précise : accepter le code produit par un modèle sans le lire, relancer le modèle sur l'erreur suivante, et itérer jusqu'à ce que la chose tourne. Sur un prototype jetable, c'est rationnel. Sur un système qui vivra deux ans, c'est un emprunt. Le message d'origine

La dette de compréhension se mesure par l'écart entre ce que le système fait et ce que l'équipe sait expliquer. Elle se cumule en silence, car chaque incrément généré s'appuie sur le précédent sans que personne n'ait relu la structure. Et elle se rembourse d'un coup, le jour où il faut raisonner sur le système sans le modèle : un incident, un audit, une reprise par une autre équipe.

Le goulot n'est pas la production du code. Le goulot est la lecture. Aucun relecteur ne tient le rythme d'un modèle qui génère, et la revue de code après coup, héritée du travail entre humains, ne passe pas à l'échelle quand l'auteur est une machine. Un diagramme de séquence, lui, se relit en deux minutes, et il dit ce qui compte : les participants, les appels, leur ordre, les chemins d'erreur. C'est là que la validation humaine redevient possible. Il faut donc déplacer la porte : plus sur le code, sur le design.

L'idée : voir le design comme on voit un diff

Avec un assistant de code, on regarde aujourd'hui deux choses : du code et des diffs de texte. La proposition est d'ajouter une troisième vue, au même niveau : des diagrammes et des diffs de diagrammes.

Le diagramme est du texte (Mermaid), donc l'assistant sait le produire, le modifier et le comparer. Mais on ne le lit pas comme du texte. On le lit rendu, et le diff aussi : ce qui est ajouté apparaît en vert, ce qui est retiré en rouge, ce qui change de forme en orange, avec un effet de surligneur sur le diagramme lui-même. Un chemin d'erreur qui manque se voit comme une flèche absente. Une responsabilité mal placée se voit comme une flèche qui part du mauvais participant.

Voici à quoi ressemble ce diff sur un flux de traitement d'ordre, entre le diagramme proposé par l'assistant et le diagramme corrigé par l'humain avant validation. C'est une vue fusionnée : un seul diagramme, où chaque élément porte son statut.

flowchart TD
    A[Réception ordre] --> B[Contrôle pré-trade]
    B --> C[Pricing]
    C --> D[Exécution]
    D --> E[Booking]
    B -. rejet .-> R[Notification rejet]
    C -. timeout .-> T[File de reprise]
    E --> F[Réconciliation]

    classDef added fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
    classDef removed fill:#fee2e2,stroke:#dc2626,stroke-width:2px,stroke-dasharray:5 5,color:#7f1d1d
    classDef changed fill:#fef3c7,stroke:#d97706,stroke-width:2px,color:#78350f

    class R,T added
    class F removed
    class B changed

Trois corrections humaines sont visibles sans lire une ligne de code : deux chemins d'erreur ajoutés (le rejet pré-trade, le timeout pricing), une étape retirée du périmètre de l'incrément (la réconciliation), et un contrôle dont le contrat change. Rien de cela n'est encore codé. C'est le moment le moins cher pour le décider.

Ce rendu n'a rien d'exotique : Mermaid sait colorer des nœuds par classe (les arêtes se colorent par index, ce qui est moins commode). Un diff structurel naïf, sur des ensembles de nœuds et d'arêtes, est simple ; détecter un renommage ou une responsabilité déplacée demande plus de travail. Ce qui manque n'est pas la technique, c'est la convention. Classes et styles Mermaid

La méthode en cinq temps

Temps Qui produit Artefact Critère de sortie
1. Intent Humain Le besoin en trois phrases + les contrats externes Entrées, sorties, invariants nommés
2. Design Assistant Diagramme de séquence, diagramme de classes si l'état le justifie, signatures Aucun corps de fonction
3. Gate Humain Le diff de diagramme, corrigé et validé Validation écrite, datée
4. Implémentation Assistant Tests d'abord, puis code, un nœud du diagramme à la fois Chaque test cite une flèche du diagramme
5. Anti-dérive Assistant Diagramme régénéré depuis le code, diff visuel avec le validé Diff vide, ou retour en 3

Intent. Trois phrases : ce que le système reçoit, ce qu'il rend, ce qui doit rester vrai entre les deux. Les contrats externes sont posés ici, en signatures, parce que c'est ce que l'humain connaît mieux que le modèle.

Design. L'assistant répond par un diagramme de séquence, et un diagramme de classes quand un état partagé le justifie. Chaque flèche a un émetteur, un récepteur, un contenu et un rang. Les chemins d'erreur y figurent ou n'existent pas. Les signatures vivent dans le fichier de design, pas dans le code source. Aucun corps de fonction.

Gate. L'humain lit le diff de diagramme, pas le diagramme entier. Il renomme, supprime une flèche, en ajoute une pour le cas d'échec, déplace une responsabilité. Puis il valide, par écrit, dans un fichier qui porte son nom et la date. Un assistant qui a écrit du code avant cette validation a violé le contrat, même si le code est bon.

Implémentation. Chaque incrément correspond à un nœud du diagramme validé. Les tests viennent d'abord et se déduisent du diagramme : un message attendu devient une assertion, un chemin d'erreur devient un cas de test. Le code vient ensuite, contraint par les signatures et la topologie validée.

Anti-dérive. Un diagramme maintenu à la main meurt en deux sprints. Le diagramme n'est donc pas maintenu, il est régénéré depuis le code, canonisé (ordre des participants et des flèches déterministe, noms stables), puis comparé au diagramme validé avec le même rendu coloré qu'à la gate. Un diff non vide a deux lectures : le code a dérivé et il faut le corriger, ou le design a évolué et il faut repasser la gate. La décision revient à l'humain.

sequenceDiagram
    participant H as Humain
    participant A as Assistant
    participant R as Dépôt

    H->>A: 1. Intent (3 phrases + contrats externes)
    A->>H: 2. Design (diagrammes + signatures, zéro code)
    loop 3. Gate : diff de diagramme
        H->>A: corrections (flèches ajoutées, retirées, déplacées)
        A->>H: diagramme révisé, changements surlignés
    end
    H->>R: validation écrite (nom, date, commit)
    A->>R: 4. Tests dérivés des flèches, puis code
    A->>A: 5. Diagramme régénéré et canonisé
    A->>H: diff visuel (régénéré vs validé)
    alt diff vide
        H->>R: merge
    else dérive
        H->>A: correction du code, ou retour en 3
    end

Ce que ça demande à l'outil

La méthode est une convention. Elle tient dans un assistant de code existant, sans produit nouveau, à trois conditions.

Un fichier de design par incrément, versionné avec le code, qui contient l'intent, les diagrammes et un bloc de validation. Tant que ce bloc est vide, l'assistant refuse d'écrire dans le code source. C'est une règle de skill ou d'instruction système, pas une fonctionnalité.

Un diff de diagramme. Les deux diagrammes sont mis sous forme canonique, comparés comme des ensembles de nœuds et d'arêtes, et le résultat est rendu en un seul diagramme Mermaid avec les classes de couleur montrées plus haut. L'assistant l'affiche à la gate et au temps 5.

Une régénération honnête. Quand l'orchestration est une donnée (un graphe d'agents, une machine à états, un catalogue de tâches), le diagramme se régénère mécaniquement et le diff est exact. Quand le code est impératif, l'assistant reconstruit le diagramme en lisant le code, et le diff porte sur cette reconstruction. C'est moins fort, et il faut le dire : le temps 5 est une preuve sur les systèmes déclaratifs, un contrôle assisté sur les autres. Sur du code impératif, le garde-fou principal reste le temps 4, les tests dérivés des flèches.

Filiation

Le TDD et le BDD ont établi que le contrat s'écrit avant le code. DGD remonte ce contrat d'un cran, à l'interaction entre composants, et les tests s'en déduisent ensuite. Le spec-driven development fait le même pari avec une spécification en prose avant de laisser l'assistant coder. La différence tient au support et à la boucle. Une spec en prose se lit en diagonale ; on y valide une intention. Un diagramme de séquence ne permet pas d'être vague : chaque flèche est un engagement. Et une spec n'est pas régénérée depuis le code ; le diagramme, si, ce qui donne au contrat une date de péremption vérifiable. GitHub Spec Kit

Ce que ce n'est pas

Ce n'est pas du waterfall. Il y a une gate par incrément, et un incrément se mesure en heures. Le diagramme validé couvre l'incrément, pas le système.

Ce n'est pas de la modélisation exhaustive. Un diagramme de séquence, un diagramme de classes si l'état le justifie, sur le périmètre de l'incrément. Les propriétés transverses (idempotence, concurrence, délais) ne se lisent pas sur une séquence et gardent leurs tests propres.

Ce n'est pas un remplacement de la revue de code. Le code est encore lu, mais contre un diagramme validé : on vérifie une conformité, on ne reconstitue plus une intention.

Ce n'est pas une méthode pour tout. Un script jetable, un correctif d'une ligne, une exploration dont on ne garde rien : la gate a un coût fixe que ces cas ne remboursent pas. Elle s'applique dès qu'un incrément touche une interface, un état partagé ou un chemin d'erreur.

Dans un système financier, le fichier de design validé a un usage de plus. Il dit ce que le composant fait, qui l'a validé et à quel commit. C'est la forme que prend un contrôle de premier niveau quand le code est écrit par une machine, et il existe avant le code plutôt que d'être reconstitué après.

Et ensuite

La méthode tient en une page, et sa mise en œuvre tient en un skill : un fichier de design par incrément, un assistant qui refuse de coder tant que le bloc de validation est vide, un diff de diagramme rendu en couleur à la gate et au temps 5. Un prototype de skill Claude Code existe à l'état de brouillon, non publié ; la même convention vaut pour Codex. Le jour où l'on regarde un diagramme surligné avec le même réflexe qu'un diff texte, la porte est en place.