Guides

Qu'est-ce que le graph engineering ? Un CLAUDE.md de 8 lignes

Le graph engineering consiste à concevoir un système d'agents IA comme un graphe : les nœuds font le travail, les arêtes décident de ce qui s'exécute ensuite, et l'état circule entre eux. Notre point de vue : le graphe remplace le fichier d'instructions, si bien qu'un CLAUDE.md peut se réduire à 8 lignes pendant que le processus et les règles vivent dans des workflows et des standards.

David Marsa

David Marsa

Founder & CEO

Intermédiaire8 min de lectureMis à jour le 10 oct. 2026

Dernière vérification : 7 oct. 2026

Outils et modèles abordés:Claude Code
Qu'est-ce que le graph engineering : un CLAUDE.md de 8 lignes alimente un tri vers un chemin fonctionnalité ou bug, puis Build + tests et un point de validation Code review dont le non renvoie vers une correction, puis vers les tests avant la fin.

Ce que vous saurez faire

  • Expliquer le graph engineering en une phrase et ce qui le distingue de LangGraph.
  • Réduire le CLAUDE.md ou l'AGENTS.md d'un agent à un court fichier d'identité.
  • Transformer un processus que votre équipe répète en workflow avec des décisions, des points de validation et des standards.
  • Prouver les chemins du « non » d'un workflow en provoquant un échec sur une tâche jetable.

Points clés

  • Le graph engineering consiste à concevoir un système d'agents comme un graphe : les nœuds font le travail, les arêtes décident de ce qui s'exécute ensuite, et l'état circule entre eux.
  • Notre point de vue : le graphe remplace le fichier d'instructions, qui se réduit à un fichier d'identité de 8 lignes.
  • Le processus passe dans des workflows faits d'étapes, de décisions et de points de validation, et les règles passent dans des standards lus à l'étape concernée.
  • La tâche porte l'état : un fichier court suffit à faire avancer le travail d'une session à l'autre.
  • La connaissance grandit, le prompt non.

Le problème : un CLAUDE.md qui ne cesse de s'allonger

Chaque équipe qui fait tourner un agent de code IA comme Claude Code tient un fichier d'instructions, et ce fichier ne fait que grossir. CLAUDE.md, AGENTS.md, .cursorrules. Il commence à vingt lignes : qui est l'agent, comment le dépôt est organisé, quelques règles.

Puis les leçons arrivent. Un bug causé par l'agent devient une règle. Certaines règles ont leur place dans un hook, pas dans un fichier : voyez comment empêcher Claude Code de supprimer vos fichiers. Un processus convenu par l'équipe devient un paragraphe. Une table de routage apparaît : « pour les bugs, faire ceci, pour les fonctionnalités, faire cela ». Quelques mois plus tard, le CLAUDE.md est trop long : des centaines de lignes, et l'agent n'en suit qu'une partie.

Ce n'est pas une impression. La documentation de bonnes pratiques de Claude Code le dit sans détour : des fichiers CLAUDE.md surchargés poussent Claude à ignorer vos véritables instructions (Anthropic, Best practices for Claude Code(s’ouvre dans un nouvel onglet)).

Chaque ligne ajoutée pour améliorer l'agent affaiblit toutes les autres. Le graph engineering est notre façon de sortir de ce piège.

Qu'est-ce que le graph engineering : la définition, et notre point de vue

Le graph engineering (ingénierie de graphes) consiste à concevoir un système d'agents comme un graphe : les nœuds font le travail, les arêtes décident de ce qui s'exécute ensuite, et l'état circule entre eux. C'est le sens courant, et nous n'avons pas inventé le terme. LangGraph est une bibliothèque pour construire de tels graphes. Le graph engineering est la discipline.

Un CLAUDE.md de 412 lignes réparti en trois : la table de routage, la checklist de release et « toujours demander avant de déployer » deviennent un workflow avec un point de validation de revue de code, les règles de code et les leçons deviennent des fichiers de standards, et seul reste un fichier d'identité de 8 lignes.

Notre point de vue va un cran plus loin. Le graphe remplace le fichier d'instructions. L'agent ne lit jamais tout le processus d'un coup. Il lit une étape, fait exactement cette étape, puis avance. Trois éléments prennent la place du long fichier :

