Claude Code

1. Installation & Setup

Prérequis

# Node.js 18+ (vérifie le minimum courant dans la doc d'install)
node --version

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

# Vérification
claude --version

Première session

# Dans le répertoire de ton projet
cd my-project
claude

# Mode non-interactif (CI/CD)
claude --print "Génère un résumé de l'architecture du projet"

Structure .claude/

.claude/
  settings.json       → Permissions, hooks, MCP servers
  skills/             → Skills encapsulés
    security-audit/
      SKILL.md
    test-generator/
      SKILL.md
  agents/             → Définitions de subagents
    reviewer.md
CLAUDE.md             → Contexte global (Module 4)

2. Permissions & Sécurité

Claude Code demande ta permission avant d'agir. C'est le mécanisme Human-in-the-Loop fondamental.

Niveaux de permission

// .claude/settings.json
{
  "permissions": {
    "allow": [
      "Bash(npm run test)",
      "Bash(npm run lint)",
      "Bash(git diff:*)",
      "Bash(git log:*)",
      "Write(src/**)",
      "Write(tests/**)"
    ],
    "deny": [
      "Bash(git push:*)",
      "Bash(npm publish:*)",
      "Bash(rm -rf:*)",
      "Write(.env*)"
    ]
  }
}

Règles de permission

À autoriser librement :

• Lecture de fichiers (Read)
• Exécution de tests et linters
• Écriture dans src/, tests/
• git diff, git log, git status

À autoriser avec précaution :

• git commit (vérifie le message)
• Commandes de build
• Modifications de config

À ne jamais autoriser :

• git push (tu décides quand)
• npm publish, docker push
• Modifications de .env
• rm -rf sur des chemins critiques

3. Les Skills : expertise on-demand

Un Skill est une expertise encapsulée, chargée uniquement quand l'agent en a besoin. Cela économise le contexte et améliore la précision.

Créer un skill manuellement

.claude/skills/security-audit/SKILL.md

---
name: security-audit
description: >
  Audite le code source pour détecter des vulnérabilités de sécurité.
  Couvre OWASP Top 10, secrets codés en dur, et mauvaises pratiques auth.
  Utilise quand : on te demande un audit sécurité, une revue de code critique,
  ou l'analyse d'un module d'authentification.
---

# Security Auditor

Tu es un expert en sécurité applicative (OWASP Top 10, CWE).

## Processus d'audit

Pour chaque fichier analysé :

### 1. Injection (A01)
- SQL : paramètres non bindés, concatenation de strings
- XSS : sortie HTML non échappée, innerHTML non sanitizé
- Command : exec/eval avec user input

### 2. Broken Authentication (A02)
- Tokens codés en dur
- Mots de passe en dur ou dans les logs
- Sessions sans expiration

### 3. Sensitive Data Exposure (A03)
- PII dans les logs
- Données sensibles dans les URLs
- Absence de chiffrement at-rest

### 4. IDOR / Missing Auth (A05)
- Accès aux ressources sans vérification de propriété
- Routes non protégées

### 5. Security Misconfiguration (A05)
- CORS trop permissif
- Headers de sécurité manquants
- Stack traces exposées

## Format de sortie

Pour chaque problème :
| Fichier:Ligne | Catégorie OWASP | Sévérité | Description | Fix recommandé |

Sévérité : Critical / High / Medium / Low / Info

Termine par un score de risque global : Critical / High / Medium / Low

Créer un skill avec l'IA

Activer un skill

4. Les Hooks : automatisation déterministe

Les Hooks s'exécutent à des moments précis du cycle de l'agent, indépendamment de ce que l'IA décide. C'est le plan de contrôle.

Événements disponibles

Exemple : Scan de secrets avant écriture de fichier

// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/scan-secrets.sh"
          }
        ]
      }
    ]
  }
}

Claude Code passe le contexte du hook en JSON sur stdin (et non en argument de ligne de commande). Le script lit tool_input.file_path :

# .claude/hooks/scan-secrets.sh
#!/usr/bin/env bash
# Le hook reçoit un objet JSON sur stdin. On en extrait le chemin du fichier.
FILE=$(jq -r '.tool_input.file_path // empty')
[ -z "$FILE" ] && exit 0

