# Guide de Claude Code : configuration pour la programmation agentique (pour débutants)

> Guide pratique complet pour configurer Claude Code : installation du CLI, configuration de CLAUDE.md et settings.json, règles d'autorisation, hooks automatiques, commande personnalisée /truth et sous-agents.

## 1. Installation de Claude Code et préparation de l'environnement

Claude Code s'installe comme une interface en ligne de commande (CLI) autonome pour interagir avec le code via les modèles agentiques d'Anthropic. Contrairement aux chatbots classiques, Claude Code interagit directement avec le système de fichiers, exécute des commandes terminal, analyse l'arborescence du projet et effectue des modifications atomiques.

### 1.1. Méthodes d'installation CLI : script natif vs npm

La méthode recommandée par les développeurs est le script système natif, qui configure automatiquement le binaire et l'environnement d'exécution. En alternative, pour les stations de travail disposant déjà d'un toolchain Node.js, vous pouvez utiliser le paquet npm global :

```bash
# macOS, Linux або WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# Альтернативне встановлення через npm
npm install -g @anthropic-ai/claude-code
```

Une fois l'installation terminée, vérifiez la fonctionnalité de la commande en exécutant `claude --version` dans votre terminal.

### 1.2. Liaison au répertoire du projet et authentification

Avant le premier lancement, il est crucial de se déplacer directement dans le dossier racine de votre projet de travail :

```bash
cd your-project-directory
claude
```

> 💡 **Pourquoi c'est important :** Claude Code lie strictement la mémoire à long terme, les règles locales et les permissions au répertoire de travail courant. Un lancement depuis le dossier home (`~`) ou le bureau entraînera la perte du contexte architectural de votre dépôt.

Lors du premier lancement, l'outil vous proposera de passer par l'authentification :
- **Connexion OAuth via navigateur** si vous disposez d'un abonnement Claude actif (Pro, Max ou Team).
- **Clé API Anthropic Console** pour un paiement à la seconde des tokens selon les tarifs API.

En plus du terminal pur, Claude Code prend en charge le fonctionnement via l'extension officielle VS Code, le plugin JetBrains, l'application desktop et l'interface web sur claude.ai. Toutes ces interfaces utilisent une structure de configuration commune `.claude/`, garantissant que les règles restent inchangées quel que soit l'environnement de travail choisi.

## 2. Trois fichiers de configuration : architecture de la mémoire et des paramètres

Claude Code utilise une hiérarchie de configuration à deux niveaux : le répertoire du projet `.claude/` (avec le fichier `CLAUDE.md` à la racine) et le répertoire global `~/.claude/` dans le dossier home de l'utilisateur. Les paramètres globaux s'appliquent à toutes les sessions sur la machine, tandis que les paramètres locaux ont la priorité pour le dépôt actuel.

### 2.1. CLAUDE.md et les règles de mémoire du dépôt

`CLAUDE.md` est la mémoire permanente du projet, que l'agent lit au début de chaque session de travail. On y fixe les repères architecturaux, les commandes de lancement des tests, les règles de style de code et la stack technologique.

| Mécanisme | Emplacement | Finalité |
| --- | --- | --- |
| **Guide racine** | `CLAUDE.md` | Instructions principales et description de la stack (recommandé < 2500 tokens). |
| **Règles modulaires** | `.claude/rules/*.md` | Instructions spécifiques liées à des chemins et fichiers précis. |
| **Générateur de mémoire** | Commande `/init` | Analyse automatique de la base de code et création du fichier initial. |
| **Éditeur de mémoire** | Commande `/memory` | Édition interactive rapide des règles fixées. |

> ⚠️ **Principe fondamental de la mémoire :** Les instructions données simplement dans le chat sont inévitablement perdues lors de la compression du contexte dans les longues sessions. Toute règle devant persister entre les sessions doit être explicitement écrite dans `CLAUDE.md`.

### 2.2. settings.json et le mécanisme de mémoire automatique (Auto memory)

Le fichier de configuration `settings.json` (situé dans `.claude/settings.json` pour le projet ou dans `~/.claude/settings.json` pour le niveau global) définit les permissions de sécurité, les hooks système, les variables d'environnement et le modèle par défaut.

