Claude Code : Le Guide Avancé

Pourquoi Claude Code Change la Donne

Claude Code n'est pas un simple copilote de code. C'est un agent de développement autonome qui opère directement dans votre terminal, comprend l'intégralité de votre codebase, exécute des commandes, édite des fichiers, et orchestre des workflows complexes — le tout sans jamais quitter la ligne de commande.

Là où GitHub Copilot suggère des lignes, où Cursor propose des éditions dans un IDE, Claude Code agit. Il lit votre projet, comprend l'architecture, planifie les modifications, les exécute, lance les tests, et itère jusqu'à ce que tout fonctionne. C'est la différence fondamentale entre un assistant et un agent.

Claude Code vs. la concurrence

Installation en 30 secondes

# Installation globale via npm
npm install -g @anthropic-ai/claude-code

# Vérifier l'installation
claude --version

# Lancer dans un projet
cd mon-projet/
claude

# Première utilisation : authentification
# Claude Code ouvrira un navigateur pour l'auth OAuth

Architecture & Configuration

Claude Code stocke toute sa configuration dans un répertoire .claude/ à la racine de votre projet. Comprendre cette structure est essentiel pour tirer parti de toutes les fonctionnalités avancées.

Structure du répertoire .claude/

mon-projet/
├── .claude/
│   ├── settings.json          # Config locale du projet
│   ├── rules/                 # Règles modulaires (*.md)
│   │   ├── testing.md         # Règles spécifiques aux tests
│   │   ├── security.md        # Règles de sécurité
│   │   └── api-design.md      # Conventions d'API
│   └── worktrees/             # Worktrees Git isolés
├── .mcp.json                  # Serveurs MCP du projet
├── CLAUDE.md                  # Instructions globales du projet
└── src/
    └── CLAUDE.md              # Instructions spécifiques à src/

Les 4 scopes de configuration

Claude Code résout la configuration par ordre de priorité décroissante. Chaque scope peut définir des permissions, des paramètres MCP, et des préférences :

Exemple complet de settings.json

{
  "permissions": {
    "allow": [
      "Read",
      "Write",
      "Edit",
      "Glob",
      "Grep",
      "Bash(npm run *)",
      "Bash(node *)",
      "Bash(git status)",
      "Bash(git diff*)",
      "Bash(git log*)",
      "Bash(git add *)",
      "Bash(git commit *)",
      "mcp__github__*",
      "mcp__postgres__query"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force*)",
      "Bash(git reset --hard*)",
      "Bash(curl*|*sh)",
      "mcp__postgres__execute"
    ]
  },
  "env": {
    "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "16000",
    "ENABLE_TOOL_SEARCH": "true"
  }
}

Le système de permissions en détail

Chaque outil de Claude Code est soumis à un système de permissions granulaire. Vous pouvez autoriser ou bloquer des outils spécifiques, et même utiliser des glob patterns pour un contrôle fin :

# Syntaxe des permissions
"Bash(pattern)"              # Commande bash spécifique
"Bash(npm run *)"            # Toute commande npm run
"Bash(git *)"                # Toutes les commandes git
"mcp__serveur__outil"        # Outil MCP spécifique
"mcp__serveur__*"            # Tous les outils d'un serveur MCP
"Read(*.env)"                # Lecture de fichiers .env (à deny !)
"Write(src/**)"              # Écriture dans src/ uniquement

CLAUDE.md : Le Cerveau du Projet

Le fichier CLAUDE.md est la pièce maîtresse de Claude Code. C'est un fichier Markdown lu automatiquement au démarrage de chaque session. Il contient les instructions, conventions, et contexte que Claude utilisera pour toutes ses interactions avec votre projet.

Emplacements et priorité de chargement

Claude Code recherche les fichiers CLAUDE.md à plusieurs endroits, chargés dans cet ordre :

Imports avec la syntaxe @

Pour éviter un CLAUDE.md monolithique, utilisez les imports :

# Mon Projet

## Architecture
@docs/architecture.md

## Conventions API
@docs/api-conventions.md

## Déploiement
@docs/deployment.md

Chaque fichier référencé par @ est injecté dans le contexte comme s'il faisait partie du CLAUDE.md principal. C'est idéal pour les gros projets avec beaucoup de documentation.

Règles modulaires avec .claude/rules/

Les fichiers dans .claude/rules/ offrent un contrôle plus fin grâce au frontmatter YAML :

---
description: "Conventions de test pour le projet"
globs: ["**/*.test.ts", "**/*.spec.ts", "tests/**"]
---

# Règles de Test

- Utiliser Vitest (pas Jest)
- Chaque fichier test doit avoir un `describe` par fonction exportée
- Préférer `it.each` pour les cas paramétriques
- Mocker les appels réseau avec `msw`
- Coverage minimum : 80% sur les branches

---
description: "Règles de sécurité obligatoires"
globs: ["src/api/**", "src/auth/**", "src/middleware/**"]
---

# Sécurité

- JAMAIS de secrets en dur dans le code
- Valider TOUS les inputs avec Zod
- Utiliser des requêtes paramétrées (jamais de concaténation SQL)
- Rate limiting sur tous les endpoints publics
- CORS strict : whitelist explicite des origines

Le champ globs est la clé : la règle n'est chargée que lorsque Claude travaille sur des fichiers qui matchent le pattern. Cela réduit le contexte inutile et améliore la pertinence.

Le système Auto Memory