Ce qu'il remplaceCe qui le remplaceEn une ligne
Le fichier d'instructionsUn fichier d'identité de 8 lignesQui est l'agent, et « suivre l'étape, puis avancer »
Les paragraphes de processusDes workflows : un graphe d'étapes, de décisions et de points de validationUne demande entre par un nœud, une décision l'envoie sur le chemin qui en a la charge
Les paragraphes de règlesDes standards : de simples fichiers markdown, un par sujetL'agent que chaque étape lance les lit à cette étape

Toute l'idée repose sur cette phrase : la connaissance grandit, le prompt non.

Nous faisons tourner ces graphes sous forme de workflows ConvOps(s’ouvre dans un nouvel onglet), et chaque exemple ci-dessous en est un, présenté sur des données de démonstration.

Les cinq parties du graphe

Nos graphes comptent cinq types de parties, et chacune supprime une section de l'ancien prompt.

Les cinq parties sur la fonctionnalité de liste d'attente de Brightloom : une étape (Build), une décision (Triage), un point de validation (Code review, dont le non mène à Fix review findings puis revient à Run tests), un standard (testing.md, lu par l'agent de l'étape) et la fiche de tâche qui contient l'étape en cours et la note de chaque étape.

PartieCe que c'estCe qu'elle remplace dans le prompt
Étape (nœud)Une unité de travail avec ses propres instructions : planifier, construire, lancer les tests, relire« Toujours planifier avant de coder, puis... »
DécisionUn nœud avec plusieurs arêtes. Elle envoie une demande sur le chemin qui en a la charge, par exemple fonctionnalité ou bugLa table de routage
Point de validationUne étape qui ne peut pas avancer sans un oui ou un non explicite. Nos points de validation demandent à l'agent de s'arrêter et de consulter une personne. Un non renvoie le travail vers une étape de correction« Toujours demander avant de... »
StandardUn fichier markdown dans standards/, lu par l'agent que l'étape lanceLes règles collées dans le prompt
ÉtatLa tâche, son étape en cours et la note que chaque étape y laisseTout réexpliquer à chaque session

Pourquoi parler d'ingénierie ? Parce que le travail consiste à choisir des nœuds et des arêtes. Par où entre une demande. Quelle décision l'envoie où. Quel agent lit quels standards. Où un humain doit dire oui. Les étapes laissent des notes sur la tâche, si bien que l'état survit à n'importe quelle session.

Une exécution, étape par étape : une tâche, trois sessions

Le plus petit exemple montre toute l'idée : une tâche traverse trois sessions sans qu'aucune ne voie l'ensemble, et le fichier d'instructions ne dit jamais comment. Prenons Brightloom, une équipe fictive de quatre personnes qui construit une application de réservation de cours pour les studios de yoga. Voici le fichier d'instructions complet de leur agent, avec les noms d'outils en langage courant :

# Who you are

You are the team's co-worker in this repo. The task system is your task list and your memory.

# How you work

1. Every request becomes a task: search first, then create one if none exists.
2. The task carries a workflow. Read the current step, do exactly what it says, then advance. Repeat until the workflow completes.

Rien sur la planification, les tests, les validations ou la reprise. Une demande arrive : « Ajoutez la politique d'annulation à l'e-mail de confirmation de réservation. » L'agent crée la tâche et le workflow en six étapes s'y rattache de lui-même : Intake, Analyze (validation), Implement, Verify (validation), Capture Learnings, Complete.

Trois sessions sur une même tâche, avec une validation humaine entre chacune : la barre de progression en six étapes s'arrête au point de validation Analyze, puis à celui de Verify, et se termine à Complete, 6 sur 6.

SessionConsigneCe que fait l'agentOù il s'arrête
1La demandeIntake, puis un plan : modifier emails/booking_confirmed.html, ajouter un paragraphe, vérifier l'aperçuPoint de validation Analyze
HumainApprouve en dehors de la session de l'agent
2« Reprenez là où nous nous sommes arrêtés. »Retrouve la tâche ouverte, fait la modification, rédige un rapport de vérification : l'aperçu s'affiche, le paragraphe est làPoint de validation Verify
HumainApprouve
3« Reprenez là où nous nous sommes arrêtés. »Rédige la note d'enseignement « les modèles d'e-mail se trouvent dans emails/ », clôt la tâcheComplete, 6 sur 6

