Claude Code dans VS Code : installer, configurer et maîtriser son premier workflow

Claude Code dans VS Code ajoute un mode de travail plus agentique que l’autocomplétion classique : vous demandez, il explore, propose un plan, modifie les fichiers, puis vous validez chaque changement dans un diff côte à côte. Dans ce guide, vous allez installer l’extension officielle, connecter votre compte, ouvrir votre première session, puis exécuter une boucle contrôlée sur un projet réel dans ~/Projets/lab-claude. L’API FastAPI ne sert ici que de support d’exercice — le sujet est Claude Code.

Ce que vous allez apprendre

Installer l’extension, vérifier le CLI et gérer le cas où le CLI est absent
Comprendre les différentes manières d’ouvrir le panneau Claude Code dans VS Code
Se connecter, démarrer une nouvelle session et reprendre une session existante
Utiliser les @-mentions pour cadrer le contexte sans copier-coller
Choisir le bon mode de permission (Normal, Plan, Auto-accept)
Relire un diff, utiliser les checkpoints et revenir en arrière si besoin
Appliquer une première modification contrôlée avec validation

Dans quel contexte ?

Ce guide est utile si vous travaillez déjà dans VS Code et que vous voulez intégrer Claude Code sans changer tout votre flux de travail. L’objectif n’est pas de faire “plus d’IA”, mais de garder un cadre clair : contexte explicite, permissions adaptées, validation systématique.

Situations concrètes où ce guide vous fait gagner du temps :

Vous voulez passer d’un prompt vague à une demande bornée et vérifiable
Vous devez modifier plusieurs fichiers sans perdre le contrôle du périmètre
Vous voulez relire chaque proposition via un diff avant d’accepter
Vous souhaitez standardiser un cycle simple : plan -> changement -> tests

Ce que ce guide couvre (et ne couvre pas)

Ce guide se concentre sur la compétence “utiliser Claude Code dans VS Code de manière contrôlée”.

Prompt ponctuel : oui, vous l’utilisez pour lancer des tâches bornées
CLAUDE.md : mentionné, mais détaillé dans un guide dédié
rules/*.md et skills/*/SKILL.md : rappelés, pas implémentés ici en profondeur
Hooks, MCP et subagents : hors périmètre opérationnel de ce premier workflow

Cette séparation est volontaire pour éviter de mélanger les leviers trop tôt.

Prérequis

VS Code 1.98.0 ou supérieur
Un compte Anthropic compatible Claude Code (Pro, Max, Team, Enterprise ou Claude Console)
Un terminal disponible sur votre machine
Le projet fil rouge disponible localement dans ~/Projets/lab-claude

Étape 1 : Installer l’extension Claude Code dans VS Code

Source officielle : Use Claude Code in VS Code.

Ouvrez l’onglet Extensions dans VS Code (Ctrl+Shift+X Linux/Windows, Cmd+Shift+X Mac)
Recherchez Claude Code (publisher : Anthropic) et cliquez sur Install
Si l’extension n’apparaît pas après installation, rechargez la fenêtre via la Palette de commandes (Ctrl+Shift+P → Developer: Reload Window)

Étape 2 : Vérifier ou installer le CLI

L’extension inclut le CLI, mais celui-ci peut être absent selon la configuration. Vérifiez d’abord.

Ouvrez le terminal intégré VS Code (Ctrl+` Linux/Windows, Cmd+` Mac)
Vérifiez le CLI
Fenêtre de terminal
```
claude --version
claude doctor
```
Si la commande est introuvable, installez le CLI manuellement (Linux/macOS)
Fenêtre de terminal
```
curl -fsSL https://claude.ai/install.sh | bash
```
Sur Windows PowerShell :
Fenêtre de terminal
```
irm https://claude.ai/install.ps1 | iex
```
Fermez le terminal intégré, ouvrez-en un nouveau, puis relancez la vérification
Fenêtre de terminal
```
claude --version
claude doctor
```

Étape 3 : Ouvrir le panneau Claude Code et se connecter