Claude Code maintient automatiquement une mémoire persistante entre les sessions, stockée dans ~/.claude/projects/{project-hash}/memory/MEMORY.md. Cette mémoire capture :

• Les décisions techniques importantes
• Les patterns validés et les anti-patterns identifiés
• Les préférences de l'utilisateur
• L'historique des sessions récentes

Vous pouvez écrire directement dans la mémoire en disant "souviens-toi que..." ou en utilisant /memory.

Exemple d'un CLAUDE.md bien structuré

# Mon API SaaS

## Stack
- Runtime: Node.js 22, TypeScript 5.7
- Framework: Fastify 5 + @fastify/type-provider-typebox
- DB: PostgreSQL 16 via Drizzle ORM
- Queue: BullMQ + Redis 7
- Tests: Vitest + MSW + Testcontainers
- Deploy: Docker → Fly.io

## Commandes
- `npm run dev` — serveur local (port 3000)
- `npm run test` — tests unitaires
- `npm run test:e2e` — tests E2E (nécessite Docker)
- `npm run db:migrate` — migrations Drizzle
- `npm run db:generate` — générer les migrations
- `npm run lint` — ESLint + Prettier check

## Architecture
@docs/architecture.md

## Conventions
- Pas de classes, que des fonctions et modules
- Chaque route dans son propre fichier: src/routes/{resource}/{method}.ts
- Schémas Typebox co-localisés avec les routes
- Erreurs via throw new AppError(code, message, statusCode)
- Logs structurés JSON via pino

## Patterns obligatoires
- Tout endpoint DOIT avoir un schéma de validation input/output
- Tout accès DB DOIT passer par le repository pattern (src/repos/)
- Les jobs BullMQ DOIVENT être idempotents
- Les tests E2E utilisent des containers PostgreSQL jetables

## Ce qu'il ne faut PAS faire
- NE PAS utiliser `any` — toujours typer explicitement
- NE PAS commiter de .env ou secrets
- NE PAS utiliser de raw SQL (passer par Drizzle)
- NE PAS modifier les migrations existantes (en créer de nouvelles)

MCP : Model Context Protocol

Le Model Context Protocol (MCP) est le système d'extension de Claude Code. Il permet de connecter n'importe quel service externe — base de données, API, outil interne — comme un outil natif que Claude peut appeler directement. C'est ce qui transforme Claude Code d'un simple agent de code en une plateforme d'automatisation universelle.

Les 4 types de transport

Installation d'un serveur MCP

Trois méthodes pour ajouter un serveur MCP :

# Ajouter un serveur depuis le registre
claude mcp add github --scope project

# Ajouter un serveur npm personnalisé
claude mcp add postgres -- npx @mcp/postgres --connection-string "$DATABASE_URL"

# Ajouter un serveur distant (HTTP)
claude mcp add notion --url https://mcp.notion.so/v1 --scope user

# Lister les serveurs configurés
claude mcp list

# Tester un serveur
claude mcp test postgres

{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@mcp/postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    },
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/data"]
    },
    "custom-api": {
      "type": "http",
      "url": "https://mcp.mon-service.com/v1",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

# Les serveurs ajoutés avec --scope user sont dans ~/.claude/settings.json
# Ils sont disponibles dans TOUS vos projets

claude mcp add slack --scope user -- npx @mcp/slack --token "$SLACK_TOKEN"
claude mcp add linear --scope user --url https://mcp.linear.app/sse

Les 3 scopes MCP

Optimiser avec ENABLE_TOOL_SEARCH

Quand vous avez beaucoup de serveurs MCP (10+), chaque outil consomme des tokens de contexte. La variable ENABLE_TOOL_SEARCH active un mode intelligent où Claude ne charge que les outils pertinents pour la tâche en cours :

{
  "env": {
    "ENABLE_TOOL_SEARCH": "true"
  }
}

Avec cette option, au lieu de charger les 50+ descriptions d'outils dans le contexte, Claude effectue une recherche sémantique et ne charge que les 5-10 outils les plus pertinents. Économie typique : 30-50% des tokens de contexte MCP.

Top 10 des serveurs MCP les plus utiles

Exemple concret : setup GitHub + PostgreSQL + Custom API

{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    },
    "db-production": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@mcp/postgres", "--readonly"],
      "env": { "DATABASE_URL": "${PROD_DB_READ_URL}" }
    },
    "db-staging": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@mcp/postgres"],
      "env": { "DATABASE_URL": "${STAGING_DB_URL}" }
    },
    "internal-api": {
      "type": "http",
      "url": "https://mcp-gateway.internal.company.com",
      "headers": {
        "Authorization": "Bearer ${INTERNAL_API_TOKEN}"
      }
    }
  }
}

Hooks : Automatisation & Garde-fous

Les hooks sont des scripts qui s'exécutent automatiquement à des moments clés du cycle de vie de Claude Code. Ils permettent d'ajouter des garde-fous, d'automatiser des tâches récurrentes, et d'intégrer Claude Code dans vos workflows existants.

Les événements de hook

Les 4 types de hooks

Codes de sortie et contrôle

Pour les hooks PreToolUse, le code de sortie détermine si l'opération continue :

Format JSON avancé

Un hook peut retourner du JSON sur stdout pour un contrôle plus fin :

{
  "decision": "block",
  "reason": "Ce fichier est protégé par la politique de sécurité",
  "suppressOutput": false
}

Exemples concrets

