# Pourquoi le harnais est important Pourquoi les fonctionnalités de Claude Code ne sont pas « juste des prompts déguisés » — et pourquoi le harnais est ce qui sépare réellement une sortie jouet d'un travail d'ingénierie de qualité production.
← Retour à Claude Code Best Practice Claude
--- ## Résumé exécutif Une réduction courante chez les utilisateurs expérimentés de Claude Code est : *« skills, commandes, sous-agents, hooks — ils deviennent tous au final des prompts pour le modèle, donc un prompt solide à lui seul est équivalent. »* À la couche de l'appel d'inférence final du modèle, c'est techniquement vrai. Le modèle ne voit jamais que des tokens. À toutes les autres couches — celles où se déroule la vraie ingénierie logicielle — **cette réduction s'effondre.** Le harnais n'est pas un système de livraison de prompt. C'est un **système de construction de prompt, un système d'exécution déterministe et un système d'architecture de contexte** — et ces capacités ne peuvent être remplacées par une formulation plus forte. Ce rapport explique où la réduction a raison, où elle échoue, et pourquoi confondre « ce que le modèle voit » avec « ce que le système fait » éloigne les praticiens des fonctionnalités qui donnent à Claude Code son levier réel. --- ## La réduction qui sonne juste Pour une **tâche atomique en un seul coup** — « écris-moi une fonction Fibonacci récursive » — le harnais ne contribue en rien à la qualité de la sortie. Donne les mêmes tokens au même modèle et tu obtiens la même distribution de sorties, qu'ils soient arrivés via un skill, une commande ou un prompt brut. Dans ce régime étroit, la réduction tient : > Qualité de sortie ≈ Qualité du prompt C'est le régime où Claude Code offre peu de valeur par rapport à un simple chatbot. C'est aussi le régime que la réduction suppose implicitement — et précisément celui dans lequel le vrai travail d'ingénierie ne se trouve pas. --- ## Où la réduction s'effondre Dix capacités architecturales du harnais opèrent à des couches auxquelles les prompts n'ont pas accès. | # | Capacité | Ce qu'elle fait | Pourquoi un prompt ne peut la répliquer | |---|------------|--------------|-------------------------------| | 1 | **Isolation de contexte** | Les sous-agents tournent dans des fenêtres de contexte séparées | Un prompt remplit une fenêtre. N sous-agents parallèles donnent ~N× de contexte effectif. | | 2 | **Restrictions d'outils imposées par le harnais** | `allowed-tools` / `disallowedTools` bloquent les outils avant que le modèle puisse les utiliser | Les instructions de prompt sont indicatives ; le modèle peut les ignorer. Les règles deny ne peuvent être ignorées. | | 3 | **Règles & mémoire en chargement paresseux** | Le frontmatter `paths:` et les fichiers `CLAUDE.md` descendants ne se chargent que lorsque Claude touche des chemins correspondants | Un prompt est statique — il ne peut charger conditionnellement selon les fichiers lus à l'exécution. | | 4 | **Hooks : exécution de code déterministe** | Des commandes shell s'exécutent à des événements de cycle de vie (PreToolUse, PostToolUse, Stop, etc.) et peuvent **bloquer** des appels d'outils | Un prompt ne peut intercepter ses propres appels d'outils. Les hooks s'exécutent même si le modèle ne « veut » pas. | | 5 | **Routage de modèle** | `model: haiku` ou `model: opus` route un appel vers un endpoint de modèle différent | Aucun token du prompt ne peut changer quel modèle répond. | | 6 | **Parallélisme** | Plusieurs sous-agents s'exécutent simultanément | Un prompt est séquentiel. Le harnais ordonnance et collecte les résultats de processus parallèles. | | 7 | **Persistance entre sessions** | Le système de mémoire et la hiérarchie des paramètres persistent entre conversations | Un prompt meurt à la fin de la session. | | 8 | **System prompt modulaire** | Le CLI charge 110+ fragments de system prompt conditionnellement selon les fonctionnalités activées | Un utilisateur ne peut écrire à la main ni substituer les fragments de prompt internes du CLI. | | 9 | **Préchargement de skill** | Le champ `skills:` injecte le contenu complet d'un skill dans le contexte de départ d'un sous-agent | L'utilisateur ne peut pré-remplir le contexte d'un autre agent — seul le loader du harnais le peut. | | 10 | **Classification de permissions** | Le mode de permissions `auto` utilise un classifieur en arrière-plan pour pré-approuver ou bloquer les appels d'outils | Un prompt ne peut s'ajouter à lui-même une couche de sécurité pré-exécution. | Chaque ligne est une dimension où la « formulation forte » n'est catégoriquement pas un substitut. --- ## Les deux usages du mot « prompt » La réduction joue sur une équivoque. Le mot *prompt* est utilisé pour signifier deux choses très différentes : | Sens | Qui le contrôle | Taille | |---------|-----------------|------| | (a) Ce que l'utilisateur a tapé | L'utilisateur | ~6–60 tokens | | (b) Ce que le modèle voit à l'inférence | Le harnais | ~5 000–50 000+ tokens | Dans un chatbot, (a) et (b) sont la même chose. Dans Claude Code, ils sont radicalement différents. Le travail du harnais est précisément de rendre (b) bien plus riche que (a) : ``` L'utilisateur tape : "write a recursive flatten function" ← (a) ~6 tokens Ce que le modèle voit réellement à l'inférence : ← (b) ~15 000 tokens ├── CLAUDE.md (conventions du projet) ├── .claude/rules/*.md correspondants (chargés via le frontmatter paths:) ├── Fragments de system prompt modulaires ├── Définitions d'outils ├── Contexte d'environnement (cwd, git status, plateforme) ├── Historique des tours précédents ├── Fichiers lus par le modèle via les outils Read/Grep └── La requête de 6 tokens de l'utilisateur ``` **La qualité de la sortie est une fonction de (b), pas de (a).** Le harnais construit (b). Un « prompt solide à lui seul » ne peut reproduire (b) car l'essentiel n'est pas écrit par l'utilisateur. --- ## Même pour la qualité de sortie, le harnais fait un travail Considère le même prompt — « write a recursive flatten function » — dans trois environnements : | Environnement | Ce que le modèle voit | Résultat typique | |-------------|---------------------|----------------| | Chatbot, sans outils | La phrase | Récursion de manuel, style générique | | Claude Code, sans lecture | Phrase + CLAUDE.md | Correspond aux conventions déclarées du projet | | Claude Code, boucle agentique | Phrase + CLAUDE.md + lecture de fichiers adjacents + exécution de tests | Correspond aux patterns réels du codebase, passe les tests, gère les cas limites que le code existant gère | Même modèle. Même prompt utilisateur. **Trois qualités de sortie différentes.** La différence est le harnais — spécifiquement, le contexte effectif qu'il assemble et la boucle d'itération qu'il permet. Pour les tâches non triviales, la qualité de sortie est une fonction de : ``` Qualité de sortie = f(contexte effectif, capacité du modèle, boucle d'itération) ``` L'utilisateur contrôle une fraction du *contexte effectif* (son prompt tapé). Le harnais contrôle le reste — et la boucle d'itération entièrement. --- ## Ce que la réduction a juste (et ce qu'elle a faux) | Affirmation | Verdict | |-------|---------| | « À l'inférence, le modèle ne voit que des tokens. » | ✅ Vrai | | « Skills, commandes et prompts de sous-agents contribuent tous des tokens à un certain contexte. » | ✅ Vrai | | « Pour une tâche atomique dans le vide, la qualité du prompt domine la qualité de sortie. » | ✅ Vrai | | « Donc un prompt solide est équivalent à utiliser les fonctionnalités. » | ❌ Faux | | « Donc le harnais n'importe pas pour la qualité de sortie. » | ❌ Faux sur les vraies tâches d'ingénierie | Les trois premières affirmations sont des observations exactes. Le saut vers la quatrième est où le raisonnement échoue : il confond le modèle avec le système qui l'enveloppe, et confond les tâches atomiques avec le vrai travail d'ingénierie. --- ## Le bon modèle mental > **Les prompts contrôlent ce qu'on demande au modèle de faire.** > **Le harnais contrôle ce que le système fait à des couches que le modèle ne peut atteindre** — avant l'arrivée des tokens, après la production des tokens, entre les sessions, entre les contextes et entre les processus. Les fonctionnalités ne sont pas des prompts avec des étapes en plus. Ce sont des **primitives au niveau du harnais** — exécution déterministe, architecture de contexte et routage d'infrastructure — qui opèrent à des couches où le modèle n'a pas voix au chapitre. Une analogie utile : | Couche | Chatbot | Claude Code | |-------|---------|-------------| | Recette | Le message de l'utilisateur | Le message de l'utilisateur + contexte assemblé par le harnais | | Cuisine | Aucune — juste un élève | Outils, hooks, mémoire, workers parallèles, événements de cycle de vie | Tu peux écrire la meilleure recette du monde. Sans cuisine, tu ne peux pas cuisiner à grande échelle. --- ## À retenir pour les praticiens 1. **Pour les questions atomiques, la qualité du prompt est ~tout.** Le harnais est sans importance. Utilise un chatbot si c'est tout ce dont tu as besoin. 2. **Pour le vrai travail sur codebase, le harnais fait un gros travail silencieux.** Le prompt effectif à l'inférence est surtout construit par le harnais, pas tapé par l'utilisateur. 3. **Utilise les fonctionnalités pour ce que les prompts ne peuvent catégoriquement pas faire :** déterminisme (hooks), isolation (sous-agents), chargement paresseux (règles avec `paths:`), persistance (mémoire), routage (`model:` par agent) et parallélisme. 4. **Un prompt solide est nécessaire mais pas suffisant.** Les fonctionnalités te donnent déterminisme, isolation et composition que les prompts ne peuvent offrir. Les deux sont complémentaires, pas substituables. --- ## Sources - [Agents vs Commandes vs Skills](claude-agent-command-skill.md) — montre l'isolation de contexte, la surcharge de modèle et les restrictions d'outils par fonctionnalité - [Claude Agent SDK vs system prompts du CLI](claude-agent-sdk-vs-cli-system-prompts.md) — documente les 110+ fragments de system prompt modulaires - [Mémoire d'agent Claude](claude-agent-memory.md) — persistance entre sessions via les portées `memory:` - [Bonnes pratiques — Mémoire de Claude](../best-practice/claude-memory.md) — fichiers `CLAUDE.md` descendants en chargement paresseux - [Bonnes pratiques — Sous-agents](../best-practice/claude-subagents.md) — référence de frontmatter pour les capacités imposées par le harnais - [Bonnes pratiques — Paramètres](../best-practice/claude-settings.md) — évaluation des règles de permission et classifieur du mode `auto` - [Workflow d'orchestration](../orchestration-workflow/orchestration-workflow.md) — démonstration concrète que la réduction échoue