Aucune session ne détient l'état. Chaque nouvelle session traduit « reprendre » par : trouver la tâche active, lire son étape, faire cette étape. Le fichier d'identité ne dit jamais comment, car la tâche sait déjà où elle en est.

Un graphe construit en parlant

Nous construisons les graphes en les décrivant, pas en les codant. Le responsable technique de Brightloom décrit le processus de l'équipe en une seule conversation : une décision sépare les fonctionnalités des bugs, un planner rédige un plan qui attend une validation, les bugs commencent par un test qui échoue, et tout se termine par un bloc commun de build, de tests et d'une revue de code qui renvoie le travail en cas de non. L'agent transforme cette description en workflows.

Dans une conversation ultérieure, le responsable demande une revue des standards après les tests. L'agent l'ajoute sous forme d'un petit sous-workflow doté de sa propre boucle de correction, auquel on accède depuis une décision, et la tâche qui l'ajoute passe par la nouvelle étape avant de se clore. Le graphe grandit. Le fichier d'identité ne change pas d'une seule ligne. Les leçons arrivent de la même façon : chacune va dans l'étape ou le standard qui en avait besoin, la boucle derrière comment nous construisons un système d'IA auto-améliorant.

Le graphe de développement avec la fonctionnalité de liste d'attente retracée en douze étapes numérotées : la première revue de code dit non parce que le test ne remplit jamais le cours, si bien que le travail part en correction, puis passe par les tests et la revue des standards avant qu'une seconde revue dise oui.

Puis une fonctionnalité passe dans le graphe : « Ajoutez une liste d'attente aux cours complets. »

ÉtapeQuiRésultatValidation
Triage : fonctionnalité ou bugdécisionChemin fonctionnalitéauto
Plan the featureplannerjoin_waitlist(class_id, member), ordre d'arrivée, promotion en cas d'annulation, 5 testsoui humain
Build, puis Run testsdeveloper, puis la session principalewaitlist.py et 5 tests, 5 réussisnote
Standards gate, Standards reviewstandards-reviewerVérifié par rapport à standards/testing.md : 0 constatoui humain
Code review, tour 1code-reviewer« test_full_class_goes_to_waitlist ne remplit jamais le cours au préalable, donc il passe sur un cours vide »non humain
Fix review findingsdeveloperRemplit le cours jusqu'à sa capacité de 12 avant l'inscriptionnote
Run tests, standards, Code review tour 2session principale, standards-reviewer, code-reviewer5 réussis, standards conformes, aucun constatoui humain
TerminéTâche terminée

Le non est tout l'intérêt. Le relecteur repère un test qui ne prouve rien, un humain confirme ce non, et le graphe envoie le travail vers Fix, puis vers les tests, puis vers une seconde revue. Personne n'a écrit « si la revue échoue, revenir en arrière » dans un prompt. C'est une arête.

Ce qui tourne mal : les passations et les chemins du non jamais testés

Un graphe sort le processus du prompt. Il ne rend pas pour autant les passations ni les chemins non testés sûrs. Nous avons rencontré les deux problèmes.

L'agent suivant ne lit pas les notes. Après Plan the feature, l'agent developer démarre avec son seul brief. Le plan approuvé se trouve sur la tâche sous forme de note d'étape qu'il n'ouvre jamais, et une nouvelle session ne voit que de courts aperçus des notes les plus récentes. La règle que nous appliquons désormais : la session principale met le plan approuvé et les constats ouverts dans le brief de l'agent suivant. La note reste sur la tâche comme trace, et le brief transmet ce dont l'étape suivante a besoin.

Un chemin du non que personne n'a emprunté n'est pas prouvé. Notre première boucle de revue passait la validation sans erreur, et pourtant le premier vrai non n'a pas pu emprunter l'arête de retour. Une validation sans erreur prouve la forme, pas le chemin.

La règle : provoquez un échec sur une tâche jetable et regardez le chemin du non s'exécuter de bout en bout. Pour Brightloom, cela veut dire une fonction sans test : la revue des standards la repère, Fix ajoute le test, la nouvelle vérification passe, et la tâche jetable est annulée.

Quand le graph engineering en vaut la peine

Un graphe est une surcharge pour un travail ponctuel et se rentabilise sur tout ce que l'équipe répète.

Prompt ou graphe : le travail ponctuel reste un simple prompt, tout travail que l'équipe répète reçoit un graphe, et les points de validation ne vont que là où le travail doit s'arrêter pour un oui ou un non.