1. Auto-format après chaque édition de fichier

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

2. Bloquer la modification de fichiers protégés

#!/bin/bash
# Hook PreToolUse : bloque l'écriture dans les fichiers critiques
INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

PROTECTED_PATTERNS=(
  "*/migrations/*.sql"
  ".env*"
  "docker-compose.prod.yml"
  "*/secrets/*"
)

for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE" == $pattern ]]; then
    echo "BLOQUÉ : $FILE est un fichier protégé"
    exit 2
  fi
done

exit 0

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash scripts/guard-protected.sh"
          }
        ]
      }
    ]
  }
}

3. Notification Slack à la fin de chaque tâche

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "https://hooks.slack.com/services/T00/B00/xxxxx",
            "method": "POST",
            "headers": { "Content-Type": "application/json" },
            "body": {
              "text": "Claude Code a terminé une tâche dans ${PROJECT_NAME}"
            }
          }
        ]
      }
    ]
  }
}

4. Lancer les tests après chaque modification de code

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c '[[ \"$CLAUDE_FILE_PATH\" == *.ts ]] && npx vitest run --reporter=dot 2>&1 | tail -5 || true'"
          }
        ]
      }
    ]
  }
}

5. Injecter du contexte dynamique avant chaque opération

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "RAPPEL : Tu es en environnement de STAGING. Ne jamais exécuter de commandes destructrices. Vérifier 2x avant tout DROP, DELETE, ou rm."
          }
        ]
      }
    ]
  }
}

Skills & Commandes Personnalisées

Les skills (compétences) sont des commandes personnalisées que vous pouvez invoquer avec /nom-de-la-skill. Elles encapsulent un workflow complet — instructions, outils autorisés, modèle à utiliser, et contexte — dans un fichier Markdown réutilisable.

Anatomie d'une skill

Chaque skill est un fichier SKILL.md dans un répertoire dédié :

.claude/
└── skills/
    ├── deploy/
    │   └── SKILL.md
    ├── review-pr/
    │   └── SKILL.md
    └── migrate-component/
        └── SKILL.md

Frontmatter et options

Contexte dynamique avec backticks

Les skills supportent l'injection de contexte dynamique via des commandes entre backticks :

---
name: review-pr
description: Review une PR GitHub en profondeur
model: opus
---

# Review PR

Contexte du projet :
`cat package.json | jq '{name, version, dependencies}'`

Derniers commits :
`git log --oneline -10`

Branche actuelle :
`git branch --show-current`

## Instructions
Analyse le diff de la PR $ARGUMENTS et fournis :
1. Un résumé des changements
2. Les problèmes potentiels (bugs, sécurité, perf)
3. Les suggestions d'amélioration
4. Un verdict : APPROVE, REQUEST_CHANGES, ou COMMENT

Substitution d'arguments

Les arguments passés après le nom de la skill sont accessibles via des variables :

• $ARGUMENTS — tous les arguments en une chaîne
• $0 — premier argument
• $1 — deuxième argument
• $2 — troisième argument, etc.

# Dans Claude Code :
/review-pr 42
# → $ARGUMENTS = "42", $0 = "42"

/deploy staging v2.1.0
# → $ARGUMENTS = "staging v2.1.0", $0 = "staging", $1 = "v2.1.0"

Exemple 1 : Skill de déploiement

---
name: deploy
description: Déployer l'application sur un environnement
tools: ["Bash", "Read", "Grep"]
---

# Déploiement sur $0

## Pré-vérifications
1. Vérifier que la branche est `main` : `git branch --show-current`
2. Vérifier qu'il n'y a pas de changements non commités : `git status --porcelain`
3. Vérifier que les tests passent : `npm run test`

## Déploiement
- Si `$0` = "staging" → `fly deploy --config fly.staging.toml`
- Si `$0` = "production" → demander CONFIRMATION explicite puis `fly deploy --config fly.production.toml`

## Post-déploiement
1. Vérifier le health check : `curl -s https://$0.mon-app.com/health`
2. Afficher les logs récents : `fly logs -a mon-app-$0 -n 20`
3. Résumer le statut du déploiement

Exemple 2 : Skill de migration de composant

---
name: migrate-component
description: Migrer un composant React class vers un composant fonctionnel
model: sonnet
agent: true
---

# Migration Class → Functional Component

Fichier cible : $ARGUMENTS

## Étapes
1. Lire le composant class actuel
2. Identifier : state, lifecycle methods, refs, context
3. Convertir en composant fonctionnel avec hooks :
   - `this.state` → `useState`
   - `componentDidMount` → `useEffect(..., [])`
   - `componentDidUpdate` → `useEffect`
   - `componentWillUnmount` → return dans `useEffect`
   - `this.refs` → `useRef`
   - `static contextType` → `useContext`
4. Préserver TOUS les types TypeScript
5. Lancer les tests existants pour vérifier la non-régression
6. Formater avec Prettier

Exemple 3 : Skill de génération de documentation API

---
name: doc-api
description: Générer la documentation OpenAPI d'une route
model: haiku
context: ["src/routes/**", "src/schemas/**"]
---

# Documentation API

Route cible : $ARGUMENTS

## Instructions
1. Lire le fichier de route et ses schémas associés
2. Générer un bloc OpenAPI 3.1 YAML avec :
   - Summary et description
   - Parameters (path, query, header)
   - Request body avec schéma JSON
   - Responses (200, 400, 401, 404, 500)
   - Exemples concrets pour chaque réponse
