Construisons l'infrastructure de Claude Code (étape par étape)

Nous allons couvrir tout ce qui entre dans la construction d'un harnais de codage : la boucle d'agent, la planification, les sous-agents, le sandboxing, la mémoire et le checkpointing, le tout construit étape par étape.

Si vous avez déjà essayé de construire votre propre agent de codage, vous savez comment ça se passe. Vous connectez un modèle à des outils de fichiers et un shell, vous le pointez vers un vrai code source, et il s'effondre en moins d'une douzaine d'appels d'outils.

Il lit les mauvais fichiers, perd l'objectif en cours de route, et remplit son contexte avec des résultats dont il n'a plus besoin.

Ensuite, la même tâche passe par Claude Code et se termine proprement. La conclusion facile est qu'Anthropic a simplement un meilleur modèle, et cette conclusion passe à côté de l'endroit où le travail se fait réellement.

La différence, c'est le harnais. Un harnais, c'est le code ordinaire qui enveloppe le modèle, et il gère la planification, l'exécution des outils, la mémoire et la sécurité, tandis que le modèle ne fait que décider de la prochaine étape.

Voici à quoi ressemble un agent entièrement harnaché quand on le schématise :

GIF

L'image peut sembler complexe, mais elle se décompose en quatre groupes :

• Mémoire : alimente le modèle avec son contexte de travail ainsi que les faits appris au cours des sessions.
• Compétences : codent la manière dont l'agent doit fonctionner, c'est-à-dire les procédures, contraintes et heuristiques qu'il suit.
• Protocoles : connectent l'agent aux utilisateurs, outils et autres agents.
• Le cœur du harnais : relie le tout avec l'orchestration des sous-agents, un sandbox, un évaluateur, une boucle d'approbation, l'observabilité et la compression de contexte.

Anthropic décrit cette séparation comme le cerveau et les mains. Le modèle est le cerveau qui choisit chaque action, et le harnais est les mains qui l'exécutent et maintiennent le cap.

Donc l'écart entre votre agent et Claude Code n'est pas le modèle, c'est la machinerie autour du modèle.

Claude Code est l'un des harnais les plus performants en production aujourd'hui, et il est construit à partir d'un nombre étonnamment restreint des couches de cette illustration. Pour voir quelle partie de cette machinerie vous devriez construire vous-même, je l'ai reconstruit dans CrewAI, un framework open-source pour orchestrer des agents.

Une plus grande partie se superpose aux fonctionnalités intégrées que je ne le pensais, et la partie qui ne le fait pas est là où se trouve le véritable travail d'ingénierie.

Construisons-le couche par couche, en commençant par la boucle principale et en ajoutant la planification, les sous-agents, le sandboxing et la mémoire. À chaque étape, nous marquerons où le framework s'arrête et où votre travail commence.

Comment fonctionne le harnais de Claude Code

Au cœur de Claude Code se trouve une simple boucle d'agent. Vous lui envoyez un message, le modèle décide de la prochaine action, et il répond directement ou demande un outil. S'il en demande un, l'outil s'exécute, le résultat retourne dans la conversation, et le modèle décide à nouveau.

Cela se répète jusqu'à ce que le modèle renvoie une réponse finale sans autre appel d'outil.

Dans cette boucle, le modèle lit des fichiers, édite du code, exécute des commandes shell et lance des tests. Ce ne sont pas des modes séparés. Ce sont simplement des appels d'outils différents dans la même boucle.

Cependant, la boucle seule ne suffit pas pour un agent de codage fiable. Claude Code ajoute la planification, les outils de fichiers, les sous-agents, la mémoire, ainsi qu'un système de permissions et de sandbox autour d'elle. Ces couches ne remplacent pas la boucle, elles la rendent suffisamment sûre et fiable pour un travail réel.

Voici l'architecture que nous allons reconstruire : d'abord la boucle centrale, puis chaque couche par-dessus, en faisant correspondre chaque couche à la fonctionnalité CrewAI qui la gère.

La boucle d'agent centrale

La boucle exécute la même séquence jusqu'à ce que la tâche soit terminée :

1. Demander au modèle d'effectuer la tâche.
2. Le modèle répond directement ou demande un ou plusieurs outils.
3. Si des outils sont demandés, les exécuter et retourner les résultats au modèle.
4. Répéter avec la conversation mise à jour.
5. Lorsque le modèle répond sans demander d'outil, la tâche est terminée.