SituationMeilleur choix
Scripts ponctuels, exploration, question rapideUn simple prompt
Un processus que l'équipe répète : fonctionnalités, bugs, releases, revuesUn graphe. Chaque répétition suit les mêmes étapes
Plusieurs personnes ou agents qui font le même type de travailUn graphe. Le processus vit à un seul endroit, pas dans le fichier de chacun
Un travail qui exige un oui humain avant d'aller plus loinUn graphe avec des points de validation. Un point de validation est un nœud : il attend une approbation à chaque exécution
Un fichier d'instructions de plus de quelques centaines de lignesUn graphe. Sortez d'abord le processus, ensuite les règles

Si votre fichier a déjà dépassé ce stade, CLAUDE.md trop long ? Que couper et où le ranger détaille l'audit ligne par ligne.

Pour essayer le graph engineering sur un processus que votre équipe répète, connectez votre agent à ConvOps(s’ouvre dans un nouvel onglet), décrivez le processus et faites passer votre prochaine tâche par le workflow qu'il construit. Pour un graphe qui s'exécute selon un planning sans que personne ne le lance, voyez comment nous menons des expériences SEO avec Claude Code, ou une boucle d'auto-réparation de site web où chaque bug obtient sa propre exécution dans un environnement isolé. Pour voir toute une entreprise tourner sur ces graphes, lisez comment nous dirigeons notre entreprise avec des workflows qui se souviennent. Pour d'autres outils qui exécutent des workflows d'agents, consultez le répertoire d'orchestration d'agents IA.

Questions fréquentes

Qu'est-ce que le graph engineering ?

Le graph engineering consiste à concevoir un système d'agents IA comme un graphe : les nœuds font le travail, les arêtes décident de ce qui s'exécute ensuite, et l'état circule entre eux. Dans ConvOps, le graphe est un ensemble de workflows que l'agent parcourt une étape à la fois : le fichier d'instructions peut se réduire à un fichier d'identité de 8 lignes, pendant que le processus vit dans le graphe.

Le graph engineering, est-ce la même chose que LangGraph ?

Non. LangGraph est une bibliothèque pour construire des graphes d'agents en code, et le graph engineering est la discipline qui consiste à les concevoir. Avec ConvOps, le graphe est un ensemble de workflows que l'agent parcourt via ses outils de tâches, sans code de graphe dans le dépôt. Les choix de conception restent les mêmes dans les deux cas : par où entre une demande, quelle décision l'oriente et où le travail s'arrête pour un oui.

Que faire quand mon CLAUDE.md est trop long ?

Sortez le processus, pas seulement les règles. Triez le fichier en trois piles : ce qui dit qui est l'agent reste, tout ce qui suit un ordre de travail devient une étape, une décision ou un point de validation de workflow, et chaque règle devient un fichier de standards. Dans ConvOps, les workflows portent les étapes : chaque nouvelle leçon va dans une étape ou un standard au lieu du fichier.

Le fichier CLAUDE.md ou AGENTS.md disparaît-il ?

Non. Il se réduit à un fichier d'identité : qui est l'agent, le fait que chaque demande devient une tâche, et qu'il suit l'étape en cours puis avance. Dans la configuration que montre ce guide, cela tient en 8 lignes, et cela ne change pas quand le graphe grandit, car le nouveau processus va dans des workflows et les nouvelles règles dans des standards.

Qu'est-ce qui empêche l'agent de sauter un point de validation ?

Le workflow. Une étape de validation ne peut pas avancer sans un oui ou un non explicite, et dans ConvOps, les instructions propres à cette étape demandent à l'agent de s'arrêter et de consulter une personne. Le fichier d'identité n'a jamais à dire « toujours demander avant de déployer », car l'arrêt se trouve sur l'étape où il s'applique.

Les agents ont-ils besoin de leurs propres instructions ?

Oui, mais courtes. Chaque rôle (planner, developer, code-reviewer, standards-reviewer) a un fichier d'agent de quelques lignes qui dit ce qu'il fait et le renvoie vers standards/. L'étape du workflow décide quel rôle s'exécute : les fichiers de rôle restent petits et le processus reste dans le graphe.

Apprenez-le en direct

Claude Code for Teams

Voir l’atelier