Claude Code : guide complet 2026 pour coder avec l’agent CLI d’Anthropic

Claude Code est l’agent de programmation officiel d’Anthropic en ligne de commande. Au lieu de simplement suggérer du code dans un chat, il travaille directement dans ton projet : il lit les fichiers, propose un plan, applique des modifications, lance des commandes, inspecte les erreurs, puis te montre les diffs à valider.

Ce guide reprend les bases, mais surtout les usages qui comptent vraiment en production : installation propre, commandes utiles, workflows de debug/refactor, fichiers CLAUDE.md, hooks, subagents, MCP, GitHub Actions, sécurité et coûts. L’objectif n’est pas de survendre l’outil : Claude Code est efficace, mais il doit être cadré.

Qu’est-ce que Claude Code exactement ?

Claude Code est un outil CLI qui donne à Claude un accès contrôlé à ton environnement de développement. Tu lances claude dans un répertoire projet, tu expliques ce que tu veux, puis l’agent utilise des outils pour explorer le code, modifier les fichiers et exécuter des commandes.

La différence avec Claude.ai ou ChatGPT est importante : dans un chat web, tu copies-colles des extraits. Dans Claude Code, l’agent observe directement le repo, garde le contexte de la tâche, et peut vérifier ce qu’il fait en lançant les tests ou le build.

Ce que Claude Code peut faire

• Lire et résumer un codebase inconnu.
• Modifier plusieurs fichiers cohérents dans une même tâche.
• Lancer des commandes shell, tests, linters, builds.
• Écrire ou améliorer des tests.
• Préparer une review de diff avant commit.
• Utiliser des intégrations externes via MCP.
• Travailler en mode interactif ou non-interactif avec --print.

Ce que Claude Code ne garantit pas

• Il ne garantit pas que le code généré soit juste sans tests.
• Il peut mal comprendre une architecture si le projet manque de documentation.
• Il peut proposer une API inexistante sur une librairie récente.
• Il peut coûter cher si tu lui fais relire un très gros contexte en boucle.
• Il ne doit jamais recevoir de secrets en clair dans un prompt ou dans un fichier versionné.

Claude Code vs Cursor, Copilot et Claude.ai

Outil	Point fort	Limite	Bon usage
Claude Code	Agent CLI multi-étapes	Demande une bonne discipline Git/tests	Refactor, debug, migration, tâches longues
Cursor	IDE visuel avec IA intégrée	Moins naturel pour automatiser un workflow terminal	Édition interactive, front, exploration rapide
GitHub Copilot	Complétion rapide dans l’IDE	Peu autonome sur une tâche complète	Écrire des fonctions et boilerplate
Claude.ai	Raisonnement et explication	Pas d’accès natif à ton repo local	Architecture, explication, brainstorming

Ma recommandation : Claude Code + ton IDE habituel. Tu continues à lire, éditer et reviewer dans ton environnement préféré. Claude Code devient le moteur d’exécution pour les tâches qui dépassent la simple autocomplétion.

Installation de Claude Code

La méthode officielle passe par npm. Le prérequis principal est donc Node.js. Si tu veux le détail par OS, garde aussi le guide dédié : installer Claude Code sur Mac, Windows et Linux.

Prérequis

• Node.js récent, idéalement une version LTS maintenue.
• Un terminal correct : iTerm, Terminal macOS, Windows Terminal avec WSL, ou terminal Linux.
• Un compte Anthropic ou une configuration API selon ton mode d’usage.
• Git installé et un projet versionné avant les premières grosses tâches.

Installation rapide

npm install -g @anthropic-ai/claude-code
claude --version

Si claude n’est pas reconnu après l’installation, vérifie où npm place les binaires globaux :

npm config get prefix
npm bin -g

Ensuite, ajoute le dossier correspondant à ton PATH si nécessaire. Ne copie pas aveuglément une commande trouvée en ligne : selon Node, npm, pnpm, nvm ou fnm, le chemin peut varier.

Premier lancement

cd ~/projets/mon-app
claude

Lors du premier lancement, Claude Code te guide pour l’authentification. Si tu utilises une clé API, charge-la via une variable d’environnement ou un gestionnaire de variables sensibles. Évite les exemples avec une vraie clé dans un fichier versionné.

# Exemple volontairement générique : ne mets pas de clé réelle dans ton repo
export ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY"
claude

Les commandes et modes à connaître

Claude Code s’utilise surtout en conversation naturelle. Les commandes spéciales servent à piloter la session.

Commande / mode	Utilité	Quand l’utiliser
/help	Voir les commandes disponibles	Première prise en main
/clear	Repartir avec un contexte propre	Quand tu changes complètement de tâche
/compact	Réduire une conversation longue	Après plusieurs étapes d’un même chantier
/model	Choisir ou vérifier le modèle actif	Quand la tâche demande plus ou moins de raisonnement
/cost	Suivre le coût de la session	Usage API ou longues sessions
--print	Mode non-interactif	Scripts, CI, résumés automatisés
Plan mode	Faire valider un plan avant modification	Refactor, migration, grosse feature

