The Claude Code Operating Model

1Même modèle, autre harnais, autre agent

Le cadre d'abord, avec un chiffre du livre. Terminal-Bench 2.0 est un banc d'essai de tâches en ligne de commande. Sur ce banc, un même modèle passe de 52,8 % à 66,5 % de réussite. Seul son entourage a changé. Le livre ne dit pas ce qui a changé dans cet entourage.

Cet entourage, Jia Huang l'appelle le harnais. Il regroupe cinq pièces :

• les outils : ce que Claude peut appeler, comme lire un fichier ou lancer une commande ;
• les permissions : ce qu'il a le droit de faire ;
• la gestion du contexte : le contexte est tout ce que Claude a sous les yeux, vos messages, ses réponses, les fichiers lus ;
• les hooks : des scripts qui contrôlent ses actions ;
• la boucle agentique : observer, faire une hypothèse, vérifier, et recommencer jusqu'à la fin de la tâche.

De ces cinq pièces vient la formule du livre : « Agent = modèle + harnais » (ch. 7). Traduction : à modèle égal, le harnais fait la différence. Un exemple du livre le montre. Un sous-agent de revue est un second Claude chargé de relire le code. Le livre ne lui donne que trois outils : Read, Grep et Glob. Ils servent à lire, chercher et lister des fichiers par motif. Ce sous-agent ne peut donc rien modifier, même s'il se trompe. La limite vient du harnais, pas du modèle.

2Un CLAUDE.md court en dit plus qu'un long

Premier axe du harnais : ce que Claude sait de votre projet. Or il en sait très peu. Dans le livre, Xiaobing demande une API de connexion. Une API est le point d'entrée qu'un programme appelle. Claude lui rend du code Express, à installer avec npm install. Or le projet utilise Fastify et pnpm.

Pour un novice, ces quatre noms se rangent en deux paires. Express et Fastify sont deux frameworks web JavaScript. npm et pnpm sont deux gestionnaires de paquets, les outils qui installent les bibliothèques. Claude a choisi la paire qu'il a vue le plus souvent pendant son entraînement. Chaque session est un premier jour : ce qui lui manque, « ce n'est pas la capacité, c'est le contexte » (ch. 10).

Ce manque de contexte, le livre le comble avec le CLAUDE.md. Le CLAUDE.md est un fichier texte à la racine du projet. Claude le lit au démarrage de chaque session, comme un manuel d'intégration pour un nouvel arrivant. Le fichier arrive comme un message de haute priorité, juste après les instructions système, les consignes de base du modèle. Il reste donc une consigne, pas un réglage forcé : Claude peut l'ignorer. Voici un mauvais fichier et un bon, d'après le livre :

# ✗ AVANT (exemple du livre)
Équipe de 5 personnes, projet démarré en mars 2024.
Le code doit être bien écrit. Les tests doivent être complets.
Merci de suivre les bonnes pratiques.

# ✓ APRÈS (exemple du livre, abrégé)
- Fastify 4 (ne pas utiliser Express)
- pnpm 8 (ne pas utiliser npm/yarn)
- src/routes/ : routes seulement ; la logique métier va dans src/services/
pnpm test   # lance vitest (outil de test JavaScript)

Le mauvais fichier échoue parce qu'il reste vague. « Bien écrit » ne dit pas quel formatage. « Complets » ne dit pas quels tests. Pour trier les règles, le livre propose un test : si Claude se comporte bien sans une règle, elle n'a rien à faire dans le fichier (ch. 14).

Ce tri a une raison : « la densité d'instructions est inversement proportionnelle à la probabilité qu'elles soient suivies » (ch. 12). Autrement dit, plus il y a de règles, moins chacune est suivie. C'est un raisonnement, sans mesure. Le livre vise moins de 200 lignes.

Ce tri laisse une question : où mettre une règle qui ne vaut que pour une partie du code ? Le livre la range dans le dossier .claude/rules/. Chaque fichier y commence par un en-tête, le frontmatter, un bloc placé entre deux lignes ---. Le champ paths: de cet en-tête dit quand charger la règle :

---
paths:
  - "**/*.test.ts"
---
Utiliser vitest ; jest est interdit.

Cette règle impose vitest à la place de jest, deux outils de test JavaScript. Elle ne se charge que si Claude touche un fichier de test.

3Un skill ne se charge que s'il sert