3. Écrire le résultat dans `docs/api/{route-name}.yaml`

Scripting & Mode Headless

Le mode headless (claude -p) est ce qui fait de Claude Code un outil d'automatisation, pas seulement un outil interactif. Il permet d'intégrer Claude dans des scripts, des pipelines CI/CD, des cron jobs, et des bots.

Usage de base

# Exécution one-shot (le plus simple)
claude -p "Explique ce que fait ce projet"

# Avec un prompt depuis un fichier
claude -p "$(cat prompts/review.md)"

# Pipe depuis stdin
echo "Ajoute des tests pour src/auth.ts" | claude -p

# Avec un format de sortie spécifique
claude -p "Liste les TODO dans le code" --output-format json

# Mode streaming (pour les longues tâches)
claude -p "Refactor le module auth" --output-format stream-json

Flags essentiels

Sortie JSON structurée

Pour intégrer Claude dans un pipeline, utilisez --json-schema pour forcer une structure de sortie précise :

#!/bin/bash
SCHEMA='{
  "type": "object",
  "properties": {
    "score": { "type": "number", "minimum": 0, "maximum": 100 },
    "issues": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "severity": { "type": "string", "enum": ["critical","high","medium","low"] },
          "file": { "type": "string" },
          "line": { "type": "number" },
          "message": { "type": "string" }
        },
        "required": ["severity", "file", "message"]
      }
    },
    "summary": { "type": "string" }
  },
  "required": ["score", "issues", "summary"]
}'

RESULT=$(claude -p "Analyse la qualité du code dans src/" \
  --output-format json \
  --json-schema "$SCHEMA" \
  --allowedTools Read,Grep,Glob \
  --model sonnet)

SCORE=$(echo "$RESULT" | jq -r '.result.score')
ISSUES=$(echo "$RESULT" | jq -r '.result.issues | length')

echo "Score: $SCORE/100 — $ISSUES issues trouvées"

# Échouer le CI si le score est trop bas
if [ "$SCORE" -lt 70 ]; then
  echo "::error::Code quality score below threshold: $SCORE/100"
  exit 1
fi

Streaming JSON pour les tâches longues

# Chaque ligne est un objet JSON (NDJSON)
claude -p "Migre tous les composants class" --output-format stream-json | while read -r line; do
  TYPE=$(echo "$line" | jq -r '.type')
  case "$TYPE" in
    "assistant")
      echo "[Claude] $(echo "$line" | jq -r '.message.content[0].text')"
      ;;
    "tool_use")
      echo "[Tool] $(echo "$line" | jq -r '.name'): $(echo "$line" | jq -r '.input | tostring')"
      ;;
    "result")
      echo "[Done] $(echo "$line" | jq -r '.result')"
      ;;
  esac
done

Gestion des sessions

# Étape 1 : analyse (sauvegarder le session ID)
SESSION_ID=$(claude -p "Analyse l'architecture du projet et identifie les problèmes" \
  --output-format json | jq -r '.session_id')

echo "Session: $SESSION_ID"

# Étape 2 : correction (reprendre la même session)
claude --resume "$SESSION_ID" -p "Corrige les 3 problèmes les plus critiques que tu as identifiés"

# Étape 3 : vérification
claude --resume "$SESSION_ID" -p "Lance les tests et confirme que tout passe"

Intégration CI/CD : GitHub Actions