La bonne habitude : utiliser le mode plan pour toute tâche qui touche plusieurs fichiers ou qui peut casser le build. Demande à Claude d’expliquer ce qu’il va modifier, puis valide ou corrige le plan avant exécution.

5 workflows concrets

1. Comprendre un repo inconnu

claude "Explore ce projet. Résume l'architecture, les points d'entrée, les commandes de test et les risques évidents. Ne modifie rien."

C’est souvent le meilleur premier prompt. Tu poses un cadre read-only. Claude lit les fichiers essentiels et te donne une carte mentale du projet.

2. Débugger avec reproduction

claude "Voici l'erreur et le contexte. Trouve la cause racine, écris d'abord un test qui reproduit le bug, puis propose le fix minimal."

Le point important est “test d’abord”. Sans reproduction, tu risques d’obtenir un patch plausible mais fragile.

3. Refactoriser sans casser

claude "Refactorise ce module pour séparer validation, accès DB et formatage. Commence par lister le plan. Après chaque étape, lance les tests pertinents."

Sur un codebase réel, demande des étapes courtes. Un refactor en dix petits diffs vérifiés vaut mieux qu’un énorme patch impossible à reviewer.

4. Review avant commit

claude "Review les changements staged. Cherche bugs, problèmes de sécurité, manque de tests et breaking changes. Ne modifie rien sans me demander."

Claude Code est très utile comme deuxième regard. Il ne remplace pas une review humaine, mais il repère souvent des oublis simples.

5. Générer une documentation technique

claude "À partir du code existant, mets à jour le README avec les commandes d'installation, de test, de build et les variables d'environnement attendues. Signale les zones incertaines au lieu d'inventer."

Pour la documentation, demande explicitement de marquer les inconnues. C’est le meilleur antidote aux hallucinations.

CLAUDE.md : la mémoire utile du projet

Le fichier CLAUDE.md documente les conventions que Claude doit connaître à chaque session : stack, commandes, architecture, style de code, règles de test, pièges connus.

# Projet

## Stack
- Next.js App Router
- TypeScript strict
- Vitest

## Commandes
- npm run test
- npm run lint
- npm run build

## Règles
- Pas de changement visible sans test associé
- Ne jamais écrire de secret dans le repo
- Proposer un plan avant toute migration

Versionne ce fichier avec ton projet. Évite d’en faire un roman : Claude doit pouvoir l’absorber vite. Les procédures très longues peuvent aller dans une documentation séparée.

Hooks, subagents et MCP

Hooks

Les hooks permettent de lancer des commandes autour des actions de Claude Code : formatage, lint, notifications, sauvegarde, audit. D’après la documentation officielle, ils se configurent via les fichiers settings de Claude Code.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint -- --fix"
          }
        ]
      }
    ]
  }
}

Commence simple. Un hook qui casse sur chaque édition devient vite pénible. Le bon premier hook est souvent un formatage ou une notification de fin de tâche.

Subagents

Les subagents servent à spécialiser Claude : reviewer sécurité, expert tests, agent documentation, agent migration. Ils ont leur propre contexte et évitent de polluer la conversation principale.

---
name: code-reviewer
description: Review stricte avant commit
tools: Bash, Read, Grep, Glob
---

Tu analyses les changements staged. Priorise bugs, sécurité, régressions et tests manquants.

Un bon subagent est court, ciblé et vérifiable. Ne crée pas dix agents flous : commence avec un reviewer et un agent test.

MCP

Le Model Context Protocol connecte Claude Code à des outils externes : documentation, GitHub, bases de données, navigateurs, systèmes internes. C’est efficace, mais il faut le traiter comme une surface d’accès réelle.

{
  "mcpServers": {
    "docs": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-example"]
    }
  }
}

Pour aller plus loin côté MCP, lis aussi : les meilleurs serveurs MCP pour Claude Code.

GitHub Actions et CI : utile, mais à cadrer

Claude Code peut être utilisé en automatisation, notamment pour analyser une PR ou générer un résumé. Le piège est de lui donner trop de droits ou trop de contexte à chaque push.

name: claude-review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Claude review
        env:
          ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY
          PR_NUMBER: $PR_NUMBER
        run: |
          claude --print "Review cette PR. Signale uniquement les points bloquants ou importants." > review.md
          gh pr comment "$PR_NUMBER" --body-file review.md

Cet exemple est volontairement générique. En vrai, utilise le stockage sécurisé des variables CI, limite les permissions du token, et évite de lancer une analyse coûteuse sur les changements de docs ou de lockfiles.

