Claude Code en profondeur : architecture cœur d'un outil de codage IA de premier plan

La plupart des articles sur Claude Code s'arrêtent à « installer le CLI, poster un diff ». Dans une vraie équipe, on comprend vite : l'architecture cœur d'un outil de codage IA de premier plan, ce n'est jamais le seul processus Agent dans le terminal — c'est la façon dont Diff, Fact, Context et Workflow se répartissent le travail et bouclent la boucle dans le Cloud Mac AI Stack.

Ce texte est la carte pilier L6-Q02 (L6-Q02) : Claude Code comme point d'entrée pour dessiner l'architecture Stack complète, l'ordre de branchement des cinq modules et la boucle fermée système. Pour le manuel opérationnel, voir le guide complet L6-Q01 ; pour les seuils de permissions, l'introduction décision L3 — ici, la carte uniquement.

Claude Code lui-même : les 10 % à comprendre (les 90 % restants, c'est le Stack)

Architecture · noyau Claude Code

Définissons d'abord Claude Code en tant que tel, puis sa place dans le Stack. C'est un Agent de codage terminal, pas une extension IDE :

Boucle Agent unique (peut itérer)

  Lire CLAUDE.md + contexte du dépôt
           │
           ▼
  Planifier (quels fichiers, quelles commandes)
           │
           ▼
  Exécuter (Write / Edit / Bash / outil MCP optionnel)
           │
           ▼
  Vérifier (vos test / lint)
           │
           └──► Livrable Diff (modifications auditables par git)

• Limites — CLAUDE.md et la politique de permissions définissent ce qu'il peut toucher ; voir guide · limites projet
• Perceptions étendues — MCP relie Issues GitHub, CodeGraph et API au Context ; voir le hub Triple Connect MCP
• vs Cursor — complétion dans l'éditeur vs Agent multi-fichiers + shell ; voir vs Cursor

On reste au niveau L3. L'« architecture cœur » qu'une organisation peut réellement adopter, c'est la carte Stack ci-dessous.

Carte Stack Cloud Mac AI complète (couches de responsabilité)

Architecture · carte globale du site

Voici le modèle unifié L0–L5 du site — revenez-y en lisant n'importe quel article thématique. Important : ce sont des couches de responsabilité, pas l'ordre d'appel à l'exécution.

Livrables : Inference · Diff · Fact · Context · Workflow

                 ┌──────────────┐
                 │  OpenHands   │  L5 · Workflow (toute la demande est-elle terminée ?)
                 └──────┬───────┘
                        │
                 ┌──────▼───────┐
                 │     MCP      │  L4 · Context (que voit l'Agent ?)
                 └──────┬───────┘
                        │
                 ┌──────▼───────┐
                 │ Claude Code  │  L3 · Diff (qu'est-ce qui a changé ?) ← entrée
                 └──────┬───────┘
                        │
                 ┌──────▼───────┐
                 │    Ollama    │  L2 · Inference (optionnel · calcul privé local)
                 └──────┬───────┘
                        │
                 ┌──────▼───────┐
                 │ GitHub Runner│  L1 · Fact (l'organisation peut-elle faire confiance ?)
                 └──────┬───────┘
                        │
                 ┌──────▼───────┐
                 │  Cloud Mac   │  L0 · infrastructure (nœud macOS 24/7)
                 └──────────────┘

L0 porte le calcul, L1 porte le Fact — ensuite seulement Diff, Context et Workflow. Quel que soit le niveau de Claude Code, sans L1, le Diff n'est qu'une expérimentation locale.

Cinq modules (+ base) : rôles et livrables

Architecture · référence modules

Workflow (L5) et Fact (L1) : OpenHands consomme à répétition le Context, produit le Diff et valide avec le Fact pendant une tâche — ce n'est pas « la CI seulement après la fin du Workflow ». Voir OpenHands · relations des livrables.

Ordre de branchement recommandé : le Fact avant le Diff

Architecture · parcours de déploiement

L'ordre à la mode est souvent : Claude Code d'abord → MCP ensuite → la CI en dernier recours. Nous recommandons plutôt cette séquence de déploiement (différente de l'ordre des couches sur le schéma) :

 ① Cloud Mac (base L0)
      │  macOS permanent · SSH · IP de sortie
      ▼
 ② GitHub Runner (L1 · Fact)
      │  push → vert/rouge reproductible · isolation workspace
      ▼
 ③ Ollama (L2 · Inference, optionnel)
      │  embedding local / petits modèles · surveiller RAM L1/L3
      ▼
 ④ Claude Code (L3 · Diff)
      │  CLAUDE.md · permissions · essai jour 1
      ▼
 ⑤ MCP (L4 · Context)
      │  GitHub / CodeGraph / Fetch · privilèges minimaux
      ▼
 ⑥ OpenHands (L5 · Workflow)
      │  issues multi-étapes · boucle Agent · empilé sur L3
      ▼
 ⑦ Boucle fermée système
      déléguer → Diff → PR → Runner Fact → revue → merge

1. ① L0 — Sans nœud macOS 24/7, Runner et Agent se disputent la RAM du portable ; voir acheter ou louer
2. ② L1 — D'abord un Fact fiable pour l'organisation ; isolation : un job, un workspace
3. ③ L2 — Optionnel ; sur le même hôte que Claude Code et Runner, voir la planification parallèle
4. ④–⑥ — Empiler l'IA une fois le Fact stabilisé ; manuel : L6-Q01
5. ⑦ Boucle fermée — section suivante

Boucle fermée système : de la délégation Claude Code à la PR verte

Architecture · boucle fermée

Le dernier pan de l'« architecture cœur », c'est comment les données reviennent — l'Agent ne peut pas vivre dans un terminal isolé :

Humain dans la boucle · L3
  Développeur ──délègue──► Claude Code (+ Context MCP)
                        │
                        │  Diff (commit)
                        ▼
                   branche feature / PR
                        │
Acceptation machine · L1        ▼
              GitHub Runner (Fact)
                   xcodebuild / test / lint
                        │
                        ├── rouge ──► retour à l'Agent (Diff ↔ Fact)
                        │
                        └── vert ──► revue humaine ──► merge

Optionnel · L5
  OpenHands vide la file d'issues la nuit ──► même boucle PR + Runner

Trois conditions strictes pour une boucle qui tient : isolation environnement Runner et Agent, la PR doit passer la CI, secrets prod jamais dans le shell Agent. Checklist production : L6-Q01 · production.

Hub de liens internes : sauter par couche

Cet article est la page carte de la série Stack. Choisissez l'entrée selon votre blocage actuel :

FAQ

Quelle est l'architecture cœur de Claude Code ? Boucle Agent terminal produisant le Diff ; en production, il faut aussi CLAUDE.md, Context MCP et Runner indépendant pour le Fact.

Faut-il installer Ollama avant Claude Code ? Non. L2 est optionnel ; le schéma montre des couches de responsabilité, pas une chaîne d'appels.

Quelle différence avec le guide L6-Q01 ? Q01 est la ligne opérationnelle (installation→CI) ; Q02 est la carte Stack globale (cet article).

OpenHands peut-il remplacer Claude Code ? Non. L5 orchestre le Workflow, L3 produit le Diff en binôme — à utiliser en empilement.

• L6-Q01 · guide complet Claude Code
• L1 · GitHub Runner Execution Engine
• L4 · hub Triple Connect MCP