Il y a plusieurs façons d’ouvrir Claude Code dans VS Code. L’icône ✦ (Spark) est le repère visuel de Claude Code partout dans l’interface.

Méthode la plus rapide : cliquez sur l’icône ✦ (Spark) dans la barre d’outils de l’éditeur (coin supérieur droit), visible uniquement lorsqu’un fichier est ouvert
Toujours visible : cliquez sur l’icône ✦ dans l’Activity Bar (barre latérale gauche) — ouvre la liste de sessions
Status Bar : cliquez sur ✱ Claude Code en bas à droite de la fenêtre — fonctionne même sans fichier ouvert
Palette de commandes : Ctrl+Shift+P puis tapez Claude Code → choisissez Open in New Tab
À la première ouverture, un écran de connexion apparaît — cliquez Sign in et finalisez l’authentification dans votre navigateur

Étape 4 : Démarrer une nouvelle session et naviguer dans l’historique

Comprendre la gestion des sessions est indispensable pour ne pas perdre de contexte.

Nouvelle session : ouvrez le panneau Claude Code puis cliquez sur l’icône nouvelle conversation (ou Ctrl+Shift+Esc pour ouvrir un nouvel onglet)
Reprendre une session : cliquez sur Session history (icône horloge en haut du panneau) — recherche par mot-clé possible, navigation par jour (Aujourd’hui, Hier, 7 derniers jours…)
Cliquez sur une session pour la rouvrir avec son historique complet
Survolez une session pour accéder aux actions renommer ou supprimer
Plusieurs sessions en parallèle : Ctrl+Shift+P → Claude Code: Open in New Tab — chaque onglet maintient son propre contexte

Étape 5 : Utiliser les @-mentions pour cadrer le contexte

Les @-mentions sont la façon la plus efficace de dire à Claude ce sur quoi il doit travailler, sans copier-coller.

Dans la zone de prompt, tapez @ suivi du nom d’un fichier ou dossier. Claude Code supporte la correspondance partielle (fuzzy matching) :

@main.py           → cible le fichier main.py
@src/routers/      → cible tout le dossier (avec le slash final)
@auth              → correspond à auth.py, AuthService.ts, etc.

Autres façons d’ajouter du contexte :

Sélection de texte : sélectionnez des lignes dans l’éditeur → Claude voit automatiquement la sélection (le pied du prompt indique le nombre de lignes)
Raccourci @-mention précis : éditeur focalisé + Alt+K (Linux/Windows) / Option+K (Mac) → insère une référence @fichier.py#5-10
Glisser-déposer : maintenez Shift en faisant glisser un fichier vers la zone de prompt pour l’attacher
Sortie terminal : référencez @terminal:nom_du_terminal pour que Claude lise la sortie sans copier-coller

Étape 6 : Choisir le mode de permission adapté

Le mode de permission contrôle le niveau d’autonomie accordé à Claude. C’est le levier le plus important pour garder le contrôle.

Le sélecteur de mode se trouve en bas de la zone de prompt.

Mode	Comportement	Recommandé quand
Normal (défaut)	Claude demande confirmation avant chaque action	Toujours en apprentissage, modifications sensibles
Plan	Claude décrit un plan d’action complet et attend votre validation avant de commencer	Tâches multi-fichiers, revue préalable requise
Auto-accept	Claude applique les modifications sans demander	Tâches répétitives bien balisées, environnement de test

En mode Plan, VS Code ouvre le plan sous forme de document Markdown éditable. Vous pouvez ajouter des commentaires inline directement dans le plan avant d’autoriser Claude à commencer.

Étape 7 : Lancer une première session sur le fil rouge

Le projet fil rouge lab-claude est une API FastAPI gérée avec uv et ruff.

Ouvrez le projet dans VS Code
Fenêtre de terminal
```
cd ~/Projets/lab-claude
code .
```
Ouvrez le panneau Claude Code et démarrez une nouvelle session

Commencez par une exploration sans édition — passez en mode Plan

Analyse la structure du projet. Identifie les points d'entrée, les routes existantes,
les commandes de validation disponibles et les zones à risque.
Ne modifie rien.