Coûts : comment éviter les mauvaises surprises

Le coût dépend du mode d’accès, du modèle, du volume de contexte et de la fréquence des appels. Les prix et limites changent : la source fiable reste la page officielle de coûts et ta console Anthropic.

• Utilise /cost pendant les longues sessions.
• Utilise /compact quand une conversation devient trop lourde.
• Utilise /clear au changement de sujet.
• Évite de demander à Claude de relire tout le monorepo sans raison.
• Pose un budget ou des limites de spend côté console si tu utilises l’API.

Évite les promesses du type “ça coûtera toujours X €/mois”. En équipe, le vrai coût vient souvent des gros contextes, des boucles de tests longues, et des tâches lancées trop largement.

Sécurité : les règles non négociables

• Commit ou backup avant grosse session. Tu dois pouvoir revenir en arrière.
• Pas de secrets dans les prompts. Ni clé API, ni token GitHub, ni mot de passe DB.
• Plan mode sur les tâches risquées. Tu valides avant modification.
• Tests après modification. Le diff seul ne suffit pas.
• Permissions MCP minimales. Ne branche pas un outil prod en écriture sans garde-fou.
• Review humaine avant prod. Surtout sur sécurité, billing, données utilisateurs et migrations.

Les erreurs fréquentes

Tout déléguer d’un coup

“Refais toute l’app” est un mauvais prompt. Claude sera meilleur si tu découpes : comprendre, planifier, tester, modifier, vérifier.

Ne pas lui donner les commandes projet

Si Claude ne sait pas comment lancer les tests, il devine. Mets les commandes dans CLAUDE.md.

Accepter un patch sans le lire

Claude peut produire un diff très convaincant mais faux. Lis les changements critiques, surtout sur auth, paiement, données et migrations.

Oublier les sources officielles

Sur une librairie ou un outil récent, demande : “vérifie la documentation officielle avant de coder”. Cela évite beaucoup d’APIs inventées.

Checklist avant une grosse session Claude Code

• Repo propre ou changement sauvegardé.
• Branche dédiée créée.
• Commandes test/lint/build connues.
• CLAUDE.md à jour.
• Secrets hors repo.
• Objectif découpé en étapes.
• Critère de réussite explicite : tests verts, build OK, diff limité, documentation mise à jour.

Essayer Claude Code

Claude Code est-il gratuit ?

Claude Code dépend du mode d'accès et des offres Anthropic disponibles au moment où tu l'utilises. Les tarifs, limites et modèles évoluent. Vérifie toujours la documentation officielle Anthropic et ta console de facturation avant un usage intensif.

Quelle est la différence entre Claude Code et Claude.ai ?

Claude.ai est l'interface web de conversation. Claude Code est un outil en ligne de commande qui travaille dans ton projet local, avec accès contrôlé aux fichiers, commandes et intégrations.

Claude Code fonctionne-t-il sur Windows ?

Oui, mais l'expérience développeur est généralement meilleure avec WSL pour les workflows bash, hooks, scripts et outils Unix. Sur Windows pur, teste d'abord sur un petit projet.

Claude Code peut-il remplacer Cursor ou VS Code ?

Non. Claude Code vit dans le terminal. Il complète ton IDE au lieu de le remplacer. Beaucoup de développeurs l'utilisent dans le terminal intégré de VS Code, Cursor, JetBrains ou iTerm.

Comment éviter que Claude Code casse mon projet ?

Travaille sur une branche, commit avant les gros changements, utilise le mode plan, demande des petits diffs, lance les tests, et review les fichiers sensibles avant merge.

Peut-on utiliser Claude Code en CI ?

Oui, notamment avec le mode non-interactif. Mais il faut limiter les permissions, protéger les secrets, filtrer les déclencheurs et surveiller les coûts.

Quels projets profitent le plus de Claude Code ?

Les projets avec tests, scripts clairs, conventions documentées et architecture lisible. Plus le projet est chaotique, plus il faut commencer par une phase read-only de compréhension.

Sources officielles et ressources

• Documentation officielle Claude Code , Overview
• Documentation officielle , Quickstart
• Documentation officielle , Settings
• Documentation officielle , Common workflows
• Documentation officielle , GitHub Actions
• Documentation officielle , MCP
• Documentation officielle , Costs
• Repository GitHub anthropics/claude-code

Pour aller plus loin sur Tutosss

• Installer Claude Code sur Mac, Windows et Linux
• Claude Code vs Cursor : comparatif objectif
• Top 15 serveurs MCP pour Claude Code
• Maîtriser les hooks Claude Code
• Subagents Claude Code : quand et comment les utiliser

Si tu veux recevoir les nouveaux guides AI-assisted development en français, inscris-toi au Brief AI Coding FR depuis la page d’accueil.