1while True:
2    reply = model(messages, tools)
3    calls = [b for b in reply if b.type == "tool_use"]
4    if not calls:            # plain text, no tool call: the job is done
5        return reply.text
6    messages += [reply, run_all(calls)]

Chaque appel d'outil complète une étape, donne au modèle de nouvelles informations et alimente la prochaine décision. Une question simple peut se terminer en une itération, tandis que corriger un bug complexe ou refactoriser une grande base de code peut prendre des dizaines d'itérations avant que le modèle n'ait suffisamment d'informations pour produire une réponse finale.

CrewAI fournit automatiquement cette boucle d'exécution dès que vous créez un agent. Vous n'implémentez pas la boucle while vous-même, vous définissez l'agent et lui assignez une tâche.

Construire le premier agent

Créons un agent simple de correction de bugs.

1from crewai import LLM, Agent, Crew, Task
2
3bug_fixer = Agent(
4    role="Bug Fixer",
5    goal="Find and describe the fix for the reported bug in the codebase.",
6    backstory="You read directories and files to build an accurate picture of the code.",
7    llm="claude-sonnet-4-6",
8)
9
10task = Task(
11    description="Find the fix for {objective}.",
12    expected_output="A short description of the fix and which file it belongs in.",
13)
14
15result = Crew(agents=[bug_fixer], tasks=[task]).kickoff(
16    inputs={"objective": "the overdraft bug in account.py"}
17)

Trois concepts à comprendre ici :

• Un Agent définit qui fait le travail, via son rôle, son objectif, son LLM et ses outils.
• Une Tâche décrit l'affectation.
• Un Équipage (Crew) rassemble les agents et les tâches. Appeler kickoff() exécute la même boucle d'exécution décrite ci-dessus, quel que soit le modèle sous-jacent (Anthropic, OpenAI, Google ou autre).

Donner des outils à l'agent

Les outils sont ce qui permet à un modèle qui ne fait que générer du texte de réellement travailler sur une base de code. Ils lisent des fichiers, les écrivent, exécutent des commandes shell et appellent des API externes.

CrewAI propose des outils pour le système de fichiers prêts à l'emploi :

• FileReadTool lit les fichiers.
• DirectoryReadTool liste les répertoires.
• FileWriterTool écrit les fichiers.

1from crewai_tools import DirectoryReadTool, FileReadTool, FileWriterTool
2
3read_file = FileReadTool()
4write_file = FileWriterTool()
5list_dir = DirectoryReadTool()
6
7filesystem_tools = [read_file, write_file, list_dir]

Ceux-ci servent également de mémoire externe. Au lieu de conserver un grand résultat de recherche dans la fenêtre de contexte du modèle, l'agent peut l'écrire dans un fichier, ne garder que le nom du fichier, et le relire si nécessaire.

Cela permet de réduire la taille de la fenêtre de contexte et de garder le modèle plus concentré, ce qu'Anthropic appelle l'ingénierie de contexte.

Les outils intégrés ne couvrent que les flux de travail courants. Pour quelque chose de plus spécifique, vous exposez une fonction Python comme outil avec le décorateur @tool.

La docstring fait office de manuel d'instructions, indiquant au modèle ce que fait l'outil, quand l'utiliser et ce qu'il attend comme entrée.

1from crewai.tools import tool
2import subprocess
3
4@tool("run_tests")
5def run_tests(path: str = "tests/") -> str:
6    """Exécute la suite pytest au chemin donné et retourne le résultat."""
7    result = subprocess.run(
8        ["pytest", path, "-q"], capture_output=True, text=True, timeout=120
9    )
10    output = result.stdout + result.stderr
11    return output[-4000:] if len(output) > 4000 else output

Planifier les tâches longues

À mesure que les tâches deviennent plus complexes, une simple boucle d'exécution commence à perdre de vue l'objectif initial. Après suffisamment d'appels d'outils, de lectures de fichiers et de résultats intermédiaires, le contexte se remplit et l'objectif est noyé par tout ce qui est venu après.

Cette dégradation progressive est ce qu'on appelle la pourriture du contexte.

La planification y remédie directement. L'agent élabore un plan étape par étape avant d'effectuer tout travail et conserve ce plan en contexte tout au long de l'exécution.

Le plan ne fait pas le travail. C'est une feuille de route qui maintient le modèle connecté à l'objectif initial, ce qui est la même fonction que la liste de tâches de Claude Code.