name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: '22'

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Review PR
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          DIFF=$(git diff origin/main...HEAD)
          REVIEW=$(claude -p "Review ce diff et identifie les problèmes potentiels :

          $DIFF

          Format ta review comme un commentaire de PR GitHub." \
            --model sonnet \
            --max-turns 3 \
            --allowedTools Read,Grep,Glob \
            --permission-mode accept-all)

          # Poster le commentaire sur la PR
          gh pr comment ${{ github.event.pull_request.number }} --body "$REVIEW"
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Pipeline batch : traitement de fichiers

#!/bin/bash
# Traiter tous les fichiers Markdown en parallèle
find docs/ -name "*.md" | while read -r file; do
  echo "Traitement: $file"
  claude -p "Corrige la grammaire et améliore la clarté de ce fichier : $file. 
             Ne change pas le sens, seulement la forme." \
    --model haiku \
    --max-turns 2 \
    --allowedTools Read,Edit \
    --permission-mode accept-all &
done

wait
echo "Tous les fichiers traités"

Subagents & Exécution Parallèle

Les subagents sont des instances Claude indépendantes lancées par l'agent principal pour exécuter des tâches en parallèle. Chaque subagent a son propre contexte, ses propres outils, et s'exécute de manière isolée — comme un développeur junior à qui vous déléguez une sous-tâche.

Types de subagents natifs

Configuration d'un subagent personnalisé

{
  "model": "sonnet",           // Modèle (opus|sonnet|haiku)
  "tools": ["Read", "Grep", "Glob", "Bash"],  // Outils autorisés
  "permissionMode": "accept-all",  // Pas d'interaction humaine
  "maxTurns": 10,              // Limite d'itérations
  "context": "...",            // Instructions spécifiques
  "worktree": true             // Isolation Git (optionnel)
}

Pattern : recherche parallèle

L'un des usages les plus puissants est la recherche simultanée dans différentes parties du codebase :

# Ce prompt dans Claude Code va automatiquement créer 3 subagents :

"J'ai besoin de comprendre comment fonctionne l'authentification dans ce projet.
Lance 3 recherches en parallèle :
1. Agent 1 : Cherche tous les fichiers liés à l'auth (middleware, routes, schemas)
2. Agent 2 : Cherche les tests d'authentification et les cas couverts
3. Agent 3 : Cherche la configuration (env vars, secrets, providers OAuth)

Synthétise les résultats des 3 agents dans un rapport structuré."

Claude va automatiquement dispatcher ces 3 tâches à des subagents Explore qui s'exécutent simultanément, puis agréger les résultats.

Pattern : modifications isolées avec worktrees

# Chaque subagent travaille dans son propre worktree Git
# Pas de conflit entre les modifications parallèles

"Refactore ces 3 modules en parallèle :
1. Agent 1 : Refactore src/auth/ (worktree isolé)
2. Agent 2 : Refactore src/billing/ (worktree isolé)  
3. Agent 3 : Refactore src/notifications/ (worktree isolé)

Chaque agent doit :
- Créer un worktree Git isolé
- Faire ses modifications
- Lancer les tests du module
- Commiter si les tests passent

Je ferai le merge manuellement après review."

Limites et bonnes pratiques

Gestion du Contexte & Mémoire

Le contexte est la ressource la plus précieuse de Claude Code. Chaque token de contexte consommé par les instructions, les fichiers lus, et les résultats d'outils réduit l'espace disponible pour le raisonnement. Gérer efficacement le contexte est la compétence #1 d'un utilisateur avancé.

Anatomie de la fenêtre de contexte

Commandes de gestion du contexte

Auto-compaction à 95%

Quand le contexte atteint 95% de sa capacité, Claude déclenche automatiquement une compaction. Le problème : cette compaction automatique peut perdre du contexte important car Claude choisit seul ce qu'il résume. La solution : compacter proactivement avec des instructions :

# Mauvais : compaction automatique (perte de contrôle)
# Le contexte atteint 95% → Claude résume tout

# Bon : compaction proactive avec focus
/compact Garde uniquement : l'architecture du module auth, 
         les 3 bugs trouvés, et le plan de migration.
         Oublie les explorations de fichiers et les tentatives échouées.

Session checkpointing avec /rewind

Claude crée automatiquement des checkpoints à chaque tour de conversation. Vous pouvez revenir en arrière si une direction ne fonctionne pas :

# Tour 1 : "Refactore le module auth en utilisant JWT"
# Tour 2 : Claude modifie 5 fichiers...
# Tour 3 : "En fait, utilise plutôt des sessions avec Redis"

# Au lieu de perdre le contexte et recommencer :
/rewind
# → Revient au Tour 1, avant les modifications JWT

# Maintenant :
"Refactore le module auth en utilisant des sessions Redis"
# → Claude repart dans la bonne direction

Reprendre une session précédente

# Lister les sessions récentes
claude sessions list

# Reprendre la dernière session
claude --continue

# Reprendre une session spécifique par ID
claude --resume abc123def456

# Reprendre en mode headless (scripting)
claude --continue -p "Continue le refactoring du module auth"

Le système de mémoire

La mémoire persistante est stockée dans ~/.claude/projects/{hash}/memory/MEMORY.md. Elle survit entre les sessions et est automatiquement chargée au démarrage :

# Dans Claude Code (interactif) :

"Souviens-toi que ce projet utilise Drizzle ORM, pas Prisma.
 Ne propose jamais de migration Prisma."

"Retiens que le déploiement sur staging nécessite un VPN.
 La commande est : vpn-connect staging && fly deploy"

"Note : le fichier config/secrets.ts ne doit JAMAIS être modifié 
 par Claude Code. Il contient les clés de chiffrement."

Optimisation Budget & Coûts

Claude Code consomme des tokens à chaque interaction. Sans optimisation, une journée de travail intensif peut coûter 50-200$ en tokens API. Avec les bonnes pratiques, vous pouvez réduire ce coût de 60-80% sans sacrifier la qualité.

Tarification par modèle

Où vont les tokens ?

10 stratégies concrètes pour réduire les coûts

Coût estimé par type de tâche

# Dans Claude Code (interactif) :
/cost       # Coût de la session actuelle
/stats      # Statistiques détaillées (tokens, outils, durée)

# En mode headless :
claude -p "tâche" --output-format json | jq '{
  input_tokens: .usage.input_tokens,
  output_tokens: .usage.output_tokens,
  cost_estimate: (.usage.input_tokens * 0.000003 + .usage.output_tokens * 0.000015)
}'

Permissions & Sécurité

La sécurité est le point le plus critique de l'utilisation d'un agent autonome. Claude Code peut exécuter des commandes shell, modifier des fichiers, et interagir avec des services externes. Un système de permissions robuste est non négociable.

Les 3 modes de permission

Syntaxe des règles allow/deny