Le CLAUDE.md dit ce que Claude doit savoir. Reste le comment : les procédures qu'il suit. Le livre les range dans des skills. Un skill est un dossier qui contient un fichier SKILL.md. Ce fichier décrit une procédure, par exemple faire une revue de code ou préparer un commit. Un commit est un enregistrement de modifications dans l'historique Git. Claude ne lit le skill que quand il en a besoin.

Ce chargement à la demande, le livre l'illustre par une image : le mur et le classeur (ch. 16). Le CLAUDE.md est le mur, toujours sous les yeux. Les skills sont le classeur, qu'on ouvre quand le dossier arrive. Le gain se compte en tokens. Un token est un morceau de mot, l'unité que le modèle compte et facture. Au repos, Claude ne charge que la description du skill : environ 100 tokens. Le skill complet en pèse 5 300.

Tout repose donc sur la description du skill : c'est le seul signal qui le déclenche (ch. 20). Or ce signal rate souvent. Le livre cite une évaluation de l'entreprise Vercel. Sans guidage explicite, le skill testé n'était pas invoqué dans 56 % des cas. Le livre précise la limite de ce chiffre : un seul skill, une seule évaluation.

D'où la méthode du livre : écrire la description avec les phrases des utilisateurs, puis la tester sur dix à vingt cas. Voici un début de SKILL.md, de mon cru :

---
name: commit
description: Prépare un commit propre quand l'utilisateur dit "commite" ou "enregistre mes changements".
disable-model-invocation: true
---

Ce skill porte un champ de plus : disable-model-invocation: true. Le champ réserve le skill à l'appel manuel, en tapant /commit. Pourquoi l'empêcher de se lancer seul, alors qu'un skill de revue le peut ? Le livre raisonne sur le pire cas. Un effet de bord est ce qu'une action change hors d'elle, comme un fichier écrit. La règle : « plus l'effet de bord est grand, plus le contrôle doit être serré » (ch. 21). Une revue ratée ne casse rien. Un commit lancé sans vous, si.

4Un sous-agent sauve le contexte, pas la facture

Le CLAUDE.md et les skills remplissent le même espace : le contexte de Claude. Or cet espace a une taille fixe. Quand Claude perd le fil, il n'oublie pas : il « se noie sous un flot d'informations » (ch. 28). Sa fenêtre de contexte est le texte qu'il garde sous les yeux, 200 000 tokens par défaut.

Imaginez cette fenêtre comme un bureau. Sur 200 lignes de tests, seule la ligne « 3 tests failed, 47 passed » compte. Le reste encombre le bureau. D'où le troisième mécanisme, le sous-agent. Un sous-agent est une seconde instance de Claude, lancée pour une tâche, avec sa propre fenêtre. Il lit le bruit à part. Seul son résumé remonte dans la conversation principale.

Le livre chiffre le gain sur cinq échanges. Un échange est un aller-retour : votre message, puis la réponse de Claude. Or l'API du modèle ne retient rien d'un échange à l'autre. Chaque échange renvoie donc tout. Les consignes système pèsent 5 000 tokens. L'historique pèse 8 000 tokens, plus 1 000 à chaque échange. Sans sous-agent, la sortie des tests ajoute 10 000 tokens. Le total sur cinq échanges :

• sans sous-agent : 23 000, 24 000, jusqu'à 27 000 tokens par échange, soit 125 000 en tout ;
• avec sous-agent : la conversation ne reçoit qu'un résumé de 100 tokens, et pèse de 13 100 à 17 100 par échange, soit 75 500. Le sous-agent consomme 41 000 tokens une fois. Total : 116 500 ;
• l'écart : 8 500 tokens, soit 6,8 %.

Cet écart déjà mince fond encore avec le cache de prompt. Grâce au cache, les tokens déjà envoyés coûtent 10 % du prix. L'écart tombe alors à 1 ou 2 %. Le livre admet qu'il grandit sur 10 ou 20 échanges. La vraie valeur est donc ailleurs. Avec un sous-agent, Claude compacte son historique moins tôt, c'est-à-dire qu'il le résume moins tôt. Il perd donc moins de détails.

Quand lancer un sous-agent, alors ? La règle pratique du livre compare le volume à lire au volume à rapporter (ch. 34).

5Le CLAUDE.md conseille, le hook tranche