CrewAI ajoute cela au niveau de l'équipage avec planning=True. Il génère un plan avant l'exécution et le maintient disponible pendant que la tâche progresse.

1from crewai import Crew, LLM
2
3crew = Crew(
4    agents=self.agents,
5    tasks=self.tasks,
6    planning=True,
7    planning_llm=LLM(model="gpt-4o-mini"),
8)

Note : Par défaut, CrewAI utilise gpt-4o-mini pour la planification, et vous pouvez le remplacer par n'importe quel LLM de votre choix pour cette étape.

Les agents individuels peuvent aussi raisonner sur leur propre travail avec reasoning=True :

1from crewai import Agent
2
3bug_fixer = Agent(
4    role="Bug Fixer",
5    goal="Find and describe the fix for the reported bug in the codebase.",
6    backstory="You read directories and files to build an accurate picture of the code.",
7    tools=[FileReadTool()],
8    reasoning=True,
9    max_reasoning_attempts=3  # Optionnel : définir un nombre maximum de tentatives de raisonnement
10)

La planification et le raisonnement résolvent des problèmes différents. La planification élabore une feuille de route de haut niveau pour l'ensemble de la tâche, tandis que le raisonnement donne à un agent le temps de réfléchir à sa propre approche avant d'agir.

Lorsque le raisonnement est activé, l'agent :

1. Réfléchit à la tâche et ébauche un plan d'exécution.
2. Évalue si le plan est prêt.
3. Raffine le plan si nécessaire, jusqu'à ce qu'il soit satisfait ou atteigne max_reasoning_attempts.
4. Injecte le plan de raisonnement finalisé dans la tâche avant l'exécution.

Ensemble, ils maintiennent l'agent concentré sur les tâches longues et réduisent la dérive par rapport à l'objectif initial.

Déléguer avec des sous-agents

La planification maintient l'agent concentré, mais elle ne réduit pas la quantité d'informations que le modèle doit retenir. Sur une grande base de code, même une tâche bien planifiée peut dépasser une seule fenêtre de contexte.

Trouver un bug peut nécessiter la lecture de dizaines de fichiers, et l'agent principal n'a pas besoin de tous les garder en mémoire.

Les sous-agents résolvent ce problème par délégation. L'agent principal confie une tâche spécifique à un agent auxiliaire, qui travaille dans son propre contexte et renvoie un résumé court. L'agent principal voit la conclusion, pas les étapes intermédiaires.

CrewAI prend en charge cela via des workflows hiérarchiques, où un agent gestionnaire délègue à des agents spécialistes et combine leurs résultats.

Dans notre configuration précédente, un seul agent de correction de bugs faisait tout le travail. Répartissons-le entre un gestionnaire et trois spécialistes :

• Explorateur de code : explore le code et cartographie le dépôt.
• Ingénieur logiciel : implémente le changement demandé.
• Exécuteur de tests : exécute les tests dans le sandbox et rapporte le succès ou l'échec.
• Responsable technique : supervise les trois spécialistes.

1from crewai import Crew, Agent, Task, Process
2
3explorer = Agent(
4    role="Codebase Explorer",
5    goal="Map the repository and surface the files relevant to the task.",
6    backstory="You read directories and files to build a picture of the code.",
7    tools=[read_file, list_dir],
8    llm=llm,
9)  # Idem pour les deux autres agents spécialistes
10
11manager = Agent(
12    role="Engineering Lead",
13    goal="Break the request into steps and delegate each to the right specialist.",
14    backstory="You decide who does what, review tests, finish once change is done.",
15    llm=llm,
16    allow_delegation=True,
17)
18
19crew = Crew(
20    agents=[explorer, coder, tester],
21    tasks=[task],
22    manager_agent=manager,
23    process=Process.hierarchical,
24)

À noter : allow_delegation est désactivé par défaut, il doit donc être explicitement activé sur le gestionnaire.

Sandboxing : sécuriser l'exécution de l'agent

Un agent avec un accès shell peut exécuter une commande destructrice, et dire au modèle de ne pas faire quelque chose n'est pas une protection.

La véritable protection vient de deux couches :

1. Un système de permissions qui exige une approbation pour les actions sensibles.
2. Un sandbox qui isole l'exécution, de sorte que même les commandes approuvées ne peuvent pas toucher la machine hôte.

Anthropic utilise la même approche. Déplacer l'exécution du code dans un sandbox réduit la fréquence à laquelle l'utilisateur doit approuver des actions tout en protégeant le système hôte.

Sandboxing dans CrewAI