Le mécanisme **Auto memory** permet à Claude Code d'enregistrer automatiquement les observations de travail entre les sessions sans intervention directe du développeur. Ce comportement peut être contrôlé par le paramètre `"autoMemoryEnabled": false` ou la variable d'environnement système `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`, si vous préférez un contrôle manuel exclusivement transparent via `CLAUDE.md`.

## 3. Configuration préalable des permissions et des hooks

Pour assurer la sécurité et éliminer les demandes de confirmation superflues, Claude Code propose un système de modes interactifs et de règles granulaires dans la configuration.

### 3.1. Modes de permissions interactifs et matrice allow/ask/deny

Le basculement rapide des modes d'exécution se fait via la combinaison de touches `Shift+Tab` :
- **Default** — demande la confirmation de l'utilisateur avant chaque opération potentiellement dangereuse ou modification de fichier.
- **Auto-Accept Edits** — applique automatiquement les modifications de fichiers, ne demandant confirmation que pour les commandes système.
- **Plan Mode** — mode lecture seule sans possibilité de modifier le code ou d'exécuter des commandes bash tant que le plan général n'a pas été approuvé.

Pour supprimer les confirmations routinières, une matrice déclarative de règles est configurée dans `.claude/settings.json` :

```json
{
  "permissions": {
    "allow": [
      "Bash(npm test:*)",
      "Bash(npm run lint:*)",
      "Read(**)"
    ],
    "ask": [
      "Bash(git push:*)"
    ],
    "deny": [
      "Bash(rm -rf /*)",
      "Bash(sudo:*)",
      "Read(.env)"
    ]
  }
}
```

La règle `deny` a toujours la priorité absolue : même si le masque `Read(**)` autorise la lecture des fichiers, l'interdiction explicite `Read(.env)` garantit que les variables d'environnement confidentielles ne pénètrent jamais dans le contexte du modèle.

### 3.2. Automatisation via les hooks PostToolUse et PreToolUse

Les hooks permettent d'exécuter des scripts locaux avant ou après l'appel des outils intégrés de l'agent.

Par exemple, le hook **PostToolUse** formate automatiquement les fichiers modifiés via Prettier :

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\""
          }
        ]
      }
    ]
  }
}
```

Et le hook **PreToolUse** permet d'intercepter et de bloquer programmatiquement les commandes bash dangereuses au niveau d'un script Python avant leur transmission effective au shell :

```python
#!/usr/bin/env python3
# .claude/hooks/block-dangerous-bash.py
import json
import re
import sys

DANGEROUS_PATTERNS = [
    r'\brm\s+.*-[a-z]*r[a-z]*f',
    r'sudo\s+rm',
    r'chmod\s+777',
    r'git\s+push\s+--force.*main',
]

input_data = json.load(sys.stdin)
if input_data.get('tool_name') == 'Bash':
    command = input_data.get('tool_input', {}).get('command', '')
    for pattern in DANGEROUS_PATTERNS:
        if re.search(pattern, command, re.IGNORECASE):
            print("BLOCKED: command matches dangerous security pattern", file=sys.stderr)
            sys.exit(2)
