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.

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 remplace | Ce qui le remplace | En une ligne |
|---|---|---|
| Le fichier d'instructions | Un fichier d'identité de 8 lignes | Qui est l'agent, et « suivre l'étape, puis avancer » |
| Les paragraphes de processus | Des workflows : un graphe d'étapes, de décisions et de points de validation | Une demande entre par un nœud, une décision l'envoie sur le chemin qui en a la charge |
| Les paragraphes de règles | Des standards : de simples fichiers markdown, un par sujet | L'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.

| Partie | Ce que c'est | Ce 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écision | Un nœud avec plusieurs arêtes. Elle envoie une demande sur le chemin qui en a la charge, par exemple fonctionnalité ou bug | La table de routage |
| Point de validation | Une é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... » |
| Standard | Un fichier markdown dans standards/, lu par l'agent que l'étape lance | Les règles collées dans le prompt |
| État | La tâche, son étape en cours et la note que chaque étape y laisse | Tout 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.

| Session | Consigne | Ce que fait l'agent | Où il s'arrête |
|---|---|---|---|
| 1 | La demande | Intake, puis un plan : modifier emails/booking_confirmed.html, ajouter un paragraphe, vérifier l'aperçu | Point de validation Analyze |
| Humain | Approuve 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 |
| Humain | Approuve | ||
| 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âche | Complete, 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.

Puis une fonctionnalité passe dans le graphe : « Ajoutez une liste d'attente aux cours complets. »
| Étape | Qui | Résultat | Validation |
|---|---|---|---|
| Triage : fonctionnalité ou bug | décision | Chemin fonctionnalité | auto |
| Plan the feature | planner | join_waitlist(class_id, member), ordre d'arrivée, promotion en cas d'annulation, 5 tests | oui humain |
| Build, puis Run tests | developer, puis la session principale | waitlist.py et 5 tests, 5 réussis | note |
| Standards gate, Standards review | standards-reviewer | Vérifié par rapport à standards/testing.md : 0 constat | oui humain |
| Code review, tour 1 | code-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 findings | developer | Remplit le cours jusqu'à sa capacité de 12 avant l'inscription | note |
| Run tests, standards, Code review tour 2 | session principale, standards-reviewer, code-reviewer | 5 réussis, standards conformes, aucun constat | oui 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.

| Situation | Meilleur choix |
|---|---|
| Scripts ponctuels, exploration, question rapide | Un simple prompt |
| Un processus que l'équipe répète : fonctionnalités, bugs, releases, revues | Un graphe. Chaque répétition suit les mêmes étapes |
| Plusieurs personnes ou agents qui font le même type de travail | Un graphe. Le processus vit à un seul endroit, pas dans le fichier de chacun |
| Un travail qui exige un oui humain avant d'aller plus loin | Un 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 lignes | Un 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.