Exécuter du code à l'intérieur d'un sandbox plutôt que sur la machine hôte applique cette deuxième couche. Dans cette configuration, le code s'exécute dans E2B, qui lance une nouvelle VM par session et la détruit ensuite.

Les commandes shell et Python s'exécutent entièrement dans cet environnement isolé.

1from crewai_tools import E2BExecTool, E2BPythonTool
2sandbox_tools = [E2BExecTool(), E2BPythonTool()]  # exécuter tests / exécuter code

Approbation humaine dans la boucle

Définir human_input=True sur une Tâche met en pause l'équipage après qu'il a généré une réponse. Vous examinez la sortie, puis l'approuvez ou la renvoyez pour une autre itération.

Lorsque l'exécution atteint cette tâche, CrewAI attend votre retour via l'entrée standard.

1from crewai import Task
2
3task = Task(
4    description=(
5        "Dans le répertoire de travail ./workspace, {objective}. "
6        "Explorez d'abord le code, effectuez la modification, puis exécutez les tests et faites un rapport."
7    ),
8    expected_output="Un résumé des fichiers modifiés et du résultat final des tests.",
9    human_input=True,
10)

Si votre équipage fonctionne derrière une application web ou une interface de chat plutôt qu'un terminal, le système d'approbation humaine basé sur les webhooks de CrewAI gère la même étape de révision.

Mémoire et checkpointing

Par défaut, un agent oublie tout une fois l'exécution terminée. Revenez le lendemain pour corriger un autre bug dans le même projet, et il repart de zéro.

Deux mécanismes permettent à un agent de transporter des informations entre les exécutions, chacun servant un objectif différent :

• Le checkpointing enregistre l'état de l'agent pendant une exécution, afin qu'il puisse reprendre après une interruption ou continuer à partir du même point sur un chemin différent.
• La mémoire persistante stocke des faits à travers des conversations séparées, y compris les préférences du projet comme "toujours formater le code final avant de terminer".

Mémoire dans CrewAI

CrewAI fournit une interface Mémoire unifiée plutôt que des types de mémoire séparés (court terme, long terme, entité, externe). Lors de l'enregistrement, il utilise un LLM pour identifier les détails importants, les organiser et les rendre récupérables plus tard.

Définir memory=True sur l'équipage lui donne une mémoire entre les exécutions. Après chaque tâche, CrewAI extrait les faits utiles de la sortie et les stocke ; lors des exécutions futures, il récupère les souvenirs pertinents et les ajoute à l'invite de la tâche.

1from crewai import Crew
2
3crew = Crew(
4    agents=[explorer, coder, tester],
5    tasks=[task],
6    memory=True,
7)

Tous les agents d'un équipage partagent sa mémoire, sauf si un agent se voit attribuer la sienne.

Checkpointing dans CrewAI

Un checkpoint est un instantané de la progression d'un agent, comprenant sa configuration, l'état de la tâche, la mémoire, les résultats intermédiaires, les entrées et l'historique d'exécution.

Par défaut, CrewAI crée un checkpoint chaque fois qu'une tâche se termine, permettant au workflow de reprendre à partir de ce point en cas d'interruption.

Les checkpoints peuvent être stockés dans l'un des deux magasins intégrés :

• JsonProvider enregistre chaque checkpoint sous forme de fichier JSON séparé, facile à lire et à inspecter manuellement.
• SqliteProvider stocke tous les checkpoints dans une seule base de données SQLite, qui tient mieux sous des checkpointings fréquents et des charges de travail plus importantes.

1from crewai import Crew
2
3crew = Crew(
4    agents=[explorer, coder, tester],
5    tasks=[task],
6    checkpoint=True,
7)

Crew, Flow et Agent acceptent tous un argument checkpoint, et les enfants héritent de leur parent sauf s'ils définissent leur propre valeur.

Tout assembler

Voici le harnais complet sur une seule tâche, avec la boucle d'exécution, les outils, la planification, les sous-agents, le sandboxing et la mémoire qui fonctionnent ensemble :