Second axe du harnais : ce que Claude a le droit de faire. Le module sur les hooks s'ouvre sur un incident. Un fichier .env contient les mots de passe et les clés d'API du projet. Ce fichier est poussé par erreur sur le dépôt, la copie partagée du code. Résultat : une demi-journée à changer toutes les clés. Aucune ligne du CLAUDE.md ne peut l'empêcher, puisque Claude peut ignorer une consigne.

Pour une règle qui ne souffre aucune exception, le livre passe donc aux hooks. Un hook est un script que Claude Code exécute avant ou après une action de Claude : lire, écrire, lancer une commande. Si le script sort avec le code 2, l'action est refusée. Son message d'erreur retourne alors à Claude. Voici un hook de mon cru, d'après le principe du livre :

#!/bin/bash
# .claude/hooks/bloque-env.sh
FICHIER=$(cat | jq -r '.tool_input.file_path // ""')
if [[ "$FICHIER" == *".env"* ]]; then
  echo "Écriture dans .env refusée" >&2
  exit 2
fi
exit 0

Le script ci-dessus se déclare dans .claude/settings.json. Un matcher y désigne les outils visés, ici Write|Edit : écrire et modifier un fichier. Un second champ donne la commande à lancer. Dans le script, jq lit les données que Claude Code envoie, au format JSON, un format texte de données structurées.

Le livre résume l'écart avec le CLAUDE.md : les hooks « ne sont pas des suggestions, ils sont une obligation » (ch. 38). Il en tire une leçon sur les règles déterministes, qui donnent toujours le même résultat pour la même entrée. Pour le livre, une telle règle est toujours plus fiable que le jugement d'un modèle (ch. 40). Un hook ne voit pourtant que ce qu'on lui montre. Mon exemple ne couvre que l'outil d'écriture. La commande cat > .env, qui écrit le fichier depuis le terminal, passe donc à côté.

Un hook peut aussi relancer les tests à chaque fin de réponse de Claude. Ce hook doit alors vérifier le drapeau stop_hook_active, une valeur vrai ou faux. Sinon, la boucle ne finit jamais :

1. Claude annonce avoir fini, le hook lance les tests, ils échouent, le hook l'empêche de s'arrêter.
2. Claude corrige et annonce la fin. Le hook se relance, avec stop_hook_active à true.
3. Le script voit ce drapeau, sort avec exit 0 sans relancer les tests, et Claude s'arrête.

6MCP : tout brancher, ouvrir peu

Les hooks encadrent ce que Claude fait dans le projet. MCP sert à l'inverse à sortir du projet, ce qui pose la même question des droits. Prenons un ticket Jira, un outil de suivi des tâches. Pour le lire, Claude a besoin d'un adaptateur : un petit programme qui le relie à Jira.

Le problème, c'est le nombre d'adaptateurs. Il en faut un pour chaque couple assistant et outil, un assistant étant par exemple Claude Code. Avec 5 assistants et 100 outils, cela fait 500 adaptateurs à écrire (5 × 100).

Le MCP (Model Context Protocol, protocole de contexte de modèle) règle ce problème avec une langue commune. Chaque assistant l'apprend une fois, et chaque outil aussi. Il suffit alors de 105 branchements (5 + 100). C'est le principe de la prise USB-C : un seul câble pour tous les appareils. Le livre reprend la formule d'Anthropic : MCP est « l'USB-C de l'intégration d'outils d'IA » (ch. 46).

Un serveur MCP est le programme qui donne accès à un outil ou à des données. On le déclare dans un fichier .mcp.json, à la racine du projet. Celui du livre donne accès au dossier /workspace. La commande npx -y lance le serveur sans l'installer d'abord :

{ "mcpServers": { "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"] } } }

Un serveur parle à Claude en stdio quand il tourne en local, et en HTTP quand il tourne à distance. L'ancien transport SSE est remplacé par HTTP (ch. 47).

Brancher un outil, c'est aussi lui ouvrir des accès. Le livre pose donc deux limites :

• une base de données ne se connecte qu'avec un compte en lecture seule (ch. 48) ;
• un serveur tiers est verrouillé sur une version, lu avant usage et doté des identifiants les plus étroits possible (ch. 49).

Reste à situer MCP par rapport aux skills de l'idée 3. L'image du livre : MCP est la cuisine, un skill la recette (ch. 50). MCP fournit les outils et les données. Le skill dit comment s'en servir pour un cas précis.

