# Claude Code : guide pour débutants > Guide complet sur l'utilisation de Claude Code d'Anthropic : installation du CLI, authentification, gestion des autorisations, raccourcis clavier et développement pas à pas de votre premier projet. Claude Code est l’interface en ligne de commande officielle d’Anthropic, capable de lire le code source, d’apporter des modifications, d’exécuter des commandes et d’interagir avec Git directement dans le terminal via un dialogue simple en langage naturel. Il ne s’agit pas d’une fenêtre de chat web séparée où il faut copier-coller le code manuellement, mais bien d’un agent autonome complet qui opère directement au sein de votre projet. Ce guide constitue le point de départ pour démarrer rapidement avec Claude Code. Le contenu est divisé en trois blocs logiques : - **Module 1 — Installation et configuration de base :** déploiement du CLI, authentification via API ou OAuth, premier lancement et revue des fichiers de configuration. - **Module 2 — Session de travail et interaction :** gestion du contexte, raccourcis clavier, slash commands, mode non interactif et optimisation de la mémoire (`/compact`). - **Module 3 — Sécurité et modèle de permissions :** configuration des fichiers `settings.json`, création de listes d’autorisations (allow) et d’interdictions (deny) pour les commandes bash. Chaque module se conclut par un exercice pratique consistant à créer, affiner et finaliser un composant web réel sur Next.js. --- ## 1. Qu’est-ce que Claude Code et prérequis système ### 1.1. Définition de Claude Code et différences avec le chat web Claude Code s’intègre à votre stack de développement quotidien comme assistant terminal. Contrairement à un chat web traditionnel, l’agent dispose d’un ensemble d’outils (Tools) : - **Lecture et recherche :** inspecte des fichiers individuels, effectue des recherches via expressions régulières (`grep`) et navigue dans la structure du projet (`glob`). - **Modification du code :** génère des modifications ciblées des fichiers via un mécanisme patch/diff, évitant ainsi la réécriture complète de gros fichiers. - **Exécution de commandes système :** lance les tests, compilateurs, linters et commandes git, avec possibilité d’analyser les codes de retour et les erreurs de compilation. ### 1.2. Prérequis système et préparation de l’environnement Avant l’installation, assurez-vous de la présence des composants nécessaires : - **Système d’exploitation :** macOS, une distribution Linux récente ou Windows via le sous-système WSL2. - **Environnement d’exécution :** Node.js version 18.0 ou supérieure (vérifiez avec `node -v`). - **Gestion de versions :** Git version 2.20+ (vérifiez avec `git --version`). - **Accès aux modèles Anthropic :** clé API active depuis la Console Anthropic ou compte disposant d’un abonnement Claude Max. --- ## 2. Installation et authentification ### 2.1. Installation du CLI via npm et gestionnaire de paquets Claude Code est distribué comme un paquet global dans le registre npm. Exécutez la commande d’installation dans le terminal : ```bash npm install -g @anthropic-ai/claude-code ``` Vérifiez la bonne installation du binaire : ```bash claude --version ``` Si le terminal renvoie une erreur `command not found`, cela indique que le chemin des paquets globaux npm n’est pas inclus dans la variable d’environnement `PATH`. La solution détaillée figure dans le bloc de diagnostic ci-dessous. ### 2.2. Authentification et liaison du compte Anthropic Deux méthodes d’autorisation sont prises en charge : **Option 1 — Clé API Anthropic :** Spécifiez le token via une variable d’environnement : ```bash export ANTHROPIC_API_KEY="sk-ant-ваш-ключ-api" ``` Pour que la clé persiste entre les redémarrages du terminal, ajoutez la commande au fichier de configuration de votre shell : ```bash echo 'export ANTHROPIC_API_KEY="sk-ant-ваш-ключ-api"' >> ~/.zshrc source ~/.zshrc ``` **Option 2 — Abonnement Claude Max (OAuth) :** Si vous utilisez un abonnement Claude Max (100 $ ou 200 $/mois), connectez-vous sans utiliser de clé API distincte : ```bash claude login ``` La commande ouvrira une session dans votre navigateur par défaut pour confirmer l’accès. --- ## 3. Premier lancement et configuration de base ### 3.1. Premier lancement dans un projet et vérification de l’environnement Accédez au répertoire de l’un de vos projets de code et initialisez Claude Code : ```bash cd ~/my-project claude ``` Après le lancement, vous accéderez à un environnement de commande interactif. Essayez d’envoyer une requête de test basique : ```text Summarize the structure of this project and list the main technologies used. ``` Claude examinera automatiquement les fichiers `package.json`, les configurations de build et la structure des répertoires, puis formulera un bref rapport d’introduction. ### 3.2. Configuration de base et dépannage (Troubleshooting) Les fichiers de configuration se trouvent dans le répertoire `~/.claude/` : - `~/.claude/settings.json` — autorisations et restrictions globales d’accès aux outils. - `~/.claude/CLAUDE.md` — instructions système personnelles de l’utilisateur. - `.claude/settings.json` — paramètres spécifiques au projet (fixés dans le système de contrôle de version). - `CLAUDE.md` — instructions au niveau du dépôt (architecture, règles de linting). | Problème lors du lancement | Cause racine | Solution technique | | :--- | :--- | :--- | | `claude: command not found` | Le répertoire bin de npm n’est pas ajouté au `PATH` | Ajoutez le chemin au shell : `export PATH="$(npm config get prefix)/bin:$PATH"` | | Erreur d’authentification `401 Unauthorized` | Clé API invalide ou expirée | Exécutez `claude logout`, vérifiez la valeur de `ANTHROPIC_API_KEY` et répétez `claude login` | | Initialisation lente de la session | Indexation d’un grand dépôt | Le premier lancement nécessite l’analyse de l’arborescence des fichiers ; les itérations suivantes utilisent le cache | --- ## 4. Pratique : création de la première application ### 4.1. Algorithme étape par étape pour le déploiement d’un prototype L’objectif du premier exercice est de créer concrètement un composant client minimal Next.js / React à l’aide de Claude Code : 1. Demandez à Claude de créer un nouveau fichier de page `app/practice/page.tsx`. 2. Chargez-le de définir un état de chargement simple et un bouton appelant un endpoint de test. 3. Vérifiez le fonctionnement de l’interface à l’adresse `http://localhost:3000/practice`. ### 4.2. Modèle de composant de départ et vérification locale Le code de base du prototype : ```tsx // app/practice/page.tsx 'use client'; import { useState } from 'react'; export default function PracticePage() { const [result, setResult] = useState(''); const [loading, setLoading] = useState(false); async function runTest() { setLoading(true); try { const response = await fetch('/api/test'); const data = await response.json(); setResult(data.message || 'Запит виконано успішно'); } catch { setResult('Помилка виконання тестового запиту'); } finally { setLoading(false); } } return (

