# Bonnes pratiques Claude Code : la checklist concrète

URL: https://agentvera.dev/fr/blog/claude-code-best-practices/ · Publié: 2026-10-27

Les bonnes pratiques Claude Code qui tiennent en vrai projet : un CLAUDE.md court, planifier, une vérification à lancer, petites tâches, /clear, permissions, hooks.

**En bref:**

- Gardez CLAUDE.md court et limité à ce que Claude ne peut pas apprendre du code : les commandes de test, de typecheck et de lint, les pièges et les décisions qui vivent hors du dépôt.
- Donnez à chaque tâche une vérification que Claude peut lancer : un test, un typecheck, un build. Demandez la commande et sa sortie comme preuve, et imposez les contrôles obligatoires avec un hook Stop.
- Travaillez par petites tâches précises, faites /clear entre deux tâches sans rapport, mettez les règles strictes dans des règles deny et des hooks, et donnez au travail parallèle son propre git worktree.

Les bonnes pratiques Claude Code qui comptent le plus sont simples : gardez `CLAUDE.md` court, planifiez avant les gros changements, donnez à Claude une vérification qu’il peut lancer, travaillez par petites tâches, videz le contexte entre elles, imposez les règles strictes par la configuration plutôt que par du texte, et faites tourner le travail parallèle dans des git worktrees séparés. Ensuite, lisez le diff et committez souvent.

Cette page est une checklist. Chaque point dit quoi faire, montre la commande ou la configuration, et renvoie vers un guide plus détaillé quand il existe. Tout ce qui suit s’appuie sur la documentation officielle de Claude Code telle qu’elle était en octobre 2026 ; les détails qui changent d’une version à l’autre sont signalés.

## La checklist en un coup d’œil

| # | Pratique | En une ligne |
| --- | --- | --- |
| 1 | `CLAUDE.md` court | Commandes, pièges et décisions uniquement |
| 2 | Prompts précis | Symptôme, emplacement, comment prouver que c’est corrigé |
| 3 | Planifier d’abord | Plan mode ou spec écrite pour tout ce qui a plusieurs étapes |
| 4 | Une vérification à lancer | Tests, typecheck, lint ; demandez des preuves |
| 5 | Petites tâches | Un objectif par session, `/clear` entre les tâches |
| 6 | Règles strictes dans la config | Règles deny, hooks, sandbox |
| 7 | Corriger tôt | `Esc`, `/rewind`, et `/clear` après deux corrections ratées |
| 8 | Subagents à bon escient | Travail parallèle et relecture neuve, pas par réflexe |
| 9 | Worktrees pour le parallèle | Un checkout par session |
| 10 | Relire et committer | Lisez le diff, committez petit, poussez vous-même |

## 1. Gardez CLAUDE.md court et factuel

Claude Code charge `CLAUDE.md` dans chaque session, donc chaque ligne prend un peu d’attention sur chaque tâche, qu’elle soit utile ou non. Le fichier fonctionne le mieux quand il ne contient que ce que Claude ne peut pas déduire du code :

- Comment valider le travail dans ce dépôt : les commandes exactes de test, de typecheck et de lint, et comment lancer un seul fichier de test.
- Les endroits où le code induit en erreur : un ancien pattern que le nouveau code ne doit pas copier, un dossier qui semble mort mais ne l’est pas.
- Les décisions qui ne sont pas dans le dépôt : quel helper d’erreur l’équipe a choisi, comment se font les déploiements.
- Tout ce que vous avez dû corriger deux fois.

Un fichier qui passe ce filtre reste petit :

```markdown
# Commands
- Install: pnpm install
- Run one test file: pnpm vitest run path/to/file.test.ts
- Typecheck: pnpm tsc --noEmit

# Conventions
- Use the error helpers in src/lib/errors.ts, never throw raw strings
- src/legacy/ is still live but don't copy its patterns into new code

# Gotchas
- Integration tests need DATABASE_URL set, see .env.example
```

Inutile de décrire votre architecture ou l’organisation des dossiers ; Claude lit le dépôt. `/init` écrit un premier jet, et à partir de là le travail consiste surtout à supprimer. Le guide officiel sur la mémoire recommande de rester sous 200 lignes. `/context` confirme que le fichier a été chargé, et `/doctor` propose des coupes. Les préférences personnelles vont dans `CLAUDE.local.md`, que vous ajoutez à `.gitignore`.