Après lecture du plan, demandez une tâche bornée

Propose un plan en 4 étapes pour ajouter un endpoint GET /health qui retourne
{"status": "ok", "version": "1.0.0"}. Critères : ne casse aucun test existant,
passe ruff check, ajoute un test unitaire. Ne modifie rien tant que je
n'ai pas validé le plan.

Relisez le plan, ajoutez des commentaires inline si besoin, puis validez

Étape 8 : Relire le diff et valider les modifications

Quand Claude applique une modification, VS Code affiche un diff côte à côte avant de demander confirmation.

Relisez le diff : fichier original à gauche, version proposée à droite
Vous pouvez éditer directement la version proposée dans le diff avant d’accepter — Claude est informé de vos modifications
Acceptez, rejetez, ou demandez un ajustement en répondant dans le chat
Après acceptation, lancez les validations dans le terminal intégré
Fenêtre de terminal
```
uv run ruff check .
uv run pytest -q
```

Étape 9 : Utiliser les checkpoints pour revenir en arrière

Chaque action de Claude crée un checkpoint. En cas d’erreur ou de direction incorrecte, vous pouvez revenir à un état précédent.

Survolez n’importe quel message dans le panneau pour faire apparaître l’icône rewind puis choisissez parmi trois options :

Option	Effet
Fork conversation from here	Nouvelle branche de conversation à partir de ce message, code intact
Rewind code to here	Revient à l’état du code à ce point, conversation conservée
Fork conversation and rewind code	Nouvelle branche + retour arrière du code simultanément

Raccourcis clavier essentiels

Action	Linux/Windows	Mac
Basculer le focus éditeur ↔ Claude	`Ctrl+Esc`	`Cmd+Esc`
Ouvrir Claude dans un nouvel onglet	`Ctrl+Shift+Esc`	`Cmd+Shift+Esc`
Insérer une @-mention avec référence	`Alt+K` (éditeur focalisé)	`Option+K`
Nouvelle ligne sans envoyer	`Shift+Enter`	`Shift+Enter`

Erreurs fréquentes

Symptôme	Cause probable	Correction
Icône ✦ absente dans la barre d’outils	Aucun fichier ouvert, ou VS Code < 1.98	Ouvrez un fichier ou vérifiez la version ; utilisez la Status Bar comme alternative
Extension ne répond plus	Session expirée ou fenêtre non rechargée	`Ctrl+Shift+P` → `Developer: Reload Window` puis `/login` si nécessaire
`claude --version` introuvable	CLI non installé automatiquement	Installation manuelle via `curl` puis nouveau terminal
Claude propose des changements trop larges	Demande trop vague	Précisez le périmètre, les fichiers concernés et les critères d’acceptation
Modifications cassent les tests	Validation absente	Imposez `ruff check` + `pytest` après chaque lot, utilisez le mode Plan

Critères de validation

L’extension VS Code est connectée et opérationnelle
Le CLI répond dans le terminal intégré (claude --version)
Une nouvelle session démarre et le panneau est accessible via l’icône ✦
Une @-mention de fichier fonctionne dans le prompt
Une modification est proposée avec diff, acceptée, puis validée avec Ruff et tests

À retenir

Le panneau Claude Code s’ouvre via l’icône ✦ (barre d’outils, Activity Bar ou Status Bar)
Les @-mentions et la sélection de texte remplacent avantageusement le copier-coller pour donner du contexte
Le mode Plan est le meilleur choix par défaut : Claude documente son intention avant d’agir
Les checkpoints et le diff côte à côte permettent de revenir en arrière à tout moment
Le CLI dans le terminal intégré et l’extension partagent le même historique de sessions

Prochaines étapes

Guide 2 (à venir) : prompting technique Claude Code Passer de demandes vagues à des demandes testables et pilotables

Guide 3 (à venir) : contrôler les modifications Plan review, diffs, checkpoints et validations avancées

GitHub Copilot dans VS Code Comparer les usages Copilot et Claude Code