La plupart des gens utilisent encore Claude Code comme un stagiaire très coûteux.
Ils lui confient une tâche, attendent une réponse, puis décident manuellement de la suite.
Mais les équipes qui tirent le meilleur parti de l'IA construisent quelque chose qui ressemble davantage à un petit système distribué.
Un agent définit le problème.
Cinq agents moins chers cherchent en parallèle.
Un script déterministe supprime les doublons.
Trois agents sceptiques tentent de réfuter les résultats.
Un modèle de premier plan rend le jugement final.
C'est ça, le graph engineering.
Avant de continuer à lire :
Mettez ce guide en favori pour pouvoir retrouver les motifs de graphes lorsque vous commencerez à construire vos propres workflows Claude.
Et suivez
@Gyome1_ -
Je décortique Claude Code, les agents IA et les systèmes qui transforment un modèle en un workflow d'ingénierie fiable.
J'ai passé des semaines à analyser des architectures d'agents réelles, des diagrammes de workflow et des patterns de production pour reconstruire le Graph Engineering en un guide pratique.
Au lieu d'écrire un prompt plus long, vous concevez le chemin que l'information emprunte à travers le système :
linéaire → fan-out → reduce → vérifier → synthétiser
Chaque agent devient un nœud avec une tâche bornée. Chaque arête transporte des données structurées. Des routeurs décident quelle branche s'exécute. Des vérificateurs rejettent les sorties faibles. Des boucles continuent jusqu'à ce que le graphe ne trouve plus rien de nouveau.
Le changement important est que Claude Code n'a plus à se comporter comme une seule intelligence qui parcourt une immense liste de contrôle.
Il peut générer le code d'orchestration, lancer une flotte de sous-agents spécialisés, router leurs sorties vers différents modèles, et assembler le résultat final seulement après que les preuves aient survécu à la vérification.
Les patterns de base ne sont pas nouveaux. Les ingénieurs logiciels utilisent des DAG, des pipelines, des barrières, MapReduce et des workers distribués depuis des décennies.
Ce qui a changé, c'est ce qui se trouve désormais à l'intérieur de chaque nœud.
Un nœud peut parcourir un dépôt, auditer une migration, contester une décision architecturale, inspecter des échecs de test, ou synthétiser cinquante résultats indépendants en un seul rapport cité.
Ce guide décompose l'ensemble du système, depuis l'agent linéaire le plus simple jusqu'aux graphes en diamant, nœuds routeurs, panels de vérificateurs adverses, boucles convergentes, classification de modèles et workflows dynamiques générés directement dans Claude Code.
À la fin, vous serez capable de regarder une tâche importante et d'arrêter de vous demander :
« Quel prompt devrais-je écrire ? »
1. LE GRAPH ENGINEERING COMMENCE PAR LA FACTURE
Le graph engineering est souvent présenté comme un moyen d'exécuter plus d'agents.
Ce cadrage oublie la partie coûteuse.
Vous pouvez lancer vingt agents Claude sur le même dépôt et recevoir vingt rapports qui se chevauchent, des contextes répétés, des conclusions contradictoires et une facture API bien plus élevée.
Un graphe utile contrôle où se déroule le calcul, quel modèle traite chaque décision et comment les résultats incertains progressent dans le workflow.
Imaginez demander à Claude Code de préparer une migration de production :
Inspectez le dépôt, trouvez toutes les dépendances, proposez la migration, identifiez les risques, vérifiez le plan et rédigez le briefing final.
Dans un seul prompt, cela devient un long processus opaque. Claude parcourt le code, stocke les résultats dans le contexte, conçoit la migration, révise son propre plan et produit le rapport final.
Lorsque le rapport échoue, il est difficile de localiser la source de l'échec. Claude a peut-être manqué un fichier, mal compris une dépendance, perdu un détail antérieur ou accepté une hypothèse faible lors de la vérification.
Chaque étape peut également s'exécuter sur le même modèle coûteux, même lorsque certaines parties de la tâche impliquent une simple extraction ou un tri.
Le graph engineering ouvre ce workflow et donne à chaque décision une place visible.
Les branches d'inspection s'exécutent en même temps car elles utilisent la même tâche cadrée et ne dépendent pas de la sortie des autres.
Leurs résultats se rencontrent à une étape de réduction, où les doublons disparaissent et où les preuves sont compressées en un ensemble de données plus petit.
Un routeur lit ensuite la sévérité. Les modifications de routine passent par une revue légère. Les résultats à haut risque reçoivent une analyse plus approfondie de plusieurs réviseurs indépendants avant d'atteindre le modèle final.
Le résultat est un workflow où la latence, le coût du modèle, la taille du contexte et la profondeur de vérification sont contrôlés par la structure du graphe.
Un nœud doit prendre une seule décision
Un nœud utile a une responsabilité bornée.
Trouvez chaque appel à l'API obsolète. Classez chaque risque de migration comme faible, moyen ou élevé. Testez le plan de rollback pour les cas d'échec.
Chaque nœud a besoin d'une entrée claire, d'une sortie définie et d'une surface de décision limitée.
Un nœud qui parcourt le dépôt, estime l'impact métier, conçoit le correctif et rédige la recommandation contient encore plusieurs étapes cachées. Le débogage reste difficile car le raisonnement intermédiaire est enterré à l'intérieur d'un seul appel de modèle.
Des limites plus petites révèlent où les preuves sont entrées dans le système et où leur sens a changé.
Une arête doit transporter des preuves
Une arête représente les données requises par le nœud suivant.
Le scanner peut retourner un objet prévisible :
1{2 "file": "src/auth/session.ts",3 "lines": [84, 119],4 "dependency": "legacySessionClient",5 "confidence": 0.94,6 "evidence": "Les deux sites d'appel dépendent de la méthode refresh obsolète."7}
Le classificateur de risque reçoit désormais les mêmes champs pour chaque résultat. Il peut rejeter les résultats incomplets, regrouper les fichiers connexes et orienter les preuves incertaines vers une autre revue.
Les schémas réduisent la dérive d'interprétation entre les nœuds. Les paragraphes libres obligent chaque agent aval à reconstruire le sens de l'agent amont. Sur plusieurs étapes, de petites ambiguïtés peuvent altérer la conclusion finale.
Une sortie structurée maintient les preuves stables pendant qu'elles traversent le graphe.
Certains nœuds sont du code ordinaire
Supposons que huit agents de recherche retournent quatre-vingts résultats.
Le workflow doit combiner les tableaux, ignorer les réponses vides, supprimer les doublons et trier les éléments restants.
Ces opérations ont des réponses déterministes :
1const uniqueFindings = [2 ...new Map(3 results4 .flatMap(batch => batch ?? [])5 .map(item => [`${item.file}:${item.lines.join("-")}`, item])6 ).values()7];
Une transformation JavaScript gère cela instantanément et produit la même sortie à chaque exécution. Envoyer la même tâche à un autre modèle ajoute un coût en tokens et crée un autre endroit où les preuves peuvent disparaître.
Les nœuds de modèle doivent être réservés à la recherche, la classification, la comparaison, la revue et la synthèse. Le code peut gérer la validation, la déduplication, le tri, les règles de routage explicites et d'autres transformations prévisibles.
Cette division devient le fondement du graphe.
Chaque appel de modèle doit correspondre à une décision qui nécessite véritablement un jugement.
2. LE DIAMANT : COMMENT LES GRAPHES D'AGENTS RÉELS DÉPLACENT LE TRAVAIL
La plupart des graphes d'agents sérieux finissent par prendre la même forme.
Une tâche commence avec un périmètre partagé, se divise en plusieurs workers indépendants, attend leurs sorties, compresse les preuves et transmet le résultat à une décision finale.
Cette forme est le diamant.
Le côté gauche est le fan-out.
Le point médian où toutes les branches se rencontrent est la barrière.
Le côté droit est le fan-in.
Ce motif apparaît partout dès qu'une tâche devient trop grande pour un seul contexte.
Un audit de dépôt peut être divisé par sous-système. Un rapport de marché peut être divisé par source. Une tâche de recherche peut être divisée par hypothèse. Une revue de migration peut être divisée par utilisation de l'API, modifications de base de données, risque de déploiement et couverture de test.
Chaque worker reçoit le même périmètre avec une affectation plus restreinte.
Le graphe attend ensuite que suffisamment de preuves utiles soient revenues.
Le fan-out doit créer un travail indépendant
Une branche appartient au fan-out lorsqu'elle peut partir de l'entrée partagée et produire un résultat utile sans lire la sortie d'une autre branche.
Pour un audit de sécurité, la division pourrait ressembler à ceci :
Claude Code peut lancer ces appels simultanément avec une primitive de barrière telle que parallel()
1const findings = await parallel(2 checks.map(check => async () => {3 return agent({4 task: check.task,5 context: auditScope,6 schema: FINDING_SCHEMA7 });8 })9);
L'orchestration reste en JavaScript ordinaire. Chaque branche reçoit une tâche bornée et retourne un objet validé.
Le résultat arrive sous forme d'une collection de sorties qui peuvent être filtrées, inspectées et transmises à l'étape suivante.
Un grand fan-out a toujours besoin d'une raison derrière chaque branche.
Diviser une affectation vague en douze agents presque identiques produit souvent des résultats répétés avec un libellé légèrement différent. Un parallélisme utile provient de sources, perspectives, régions de code ou hypothèses distinctes.
La barrière crée un point de décision
Une barrière met en pause l'étape suivante jusqu'à ce que les branches requises soient terminées.
Cette pause est importante car certaines décisions dépendent de l'ensemble complet.
Un nœud de classement ne peut pas identifier la vulnérabilité la plus importante alors que la moitié du dépôt est encore en cours d'inspection. Un modèle de synthèse ne peut pas écrire un plan de migration complet alors que la revue de déploiement est toujours en cours.
À la barrière, le graphe a la possibilité d'inspecter l'état de l'exécution :
1const completed = findings.filter(Boolean);23if (completed.length < MIN_REQUIRED_RESULTS) {4 throw new Error("Couverture d'audit insuffisante");5}
C'est là que les échecs partiels deviennent visibles.
Un worker peut expirer, retourner des données malformées ou ne produire aucun résultat. Filtrer les valeurs nulles maintient l'exécution, mais les workflows de production ont généralement besoin d'une politique plus claire :
- combien de branches réussies sont requises ;
- quelles branches sont obligatoires ;
- si un nœud défaillant doit réessayer ;
- si le résultat final doit être marqué comme incomplet.
La barrière fait donc partie du modèle de fiabilité, et non pas simplement un mécanisme de synchronisation.
Réduire avant de synthétiser
Après le fan-out, le graphe peut contenir des dizaines de résultats qui se chevauchent.
Les envoyer tous directement dans un modèle de premier plan crée un grand contexte, répète les mêmes preuves et rend les détails importants plus difficiles à distinguer.
L'étape de réduction prépare les preuves.
Une partie de la réduction peut se faire dans le code :
1const unique = deduplicateByKey(2 completed.flatMap(result => result.findings),3 finding => `${finding.file}:${finding.line}:${finding.type}`4);
La couche suivante peut nécessiter un jugement :
1const curated = await agent({2 task: `3 Regroupez les résultats connexes.4 Conservez toutes les références de fichier et de ligne.5 Classez chaque groupe par impact opérationnel.6 Renvoyez la preuve la plus solide pour chaque conclusion.7 `,8 input: unique,9 schema: CURATED_FINDINGS_SCHEMA10});
La réduction contrôle ce qui atteint le modèle final.
Un bon réducteur supprime la répétition tout en préservant les preuves. Un réducteur agressif peut compresser plusieurs risques distincts en un seul résumé vague et effacer les détails nécessaires à la vérification.
Le motif le plus sûr conserve un lien entre chaque affirmation réduite et ses éléments sources.
1{2 "risk": "Le rafraîchissement de session peut échouer après la migration",3 "severity": "élevée",4 "sourceFindingIds": ["AUTH-04", "API-11", "TEST-07"],5 "evidence": [6 "Trois services appellent la méthode refresh obsolète",7 "Aucun chemin de repli n'existe",8 "La couverture d'intégration est manquante"9 ]10}
Maintenant, le nœud de synthèse reçoit un ensemble de données plus petit sans perdre la traçabilité.
3. LA FIABILITÉ FAIT PARTIE DU GRAPHE
Un graphe peut se terminer rapidement et produire tout de même une mauvaise réponse.
Une fois que plusieurs agents commencent à chercher, classer et réviser la même tâche, le problème principal devient le contrôle.
Le système a besoin de règles pour décider quels résultats méritent un travail plus approfondi, quelles sorties doivent être rejetées et quand le workflow a suffisamment cherché.
Router par risque
Un nœud routeur lit la sortie structurée et choisit la branche suivante.
La classification peut provenir d'un modèle, tandis que la branche elle-même reste explicite dans le code.
1const route =2 finding.severity === "high"3 ? runFullAudit(finding)4 : runQuickReview(finding);
Cela concentre les révisions coûteuses autour des résultats ayant un impact significatif.
Un routeur utile s'appuie sur des champs que le graphe peut inspecter : sévérité, confiance, systèmes affectés, exposition financière ou présence de preuves manquantes.
Ajouter une vérification indépendante
Un agent qui révise sa propre conclusion transporte les mêmes hypothèses dans les deux étapes.
Un graphe plus robuste envoie les résultats importants à plusieurs réviseurs avec des missions différentes.
Les réviseurs ne doivent pas recevoir d'instructions pour améliorer la réponse originale. Leur tâche est de chercher des raisons pour lesquelles elle pourrait être incomplète ou erronée.
Le graphe peut exiger un accord avant qu'un résultat ne progresse :
1const accepted = votes.filter(vote => vote.approve).length >= 2;
Isoler les agents qui modifient le code
Les agents de codage parallèles peuvent interférer entre eux lorsqu'ils modifient le même répertoire de travail.
Un agent peut écraser un fichier pendant qu'un autre est en train de le lire. Les tests peuvent s'exécuter sur un mélange de modifications non liées.
Les worktrees Git donnent à chaque branche sa propre copie du dépôt.
1dépôt principal2 │3 ├→ worktree/auth-fix4 ├→ worktree/db-migration5 └→ worktree/test-repair
Chaque agent peut modifier des fichiers et exécuter des tests dans son propre environnement. Un nœud ultérieur compare les correctifs, vérifie les conflits et sélectionne ce qui doit être fusionné.
Cela transforme l'isolation en une partie du graphe plutôt qu'en une étape de nettoyage manuelle.
Laisser la découverte converger
Certaines tâches ne peuvent pas être achevées en une seule passe.
Un audit de dépôt peut découvrir une dépendance qui pointe vers un autre package. Ce package peut révéler un autre site d'appel. Le graphe a besoin d'un moyen contrôlé de continuer à chercher sans répéter tout ce qu'il a déjà vu.
1const seen = new Set();2let dryRounds = 0;34while (dryRounds < 2) {5 const findings = await discoverNext([...seen]);6 const fresh = findings.filter(item => !seen.has(item.id));78 fresh.forEach(item => seen.add(item.id));9 dryRounds = fresh.length === 0 ? dryRounds + 1 : 0;10}
Le détail important est de dédupliquer par rapport à chaque élément déjà vu.
Dédupliquer uniquement par rapport aux résultats confirmés permet aux éléments rejetés ou incertains de revenir lors du passage suivant et de consommer à nouveau le même travail.
La boucle s'arrête après plusieurs tours secs, un budget fixe ou un nombre maximum d'itérations. Les graphes de production ont généralement besoin des trois.
Faire correspondre le modèle au nœud
Tous les nœuds n'ont pas besoin du modèle le plus fort disponible.
L'extraction, la classification de base et les recherches étroites peuvent souvent s'exécuter sur un niveau plus rapide. La revue d'architecture, la vérification adverse et la synthèse finale peuvent justifier un modèle plus fort.
La classification des modèles devient une autre propriété du graphe.
Le budget est déterminé par le nombre de nœuds exécutés, la fréquence des répétitions de boucles, la quantité de contexte traversant chaque arête et le modèle qui gère chaque étape.
Un graphe avec vingt appels de recherche bon marché peut encore coûter plus cher qu'un seul appel fort. L'architecture a besoin d'un budget de tokens avant d'avoir besoin d'une autre branche.
Savoir quand arrêter de dessiner
Les petites tâches ont rarement besoin de routeurs, de panels de vote, de worktrees et de boucles de convergence.
La surcharge d'un graphe comprend le code d'orchestration, les schémas, les tentatives, la journalisation, le stockage intermédiaire et davantage d'états d'échec à déboguer.
Un workflow linéaire est généralement suffisant lorsqu'un modèle peut contenir le contexte pertinent, que la tâche a peu de branches indépendantes et que le coût d'une mauvaise réponse est faible.
Le graph engineering devient utile à mesure que la tâche gagne en travail parallèle, en décisions coûteuses, en grands ensembles de preuves ou en exigences de vérification significatives.
Le workflow complet peut éventuellement ressembler à ceci :
La valeur vient du fait de rendre le mouvement du travail visible.
Chaque nœud a une responsabilité limitée. Chaque arête transporte des preuves structurées. Chaque branche a une raison d'exister. Chaque boucle a une condition d'arrêt.
À ce stade, Claude Code ne suit plus une longue instruction.
Il exécute un système conçu.