7Sans personne devant l'écran, tout se règle d'avance

Jusqu'ici, une personne regarde Claude travailler et le guide. Le dernier mécanisme se passe d'elle. Le mode headless (littéralement « sans tête ») fait tourner Claude sans écran, depuis un script. On le lance avec claude -p "...". On s'en sert surtout en CI. La CI (intégration continue) est un robot qui vérifie chaque modification poussée sur le dépôt.

Or cette personne faisait trois choses. Elle approuvait les actions, jugeait le résultat et décidait de la suite. Sans elle, il faut écrire ces trois décisions d'avance dans la commande. Voici la commande de revue du livre, abrégée :

claude -p "Relis ces fichiers. Termine par <VERDICT>approved</VERDICT>
ou <VERDICT>request_changes</VERDICT>" \
  --max-turns 10 --max-budget-usd 0.50 --allowedTools "Read,Grep,Glob"

Chaque réglage de cette commande remplace l'une de ces trois décisions :

• Liste blanche d'outils (--allowedTools), à la place de la personne qui approuve : seuls Read, Grep et Glob sont permis.
• Plafonds de tours et de budget, à la place de la personne qui décide de la suite. Un tour est une étape de la boucle de l'assistant. Il peut contenir plusieurs appels d'outils : tours et appels ne coïncident donc pas un pour un.
• Statut final et ligne sentinelle, à la place de la personne qui juge le résultat. Le statut final dit comment l'exécution s'est terminée. La ligne sentinelle est un repère fixe que le script cherche dans la réponse, ici <VERDICT>.

Chacun de ces réglages a son piège. Premier piège, les plafonds : fixez-les au-dessus du maximum observé sur dix exécutions réelles. Une exécution coupée par son plafond sort avec le statut error_max_turns. Un script qui ne teste pas ce statut y voit un succès. Le plafond de budget donne un autre statut, error_max_budget_usd, et aucune conclusion.

Second piège, la détection du verdict. La ligne sentinelle fait échouer la CI sans ambiguïté. Une recherche de mot avec grep fait moins bien : un grep critical se déclenche aussi sur « no critical issues », qui dit pourtant que tout va bien (ch. 56).

Même avec ces limites, un agent peut laisser fuir un secret. Exemple du livre : un agent de revue en lecture seule reçoit la consigne de « vérifier la configuration ». Il recopie le .env, le fichier des secrets, dans le journal de la CI. GitHub Actions est le service de CI de GitHub, et il masque les secrets dans ses journaux. Ce masquage ne couvre pas le texte écrit par le modèle (ch. 59).

8La facture triple, et Claude n'y est pour rien

Les sept premières idées règlent l'outil. La dernière montre qu'un outil bien réglé ne suffit pas pour une équipe entière. Voici le cas du livre. Trois mois après l'adoption de Claude Code, la facture est trois fois plus haute que prévu. La cause est une session de près de cinq heures sur des logs, les journaux écrits par une application. Ces logs restaient dans la conversation, donc ils étaient facturés de nouveau à chaque échange.

Un second souci s'ajoute : chaque ingénieur a son propre CLAUDE.md, donc Claude ne suit pas les mêmes règles chez l'un et chez l'autre.

Le directeur technique en tire une leçon : « nous avons l'outil, mais nous n'avons pas encore établi les pratiques d'ingénierie qui vont avec » (ch. 76). Le livre propose trois pratiques pour combler ce manque :

• Chercher la cause dans l'ordre (ch. 78). Exemple imaginé, pas du livre : Claude utilise Express, une bibliothèque web JavaScript, alors que l'équipe en utilise une autre. Première cause possible, le contexte manquait : le CLAUDE.md n'en dit rien. Deuxième cause, des consignes se contredisaient. Troisième cause, une permission manquait, et Claude s'est rabattu sur ce qu'il avait. L'exemple est de moi, l'ordre est du livre.
• Relire le CLAUDE.md comme du code : toute modification passe par une pull request, c'est-à-dire une proposition de changement relue. Un ingénieur senior l'approuve avant fusion (ch. 82).
• Ne pas payer les logs à chaque échange : confiez l'analyse à un sous-agent. Il lit les logs de son côté, et la conversation principale ne les porte plus (ch. 77).