{
  "permissions": {
    "allow": [
      // Outils de base (lecture seule)
      "Read",
      "Glob",
      "Grep",
      
      // Écriture restreinte à certains dossiers
      "Write(src/**)",
      "Write(tests/**)",
      "Edit(src/**)",
      "Edit(tests/**)",
      
      // Commandes shell spécifiques
      "Bash(npm run *)",
      "Bash(npx vitest*)",
      "Bash(git status)",
      "Bash(git diff*)",
      "Bash(git log*)",
      "Bash(git add src/* tests/*)",
      "Bash(git commit -m *)",
      
      // MCP : lecture seule sur la DB prod
      "mcp__db-prod__query",
      
      // MCP : accès complet sur staging
      "mcp__db-staging__*",
      
      // GitHub : tout sauf delete
      "mcp__github__create_pull_request",
      "mcp__github__list_issues",
      "mcp__github__add_comment"
    ],
    "deny": [
      // Commandes destructrices
      "Bash(rm -rf *)",
      "Bash(git push --force*)",
      "Bash(git reset --hard*)",
      "Bash(git checkout -- *)",
      "Bash(DROP *)",
      "Bash(DELETE FROM *)",
      "Bash(curl * | *sh)",
      "Bash(wget * && *sh)",
      
      // Fichiers sensibles
      "Write(.env*)",
      "Write(**/secrets/**)",
      "Write(**/credentials/**)",
      "Read(.env.production)",
      
      // MCP : écriture sur prod
      "mcp__db-prod__execute",
      "mcp__db-prod__insert",
      "mcp__db-prod__update",
      "mcp__db-prod__delete"
    ]
  }
}

Sandbox : isolation système

Claude Code inclut un mécanisme de sandbox qui restreint l'accès au système de fichiers et au réseau :

{
  "sandbox": {
    "filesystem": {
      "allowedPaths": [
        "/Users/dev/projects/mon-app",
        "/tmp/claude-*"
      ],
      "deniedPaths": [
        "/etc",
        "/var",
        "~/.ssh",
        "~/.aws"
      ]
    },
    "network": {
      "allowedHosts": [
        "github.com",
        "api.anthropic.com",
        "registry.npmjs.org",
        "*.mon-domaine.com"
      ],
      "deniedHosts": [
        "*.internal.corp.com"
      ]
    }
  }
}

Managed policies (Entreprise)

Pour les organisations, le scope managed permet d'imposer des politiques irrévocables :

// Politique poussée par l'admin — impossible à contourner par les devs
{
  "managedPolicy": {
    "permissions": {
      "deny": [
        "Bash(rm -rf /)",
        "Bash(curl * | bash)",
        "Write(.env.production)",
        "mcp__*__execute(DROP *)",
        "mcp__*__execute(TRUNCATE *)"
      ]
    },
    "requiredHooks": {
      "PreToolUse": [
        {
          "matcher": "Bash",
          "hooks": [{
            "type": "command",
            "command": "/opt/security/audit-command.sh"
          }]
        }
      ]
    },
    "maxCostPerSession": 50.00,
    "allowedModels": ["sonnet", "haiku"]
  }
}

Intégrations IDE

Bien que Claude Code soit un outil terminal-first, il s'intègre parfaitement avec les IDEs modernes. Vous pouvez l'utiliser en parallèle de votre éditeur, ou directement à l'intérieur.

VS Code — Extension officielle

L'extension Claude Code for VS Code transforme votre éditeur en environnement agent complet :

# Via la ligne de commande VS Code
code --install-extension anthropic.claude-code

# Ou depuis le marketplace VS Code :
# Chercher "Claude Code" dans les extensions

# Configuration dans settings.json (VS Code) :
{
  "claudeCode.terminalProfile": "default",
  "claudeCode.autoStart": false,
  "claudeCode.showDiffOnEdit": true
}

JetBrains — Plugin officiel

Le plugin JetBrains (IntelliJ, WebStorm, PyCharm, GoLand) offre une intégration similaire :

# Depuis l'IDE :
# Settings → Plugins → Marketplace → "Claude Code"

# Ou via la CLI JetBrains :
# jetbrains-cli install-plugin claude-code

# Raccourci : Alt+C pour ouvrir le panneau Claude Code
# Le plugin détecte automatiquement le fichier ouvert comme contexte

Terminal pur — Configuration avancée

Pour les adeptes du terminal, quelques configurations pour améliorer l'expérience :

# Alias utiles
alias cc="claude"
alias ccp="claude -p"
alias ccr="claude --continue"
alias ccs="claude --resume"

# Fonction pour lancer Claude dans un projet spécifique
ccproject() {
  cd "$1" && claude
}

# Auto-complétion (zsh)
eval "$(claude completion zsh)"

# Variables d'environnement
export ANTHROPIC_API_KEY="sk-ant-..."
export CLAUDE_CODE_DEFAULT_MODEL="sonnet"
export CLAUDE_CODE_MAX_TURNS="50"

Développement distant (SSH/Container)

Claude Code fonctionne dans les environnements distants :

# SSH vers un serveur de dev
ssh dev-server "cd /app && claude -p 'Lance les tests et corrige les échecs'"

# Dans un container Docker
docker exec -it my-app claude -p "Analyse les logs et identifie le problème"

# GitHub Codespaces
# Claude Code est pré-installé dans les devcontainers Anthropic

# VS Code Remote (SSH/WSL/Container)
# L'extension Claude Code fonctionne en mode Remote automatiquement

Git Worktrees & Sessions Parallèles

Les worktrees Git sont la solution de Claude Code pour l'isolation. Chaque worktree est un répertoire de travail séparé qui partage le même dépôt Git mais opère sur une branche différente. C'est essentiel pour le travail parallèle et les subagents qui modifient des fichiers.

Pourquoi les worktrees sont importants

Créer un worktree

# Dans Claude Code interactif :
# Dites simplement "Travaille dans un worktree"
# Claude crée automatiquement .claude/worktrees/{nom}/