Практична вправа 1: Прототип

{result && (
{result}
)}
); } ``` --- ## 5. Session de travail et cycle de dialogue ### 5.1. Lancement d’une session REPL interactive Pour le développement quotidien, accédez au répertoire de travail et activez la boucle interactive de lecture-exécution (REPL) : ```bash cd ~/my-project claude ``` Claude conserve le contexte de la conversation tout au long de la session, mémorisant les fichiers modifiés et les erreurs détectées. L’échange se fait en langage courant, sans syntaxe formalisée. ### 5.2. Cycle de dialogue : planification, outils et exécution Le fonctionnement de l’agent suit un cycle en cinq étapes : ```mermaid flowchart TD A["Користувач ставить завдання природною мовою"] --> B["Claude аналізує кодову базу та формує план"] B --> C["Агент запитує дозвіл на модифікацію файлів/команд"] C --> D["Виконання затверджених дій та валідація дифу"] D --> E["Користувач перевіряє результат та надає фідбек"] ``` Un fragment typique d’interaction : - **Requête :** `Ajoute un indicateur de chargement sur la page du dashboard.` - **Analyse :** Claude lit `app/dashboard/page.tsx` et détecte l’absence de gestion de l’attente des données. - **Proposition :** Création d’un composant `loading.tsx` et enveloppement du bloc dans les limites de `Suspense`. - **Résumé :** L’agent présente un diff ciblé et attend votre approbation. --- ## 6. Raccourcis clavier, commandes et modes de travail ### 6.1. Raccourcis clavier et slash commands pour la gestion du contexte Une navigation efficace dans le terminal repose sur les raccourcis système : | Combinaison | Fonction | | :--- | :--- | | `Enter` | Envoi du message actuel à l’agent | | `Escape` | Annulation immédiate de la génération active ou de l’exécution de l’outil | | `Ctrl+C` | Terminaison propre de la session Claude Code | | `Up` / `Down` | Navigation dans l’historique des requêtes précédentes | | `Shift+Tab` | Basculement entre saisie mono-ligne et multi-ligne | Slash commands intégrées spéciales pour le contrôle de l’environnement : - `/help` — liste des directives disponibles. - `/clear` — réinitialisation de l’historique des messages actuel. - `/compact` — compression de la fenêtre de contexte pour économiser des tokens sans perte de substance. - `/model` — changement rapide du modèle actuel (par exemple, bascule entre Sonnet et Opus). - `/permissions` — vérification des autorisations actives pour l’appel des utilitaires système. ### 6.2. Mode non interactif et conseils pour un travail efficace Pour utiliser Claude Code dans des scripts d’automatisation ou des opérations ponctuelles, appliquez le flag `-p` (`print`) : ```bash # Отримання швидкої довідки про проєкт claude -p "Яку базу даних використовує цей проєкт?" # Передача логів для аналізу через пайплайн cat error.log | claude -p "Знайди першопричину збою та запропонуй рішення" ``` > 💡 **Recommandations pour un fonctionnement stable :** > - Formulez les exigences de manière précise : au lieu de « corrige le formulaire », écrivez « ajoute un debounce au handler de clic du bouton d’envoi du formulaire ». > - Lancez régulièrement `/compact` lorsque la longueur du dialogue dépasse 30–40 étapes. --- ## 7. Pratique : amélioration de l’application ### 7.1. Refactoring et amélioration de la base de code via Claude Dans la deuxième partie pratique, nous étendrons le prototype créé en chargeant Claude d’améliorer la gestion des cas limites et le typage. Envoyez à l’agent l’instruction suivante : ```text Ouvre app/practice/page.tsx. Ajoute une typage TypeScript strict correct, un bloc de gestion des erreurs try/catch affichant le message d'erreur sur fond rouge, ainsi qu'un spinner CSS animé pendant le chargement. ``` ### 7.2. Extension des fonctionnalités : stylisation, gestion des erreurs et animation Le code mis à jour de la page : ```tsx // app/practice/page.tsx - Доопрацьована версія 'use client'; import { useState } from 'react'; export default function PracticePage() { const [result, setResult] = useState(null); const [error, setError] = useState(null); const [loading, setLoading] = useState(false); async function runTest() { setLoading(true); setError(null); try { const response = await fetch('/api/test'); if (!response.ok) throw new Error(`Помилка сервера: код ${response.status}`); const data = await response.json(); setResult(data.message || 'Операцію успішно завершено'); } catch (err: unknown) { setError(err instanceof Error ? err.message : 'Сталася непередбачена помилка'); } finally { setLoading(false); } } return (