Deux outils voisins gardent le fichier principal léger. Les règles qui ne concernent qu’une zone vont dans `.claude/rules/*.md` avec un filtre `paths:`, pour ne se charger que lorsque Claude y travaille. Les procédures d’équipe, comme une checklist de release, vont dans un skill à `.claude/skills/<name>/SKILL.md` ; Claude n’en voit que le nom et la description jusqu’à ce qu’il ait besoin du texte complet. Le guide complet est dans [Bonnes pratiques CLAUDE.md et AGENTS.md](/fr/blog/claude-md-agents-md/ "CLAUDE.md et AGENTS.md").

Si Claude ignore sans cesse une ligne, écrire IMPORTANT en majuscules aide rarement. Soit le fichier est trop long, soit la ligne est une règle sans exception, qui a sa place dans un hook (voir le point 6).

## 2. Écrivez des prompts qui disent où, quoi et comment vérifier

Un prompt vague oblige Claude à deviner. Un prompt précis nomme le symptôme, l’endroit où chercher et la façon de prouver la correction :

```text
Des utilisateurs signalent que la connexion échoue après l’expiration de la session. Regarde le rafraîchissement du token dans src/auth/, écris un test qui échoue et reproduit le problème, puis corrige-le.
```

Désignez les fichiers avec `@`, collez des captures d’écran et envoyez les logs par un pipe au lieu de les décrire. Quand vous ne savez pas encore ce que vous voulez, laissez Claude vous interviewer d’abord :

```text
Je veux ajouter du rate limiting à l’API publique mais je n’y ai pas encore bien réfléchi. Pose-moi des questions jusqu’à pouvoir écrire la spec, puis écris-la dans SPEC.md.
```

Ouvrez ensuite une nouvelle session qui construit à partir de `SPEC.md`. Le développement démarre avec un contexte propre et une définition écrite de « terminé », et la spec sert ensuite de référence au relecteur. D’autres patterns de prompts sont dans [Écrire des prompts pour agents de code IA](/fr/blog/prompts-for-ai-coding-agents/ "Prompts pour agents de code IA").

Deux habitudes à abandonner : des formules comme « think hard » n’augmentent pas l’effort de raisonnement (utilisez `/effort high` ou mettez `ultrathink` dans un seul prompt), et l’insistance en MAJUSCULES pousse surtout Claude à appliquer une règle à l’excès.

## 3. Planifiez avant les changements en plusieurs étapes

Pour tout ce qui touche plusieurs fichiers, séparez la réflexion de l’édition. Le plan mode permet à Claude de lire le code et de proposer un plan sans rien modifier. Vous pouvez y passer avec `Shift+Tab` ou démarrer une session directement dedans :

```bash
claude --permission-mode plan
```

Lisez le plan, corrigez-le, et seulement ensuite laissez Claude construire. Une hypothèse erronée repérée dans le plan coûte un message ; repérée dans le diff, elle coûte une réécriture. Les petites corrections évidentes n’ont pas besoin de plan. Les détails, y compris comment modifier un plan avant de l’approuver, sont dans [Plan mode de Claude Code](/fr/blog/claude-code-plan-mode/ "Plan mode de Claude Code").

## 4. Donnez à Claude une vérification qu’il peut lancer

C’est l’habitude qui rapporte le plus. Claude ne peut savoir qu’il a terminé que s’il a quelque chose à lancer : une suite de tests, un typecheck, une commande de lint, le code de sortie d’un build, un script qui compare une sortie à une fixture. Si votre dépôt en a une, la ligne la plus utile de `CLAUDE.md` est la commande qui la lance.

C’est vous qui choisissez avec quelle rigueur la vérification s’applique :

- **Dans le prompt.** « Lance les tests d’auth après, et continue jusqu’à ce qu’ils passent. » Fonctionne pour n’importe quelle tâche, sans configuration.
- **Comme objectif.** `/goal all tests in tests/auth pass and lint is clean` fixe une condition qu’un modèle séparé vérifie après chaque tour. Surtout utile pour les longues exécutions.
- **Comme hook Stop.** Claude Code lance votre script quand Claude essaie de terminer son tour et le renvoie au travail si le script sort avec le code 2.
- **Avec un relecteur indépendant.** `/code-review` relit le diff dans un subagent neuf qui n’a jamais vu votre conversation.

La version hook Stop de « le typecheck doit passer » se place dans `.claude/settings.json` :

```json
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "pnpm tsc --noEmit 1>&2 || exit 2" }
        ]
      }
    ]
  }
}
```

Stderr est renvoyé à Claude comme raison pour laquelle il ne peut pas encore s’arrêter, d’où la redirection de la sortie du compilateur. Si le hook bloque huit arrêts d’affilée sans appel d’outil entre eux, Claude Code termine quand même le tour ; `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` relève cette limite.