# Détecte les patterns de secrets courants
if grep -Eq "(api_key|secret|password|token)[[:space:]]*=[[:space:]]*['\"][^'\"]{8,}" "$FILE" 2>/dev/null; then
  echo "SECRET DÉTECTÉ dans $FILE — écriture bloquée" >&2
  exit 2  # Code 2 = bloque l'action et renvoie stderr à Claude
fi
exit 0

Exemple : Injection de contexte Git au démarrage

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/inject-git-context.sh"
          }
        ]
      }
    ]
  }
}

Ce que le hook écrit sur stdout est injecté dans le contexte de la session :

# .claude/hooks/inject-git-context.sh
BRANCH=$(git branch --show-current)
LAST_COMMITS=$(git log --oneline -5)
CHANGED_FILES=$(git diff --name-only HEAD~1)

printf '## Contexte Git actuel\n'
printf 'Branche : %s\n' "$BRANCH"
printf 'Derniers commits :\n%s\n' "$LAST_COMMITS"
printf 'Fichiers modifiés depuis le dernier commit :\n%s\n' "$CHANGED_FILES"

Codes de retour des hooks

5. Les Subagents : délégation et isolation

Les subagents permettent d'isoler des tâches spécifiques dans des sessions séparées, sans polluer le contexte principal.

Cas d'usage

Pattern Writer / Reviewer

Un pattern simple et redoutable pour la qualité : deux sessions Claude distinctes, aucune mémoire partagée entre elles.

Résultat : le Reviewer n'a aucun biais positif envers le code du Writer. La qualité de la revue est maximale.

Fan-out sur plusieurs fichiers

# Traiter de nombreux fichiers en parallèle.
# `claude --print` écrit sur stdout : on redirige avec `>`.
shopt -s globstar             # nécessaire pour que src/**/*.ts soit récursif
for file in src/**/*.ts; do
  claude --print "Ajoute les JSDoc manquants à ce fichier.
  Conventions : @src/examples/documented.ts
  Fichier : $(cat "$file")" > "${file%.ts}.documented.ts" &
done
wait

6. Model Context Protocol (MCP)

Le MCP permet de connecter Claude Code à des services externes : GitHub, Linear, Sentry, base de données, Figma...

Configuration d'un serveur MCP

// .claude/settings.json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "${DATABASE_URL}"
      }
    },
    "sentry": {
      "command": "npx",
      "args": ["@sentry/mcp-server@latest"],
      "env": {
        "SENTRY_AUTH_TOKEN": "${SENTRY_TOKEN}"
      }
    }
  }
}

Workflows rendus possibles avec MCP

Workflow 1 : Bug depuis Sentry → Fix automatique

Workflow 2 : Issue GitHub → Implémentation

Workflow 3 : Analyse de la base de données

Règles de sécurité MCP

À privilégier :

• Serveurs MCP officiels et maintenus
• Tokens avec permissions minimales (read-only si lecture seule)
• Variables d'environnement pour les tokens (jamais hardcodés)

À proscrire :

• Serveurs MCP tiers non vérifiés
• Tokens avec permissions complètes si non nécessaire
• MCP connectés à la production sans whitelist d'actions

7. Mode CI/CD et non-interactif

Claude Code peut s'exécuter sans supervision humaine dans les pipelines CI.

Cas d'usage CI/CD

# .github/workflows/ai-review.yml
name: AI Code Review
on: [pull_request]

jobs:
  ai-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: AI Security Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          git diff origin/main...HEAD > /tmp/diff.txt
          claude --print "
          Revois ce diff pour des problèmes de sécurité critiques.
          Focus : secrets exposés, injections, auth manquante.
          Format : JSON avec champs file, line, severity, issue, fix.
          Si aucun problème critique : réponds {"issues": []}
          Diff : $(cat /tmp/diff.txt)
          " > /tmp/review.json

      - name: Post Review Comment
        uses: actions/github-script@v7
        with:
          script: |
            const review = require('/tmp/review.json');
            if (review.issues.length > 0) {
              github.rest.issues.createComment({...});
            }

Contrôle du niveau d'autonomie

# Aucune interaction humaine (CI/CD) — la sortie va sur stdout, on redirige
claude --print "tâche" > output.txt

# Sortie structurée JSON (pour pipe vers un autre outil)
claude --print --output-format json "tâche" > output.json

# Sans confirmation de permissions (uniquement en environnement isolé/CI)
claude --print --dangerously-skip-permissions "tâche"

