Claude Code : de l'installation au workflow de production

Les tutoriels éparpillés sur Claude Code vont du simple npm install à une capture de diff, en mélangeant MCP et permissions. Pour passer en production, il ne manque pas « un raccourci de plus », mais un parcours complet du CLI à la CI au vert.

Ce texte est le guide pilier Cloud Mac AI Stack · L6 (L6-Q01) : Claude Code comme agent de codage de bout en bout — installation, premier pilote, délégation quotidienne, MCP, jusqu'au workflow de production couplé au GitHub Runner. Seuils de décision et permissions : introduction L3 ; MCP pas à pas : tutoriel MCP — ici, seulement la ligne directrice.

Squelette de ce guide

Ce n'est pas la liste officielle exhaustive des capacités, mais l'arbre directeur de L6-Q01 — chaque branche correspond à une section (ancre entre parenthèses). Sous chaque titre, des renvois au squelette alignés sur le tableau. Hooks, sous-agents, gestion entreprise, etc. : articles dédiés ou documentation officielle.

De l'installation au workflow production · juin 2026

Ligne directrice (guide complet Claude Code)
├── Choix d'environnement (#prereq)
│   ├── macOS / Linux — périmètre officiel
│   ├── Mac mini / MacBook local vs Cloud Mac
│   └── Node 18+ · réseau · compte Anthropic / clé API
├── Validation installation (#install)
│   ├── npm install -g @anthropic-ai/claude-code
│   ├── claude doctor · claude login
│   └── 5 étapes (racine dépôt · /help · pas de 401)
├── Premier jour (#first-day)
│   ├── Petite délégation + tests tous verts
│   ├── git diff — vérifier le périmètre
│   └── Habitude de revue (hors limites → décision L3)
├── Limites projet (#claude-md)
│   ├── Template minimal CLAUDE.md (install / test / interdits)
│   └── Commandes exécutables avant la prose
├── Rythme quotidien (#daily)
│   ├── Trois niveaux de délégation (haut / coop / bas)
│   └── Cycle en 4 temps (déléguer → observer → revue → merge)
├── Couche connexion (#mcp)
│   ├── ~/.claude.json · mcpServers
│   ├── GitHub / CodeGraph / Fetch — combo courant
│   └── Validation /mcp (détails → tutoriel MCP)
├── Chaîne CI Fact (#ci)
│   ├── Diff (Claude Code) vs Fact (Runner)
│   ├── Branche feature → Runner self-hosted → PR verte
│   └── Secrets isolés du shell Agent
├── Checklist production (#production)
│   ├── CLAUDE.md / permissions / MCP / secrets / CI / revue / coût
│   └── Tableau pilote vs production
└── Position Stack (#stack-map)
    ├── L0–L5 dans Cloud Mac AI Stack
    └── Liens : décision L3 · tutoriel MCP · Runner Execution Engine

Environnement : Mac ou Cloud Mac ?

Squelette · #prereq · choix d'environnement

Claude Code supporte officiellement macOS et Linux. Web/backend seul : un cloud Linux suffit ; dès que xcodebuild, simulateur iOS ou toolchain macOS entre en jeu, il faut macOS.

• Mac mini / MacBook local — 24 Go de RAM plus confortable (Chrome + Docker + Claude Code : 16 Go swap vite), voir choix M4/M5
• Cloud Mac — sans achat matériel ou pour un environnement dev/CI isolé, voir acheter ou louer
• Déconseillé — secrets prod, agent sans isolation et Runner CI sur le même portable principal (isolation Runner)

Prérequis logiciels : Node.js 18+, accès réseau Anthropic, compte Anthropic (Claude Pro/Max/Team) ou clé API.

Installation et login (5 étapes de validation)

Squelette · #install · validation installation

Commandes à exécuter dans le terminal macOS (identique sur Cloud Mac) :

# 1. Installation globale du CLI
npm install -g @anthropic-ai/claude-code

# 2. Auto-diagnostic (version Node, PATH…)
claude doctor

# 3. Connexion (OAuth navigateur ou clé API)
claude login

Premier jour : valider la première délégation

Squelette · #first-day · premier jour

Installer ne signifie pas « maîtriser ». Le jour 1, un seul objectif : petite modification + tous les tests au vert — calibrer l'intuition sur le comportement de l'agent.

1. Créer ou compléter CLAUDE.md à la racine (section suivante)
2. Lancer claude, déléguer par ex. : « Ajouter une section Développement local au README — README uniquement, aucun autre fichier »
3. Observer : l'agent lit-il d'abord, modifie-t-il, exécute-t-il vos commandes de validation ?
4. git diff pour vérifier le périmètre — pas de débordement
5. Avant merge, relancer vous-même les tests (ne pas croire aveuglément « l'agent dit vert »)

L'objectif jour 1 n'est pas la vitesse mais l'habitude de revue. Si l'agent modifie les mauvais dossiers ou exécute des commandes risquées : retour à la décision permissions, pas de rush sur le dépôt prod.

CLAUDE.md : limites du projet

Squelette · #claude-md · limites projet

CLAUDE.md est le « README for Agent » — plus de commandes exécutables et interdictions que de prose marketing. Quasi indispensable en dépôt de production.

# Projet : my-saas

## Installation
pnpm install

## Tests (tout lancer après modification)
pnpm test
pnpm lint

## Ne pas modifier
- Ne pas toucher .env, secrets/
- Pas de upgrade major de dépendances sans consigne explicite
- Changements billing : mettre à jour les tests associés

## Convention répertoires
- src/app — pages Next.js
- packages/api — logique backend

Avec un CLAUDE.md complet, le taux de mauvais fichiers et les tours de boucle de tests baissent souvent — dans notre test workstation, environ 20 % de temps en moins vs template vide.

Workflow de développement quotidien

Squelette · #daily · rythme quotidien

Après le pilote, le rythme courant. Trois niveaux de tâches plutôt que « tout à l'agent » :

Cycle quotidien en quatre temps :

1. Déléguer — périmètre, critères d'acceptation, répertoires interdits
2. Observer — fichiers lus, commandes shell exécutées
3. Revue — git diff + vos tests (comme CLAUDE.md)
4. Merge — PR + code review ; pas de commits directs sur main par l'agent

Par rapport à Cursor : Cursor pour complétion et petits diffs ; Claude Code pour multi-fichiers + shell + boucles de tests. Les deux coexistent — un seul outil ne couvre pas tout.

Brancher MCP (couche connexion)

Squelette · #mcp · couche connexion

Quand l'agent doit lire des Issues GitHub, un graphe de code ou de la doc API, le grep du dépôt ne suffit pas — alors MCP (Model Context Protocol), l'équivalent d'un port standard pour Claude Code.

• Configuration — section mcpServers dans ~/.claude.json
• Combo courant — GitHub MCP (Issue/PR), CodeGraph MCP (impact), Fetch MCP (documentation)
• Validation — dans Claude Code, saisir /mcp ; outils mcp__github__* visibles

Installation pas à pas : tutoriel MCP (15 min) ; modèle de permissions : MCP privilèges minimaux. MCP est un composant clé du workflow production, mais pas tout le jour 1 — d'abord le flux de base sans MCP, puis GitHub MCP.

Relier la CI : Claude Code + Runner

Squelette · #ci · chaîne CI Fact

Tests locaux au vert après l'agent ne font pas encore la production — il faut une chaîne CI Fact isolée de la machine de dev. Formule du Stack :

Claude Code produit le Diff, GitHub Runner produit le Fact.

Workflow recommandé :

1. Le dev termine sur Cloud Mac / Mac local avec Claude Code, pousse une branche feature
2. Runner self-hosted (séparé de l'agent) exécute xcodebuild test / pnpm test, etc.
3. Merge PR seulement si CI verte + revue humaine
4. Secrets prod uniquement sur Runner ou gestionnaire de secrets — pas dans le shell Agent

Enregistrement et isolation Runner : Execution Engine · file d'attente et TCO · un job, un workspace.

Si Ollama + Claude Code + Runner sur le même hôte : planifier la RAM, éviter le swap — planification parallèle.

Checklist production (avant mise en ligne)

Squelette · #production · checklist production

De « ça tourne » à « déployable » — parcourir ce tableau :

Carte Stack complète

Squelette · #stack-map · position Stack

Place dans le Cloud Mac AI Stack :

• L0 Base — Pourquoi Cloud Mac
• L1 Execution — GitHub Runner (couche Fact)
• L2 Inference — Ollama inference privée (optionnel, embeddings / petits modèles locaux)
• L3 Coding — ce guide · Claude Code complet (ligne Diff)
• L4 Connect — MCP Triple Connect
• L5 Automation — plateforme agent OpenHands

L'architecture Stack globale + ordre de branchement des cinq modules est dans la carte pilier L6-Q02 · architecture cœur Claude Code & carte Stack — ce guide est le manuel terrain « agent de codage ».

FAQ

Squelette · #faq · réponses complémentaires

Faut-il obligatoirement un Mac pour Claude Code ? Officiellement macOS et Linux. Builds iOS/macOS : Mac requis — local ou Cloud Mac.

Abonnement ou clé API ? Pilote : abo Pro/Max le plus simple ; équipe ou CI souvent clé API avec contrôle d'usage. Coûts : tarification modèles.

MCP obligatoire en production ? Petits dépôts : non ; dès qu'il faut lire des Issues GitHub ou de la doc cross-service, quasi standard.

L'agent a cassé quelque chose ? git checkout -- . ou git stash ; petits commits, branches fréquentes — pas plusieurs délégations sur working tree sale.

• Décision L3 : quand brancher l'agent officiellement
• Tutoriel installation MCP Claude Code
• Test workstation Mac mini
• GitHub Runner Execution Engine