Quel que soit votre choix, demandez des preuves : la commande que Claude a lancée et sa sortie. « Tous les tests passent », seul, ne vous dit pas grand-chose. Après une modification d’interface, `/verify` fait construire et lancer l’application par Claude, qui regarde le résultat.

## 5. Gardez des tâches petites et un contexte propre

Une session, un objectif. Une conversation qui a accumulé trois tâches sans rapport les renvoie toutes à chaque tour de la quatrième, ce qui coûte plus cher et rend les réponses moins ciblées.

- `/clear` entre deux tâches sans rapport. `/clear oauth-migration` nomme aussi la session que vous quittez pour pouvoir y revenir.
- `/compact keep the API changes and the test commands` raccourcit une longue session en gardant l’essentiel. Sur une longue session, `/compact` est lui-même une grosse requête.
- `/usage` montre où part votre consommation, y compris par subagent, skill et serveur MCP sur les abonnements.

En octobre 2026, la plupart des modèles actuels ont une fenêtre d’un million de tokens et la compaction se déclenche toute seule, donc manquer de contexte est rare. Vider le contexte est une question de concentration et de coût, pas de survie. Le cache de prompt dure environ une heure sur un abonnement et environ cinq minutes avec une clé API, donc une session restée inactive pendant le déjeuner coûte plus cher à reprendre qu’une nouvelle. Le fonctionnement est expliqué dans [Fenêtre de contexte de Claude Code](/fr/blog/claude-code-context-window/ "Fenêtre de contexte de Claude Code").

## 6. Mettez les règles intransigeantes dans la configuration

`CLAUDE.md` contient des consignes, et Claude a le droit de décider qu’une consigne ne s’applique pas. Pour les quelques règles où « presque toujours » ne suffit pas, utilisez des contrôles que Claude Code applique lui-même.

**Règles de permission.** Autorisez ce qui est sûr et fréquent, demandez pour ce qui est risqué, refusez ce qui ne doit jamais arriver :

```json
{
  "permissions": {
    "allow": ["Bash(pnpm tsc --noEmit)"],
    "ask": ["Bash(git push *)"],
    "deny": ["Read(./.env)", "Read(./.env.local)", "Read(./secrets/**)"]
  }
}
```

Les règles deny s’appliquent dans tous les modes de permission, et la règle `Read` bloque aussi les commandes shell courantes de lecture de fichier comme `cat .env`. Elle ne bloque pas un script qui ouvre le fichier ; pour un travail sensible côté sécurité, activez donc aussi le sandbox avec `/sandbox`, qui confine les commandes shell au niveau du système d’exploitation sur macOS, Linux et WSL2.