# Interactif normal (développement)
claude

Agent SDK : embarquer Claude dans son propre code

Quand claude --print ne suffit pas (orchestration custom, streaming dans une UI, contrôle fin du contexte), passer par le SDK officiel.

import { query } from '@anthropic-ai/claude-agent-sdk'

// query() renvoie directement un async generator : on itère dessus,
// pas besoin de l'attendre avec await.
for await (const message of query({
  prompt: 'Résume ce diff et propose un commit message',
  options: {
    cwd: process.cwd(),
    permissionMode: 'plan',         // Ne modifie rien
    allowedTools: ['Read', 'Grep'], // Lecture seule
    maxTurns: 4,
  },
})) {
  // Stream des événements (tool calls, texte, fin de session)
  console.log(message)
}

À ce niveau, Claude Code devient un runtime d'agent qu'on intègre dans un bot Slack, une route API, un job worker. Le SDK existe en TypeScript et en Python.

8. Gestion de session avancée

Commandes essentielles

Quand utiliser /compact vs /clear

Template de démarrage de session productive

Contexte du projet : @CLAUDE.md
Tâche actuelle : [description précise]
Fichiers concernés : @[fichier1] @[fichier2]
Objectif de cette session : [ce que je veux atteindre]
Critère de succès : [comment savoir qu'on a réussi]

On commence par la phase EXPLORE.

9. Slash commands personnalisés

Au-delà des commandes système (/clear, /compact), tu peux créer tes propres slash commands au niveau projet ou utilisateur. C'est le feature qui transforme un workflow récurrent en un seul /audit, /migrate, /release-notes.

Création

.claude/commands/
  audit-security.md   → invoqué par /audit-security
  release-notes.md    → invoqué par /release-notes
  refactor-module.md  → invoqué par /refactor-module

Anatomie d'un slash command

---
description: Audit sécurité complet du diff courant
argument-hint: [optionnel : chemin spécifique à auditer]
allowed-tools:
  - Read
  - Grep
  - Bash(git diff:*)
---

Tu es expert sécurité applicative (OWASP Top 10).

Si un argument est fourni : audite ce chemin. Sinon : audite `git diff origin/main...HEAD`.

Cherche :
1. Injection (SQL, XSS, command, prompt injection)
2. Auth/authz manquante ou mauvaise
3. Secrets exposés ou loggés
4. Validation des entrées manquante
5. Exposition d'erreurs internes

Pour chaque problème : fichier:ligne, sévérité (Critical/High/Medium/Low), fix concret.
Termine par un score global et une recommandation merge/no-merge.

Commandes utiles à avoir d'office

Plugins & marketplaces : partager tout d'un coup

Un slash command se partage bien. Mais quand ton équipe a construit plusieurs commandes, des skills, des hooks et une config MCP, les copier-coller de projet en projet devient vite pénible. Les plugins règlent ça : un plugin regroupe commandes, skills, hooks et serveurs MCP dans un seul paquet qu'on installe et met à jour en une commande.

Et une marketplace, c'est simplement un dépôt Git qui liste des plugins. Ton équipe peut avoir la sienne, en interne.

# Ajouter la marketplace de ton équipe (un repo Git)
/plugin marketplace add mon-org/claude-plugins

# Installer un plugin depuis cette marketplace
/plugin install security-pack@mon-org

L'intérêt concret :

• Un seul point de vérité. Tu corriges un hook une fois dans le plugin, tout le monde reçoit la mise à jour. Fini les copies qui divergent d'un repo à l'autre.
• De l'onboarding en une commande. Un nouvel arrivant installe le plugin de l'équipe et récupère d'un coup les conventions, les commandes et les garde-fous.
• Du versionnage. Un plugin a une version : tu sais qui utilise quoi, et tu peux revenir en arrière.

10. Plan mode, checkpoints et rewind

Plan mode

Active explicitement le mode où Claude ne peut que lire et planifier — pas écrire. Idéal pour la phase EXPLORE.

# Au lancement
claude --permission-mode plan

# Ou dans la session
Shift+Tab → cycle entre Plan / Default / Accept-edits

Checkpoints et rewind

Claude Code prend des checkpoints à chaque modification (write/edit). Tu peux revenir en arrière sans toucher à Git.

/rewind        → ouvre le sélecteur de checkpoints (ou double Esc)

Le sélecteur te laisse choisir le point de retour et ce que tu restaures : le code seul, la conversation seule, ou les deux. C'est la différence entre « j'efface tout » et « je rollback proprement à l'avant-dernière étape ». Sur une session d'agent qui part en vrille, ça sauve la mise.

Reprise de session

/resume        → sélecteur des sessions précédentes
claude --resume   → idem au lancement, depuis le terminal

Les sessions vivent dans ~/.claude/projects/<chemin-projet>/<session-id>.jsonl. Tu peux archiver ces transcripts si tu veux un audit trail (voir Module 8).

11. Construire son MCP server interne

Quand le serveur MCP n'existe pas pour ton SI interne (ton CRM maison, ton wiki Confluence avec une politique d'accès custom, ton outil de tickets), construis le tien. Le SDK MCP est simple, le protocole est stable.