# Via le flag CLI :
claude --worktree

# Avec un nom personnalisé :
claude --worktree --worktree-name "refactor-auth"

# Le worktree est créé dans :
# .claude/worktrees/refactor-auth/
# Branche : claude/refactor-auth-{hash}
# Base : HEAD de la branche courante

Workflow avec subagents et worktrees

# Prompt dans Claude Code :
"Lance 3 subagents dans des worktrees séparés :

Agent 1 (worktree: refactor-auth) :
- Migre src/auth/ de Express middleware vers Fastify hooks
- Lance les tests auth

Agent 2 (worktree: refactor-db) :
- Migre src/db/ de Knex vers Drizzle ORM  
- Régénère les types

Agent 3 (worktree: refactor-api) :
- Migre les routes src/routes/ vers le nouveau format Fastify
- Met à jour les schémas de validation

Quand les 3 ont terminé, montre-moi un résumé des changements."

# Résultat :
# .claude/worktrees/refactor-auth/   → branche claude/refactor-auth-abc
# .claude/worktrees/refactor-db/     → branche claude/refactor-db-def
# .claude/worktrees/refactor-api/    → branche claude/refactor-api-ghi

# Merge manuel après review :
git merge claude/refactor-auth-abc
git merge claude/refactor-db-def
git merge claude/refactor-api-ghi

Hooks de worktree

Vous pouvez configurer des hooks WorktreeCreate et WorktreeRemove pour automatiser des actions :

{
  "hooks": {
    "WorktreeCreate": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npm install && npm run build"
          }
        ]
      }
    ],
    "WorktreeRemove": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Worktree supprimé : $WORKTREE_PATH'"
          }
        ]
      }
    ]
  }
}

Nettoyage des worktrees

# À la fin de la session Claude Code, un prompt demande :
# "Voulez-vous garder ou supprimer le worktree ?"

# Nettoyage manuel :
git worktree list                    # Voir tous les worktrees
git worktree remove .claude/worktrees/refactor-auth  # Supprimer
git worktree prune                   # Nettoyer les entrées orphelines

# Supprimer tous les worktrees Claude :
rm -rf .claude/worktrees/
git worktree prune

Patterns Avancés & Cas d'Usage

Cette section présente 6 patterns architecturaux pour tirer le maximum de Claude Code. Chaque pattern est un workflow complet avec des exemples de code prêts à l'emploi.

Pattern 1 : Pipeline multi-modèle (Haiku → Sonnet → Opus)

Utilisez le modèle le moins cher possible pour chaque étape, en escaladant vers Opus uniquement quand nécessaire :

#!/bin/bash
# Étape 1 : Haiku collecte les données (pas cher)
FILES=$(claude -p "Liste tous les fichiers TypeScript qui importent 'express'" \
  --model haiku \
  --allowedTools Grep,Glob \
  --output-format json \
  --permission-mode accept-all | jq -r '.result')

echo "Fichiers trouvés : $FILES"

# Étape 2 : Sonnet analyse et planifie (rapport qualité/prix)
PLAN=$(claude -p "Voici les fichiers Express à migrer vers Fastify :
$FILES

Crée un plan de migration détaillé avec l'ordre des fichiers, 
les dépendances entre eux, et les risques." \
  --model sonnet \
  --allowedTools Read,Grep \
  --output-format json \
  --permission-mode accept-all | jq -r '.result')

echo "Plan de migration :"
echo "$PLAN"

# Étape 3 : Opus exécute la migration (complexe, besoin du meilleur)
claude -p "Exécute ce plan de migration Express → Fastify :

$PLAN

Migre chaque fichier, adapte les tests, et vérifie que tout compile." \
  --model opus \
  --max-turns 30 \
  --permission-mode accept-all

Pattern 2 : Code review automatisée en CI/CD

name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize]

permissions:
  pull-requests: write
  contents: read