Практична вправа 2: Доопрацювання

Тестування обробки винятків та динамічних станів.

{error && (
{error}
)} {result && (
{result}
)}
); } ``` --- ## 8. Modèle de permissions et sécurité ### 8.1. Architecture du modèle de permissions et niveaux de risque des outils Le système de sécurité de Claude Code répartit toutes les opérations accessibles en deux catégories fondamentales selon le niveau de risque potentiel : | Niveau d’accès | Opérations disponibles | Mécanisme d’exécution | | :--- | :--- | :--- | | **Sûr (Read-only)** | `Read`, `Grep`, `Glob`, listage de répertoires | Exécutées automatiquement sans demande à l’utilisateur | | **Potentiellement dangereux** | `Edit`, `Write`, `Bash`, suppression de fichiers, `git push` | Nécessitent une confirmation explicite avant l’exécution | ### 8.2. Mécanisme d’approbation et de rejet des actions potentiellement dangereuses Avant d’exécuter une action risquée, Claude suspend l’exécution et affiche une demande : ```text Claude wants to run: npm install express Allow? (y/n/always) ``` Options de choix disponibles : - `y` (`yes`) — approuver cet appel unique spécifique. - `n` (`no`) — rejeter l’action en indiquant la raison du refus. - `always` (ou `a`) — accorder la permission d’appeler cet outil jusqu’à la fin de la session de travail actuelle. --- ## 9. Fichiers de configuration et gestion des droits ### 9.1. Fichiers de configuration globaux et spécifiques au projet (settings.json) Pour fixer des règles permanentes, créez ou éditez le fichier global `~/.claude/settings.json` : ```json { "permissions": { "allow": [ "Read", "Glob", "Grep", "Edit", "Write", "Bash(npm run *)", "Bash(git status)" ], "deny": [ "Bash(rm -rf *)", "Bash(sudo *)" ] } } ``` ### 9.2. Motifs pour les commandes bash et vérification via /permissions La section `permissions.allow` prend en charge des masques de recherche flexibles (glob patterns) : - `Bash(npm test *)` — permet l’exécution des suites de tests sans confirmations. - `Bash(git commit *)` — permet la validation des changements. - `Bash(rm -rf *)` dans la liste `deny` — garantit un blocage absolu de la suppression massive de données. Pour consulter les règles effectives à tout moment pendant la session, exécutez la commande `/permissions`. --- ## 10. Meilleures pratiques de sécurité et de travail ### 10.1. Stratégie de contrôle d’accès : principe du moindre privilège - **Extension progressive des droits :** Commencez le travail avec une modération manuelle complète. N’ajoutez des commandes à la liste `allow` qu’après avoir confirmé la stabilité du comportement de l’agent. - **Interdiction du wildcard pour bash :** Ne spécifiez jamais `"Bash(*)"` dans les outils autorisés — cela neutralise entièrement le bac à sable protecteur. - **Utilisation active de deny :** Bloquez explicitement les utilitaires destructeurs (`sudo`, `mkfs`, `dd`) pour empêcher toute endommagement accidentel du système. ### 10.2. Protection des secrets d’environnement et audit rigoureux des diffs - **Isolation des tokens :** Claude Code a accès aux variables d’environnement du shell actuel. Ne conservez pas dans la session de travail de clés critiques provenant de bases de données de production. - **Revue du diff avant approbation :** Analysez toujours le diff proposé pour la modification d’un fichier afin de repérer à temps une suppression accidentelle de modules adjacents. --- ## 11. Pratique : version finale de l’application ### 11.1. Version sécurisée de l’application