Template minimal Node.js

// my-internal-mcp/server.ts
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
import { z } from 'zod'

const server = new McpServer({ name: 'internal-tickets', version: '1.0.0' })

// L'API haut niveau `registerTool` déclare le schéma (via zod) et le handler
// en un seul endroit — plus de setRequestHandler(...) bas niveau à câbler.
server.registerTool(
  'get_ticket',
  {
    description: 'Récupère un ticket Jira interne par sa clé',
    inputSchema: { key: z.string().describe('Clé du ticket, ex. PROJ-1234') },
  },
  async ({ key }) => {
    const ticket = await fetchTicket(key) // Ton API interne
    return { content: [{ type: 'text', text: JSON.stringify(ticket) }] }
  },
)

await server.connect(new StdioServerTransport())

Enregistrement dans Claude Code

// .claude/settings.json
{
  "mcpServers": {
    "internal-tickets": {
      "command": "node",
      "args": ["/path/to/my-internal-mcp/server.js"],
      "env": {
        "INTERNAL_API_TOKEN": "${env:INTERNAL_API_TOKEN}"
      }
    }
  }
}

Bonnes pratiques d'entreprise

• Auth par token court dans env, jamais hardcodé.
• Allowlist des actions : un MCP qui lit n'écrit pas, un MCP qui écrit ne supprime pas.
• Rate limiting côté serveur MCP (évite qu'un agent bouclant n'épuise l'API interne).
• Logs structurés côté MCP : tout appel d'outil tracé avec timestamp + session ID Claude.

12. Coûts et quotas

Un agent qui tourne en boucle peut consommer plusieurs millions de tokens en une heure. Un senior pilote son budget.

Un ordre de grandeur pour te repérer

Avant de mesurer, il faut un repère. Voici des fourchettes en tokens (plus stables que les prix, qui bougent tout le temps). Prends-les comme un ordre de grandeur, pas comme une facture.

Pour convertir en euros, une seule règle : va chercher le prix courant du provider (il change trop souvent pour tenir dans un livre) et applique-le au ratio input/output/cache que te donne /cost. Exemple de raisonnement, à recalculer avec les tarifs du jour : une feature moyenne à ~1 M de tokens, majoritairement en input, coûte « quelques euros » sur un modèle Sonnet, sensiblement plus sur un modèle Opus. Le prompt caching (Module 1) peut diviser la part de contexte répété par ~10 : c'est souvent lui qui fait la différence entre une session à quelques centimes et une session à quelques euros.

Mesurer

# Dans la session
/cost     → coût de la session courante (input/output/cache)
/status   → tokens consommés + remaining quota

Optimiser

• Prompt caching (voir Module 1) : le CLAUDE.md devient quasi gratuit en cache hit.
• Plan mode pour les phases exploratoires : évite les écritures coûteuses sur des sessions qui auraient dérivé.
• Subagents ciblés : un subagent qui investigue n'a pas besoin du contexte complet du parent.
• Modèle adapté à la tâche : Haiku pour le boilerplate, Sonnet pour la majorité, Opus uniquement pour le raisonnement complexe ou les architectures.

Alertes

Si tu opères Claude Code en équipe, mets en place :

• Un budget mensuel par utilisateur via l'API Anthropic.
• Une alerte Slack quand un utilisateur dépasse un seuil quotidien anormal.
• Un dashboard interne (Anthropic expose les usages par API key) pour repérer les agents qui bouclent.