Architecture, modèles, settings et prompt engineering

Pourquoi ce module

C'est le Jour 1 du tronc commun « Claude Code Expert ». Avant d'industrialiser quoi que ce soit (hooks, MCP, agents), il faut comprendre ce qu'est réellement Claude Code : un harness agentique qui orchestre un modèle, des outils et une cascade de configuration — pas un simple chat dans le terminal.

La plupart des utilisateurs sous-exploitent l'outil parce qu'ils ignorent trois leviers : la cascade settings.json, les modes de permission, et le réglage modèle × effort. Ce module pose ces fondations, puis enchaîne sur le prompt engineering Anthropic et le prompt caching (jusqu'à 90 % d'économie sur l'input).

Prérequis — cette formation se pratique dans un terminal

🖥️ Claude Code est avant tout un outil en ligne de commande (CLI). L'ensemble du cursus (settings.json, hooks, MCP, skills, sous-agents, mode headless) suppose un terminal. Une app Desktop de Claude Code (Mac/Windows, à ne pas confondre avec le chat Claude.ai) et des extensions IDE existent et font tourner le même moteur, mais exposent moins de leviers. Vous devez être à l'aise pour ouvrir un terminal et lancer claude dans un dossier de projet — si ce n'est pas (encore) le cas, déroulez le pré-travail J0 — Préparation de l'environnement (terminal, WSL2, installation, claude doctor) avant cette session.

💡 Même moteur partout. CLI, app Desktop, VS Code/JetBrains, web, mobile (iOS) et Slack partagent le même engine Claude Code ; sur les surfaces locales, settings.json, la mémoire projet et les serveurs MCP sont partagés. On peut donc mixer : apprendre et automatiser en CLI, ouvrir l'IDE pour une revue visuelle — sans reconfigurer.

CLI vs extension IDE vs Desktop : avantages et inconvénients

À retenir : on apprend et on industrialise en CLI — la seule surface qui donne accès à tout (scripting, Agent SDK, hooks, exécution distante). Au quotidien, l'extension IDE (VS Code en tête) est souvent le meilleur compromis : la puissance du CLI plus les diffs visuels, les checkpoints (/rewind) et la revue de plan, sans quitter l'éditeur — on rebascule au terminal pour le scripting et le MCP avancé. Le Desktop reste un bon complément de revue et la porte d'entrée des non-tech (voir M13 — Cowork).

Brancher, forker, déléguer : /branch, /fork et /subtask (modèle mental git)

Claude Code expose trois outils de parallélisation de session. Ils partent tous du même point — une copie de la conversation courante — et se distinguent par qui continue où :

• /branch [nom] : copie la conversation au point courant et vous bascule dedans. L'originale est préservée et reste joignable via /resume. Les deux conversations sont indépendantes à partir de là. Analogue à git checkout -b <nom> : explorer une autre direction, garder l'ancienne en réserve.

  • Usage : « je teste une approche parallèle, l'autre session me sert de sauvegarde »

• /fork [prompt] : copie la conversation dans une session en arrière-plan — sa propre ligne dans l'Agent view (cf. J5) — et vous restez ici. Avec un prompt, la copie s'y met immédiatement ; sans prompt, elle attend sa première consigne dans l'Agent view. Analogue à git worktree add : un deuxième plan de travail qui vit sa vie.

  • Usage : « que cette copie parte auditer/migrer pendant que je continue »

• /subtask <directive> : confie une tâche latérale à un sous-agent qui hérite du contexte et rapporte dans cette conversation. Analogue à lancer une CI et attendre son verdict : le résultat revient chez vous, pas dans une session à part.

  • Usage : « donne-moi un avis sur ce code sans que je change de fenêtre »

Modèle décisionnel — la question à se poser est « où veux-je être quand ça repart ? » :

⚠️ Piège de version : /fork a changé de sens. Depuis la v2.1.212, /fork crée une session en arrière-plan. De la v2.1.161 à la v2.1.211, la même commande lançait un sous-agent forké — ce qui s'appelle désormais /subtask. Avant la v2.1.161, /fork était un simple alias de /branch. Beaucoup de tutoriels en ligne (et de notes de formation) décrivent encore l'ancien comportement : vérifiez votre version avec claude --version avant de suivre une procédure. Cas particulier : si l'Agent view est désactivée, /fork conserve le comportement sous-agent.

Objectifs pédagogiques

À l'issue de ce module, vous serez capable de :

1. Cartographier l'écosystème Anthropic (Claude.ai, Claude Code CLI, API, Workbench) et choisir le bon outil par cas d'usage
2. Décrire l'architecture interne d'une session Claude Code (harness, system prompt, runtime, tools) et ses points de contrôle
3. Démarrer par le Q&A de base de code et exploiter l'historique Git comme source de contexte
4. Construire une boucle de feedback : donner à Claude un moyen de vérifier son propre travail
5. Maîtriser les 5 modes de permission (manual, plan, acceptEdits, bypassPermissions, auto) et savoir quand les employer
6. Régler settings.json : cascade des scopes, permissions allow/deny/ask, env, model, effortLevel
7. Choisir modèle × effort : Opus 5 / Sonnet 5 / Haiku 4.5 et les niveaux low→xhigh/max
8. Appliquer le prompt engineering Anthropic et le prompt caching mesurable
9. Structurer la mémoire projet : CLAUDE.md, .claude/rules/ à portée de chemin, auto memory
10. Ablater sa mémoire projet : distinguer le correctif périmé du fait non devinable, et de la règle d'enforcement

Plan détaillé

1. Écosystème Anthropic 2026 : qui fait quoi
2. Architecture interne d'une session Claude Code
3. Par où commencer : le Q&A de base de code
4. La boucle de feedback : donner à Claude un oracle
5. Modes de permission : du manual au auto
6. settings.json : cascade des scopes et clés principales
7. Permissions allow / deny / ask
8. Modèles 2026 et niveaux d'effort
9. Prompt engineering Anthropic (XML, few-shot, CoT, structured output)
10. Prompt caching : cache_control, éphémère 5 min / 1 h
11. Mémoire projet : CLAUDE.md, .claude/rules/, auto memory
12. Aide-mémoire : raccourcis et modes de saisie
13. Atelier : audit + refonte de votre configuration

Écosystème Anthropic 2026 : qui fait quoi

Claude Code est la surface dev-first : c'est là que ce cursus se déroule.

Architecture interne d'une session Claude Code

Claude Code n'envoie pas votre message brut au modèle. Un harness assemble un system prompt interne, expose un runtime d'outils (Read, Edit, Bash, Grep, etc.), et applique vos settings.json + hooks à chaque tour. C'est aussi le harness — pas le modèle — qui décide quand la tâche est terminée : il pilote la boucle « appeler le modèle → exécuter l'outil → réinjecter le résultat » et choisit le moment de s'arrêter. C'est ce critère qui distingue un vrai harness d'un simple wrapper d'appels.

📌 D'où vient le terme. « Agent harness » a été formalisé en février 2026 par Mitchell Hashimoto, qui a nommé une pratique que les développeurs construisaient déjà sans vocabulaire commun ; Anthropic l'a popularisé en parallèle (« Claude Code serves as the agentic harness around Claude »). L'idée tient en une phrase : le LLM est la plus petite partie de votre système d'agent — tout le reste, c'est le harness.

🔍 Tracer une session. Lancez claude --debug pour voir, pas à pas, les appels d'outils, le contexte chargé et les décisions de permission. C'est l'outil n°1 pour comprendre pourquoi l'agent a fait quelque chose.

🧪 Repartir d'une session vierge — --safe-mode (v2.1.169). Le flag claude --safe-mode démarre sans aucune personnalisation : ni CLAUDE.md, ni plugins, skills, hooks ou serveurs MCP. Indispensable pour isoler une régression (« est-ce mon hook ou Claude Code ? »), reproduire un bug proprement, ou auditer un repo inconnu sans exécuter sa config. Le pendant « bac à sable » du --debug qui, lui, ne fait qu'observer.

Par où commencer : le Q&A de base de code

Face à une invite vide, la question de tout débutant est « qu'est-ce que je tape ? ». La réponse n'est pas « fais-moi une feature » — c'est poser des questions sur le code.

Trois raisons de commencer par là, et pas par l'édition :

• Risque nul. Poser des questions n'écrit rien. On apprend l'outil sans exposer le repo — a fortiori en mode plan, où les écritures sont bloquées (voir section suivante).
• C'est ce qui construit le modèle mental. En quelques questions, on découvre la frontière réelle : ce que Claude trouve seul, ce qu'il faut lui pointer, ce qui passe en un coup et ce qui demande d'itérer. Cette frontière ne s'explique pas, elle se constate.
• La valeur est immédiate, même sans écrire une ligne : comprendre un module inconnu, retrouver où vit une règle métier, reconstituer l'intention derrière un bout de code.

Claude ne fait pas qu'un grep. Sur « comment on instancie PaymentProvider ? », il enchaîne recherche, lecture des définitions et des appels, puis synthétise les usages réels — là où un Ctrl+F ne rend que des occurrences.

Les questions qui rendent le plus, par ordre de rentabilité :

🔍 L'historique Git est du contexte gratuit — et sous-exploité. Les deux dernières lignes du tableau sont les plus négligées. Un git blame remonte qui a écrit une ligne ; Claude remonte pourquoi : il lit les messages de commit, suit les numéros d'issue, et reconstitue la décision. Sur du code legacy dont l'auteur est parti, c'est souvent la seule archéologie disponible. Aucune configuration nécessaire — le repo est déjà là, il suffit de dire « regarde l'historique git ».

Trois leviers 2026 qui renforcent cette phase :

• L'agent Explore (sous-agent intégré) explore dans un contexte isolé et ne renvoie que sa conclusion : la session principale ne se remplit pas des dizaines de fichiers lus au passage. À privilégier dès que la question demande de ratisser large (cf. J4).
• Le code intelligence (LSP) — activé en installant un code intelligence plugin pour votre langage — donne la navigation symbolique et les erreurs de type réelles, au lieu d'inférer depuis le texte.
• /context visualise ce qui occupe la fenêtre : les fichiers de mémoire chargés, le coût des outils MCP, la marge restante.

🔒 « Est-ce que mon code part chez Anthropic ? » — la réponse honnête. C'est la question du RSSI, et la formulation naïve (« tout reste en local, rien n'est jamais entraîné ») est fausse en 2026. Ce qui est exact :

