Sous le capot de Claude Code : l'art de l'ingénierie agentique

Le terminal n’a jamais été aussi intelligent. Si vous avez testé Claude Code, vous savez que ce n'est pas un simple "wrapper" autour d'une API. C'est une bête de performance capable de naviguer dans des millions de lignes de code, d'exécuter des tests et de corriger des bugs en toute autonomie.

J'ai décidé de plonger dans le code source du projet pour comprendre comment il est construit. Voici ce que j'ai appris sur l'art de l'ingénierie agentique.

Pourquoi Claude Code est différent ?

Contrairement à une interface de chat classique, Claude Code est un agent orienté action. Il ne se contente pas de suggérer du code, il possède un "corps" (via le terminal) pour interagir avec votre environnement local.

Les points forts :

Rapidité d'exécution grâce à un runtime moderne.
Autonomie réelle via une orchestration d'outils intelligente.
Gestion du contexte chirurgicale pour ne jamais "perdre le fil".

Une pile technique taillée pour la performance

Le premier secret de sa fluidité réside dans ses choix technologiques. On oublie Node.js pour quelque chose de plus nerveux.

Bun : le moteur de bundle

Le choix de Bun permet un démarrage quasi instantané. Le code utilise massivement les imports dynamiques et des macros de build pour n'injecter que le nécessaire selon la plateforme.

React + Ink : l'UI réactive dans le terminal

C'est sans doute le point le plus surprenant : Claude Code utilise React avec la bibliothèque Ink. Cela permet de gérer l'affichage (barres de progression, menus interactifs) comme une application web, mais directement dans votre shell.

// Exemple conceptuel de composant Ink utilisé dans le projet
import React from 'react';
import {Text} from 'ink';

const StatusLine = ({status}) => (
  <Text color="green">
    [Claude] {status}...
  </Text>
);

Architecture Core

Points d'entrée :
- src/main.tsx : Point d'entrée principal du CLI.
- src/entrypoints/cli.tsx : Logique de bootstrap, gestion des chemins rapides (ex: --version) et modes spécialisés (daemon, serveur MCP).
Commandes (src/commands/) :
- Implémentation des commandes CLI comme init, login, review, commit, mcp, session, tasks, etc.
- src/commands.ts : Registre central où les commandes sont importées et configurées.
Outils (src/tools/) :
- Outils fournissant des capacités à l'agent IA, incluant BashTool, AgentTool, GitTool, LSPServerTool, et le support de MCP (Model Context Protocol).
Services (src/services/) :
- Intégration avec des services externes : API, Analytics (GrowthBook), Registre MCP, PolicyLimits.
Composants UI (src/components/ & src/screens/) :
- Composants React basés sur Ink pour le rendu terminal, incluant les boîtes de dialogue, les lignes de statut et les invites interactives.
Utilitaires (src/utils/) :
- Ensemble complet d'aides pour les opérations de système de fichiers (fsOperations.ts), l'intégration Git (git.ts), la détection de plateforme (platform.ts), la télémétrie, et plus encore.

La boucle de réflexion (Agent Logic)

Le cœur du réacteur se trouve dans src/query.ts. Claude Code n'envoie pas juste une question à l'IA ; il gère une boucle itérative sophistiquée.

Thinking : L'IA génère un bloc de réflexion pour planifier ses étapes.
Orchestration : Le système décide d'exécuter des outils en parallèle (lecture) ou en séquence (écriture).
Intégration : Les résultats du terminal sont réinjectés pour le tour suivant.

L'orchestration intelligente

Dans src/services/tools/toolOrchestration.ts, on voit une gestion fine de la concurrence :

Lecture parallèle : Plusieurs ls ou grep s'exécutent en même temps.
Écriture séquentielle : Pour éviter les conflits d'édition sur vos fichiers source.

L'extension sans limite via MCP

Claude Code implémente le Model Context Protocol (MCP). C'est, selon moi, l'avenir de l'IA extensible. Grâce à MCP, l'agent peut se connecter à des serveurs externes sans que son code de base ne soit modifié.