1from crewai import Agent, Crew, LLM, Process, Task
2from crewai.tools import tool
3from crewai_tools import (DirectoryReadTool, FileReadTool, FileWriterTool,
4E2BExecTool, E2BPythonTool)
5
6llm = LLM(model="anthropic/claude-sonnet-4.6")
7
8list_dir = DirectoryReadTool(directory="./workspace")
9filesystem_tools = [FileReadTool(), FileWriterTool(), list_dir]
10sandbox_tools = [exec_tool, E2BPythonTool()]
11
12@tool("run_tests")
13def run_tests(path: str = "tests/") -> str:
14    """Synchronise ./workspace dans le sandbox, puis exécute pytest."""
15    return E2BExecTool().run(command=sync_and_test_command(path))
16
17explorer = Agent(role="Codebase Explorer", goal="Mapper le dépôt, faire remonter les fichiers pertinents.",
18    tools=[read_file, list_dir], llm=llm)
19coder = Agent(role="Software Engineer", goal="Implémenter le changement demandé.",
20    tools=filesystem_tools, reasoning=True, llm=llm)
21tester = Agent(role="Test Runner", goal="Exécuter les tests dans le sandbox, rapporter succès/échec.",
22    tools=sandbox_tools + [read_file] + [run_tests], llm=llm)
23manager = Agent(role="Engineering Lead", goal="Déléguer les étapes, terminer une fois les tests passés.",
24    allow_delegation=True, llm=llm)
25
26task = Task(
27    description="Dans ./workspace, {objective}. Explorer, éditer, tester, rapporter.",
28    expected_output="Résumé des modifications et résultat des tests.", human_input=True,
29)
30crew = Crew(
31    agents=[explorer, coder, tester], tasks=[task],
32    manager_agent=manager, process=Process.hierarchical,
33    planning=True, memory=True, checkpoint=True,
34)
35result = crew.kickoff(inputs={"objective": "corriger les tests échoués dans account.py"})

Les harnais d'agents sont plus faciles à évaluer lorsque le succès peut être vérifié automatiquement. Une suite de tests donne à l'agent un objectif concret, afin qu'il puisse planifier, éditer, tester et répéter jusqu'à ce que tout réussisse.

Ceci a donc été testé sur une petite base de code, une classe BankAccount avec deux vrais bugs et cinq tests, dont trois échouaient. La règle était de ne corriger que l'implémentation, pas les tests.

Cela reflète la façon dont Anthropic évalue les agents de codage en interne. Un exemple publié montre Claude reconstruisant un clone de l'interface claude.ai face à une grande suite de tests échoués.

Ici, le harnais a fait passer le projet de 3 échecs et 2 succès à 5 succès, la règle de ne modifier que l'implémentation empêchant la solution de facilité consistant à éditer ou supprimer les tests échoués.

Ce qui reste votre travail

Certaines parties du système ne sont pas construites par le framework pour vous :

• Les prompts. Le comportement de chaque agent provient de son rôle, de son objectif et de son histoire. Les obtenir correctement demande des tests et des itérations, et aucun paramètre de configuration ne peut les remplacer.
• L'environnement d'exécution. Le sandbox, que ce soit E2B ou une VM auto-gérée, doit être configuré et connecté.
• La sélection des outils. Quels outils chaque agent reçoit, et quel agent doit avoir accès à quoi, est une décision de conception que le framework ne prend pas.

Il y a aussi un coût au harnais lui-même. La planification, les sous-agents et les boucles ajoutent tous des appels API, de sorte qu'une configuration d'agent complexe peut finir par coûter plus cher qu'une tâche qu'un seul appel de modèle aurait résolu directement.

Et il y a une limitation à plus long terme à garder à l'esprit. À mesure que les modèles s'améliorent, une partie de l'infrastructure cesse d'être nécessaire, car une partie de ce qui est intégré dans un harnais aujourd'hui est un contournement des limites actuelles du modèle plutôt qu'une exigence permanente.

Anthropic utilisait à l'origine des réinitialisations de contexte pour empêcher Claude Sonnet 4.5 de terminer les tâches trop tôt, et elles n'étaient plus nécessaires avec le plus performant Claude Opus 4.5.

Pour conclure

Voilà toute la découverte. La capacité d'un agent de codage réside principalement dans le harnais, et un framework d'orchestration vous donne une plus grande partie de ce harnais que vous ne le pensez.

La boucle, la planification, la délégation, le sandboxing et la mémoire arrivent tous sous forme de configuration, tandis que les prompts, l'environnement d'exécution et les choix d'outils restent les vôtres.

Si vous souhaitez exécuter ceci sur votre propre base de code, la documentation de CrewAI couvre toutes les fonctionnalités utilisées ici, et le framework est entièrement open source.

Consulter la documentation CrewAI →

Trouver tout le code ici →

Merci d'avoir lu !

Bravo ! :)