• Il n'y a pas d'index distant de votre dépôt. Claude Code explore à la demande, fichier par fichier, via ses outils — aucune base vectorielle préconstruite, aucune étape d'indexation préalable. Vérifiez-le vous-même : claude --debug montre chaque lecture.
• Ce qui part sur le réseau, ce sont les prompts et les contenus que les outils remontent dans le contexte — donc, de fait, les fichiers lus. Chiffré en transit (TLS 1.2+).
• Entraînement : sur les offres commerciales (Team, Enterprise, API, plateformes tierces), Anthropic n'entraîne pas ses modèles sur votre code ou vos prompts — sauf adhésion explicite au Development Partner Program. Sur les offres grand public (Free, Pro, Max), les données sont utilisées pour l'entraînement si le réglage correspondant est activé sur le compte, Claude Code inclus. Un développeur qui travaille sur du code client avec son abonnement Pro perso doit le savoir.
• Rétention : 30 jours en commercial standard ; 5 ans côté grand public si le partage est activé, 30 jours sinon. Le Zero Data Retention existe mais n'est ni automatique ni inclus dans le plan Enterprise standard — il s'active par organisation après éligibilité.
• En local : les transcriptions de session sont stockées en clair sous ~/.claude/projects/ pendant 30 jours par défaut (réglable via cleanupPeriodDays). À intégrer dans votre analyse de risque poste de travail.
• Exception majeure : Claude Code on the web clone le dépôt dans une VM gérée par Anthropic. Là, « le code ne quitte pas ma machine » ne tient plus.