Imaginez Claude capable d'interroger votre base de données SQL ou votre Slack d'entreprise via un simple protocole standardisé. C'est le "USB" de l'intelligence artificielle.

La guerre contre l'oubli : Gestion du Contexte

Le plus grand défi des agents est la taille de la mémoire vive (le contexte). Claude Code utilise des techniques de chirurgie de contexte :

Micro-compaction : Résume les sorties de commandes trop verbeuses.
Snipping : Supprime les messages de "bruit" (erreurs répétées, logs inutiles) pour libérer de la mémoire vive pour l'IA.
Persistence : Chaque tour est enregistré via recordTranscript. Vous pouvez couper votre terminal et reprendre exactement là où vous en étiez avec la commande resume.

L'expérience invisible : Observabilité

Le génie se cache aussi dans src/services/analytics/. Claude Code suit en temps réel la "santé" de l'agent :

Latence des appels API.
Taux de réussite des outils utilisés.
Consommation de tokens par tâche.

Cette observabilité agentique permet de détecter si l'IA s'enferme dans une boucle infinie ou si un outil devient trop lent.

Le Packaging : Une Chirurgie de Précision

L'un des aspects les plus impressionnants est la façon dont le code est assemblé. Le projet utilise le bundler de Bun avec un système de Feature Flags (feature('KAIROS')) et de Macros.

Builds Différenciés : Le code contient des blocs entiers qui sont supprimés lors de la compilation pour les versions externes. Cela permet de garder une version publique légère tout en conservant des fonctionnalités expérimentales en interne.
Macros de Build : Des informations comme l'heure de compilation (MACRO.BUILD_TIME) ou la version (MACRO.VERSION) sont injectées directement dans le binaire.
Zéro Dépendance Externe au Runtime : Grâce au bundling, l'utilisateur final n'a pas besoin d'installer des milliers de modules node_modules. Tout est packagé dans un exécutable cohérent.

Fonctionnement avec un exemple : Flux de Requête

Lorsqu'un utilisateur soumet une requête (ex: "Écris une méthode Java pour calculer des factorielles"), Claude Code suit ce flux interne :

Capture de l'entrée : Le REPL ou le CLI capture l'invite de l'utilisateur.
Assemblage du contexte : src/query.ts rassemble le contexte pertinent, incluant l'état du répertoire actuel, les fichiers ouverts et les ressources MCP.
Logique de l'agent : Le QueryEngine envoie l'invite et le contexte à l'API Claude. L'agent décide quels outils sont nécessaires.
Orchestration des outils : src/services/tools/toolOrchestration.ts gère l'exécution des outils.
- Exemple (Méthode Java) :
  - L'agent peut d'abord utiliser BashTool pour l'équivalent d'un ls afin de localiser les fichiers source Java.
  - Il utilise ensuite FileReadTool pour comprendre la structure des classes existantes.
  - Enfin, il utilise FileWriteTool (ou ReplaceTool) pour insérer la nouvelle méthode dans le fichier .java approprié.
Validation : Si configuré, l'agent peut réutiliser BashTool pour exécuter javac ou mvn test afin de vérifier le code.
Réponse : Le résultat final et les sorties du terminal sont rendus à l'utilisateur via Ink.

Conclusion et inspirations

Ce que l'on peut retenir de Claude Code pour nos propres projets :

L'IA a besoin d'agir : Ne construisez pas que des chatbots, construisez des outils avec des capacités d'action réelles.
La sécurité est primordiale : Le système de permissions granulaires de Claude Code est un modèle du genre.
Soignez le startup : Dans un CLI, chaque milliseconde de délai au démarrage compte.

Claude Code est un chef-d'œuvre d'ingénierie logicielle moderne qui montre qu'un agent efficace n'est pas seulement "intelligent", il est surtout bien orchestré.

Ressources

🌐 Site officiel : https://code.claude.com/
💻 GitHub : https://github.com/anthropics/claude-code
📚 Guide utilisateur : https://code.claude.com/docs/fr/overview

#OpenSource #AI #SoftwareEngineering #ClaudeCode #TypeScript #Bun #React #MCP #Observability #Performance

Sous le capot de Claude Code : l'art de l'ingénierie agentique