sys.exit(0)
```

Le code de retour `2` signale à Claude Code un blocage critique de l'appel sans exécution de la commande dans le système.

## 4. Commandes à apprendre en premier

La bibliothèque intégrée de Claude Code contient plus de soixante slash commands, mais un noyau de base suffit pour une productivité quotidienne efficace.

### 4.1. Tableau récapitulatif des slash commands de base et avancées

Voici un guide structuré des commandes CLI les plus importantes :

| Commande | Catégorie | Finalité et comportement |
| --- | --- | --- |
| `/init` | Configuration | Scanne le projet et crée le `CLAUDE.md` initial. |
| `/memory` | Configuration | Ouvre le fichier de mémoire du projet pour édition directe. |
| `/clear` | Contexte | Réinitialise la conversation actuelle, en préservant la mémoire du projet. |
| `/compact [focus]` | Contexte | Compresse l'historique de la session, en conservant les aspects clés indiqués. |
| `/context` | Contexte | Affiche l'état détaillé de remplissage de la fenêtre de contexte. |
| `/plan` | Planification | Bascule le CLI en mode lecture seule et conception des étapes. |
| `/diff` | Vérification | Affiche une revue interactive de tous les changements de la session actuelle. |
| `/code-review [--fix]` | Vérification | Analyse les modifications non commitées pour détecter les erreurs logiques. |
| `/security-review` | Vérification | Audit spécialisé du code pour détecter les vulnérabilités. |
| `/resume [session]` | Navigation | Reprend une session précédente par son ID ou son nom. |
| `/branch [name]` | Navigation | Crée une branche de conversation séparée sans relancer la session. |
| `/rewind` | Navigation | Rembobine l'état des fichiers ou du dialogue jusqu'à un checkpoint précédent. |
| `/model` | Productivité | Change le modèle de travail (Sonnet, Haiku, Opus) en cours de conversation. |
| `/effort` | Productivité | Ajuste la profondeur de la chaîne de raisonnement du modèle (de low à max). |
| `/cost` | Productivité | Affiche les statistiques de consommation de tokens et le solde de la session. |
| `/agents` | Délégation | Gère les sous-agents spécialisés et les tâches en arrière-plan. |
| `/permissions` | Configuration | Menu interactif de visualisation et de modification de la liste des permissions. |
| `/hooks` | Configuration | Panneau de diagnostic des hooks système enregistrés. |
| `/doctor` | Diagnostic | Vérification complète de l'environnement, du réseau et des clés système. |

![Aperçu et navigation des slash commands intégrées dans Claude Code](/api/guides-media/automation/claude-code-agentic-programming-setup-guide/images/claude-code-agentic-programming-setup-guide-extra-01.webp)

### 4.2. La triade de productivité quotidienne : /compact, /plan et /diff

Pour une prise en main rapide, il est recommandé de maîtriser trois outils essentiels :
1. **`/plan`** — lancez-le toujours au début d'une tâche complexe. Cela élimine les modifications de code chaotiques et incontrôlées sans compréhension claire des conséquences.
2. **`/compact`** — utilisez-le toutes les 20–30 minutes de dialogue actif ou après la fin d'une sous-tâche pour éviter la baisse de vitesse et la perte d'attention du modèle.
3. **`/diff`** — ouvrez-le avant tout commit pour une vérification visuelle étape par étape du code généré.

## 5. Création de votre propre commande /truth

La commande `/truth` ne fait pas partie de la distribution standard de Claude Code, mais elle résout un problème fondamental du développement agentique : la tendance du modèle à signaler un succès sans vérifier réellement les résultats dans le système de fichiers.

### 5.1. Concept de vérification des faits contre la base de code

Lorsque l'agent affirme : *« J'ai mis à jour le type dans le fichier X et vérifié les imports dans le fichier Y »*, il s'appuie souvent sur ses propres intentions intermédiaires issues du contexte. Le concept de la commande `/truth` consiste à forcer le rechargement des fichiers réels depuis le disque et à confronter chaque affirmation avec `git diff`.

![Gestion interactive du contexte, des sessions et des commandes Claude Code](/api/guides-media/automation/claude-code-agentic-programming-setup-guide/images/claude-code-agentic-programming-setup-guide-extra-02.webp)

### 5.2. Implémentation du skill .claude/skills/truth/SKILL.md

Les commandes personnalisées sont formatées comme des skills. Créez le fichier `.claude/skills/truth/SKILL.md` dans votre projet :

```markdown
---
description: "Verify Claude's most recent claims and edits against the actual codebase"
allowed-tools: ["Read", "Grep", "Glob", "Bash(git diff:*)"]
---

Re-examine everything you just told me in this conversation against what actually exists in the codebase right now. Specifically:

1. For every file you claim to have edited, read it again and confirm the change is actually present and matches what you described.
2. For every claim about existing code (a function's behavior, a config value, an import, a dependency version), verify it against the real file rather than your memory of reading it earlier in the session.
3. Run `git diff` and compare the actual diff against what you described changing.
4. Report back plainly: which claims checked out, which didn't, and exactly what the discrepancy was for anything that failed. Do not soften or hedge a discrepancy you find, state it directly.
```

Grâce à l'isolation dans `allowed-tools`, la commande n'a physiquement pas le droit de modifier les fichiers — elle fonctionne exclusivement comme un auditeur indépendant.

## 6. Sous-agents et travail parallèle

Lors du travail sur de grands projets, le problème de la surcharge du contexte survient : la lecture de dizaines de fichiers et l'exécution de tests lourds remplissent rapidement la fenêtre de contexte disponible.

### 6.1. Isolation du contexte et sous-agents spécialisés (/agents)

Un sous-agent est une instance distincte de Claude Code avec son propre contexte isolé, son jeu d'outils et un prompt système étroit. Il résout la sous-tâche assignée de manière autonome et ne renvoie à la session principale qu'un résumé concis.

```bash
# Відкрити інтерактивне меню субагентів усередині сесії
/agents
```

Vous pouvez également décrire de manière déclarative un sous-agent permanent dans le fichier `.claude/agents/code-reviewer.md` :
- Lui donner accès uniquement en lecture (`Read`, `Grep`, `Glob`).
- Lui assigner un modèle rapide et économique.
- Interdire toute modification autonome du code, le transformant ainsi en un relecteur fiable.

### 6.2. Mise à l'échelle des tâches via worktree et exécution par lot (/batch)

Pour l'exécution parallèle de plusieurs tâches indépendantes, Claude Code prend en charge le mode Git Worktree et la commande `/batch` :
- **Arbres parallèles (`--worktree`) :** plusieurs agents travaillent dans des copies de travail isolées du dépôt, sans conflits de verrouillage de fichiers.
- **Mode par lot (`/batch`) :** exécution en arrière-plan de tâches homogènes de refactoring ou de génération de documentation.

## 7. Modèle prêt à l'emploi CLAUDE.md et settings.json

Voici des fichiers de configuration éprouvés en pratique, qu'il convient de commiter dans le dépôt de votre projet pour créer un environnement de production stable.

### 7.1. Modèle de base de mémoire CLAUDE.md

Enregistrez le contenu suivant dans le fichier `CLAUDE.md` à la racine de votre dépôt :

```markdown
# Project Context

### Stack
- Language/Framework: [Node.js, TypeScript, Next.js / Python, FastAPI]
- Styling: [Tailwind CSS]
- Database: [PostgreSQL / SQLite via Drizzle ORM]

### Commands
- Dev server: `npm run dev`
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`

### Conventions
- Strict TypeScript typing without `any`
- Functional React components with named exports
- Keep business logic in services or hooks, not inside UI components

### Before finishing any task
- Run test suite and confirm 100% pass rate
- Run `/truth` if the task involved modifying multiple files
```

### 7.2. Config de production .claude/settings.json avec hooks

Enregistrez la configuration dans `.claude/settings.json` :

```json
{
  "permissions": {
    "allow": [
      "Bash(npm test:*)",
      "Bash(npm run lint:*)",
      "Read(**)"
    ],
    "ask": [
      "Bash(git push:*)"
    ],
    "deny": [
      "Bash(rm -rf /*)",
      "Bash(sudo:*)",
      "Read(.env)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/block-dangerous-bash.py"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\""
          }
        ]
      }
    ]
  }
}
```

Pour les paramètres locaux spécifiques à votre machine, utilisez `.claude/settings.local.json`, en l'ajoutant au `.gitignore`.

## 8. Conclusion et checklist de préparation

Un environnement de qualité pour le développement agentique se distingue d'un chat chaotique par la configuration préalable des mécanismes de protection, des règles de mémoire et de protocoles de vérification clairs.

### 8.1. Principes clés du développement agentique

1. **Le contexte doit rester propre :** utilisez régulièrement `/compact` et déléguez les tâches longues aux sous-agents.
2. **La mémoire doit être écrite :** si une règle est importante, fixez-la dans `CLAUDE.md`, ne la répétez pas dans les messages.
3. **Les actions doivent être vérifiées :** activez `/truth` et `/diff` avant de figer les modifications dans le système de contrôle de version.

### 8.2. Checklist de configuration initiale de l'espace de travail

| Étape | Action | Statut de préparation |
| --- | --- | --- |
| **Installation** | CLI natif Claude Code installé et authentification réussie | `Obligatoire` |
| **Mémoire du projet** | `CLAUDE.md` créé avec description de la stack, des commandes et des conventions | `Obligatoire` |
| **Permissions** | Listes `allow`, `ask` et `deny` formées dans `settings.json` | `Obligatoire` |
| **Hook de formatage** | `PostToolUse` configuré pour l'appel automatique de Prettier | `Recommandé` |
| **Script de sécurité** | `block-dangerous-bash.py` connecté via `PreToolUse` | `Recommandé` |
| **Skill personnalisé** | Commande de vérification `.claude/skills/truth/SKILL.md` créée | `Recommandé` |