Traitement complet côté conformité en M1 ; ici, retenez la nuance et la manière de la vérifier.

La boucle de feedback : donner à Claude un oracle

C'est le levier de qualité le plus rentable du harness, et le plus souvent oublié.

Un agent sans moyen de mesurer son résultat s'arrête au premier « ça a l'air correct ». Donnez-lui un oracle — quelque chose qui répond oui/non ou voici l'écart — et il itère seul jusqu'à converger. C'est la différence entre un one-shot approximatif et un résultat quasi juste en deux ou trois tours.

Trois familles d'oracles, selon le domaine :

Le pattern complet tient en trois ingrédients : une cible (maquette, critère d'acceptation, test rouge), un moyen de mesurer l'écart, et l'autorisation de boucler. Retirez-en un, la boucle ne se ferme pas.

💡 Cas d'école : l'UI depuis une maquette. Glissez l'image dans la session, demandez l'implémentation, puis donnez l'URL du serveur de dev et l'accès au navigateur. Le premier jet est correct ; après deux ou trois passes de comparaison capture ↔ maquette, il devient difficile à distinguer. Sans l'accès au rendu, vous restez bloqué au premier jet et vous corrigez à la main.

⚠️ L'anti-pattern miroir. Demander une feature de 3 000 lignes en une fois, sans test ni rendu vérifiable : parfois ça tombe juste, souvent on obtient quelque chose de propre qui ne fait pas ce qu'on voulait. Le réflexe n'est pas « mieux prompter » mais découper et instrumenter : plan d'abord (M8), oracle ensuite, boucle enfin. La commande /goal (cf. J5) formalise le dernier étage : travailler jusqu'à ce qu'une condition soit remplie.

Modes de permission : du manual au auto

Claude Code expose cinq modes (source : docs officielles settings). On bascule avec /permissions <mode> ou le flag --permission-mode.

⚠️ bypassPermissions (anciennement --dangerously-skip-permissions) ne s'utilise que dans un environnement jetable : aucune protection ne s'applique.

✏️ Renommage (v2.1.200). Le mode historiquement appelé default s'affiche désormais « Manual » partout (CLI, --help, VS Code, JetBrains). --permission-mode manual et "defaultMode": "manual" sont acceptés, et l'ancienne valeur default reste valide — pas de migration à faire dans vos settings.json.

settings.json : cascade des scopes et clés principales

La configuration est hiérarchique et rechargée à chaud. Priorité (du plus fort au plus faible) :

1. Managed (déployé par l'IT, non surchargeable)
2. Command line (flags de session)
3. Local — .claude/settings.local.json (perso, gitignoré)
4. Project — .claude/settings.json (partagé en équipe, versionné)
5. User — ~/.claude/settings.json (vos défauts)

🏢 Gouvernance de flotte (managed settings). Le scope Managed sert à l'IT à imposer des garde-fous non contournables. Depuis v2.1.163, il accepte requiredMinimumVersion et requiredMaximumVersion : on épingle la fourchette de versions de Claude Code autorisée sur le parc (bloquer une version trop ancienne non patchée, ou geler avant une montée de version validée). Couplé aux permissions.deny managés, c'est le socle d'un déploiement entreprise maîtrisé.

Principales clés (non exhaustif) :

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-4-6",        // modèle par défaut
  "effortLevel": "xhigh",              // low | medium | high | xhigh
  "permissions": { /* voir ci-dessous */ },
  "env": { "NODE_ENV": "development" },  // variables injectées dans les sessions
  "hooks": { /* cf. J2 */ },
  "statusLine": { "type": "command", "command": "~/.claude/statusline.sh" },
  "autoMemoryEnabled": true,
  "editorMode": "vim"
}

Quelques variables d'env utiles dans env : CLAUDE_CODE_ENABLE_TELEMETRY, CLAUDE_CODE_DISABLE_AUTO_MEMORY, CLAUDE_CODE_DISABLE_THINKING, CLAUDE_CODE_USE_POWERSHELL_TOOL, DISABLE_AUTOUPDATER.

🔧 Régler un setting depuis le prompt (v2.1.181 et v2.1.183). Le /config key=value (depuis v2.1.181) permet de changer un setting dynamiquement sans quitter la session ni éditer settings.json — pratique pour tester un réglage avant de le persister. Exemple : /config effortLevel=high ou /config model=claude-opus-4-8. Depuis v2.1.183, le menu /config --help liste tous les réglages disponibles et ouvre un TUI interactif : les touches Enter ou Espace modifient la valeur directement, Échap sauve et ferme — une petite interface éphémère, sans fichier. Pratique pour un one-shot ou un debug rapide avant de figer dans settings.json.

Permissions allow / deny / ask

Trois listes de patterns d'outils (wildcards * et globs /**). deny l'emporte toujours sur allow.

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Read(src/**)"
    ],
    "deny": [
      "Bash(rm *)",
      "Bash(git push --force*)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ],
    "ask": [
      "Write(./src/**)"
    ]
  }
}

• allow : approuvé automatiquement
• deny : rejeté sans prompt (vos garde-fous durs : rm, git push --force, secrets)
• ask : déclenche une confirmation

🎯 Matching fin sur les paramètres (v2.1.178). Depuis v2.1.178, la syntaxe Tool(param:value) permet de matcher non pas le nom de l'outil, mais un paramètre spécifique et sa valeur : granularité bien plus fine. Exemple : Bash(command:npm run test *) valide tout appel Bash avec command égal à npm run test *, mais refuse npm install. Autre cas : WebFetch(url:*.anthropic.com/*) ré-autorise les fetches des domaines Anthropic en deny-all. En pratique :

{
  "permissions": {
    "deny": ["*"],  // tout refusé par défaut
    "allow": [
      "Bash(command:npm run lint)",
      "Bash(command:npm run test *)",
      "Read(file_path:src/**)",
      "WebFetch(url:https://docs.anthropic.com/*)"
    ]
  }
}

Cette approche rétrécit l'intention et bloque les oublis dangereux : approuver Bash en général risque un mauvais invocation (ex. rm), mais Bash(command:npm *) sécurise les seules commandes npm.

🔒 Glob sur le nom d'outil (v2.1.166). Les patterns glob fonctionnent désormais aussi sur le nom de l'outil, pas seulement sur ses arguments : "*" en deny interdit tous les outils. Pattern « deny-all puis allow-list » pour un repo très sensible — on bloque tout, on ré-autorise explicitement le strict nécessaire :

"permissions": {
  "deny": ["*"],                       // tout est refusé par défaut
  "allow": ["Read(src/**)", "Bash(npm run test *)"]  // sauf ceci
}

🔴 Le piège du glob à segment unique — corrigé en v2.1.214, à connaître absolument. Une règle allow comme Edit(src/**) n'était pas interprétée comme vous le pensiez : elle auto-approuvait les écritures dans n'importe quel dossier src/ de l'arbre, à n'importe quelle profondeur — y compris node_modules/<paquet>/src/, vendor/<lib>/src/, ou le src/ d'un sous-module. Autrement dit, une allow-list que vous croyiez serrée ouvrait beaucoup plus large que prévu.

Depuis la v2.1.214, un pattern à segment unique comme dir/** ne matche plus que <cwd>/dir. Pour retrouver volontairement le match à toute profondeur, écrivez explicitement **/dir/**.

Pattern	Avant v2.1.214	Depuis v2.1.214
Edit(src/**)	tout src/ de l'arbre ⚠️	<cwd>/src uniquement ✅
Edit(**/src/**)	tout src/ de l'arbre	tout src/ de l'arbre (explicite)

Deux exceptions à retenir. Les règles deny et ask conservent le match à toute profondeur — c'est délibéré : une interdiction doit rester large, sinon la correction créerait un trou de sécurité. En revanche les conditions if: des hooks (cf. J2) suivent la nouvelle règle stricte. Si vous aviez des règles allow écrites avant juillet 2026, relisez-les : certaines ne couvrent plus ce qu'elles couvraient, et vos permissions vont redemander confirmation là où elles passaient toutes seules. C'est le bon comportement — mais la surprise est réelle.

Modèles 2026 et niveaux d'effort

🆕 Claude Opus 5 (24 juillet 2026, ID claude-opus-5). Nouveau défaut Opus de Claude Code, 1M de contexte, et — le point qui compte pour un budget — le même tarif qu'Opus 4.8 : 5 $ / 25 $ par Mtok. Une montée de génération sans surcoût, ce qui est rare : le réflexe « je reste sur l'ancien modèle pour économiser » n'a ici aucun fondement. Anthropic annonce plus du double de la performance d'Opus 4.8 sur Frontier-Bench v0.1 à coût par tâche inférieur, et un score à 0,5 % de Fable 5 sur CursorBench 3.2 pour moitié prix — Fable 5 restant à 10 $ / 50 $ (cf. M4 pour l'arbitrage complet). Le sélecteur /model affiche la ligne fusionnée « Opus (1M context) ». (Source : annonce officielle.)

⚠️ Le défaut n'est pas le même partout. Depuis la v2.1.207, Bedrock, Vertex et Claude Platform on AWS restent par défaut sur Opus 4.8. En environnement cloud d'entreprise, vérifiez ce que /model affiche réellement plutôt que de supposer.

🆕 Claude Sonnet 5 (30 juin 2026, ID claude-sonnet-5). « Le Sonnet le plus agentif à ce jour » : proche d'Opus 4.8 sur les tâches agentiques pour 2,5× moins cher pendant la promo, contexte 1M natif (sans premium long-contexte — cf. M5), taux d'hallucination et de sycophantie en baisse vs 4.6. Attention au nouveau tokenizer : le même contenu compte 1,0–1,35× plus de tokens — comparez les coûts en $, pas en tokens. C'est le nouveau défaut de Claude Code et de claude.ai (Free/Pro). (Source : annonce officielle.)

L'effort (adaptive reasoning) règle combien le modèle réfléchit, indépendamment du modèle :

Réglage : menu /effort, clé effortLevel (settings), ou env CLAUDE_CODE_EFFORT_LEVEL.

🏢 Restrictions de modèle par l'organisation (v2.1.187). Un admin peut désormais restreindre les modèles disponibles : la liste filtrée s'applique au picker /model, au flag --model et à la variable ANTHROPIC_MODEL. Depuis la v2.1.196, l'admin peut aussi fixer un modèle par défaut d'organisation (ou par rôle) dans la console : il s'affiche « Org default » / « Role default » dans /model tant que l'utilisateur n'a pas choisi lui-même. Utile en gouvernance (forcer Sonnet/Haiku sur certains périmètres, bloquer un modèle non validé) — cf. M11 (adoption/gouvernance) et M9 (cadre).

💡 Réflexe : comparez toujours (modèle × effort), pas seulement le modèle. Un Opus en low peut être plus rapide/économe qu'un Sonnet en high.

Prompt engineering Anthropic

Claude répond particulièrement bien à une structure explicite :

• Balises XML pour délimiter contexte/instructions/exemples : <contexte>…</contexte>, <regles>…</regles>
• Few-shot : 2–5 exemples entrée→sortie représentatifs
• Chain-of-thought : demander un raisonnement étape par étape avant la réponse (ou laisser l'effort s'en charger)
• Structured output : imposer un JSON Schema pour une sortie machine-exploitable
• Dire quoi faire, pas quoi éviter : Claude suit mieux une consigne positive (« réponds en 3 puces ») qu'une négative (« n'écris pas de paragraphes »). Les interdictions restent utiles comme garde-fous durs (sécurité, périmètre), mais pour le style, formulez en positif.
• Clarté avant longueur : minimal ≠ court. Un prompt long mais structuré est bon ; un prompt vague (« améliore ça ») est mauvais quelle que soit sa taille. Règle d'or Anthropic : si un collègue sans contexte ne saurait pas l'exécuter, Claude non plus.

🧯 Idées reçues à corriger (vues en ligne). Plusieurs « règles » virales sur Claude sont fausses ou datées — utiles à désamorcer en formation :

• ❌ « L'Adaptive Thinking est désactivé par défaut, d'où des réponses plates. » → Faux. Le raisonnement adaptatif est le mode par défaut (Opus 4.8/4.7). Ce qui est masqué par défaut sur claude.ai, c'est l'affichage du raisonnement. Une réponse « plate » vient d'un niveau d'effort trop bas (low/medium), pas d'un thinking « éteint » — d'où l'intérêt de /effort high.
• ❌ « Un prompt de plus de 500 mots est forcément paresseux. » → Faux : c'est le manque de structure qui pèche, pas la longueur.
• ✅ « Éditer un message plutôt que relancer un follow-up économise des tokens. » → Vrai : le bouton Modifier remplace la suite de la conversation au lieu de l'empiler (cf. token economics, M2).

Prompt caching : cache_control, éphémère 5 min / 1 h

Le prompt caching stocke la partie stable du contexte (system prompt, tools, gros document) côté Anthropic. Sur les appels suivants, l'input caché coûte ~0,1× son prix → jusqu'à 90 % d'économie sur l'input, pour un coût d'écriture initial de ~+25 % (5 min) à +100 % (1 h).

client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    system=[{
        "type": "text",
        "text": "[ruleset stable, 5k tokens]",
        "cache_control": {"type": "ephemeral"},   # marque la frontière de cache
    }],
    messages=[{"role": "user", "content": "Analyse ce document…"}],
)

Durée de cache : 5 min par défaut (éphémère), 1 h disponible pour les préfixes très réutilisés. Idéal pour les boucles (batch de documents, sessions de chat, pipelines courts). Détail FinOps dans M2.

Cycle de vie d'une session + auto memory

Invocation → chargement du contexte (CLAUDE.md, règles, MEMORY.md) → tool calls →
compaction automatique quand la fenêtre se remplit → /clear ou /compact

• /clear repart à zéro ; /compact résume pour libérer du contexte sans tout perdre.
• /rewind revient à un checkpoint antérieur — et depuis v2.1.191, il peut reprendre une conversation d'avant un /clear : un /clear trop hâtif n'est plus irréversible.
• Après un /compact, le CLAUDE.md de la racine du projet est relu depuis le disque et réinjecté. Les CLAUDE.md imbriqués, eux, ne le sont pas : ils rechargeront à la prochaine lecture d'un fichier de leur dossier. Une consigne « perdue après compaction » vient presque toujours de là — ou d'une consigne donnée seulement à l'oral dans la conversation.

Mémoire projet : CLAUDE.md, .claude/rules/, auto memory

Deux mécanismes complémentaires traversent les sessions : ce que vous écrivez (CLAUDE.md, règles) et ce que Claude note lui-même (auto memory).

⚠️ Ce n'est pas de la configuration exécutoire. CLAUDE.md est injecté comme contexte, pas comme contrainte : Claude essaie de le suivre, sans garantie. Une règle qui doit tenir à tous les coups (« ne jamais toucher .env ») s'écrit en hook PreToolUse (J2), pas en ligne de markdown. Le markdown oriente, le hook empêche.

Où placer un CLAUDE.md

Par ordre de chargement, du plus large au plus spécifique :

Comment ils se chargent — c'est additif, jamais un override : Claude remonte l'arbre depuis le dossier courant et concatène tout ce qu'il trouve, de la racine vers le dossier de lancement (le plus proche est donc lu en dernier). À chaque niveau, CLAUDE.local.md est ajouté après CLAUDE.md. Les CLAUDE.md situés dans des sous-dossiers ne sont pas chargés au lancement : ils entrent en contexte à la demande, quand Claude lit un fichier de ce dossier. C'est le mécanisme à connaître en monorepo — et claudeMdExcludes (glob sur chemins absolus, cumulable sur tous les scopes) permet d'ignorer les CLAUDE.md des autres équipes.

📏 Viser moins de 200 lignes par fichier. C'est la recommandation officielle, et elle a deux justifications : un CLAUDE.md long consomme du contexte à chaque requête et dégrade l'adhérence — plus le fichier est bavard, moins les consignes sont suivies. Depuis v2.1.206, /doctor propose des coupes sur un CLAUDE.md versionné : il retire ce que Claude peut déduire du code (arborescences, listes de dépendances, survol d'architecture) et garde ce qui ne se devine pas — pièges, raisons, conventions qui s'écartent des défauts.

La dette de prompt : ablater plutôt qu'accumuler

Un CLAUDE.md n'est presque jamais écrit d'un coup : c'est un empilement de correctifs, chacun ajouté le jour où un modèle a raté quelque chose. Le piège, c'est que le correctif survit au problème. Le modèle progresse, la consigne reste — et elle continue de coûter du contexte à chaque requête, tout en diluant les consignes qui, elles, servent encore.

D'où la discipline inverse, que l'équipe Claude Code s'applique à elle-même : l'ablation. On supprime tout, puis on remet une consigne à la fois, uniquement quand on constate le modèle échouer sans elle. À la sortie d'Opus 5, plus de 80 % du system prompt de Claude Code a été supprimé — et le modèle s'en est trouvé meilleur. Le conseil de Boris Cherny, créateur de l'outil : refaire l'exercice tous les 3 à 6 mois, et à chaque nouvelle génération de modèle, parce qu'un comportement calibré pour un modèle ne se transfère pas au suivant.

Deux commandes pour ablater proprement — à ne pas confondre :

La seconde est l'ablation qu'Anthropic utilise en interne pour vérifier que son propre prompting « gagne sa place ».

⚠️ CLAUDE_CODE_SIMPLE n'est pas documenté dans claude --help (vérifié présent dans le binaire v2.1.220). C'est un outil de diagnostic, pas une API : il peut changer ou disparaître sans préavis. À utiliser pour comprendre, jamais dans un script de production.

🛑 Ce qu'on n'ablate jamais. Le conseil vise les consignes comportementales — « code de telle façon », « pense à faire ceci » — que les modèles récents n'ont plus besoin qu'on leur dicte. Il ne vise ni les faits non devinables (votre shell réel, un port occupé, une commande maison, un piège de votre stack), ni l'enforcement : un hook PreToolUse qui bloque rm -rf, une permissions.deny sur les secrets, une contrainte d'audit sont des politiques, pas des instructions que le modèle finira par « dépasser ». Elles restent, quelle que soit la génération. C'est l'encadré ⚠️ en tête de section, dans l'autre sens : le markdown oriente, le hook empêche — donc le markdown s'ablate, le hook non.

Sources : Boris Cherny, Y Combinator Startup School, juillet 2026 (les 80 %, le cycle de 6 mois, CLAUDE_CODE_SIMPLE) et sa méthode d'ablation détaillée (« supprimez tous les 3 mois, puis remettez une instruction à la fois quand vous voyez le modèle buter dessus »).

Imports @chemin

Un CLAUDE.md peut en importer d'autres avec la syntaxe @chemin/vers/fichier :

Voir @README pour le survol et @package.json pour les commandes npm.

# Conventions Git
- @docs/git-instructions.md

Chemins relatifs au fichier qui importe (pas au dossier courant), récursivité jusqu'à 4 sauts. Le parsing ignore les blocs de code et les code spans : `@README` entre backticks reste du texte, @README sans backticks importe. Un import externe (qui sort du dossier de travail, typiquement @~/.claude/mes-prefs.md) déclenche une fois un dialogue d'approbation — garde-fou contre un fichier malveillant committé par un tiers dans un repo partagé.

⚠️ Un import ne réduit pas le contexte. Les fichiers importés sont chargés au lancement, comme le reste. Découper en imports organise ; pour réellement alléger, il faut des règles à portée de chemin (ci-dessous) ou des skills (J3).

AGENTS.md : Claude Code lit CLAUDE.md, pas AGENTS.md

Point régulièrement mal compris. Si votre dépôt utilise déjà AGENTS.md pour d'autres agents de code, Claude Code ne le lit pas tout seul. La solution officielle : un CLAUDE.md qui l'importe, avec éventuellement des consignes spécifiques à Claude en dessous.

@AGENTS.md

## Claude Code
Utiliser le mode plan pour toute modification sous `src/billing/`.

Un symlink (ln -s AGENTS.md CLAUDE.md) fonctionne aussi si vous n'avez rien à ajouter — mais il demande les droits administrateur ou le mode développeur sous Windows : préférez l'import. Pour vérifier que ça a bien pris : /context, section Memory files.

.claude/rules/ : la réponse au CLAUDE.md obèse

Plutôt que de gonfler un fichier unique, on éclate les consignes en fichiers thématiques dans .claude/rules/ — découverts récursivement, un sujet par fichier :

.claude/
├── CLAUDE.md
└── rules/
    ├── code-style.md
    ├── testing.md
    └── api-design.md

Une règle sans frontmatter est chargée au lancement, avec la même priorité que .claude/CLAUDE.md. Une règle avec un champ paths n'entre en contexte que lorsque Claude touche un fichier correspondant :

---
paths:
  - "src/api/**/*.ts"
---

# Règles API
- Valider toutes les entrées
- Format d'erreur standard maison

C'est le levier pour tenir sous les 200 lignes sans rien perdre : les conventions TypeScript ne pèsent plus rien quand vous travaillez sur la CI. Les globs acceptent l'expansion d'accolades (src/**/*.{ts,tsx}). Variante personnelle : ~/.claude/rules/, chargé avant les règles projet — et le dossier accepte les symlinks, donc un jeu de règles maison peut être partagé entre plusieurs dépôts.

Auto memory : ce que Claude note tout seul

Stockage : ~/.claude/projects/<projet>/memory/, avec un MEMORY.md qui sert d'index et des fichiers thématiques lus à la demande. Seules les 200 premières lignes (ou 25 Ko) de l'index sont chargées au démarrage — au-delà, c'est silencieusement tronqué, d'où la discipline « une ligne par entrée, le détail dans un fichier dédié ». Réglages : autoMemoryEnabled (activé par défaut), autoMemoryDirectory pour déplacer le dossier, ou CLAUDE_CODE_DISABLE_AUTO_MEMORY=1. La mémoire est locale à la machine : elle ne suit ni le dépôt ni le cloud.

🧰 Les quatre commandes à connaître. /memory liste et ouvre les fichiers de mémoire (et bascule l'auto memory) · /context montre ce qui a réellement été chargé dans la session — c'est l'outil de diagnostic n° 1 quand une consigne est ignorée · /init génère un premier CLAUDE.md à partir du code (avec CLAUDE_CODE_NEW_INIT=1, un parcours interactif qui propose aussi skills et hooks) · /doctor audite l'installation et propose les coupes évoquées plus haut.

📌 Pour faire retenir quelque chose en cours de session, demandez-le en clair (« retiens que les tests ont besoin d'un Redis local ») : Claude l'écrit dans l'auto memory. Pour viser le fichier versionné, dites-le explicitement (« ajoute ça au CLAUDE.md »).

Aide-mémoire : raccourcis et modes de saisie

Le terminal n'affiche pas ses raccourcis : on peut utiliser Claude Code des mois sans en connaître la moitié. Voici ceux qui changent le quotidien (vérifiés sur v2.1.219).

Deux modes de saisie à connaître :

• ! — mode bash. Tapez ! puis une commande : elle s'exécute localement et sa sortie entre dans le contexte. Depuis v2.1.186, Claude répond automatiquement à cette sortie — ! npm test donne directement l'analyse des échecs, sans second prompt. Pour retrouver l'ancien comportement (sortie ajoutée au contexte, sans réponse), passer respondToBashCommands à false.
• Mode vim — editorMode: "vim" dans settings.json, avec vimInsertModeRemaps depuis v2.1.208 pour mapper une séquence de deux touches sur Échap ({"jj": "<Esc>"}).

Côté reprise de session : --continue (-c) reprend la dernière conversation du dossier, --resume (-r) ouvre un sélecteur ou cible un ID, --fork-session repart d'une session existante sous un nouvel identifiant sans écraser l'originale.

🎙️ Dictez vos prompts. Claude Code n'a pas d'entrée vocale native : cela se joue au niveau de l'OS (dictée macOS dans Réglages → Accessibilité) ou via un outil tiers. L'intérêt n'est pas la vitesse de frappe — c'est que dicter produit des prompts plus longs et plus spécifiques que taper, et la spécificité est le premier facteur de qualité du résultat. On parle à Claude Code comme on expliquerait la tâche à un collègue, avec le contexte que l'on n'aurait pas pris la peine d'écrire.

⌨️ Personnalisation. Les raccourcis sont rebindables via ~/.claude/keybindings.json. Et /terminal-setup configure votre émulateur pour que Shift+Entrée fasse un saut de ligne — à lancer une fois, cela évite les \ en fin de ligne pour les prompts multi-lignes.

Atelier (90 min) : audit + refonte de votre configuration

1. (10 min) Q&A à froid : sur un dépôt que vous connaissez mal, poser 3 questions — une de localisation (« où vit… »), une d'usage (« comment on instancie… »), une de « pourquoi » qui force le passage par l'historique Git.
2. (15 min) Lancer une tâche réelle avec claude --debug, repérer 3 décisions de permission, puis /context pour lister ce qui occupe réellement la fenêtre.
3. (20 min) Écrire un ~/.claude/settings.json : model, effortLevel, et un bloc permissions (≥ 3 deny durs : rm, git push --force, secrets).
4. (20 min) Assainir la mémoire : ramener le CLAUDE.md du projet sous 200 lignes (au besoin avec /doctor), déplacer une section thématique vers .claude/rules/ avec un frontmatter paths:, puis vérifier via /context qu'elle ne se charge que sur les fichiers ciblés. Terminer par une passe d'ablation : relire chaque ligne restante et la classer en correctif comportemental (candidat à la suppression), fait non devinable (on garde) ou enforcement (à déplacer en hook ou en permissions.deny). Rejouer la même tâche qu'à l'étape 1 en --safe-mode pour voir ce que le modèle fait sans votre configuration.
5. (15 min) Tester les modes : même tâche en plan puis acceptEdits ; refaire en changeant (modèle × effort) à chaud via /config.
6. (10 min) Ajouter un cache_control sur un gros system prompt et mesurer l'économie d'input sur 5 appels.

Livrable : un settings.json opérationnel, un CLAUDE.md + une règle à portée de chemin assainis, et une note « quel (modèle × effort) pour quel type de tâche chez moi ».

Pour aller plus loin

• 📖 Claude Code — Settings
• 📖 Claude Code — Mémoire : CLAUDE.md, règles, auto memory
• 📖 Claude Code — Mode interactif (raccourcis complets)
• 📖 Claude Code — Usage des données (entraînement, rétention, ZDR)
• 📖 Claude Code — Model configuration & effort
• 📖 Prompt caching (API Anthropic)
• 🎯 Suite du tronc commun : J2 (hooks, Git/CI) · approfondissements : M2 (FinOps), M4 (comparatif modèles), M1 (conformité et traitement des données)