**Hooks.** Un formateur qui tourne après chaque modification ne dépend plus de la mémoire de Claude :

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "npx prettier --write --ignore-unknown \"$(jq -r '.tool_input.file_path')\"" }
        ]
      }
    ]
  }
}
```

Réservez les hooks aux règles sans aucune exception ; « préférer les exports nommés » reste dans `CLAUDE.md`. Le [guide des hooks Claude Code](/fr/blog/claude-code-hooks-guide/ "Hooks Claude Code : guide pratique") couvre chaque événement et chaque code de sortie.

**Modes de permission.** En octobre 2026, les nouvelles sessions interactives démarrent en mode auto, où un classifieur examine les actions risquées au lieu de vous demander pour chacune. C’est efficace, mais c’est un jugement : vos règles « jamais » ont toujours leur place dans les règles deny et les hooks. Si vous préférez approuver chaque étape, `Shift+Tab` passe à Manual, ou démarrez avec `claude --permission-mode manual`. Quand Manual demande trop souvent, `/fewer-permission-prompts` ajoute vos commandes courantes en lecture seule à une liste d’autorisation. Pourquoi ignorer complètement les permissions est un mauvais calcul est expliqué dans [Claude Code et --dangerously-skip-permissions](/fr/blog/claude-code-skip-permissions/ "Claude Code skip permissions").

## 7. Corrigez tôt, repartez à zéro au lieu d’argumenter

Surveillez la première minute d’une tâche. Les commandes sont peu nombreuses :

- `Esc` arrête Claude en pleine action et conserve tout ce qui a été fait, pour que vous puissiez le réorienter.
- `/rewind`, ou `Esc` deux fois sur un prompt vide, ramène le code, la conversation ou les deux à un prompt antérieur.
- `/clear` repart de zéro. Après deux corrections ratées, une troisième ajoute surtout une tentative ratée de plus que Claude devra relire. Videz le contexte et écrivez un meilleur prompt qui intègre ce que vous avez appris.

Les checkpoints couvrent les fichiers que Claude a modifiés avec ses propres outils d’édition ; un fichier touché uniquement par une commande Bash n’est pas restauré. Ils fonctionnent avec git, pas à sa place. Pour un travail qui s’étale sur plusieurs jours, `/rename oauth-migration` nomme la session et `claude --resume oauth-migration` la reprend plus tard.

## 8. Utilisez les subagents à bon escient

Claude Code délègue déjà de lui-même : les recherches larges partent vers l’agent intégré Explore, et les subagents tournent en arrière-plan par défaut. Chaque subagent envoie ses propres requêtes, donc il coûte des tokens, et il ne rend pas une réponse plus intelligente. Utilisez-les pour :

- Des morceaux de travail indépendants qui peuvent tourner en même temps.
- Garder une longue sortie, comme une exécution complète des tests, hors de la conversation principale.
- Un relecteur qui n’a pas vu comment le code a été écrit.
- Une tâche qui doit avoir moins d’outils que la session principale.

Un relecteur en lecture seule tient dans un court fichier à `.claude/agents/reviewer.md` :

```markdown
---
name: reviewer
description: Reviews changed files against the spec they were built from. Use after implementing a feature, before opening the PR.
tools: Read, Grep, Glob
---
You're reviewing code you didn't write. Compare the changed files against the spec you're given,
check that every requirement is implemented and the listed edge cases have tests,
and report only the gaps that affect correctness. Skip style.
```

Pour les tâches simples comme rassembler les fichiers qui importent un module, ajoutez `model: haiku` à la définition. Puis demandez :

```text
Demande au relecteur de comparer le rate limiter avec SPEC.md.
```

D’autres patterns sont dans [Subagents Claude Code](/fr/blog/claude-code-subagents/ "Subagents Claude Code").

## 9. Faites tourner le travail parallèle dans des worktrees

Deux sessions qui modifient le même checkout s’écrasent mutuellement. Donnez à chacune son propre [git worktree](/fr/glossary/git-worktree/ "Qu’est-ce qu’un git worktree") :

```bash
claude -w feature-auth
```

Un worktree est un checkout neuf : les fichiers ignorés par git comme `.env` n’y sont pas et les dépendances ne sont pas installées. Listez les petits fichiers ignorés dans `.worktreeinclude` à la racine du dépôt, et Claude Code les copie dans chaque worktree qu’il crée :

```text
.env
.env.local
config/dev-credentials.json
```

N’y mettez pas `node_modules` : le dossier est copié, pas lié. Gardez plutôt la commande d’installation dans `CLAUDE.md`, ou utilisez le réglage `worktree.symlinkDirectories`. Quand vous quittez sans modification une session de worktree sans nom, Claude Code le supprime ; sinon, il vous demande. Pour un gros changement mécanique, `/batch` découpe le travail en unités, lance chacune dans son propre worktree et ouvre une PR par unité. Plus de détails dans [Git worktrees pour agents IA en parallèle](/fr/blog/git-worktree-parallel-agents/ "Git worktrees pour agents en parallèle").

## 10. Lisez le diff, committez petit, poussez vous-même

L’agent écrit ; vous approuvez. Avant d’accepter un tour, lisez `git diff`, pas le résumé. Committez après chaque étape qui fonctionne, pour qu’une mauvaise étape suivante soit à un `git reset` près. Gardez les push, les merges et les déploiements derrière une personne : la règle `ask` sur `git push *` ci-dessus fait exactement cela. Une deuxième session qui relit `@src/middleware/rateLimiter.ts` sans avoir assisté à son écriture est le relecteur indépendant le moins cher que vous ayez.

## Bonus : avant de laisser Claude sans surveillance

La documentation officielle liste cinq questions pour toute exécution que personne ne surveille. Elles font un bon contrôle final :

1. Sait-il à quoi ressemble « terminé » ? Un objectif, un fichier de spec, un test qui échoue.
2. Peut-il vérifier son propre travail ? Des tests, un hook Stop, une étape de relecture.
3. À quoi peut-il toucher ? Règles de permission, `dontAsk`, le sandbox, un worktree.
4. Qu’est-ce qui l’arrête ? `--max-turns`, `--max-budget-usd`, une limite de dépenses.
5. Où va le résultat, et qui valide ? Une PR et une personne qui approuve le merge.

Pour les exécutions scriptées et en CI, voir [Mode headless de Claude Code](/fr/blog/claude-code-headless-mode/ "Mode headless de Claude Code").

## Avec AgentVera

L’essentiel de cette checklist relève de la discipline ; [AgentVera](/fr/agents/claude-code/ "Claude Code dans AgentVera") facilite quelques points quand vous faites tourner plus d’une session. Chaque volet de l’[espace de travail](/fr/features/workspace/ "Espace de travail AgentVera") est le vrai terminal Claude Code, donc `Shift+Tab`, le plan mode, les hooks et votre `CLAUDE.md` fonctionnent comme d’habitude. Vous pouvez créer un worktree par agent depuis le panneau Git, et la [coordination des agents](/fr/features/agent-coordination/ "Coordination des agents") vous avertit quand deux agents modifient le même fichier.

Pour le point 4, la [revue de code automatique](/fr/features/code-review/ "Revue de code automatique") fait relire les changements de chaque tour par le modèle Claude de votre choix, liste les constats avec leur gravité et leur fichier:ligne, et peut les renvoyer à l’agent. [Verify](/fr/features/verify/ "AgentVera Verify") (Pro et Team) transforme votre message en critères d’acceptation et les fait contrôler, preuves à l’appui, par un vérificateur distinct à la fin du tour. Pour le point 7, les [checkpoints](/fr/features/checkpoints-and-replay/ "Checkpoints et replay de session") prennent un instantané de chaque tour dans une ref git cachée et gardent les 60 derniers par agent. La grille, les worktrees, la revue de code et les checkpoints sont inclus dans l’offre gratuite ; [téléchargez AgentVera](/fr/download/ "Télécharger AgentVera") pour les essayer.

## En résumé

Si vous n’adoptez que trois points, prenez ceux-ci : un `CLAUDE.md` court avec vos vraies commandes, une vérification que Claude lance avant de dire « terminé », et `/clear` entre les tâches. Ajoutez des règles deny et des hooks pour ce qui ne doit jamais arriver, des worktrees dès que vous faites tourner des sessions en parallèle, et gardez pour vous la relecture finale et le push.

## Questions fréquentes

**Quelle est l’habitude la plus utile avec Claude Code ?** Donner à Claude un moyen de vérifier son propre travail. Mettez les commandes exactes de test, de typecheck et de lint dans CLAUDE.md, nommez la vérification dans votre prompt et demandez la commande et sa sortie quand Claude dit avoir terminé. Sans vérification, « terminé » veut seulement dire que Claude s’est arrêté.

**Quelle longueur pour CLAUDE.md ?** Court. Claude Code le charge dans chaque session, donc chaque ligne coûte un peu d’attention sur chaque tâche. Le guide officiel sur la mémoire recommande de rester sous 200 lignes. Lancez /init pour un premier jet, puis supprimez surtout : gardez les commandes, les pièges et les décisions qui ne sont pas visibles dans le code.

**Faut-il utiliser /clear ou /compact ?** Utilisez /clear entre deux tâches sans rapport : cela ne coûte rien et la tâche suivante cesse de payer pour l’ancien historique. Utilisez /compact avec une consigne, par exemple « /compact keep the API changes and the test commands », quand vous voulez poursuivre la même tâche avec un historique plus court.

**Est-il sûr de laisser Claude Code lancer des commandes sans demander ?** En octobre 2026, les sessions interactives démarrent en mode auto, où un classifieur examine les actions risquées. C’est un jugement, pas une règle stricte : tout ce qui ne doit jamais arriver a sa place dans les règles deny, les hooks ou le sandbox. Shift+Tab passe en mode Manual si vous voulez approuver chaque étape.

**Comment lancer plusieurs sessions Claude Code en même temps sans conflit ?** Donnez à chaque session son propre git worktree, par exemple avec claude -w feature-auth. Chaque worktree est un checkout séparé sur sa propre branche, donc les modifications ne peuvent pas se télescoper. Listez les fichiers ignorés par git comme .env dans .worktreeinclude pour qu’ils soient copiés dans les nouveaux worktrees.

---

**À propos d’AgentVera.** AgentVera est une app de bureau pour macOS, Windows et Linux, développée par Solviera Teknoloji. Elle exécute 18 agents de code IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) côte à côte, par projet, dans de vrais terminaux avec les installations et connexions CLI de l’utilisateur. L’offre gratuite inclut des agents illimités. Télécharger: https://agentvera.dev/fr/download/ · Tarifs: https://agentvera.dev/fr/pricing/