jobs:
  review:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: '22'

      - run: npm install -g @anthropic-ai/claude-code

      - name: Generate Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          # Obtenir le diff
          DIFF=$(git diff origin/${{ github.base_ref }}...HEAD)
          
          # Obtenir la description de la PR
          PR_BODY=$(gh pr view ${{ github.event.pull_request.number }} --json body -q '.body')
          
          # Lancer la review
          REVIEW=$(claude -p "Tu es un senior code reviewer. Review cette PR.

          ## Description de la PR
          $PR_BODY

          ## Diff
          \`\`\`diff
          $DIFF
          \`\`\`

          Fournis :
          1. Résumé (2-3 phrases)
          2. Points positifs
          3. Problèmes (classés par sévérité)
          4. Suggestions d'amélioration
          5. Verdict : APPROVE / REQUEST_CHANGES / COMMENT
          
          Format en Markdown." \
            --model sonnet \
            --max-turns 3 \
            --allowedTools Read,Grep,Glob \
            --permission-mode accept-all)
          
          # Poster le commentaire
          gh pr comment ${{ github.event.pull_request.number }} \
            --body "## Claude Code Review

          $REVIEW
          
          ---
          *Review automatique par Claude Code (Sonnet)*"
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Pattern 3 : Automatisation planifiée avec bot Discord

# Architecture :
# Discord Bot → Schedule → tmux → claude -p → git push → GitHub Pages
#
# Le bot Discord maintient un scheduler qui exécute :
# - Briefing quotidien à 7h00
# - Scanner de marché à 23h00 (Lun-Ven)
# - Rétrospective hebdomadaire le vendredi 23h00
# - Rapport weekly le dimanche 18h00

# Commande Discord :
# every day at 07:00 articles analyse daily

# Ce que le bot exécute :
cd /path/to/articles
claude -p "Génère le briefing quotidien du jour" \
  --permission-mode accept-all \
  --max-turns 50

# Claude Code va :
# 1. Lire le CLAUDE.md pour comprendre le format
# 2. Appeler les MCP servers pour les données marché
# 3. Faire des WebSearch pour les actualités
# 4. Générer le HTML complet
# 5. Indexer l'article (node tools/add_card.js)
# 6. Commiter et pusher sur GitHub
# 7. GitHub Pages déploie automatiquement

Pattern 4 : Workflow structuré Plan → Code → Test → Review

#!/bin/bash
TASK="$1"  # ex: "Ajouter l'authentification OAuth2 Google"

echo "=== PHASE 1 : PLANIFICATION (Opus) ==="
PLAN=$(claude -p "PHASE PLAN UNIQUEMENT. Ne code rien.

Tâche : $TASK

Produis un plan technique détaillé :
1. Fichiers à créer/modifier
2. Dépendances à installer
3. Schéma de la base de données
4. Endpoints API
5. Tests à écrire
6. Risques et edge cases" \
  --model opus \
  --max-turns 5 \
  --allowedTools Read,Grep,Glob \
  --output-format json \
  --permission-mode accept-all | jq -r '.result')

echo "$PLAN"
echo ""
echo "=== PHASE 2 : IMPLÉMENTATION (Sonnet) ==="
claude -p "Implémente ce plan EXACTEMENT comme décrit. Ne dévie pas.

$PLAN

Crée tous les fichiers, installe les dépendances, et vérifie que ça compile." \
  --model sonnet \
  --max-turns 20 \
  --permission-mode accept-all

echo ""
echo "=== PHASE 3 : TESTS (Sonnet) ==="
claude --continue -p "Écris les tests unitaires et d'intégration pour tout ce que tu viens d'implémenter.
Lance-les et corrige les échecs." \
  --model sonnet \
  --max-turns 15

echo ""
echo "=== PHASE 4 : REVIEW (Opus) ==="
claude --continue -p "Review critique de tout le code que tu as écrit :
- Bugs potentiels
- Failles de sécurité
- Problèmes de performance
- Manques dans les tests
- Conformité avec le plan initial

Corrige les problèmes trouvés." \
  --model opus \
  --max-turns 10

Pattern 5 : Knowledge base avec MCP + CLAUDE.md + Skills

# Structure d'un projet avec knowledge base complète :
mon-projet/
├── CLAUDE.md                    # Conventions + architecture
├── .claude/
│   ├── settings.json            # Permissions + hooks
│   ├── rules/
│   │   ├── api-design.md        # Conventions API (globs: src/routes/**)
│   │   ├── db-patterns.md       # Patterns DB (globs: src/repos/**)
│   │   ├── testing.md           # Conventions test (globs: **/*.test.*)
│   │   └── security.md          # Règles sécu (globs: src/auth/**)
│   └── skills/
│       ├── deploy/SKILL.md      # /deploy staging|production
│       ├── review-pr/SKILL.md   # /review-pr {number}
│       ├── new-route/SKILL.md   # /new-route {resource}
│       └── debug/SKILL.md       # /debug {error-message}
├── .mcp.json                    # GitHub, PostgreSQL, Sentry
├── docs/
│   ├── architecture.md          # @import dans CLAUDE.md
│   ├── api-spec.md              # Spec OpenAPI
│   └── runbook.md               # Procédures opérationnelles
└── src/
    └── CLAUDE.md                # Conventions src/ spécifiques

# Résultat : Claude comprend TOUT le projet
# - Architecture globale (CLAUDE.md + imports)
# - Conventions par domaine (rules/ avec globs)
# - Procédures opérationnelles (skills/)
# - Accès aux données (MCP servers)
# - Historique (Auto Memory)
# - Sécurité (permissions + hooks)

Pattern 6 : Déploiement sécurisé avec hooks

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash scripts/pre-deploy-check.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash scripts/post-deploy-notify.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# Bloquer les déploiements si les tests ne passent pas
if echo "$COMMAND" | grep -q "fly deploy\|docker push\|kubectl apply"; then
  echo "Déploiement détecté. Vérification des prérequis..."
  
  # Vérifier la branche
  BRANCH=$(git branch --show-current)
  if [ "$BRANCH" != "main" ]; then
    echo "BLOQUÉ : Déploiement uniquement depuis main (actuellement sur $BRANCH)"
    exit 2
  fi
  
  # Vérifier les tests
  if ! npm run test --silent 2>/dev/null; then
    echo "BLOQUÉ : Les tests ne passent pas"
    exit 2
  fi
  
  # Vérifier le linting
  if ! npm run lint --silent 2>/dev/null; then
    echo "BLOQUÉ : Erreurs de lint détectées"
    exit 2
  fi
  
  echo "Tous les checks passent. Déploiement autorisé."
fi

exit 0

Récapitulatif & Ressources

Ce guide a couvert l'ensemble des fonctionnalités avancées de Claude Code. Voici un récapitulatif de toutes les capacités et les ressources pour aller plus loin.

Tableau récapitulatif des fonctionnalités

Parcours d'apprentissage recommandé

Ressources essentielles