Utiliser Haiku 5.5 comme sous-agent en lecture seule dans Claude Code et vérifier le modèle

La méthode la plus sûre ne consiste pas à basculer toute la session Claude Code vers un petit modèle. Confiez à Haiku 5.5 uniquement les tâches bornées, en lecture seule et faciles à contrôler : rechercher les références d’un symbole, suivre des imports, localiser une configuration ou résumer un ensemble défini de fichiers. Gardez Sonnet ou Opus dans la conversation principale pour les décisions, les modifications, les tests et la validation finale.

Une configuration n’est pas prouvée parce que le prompt dit « utilise Haiku » ou qu’un fichier contient model: haiku. Il faut trois niveaux de preuve : le modèle explicite dans la définition de l’agent, le modèle affiché par Claude Code pendant l’exécution et le Model ID réel dans l’enregistrement de la requête chez le fournisseur. Ne considérez le changement comme vérifié que lorsque ces trois niveaux concordent.

Décider ce qui peut être délégué

Anthropic présente Haiku 5.5 comme adapté aux tâches rapides et répétitives : résumés, compaction, requêtes de base de données et classification. L’annonce officielle le décrit aussi comme un sous-agent de programmation aux côtés de Sonnet 5.5 ou Opus 5.5, tout en réservant le coding agentique complexe aux modèles plus grands. Consultez l’annonce de Haiku 5.5.

Commencez par cette répartition :

Tâche	Exécutant recommandé	Pourquoi
Trouver toutes les références à une classe, fonction ou option	Sous-agent en lecture seule sur petit modèle	Entrée, sortie et condition d’arrêt sont claires
Résumer le rôle des fichiers d’un répertoire	Sous-agent en lecture seule	Il faut lire et synthétiser, pas modifier
Suivre une requête du point d’entrée jusqu’à la base	Sous-agent en lecture seule	Le résultat se vérifie avec chemins et numéros de ligne
Choisir une architecture, une migration ou une limite de sécurité	Agent principal Sonnet/Opus	Il faut arbitrer un contexte large et un risque élevé
Modifier le code, lancer une migration, changer dépendances ou droits	Agent principal Sonnet/Opus	Le workspace change et exige une revue stricte
Décider puis implémenter le correctif final	Agent principal Sonnet/Opus	Il doit combiner les preuves et assumer le résultat

Test simple : pouvez-vous exprimer en une phrase ce qu’il faut chercher, ce qu’il faut rendre et quand s’arrêter, sans écrire de fichier ? Sinon, gardez la tâche dans la conversation principale.

Comprendre quatre contrôles de modèle différents

Claude Code comporte plusieurs mécanismes faciles à confondre :

1. Modèle de la conversation principale : sélectionné avec /model, une option de lancement ou les settings.
2. Champ model du frontmatter du sous-agent : appliqué à cette définition précise.
3. Alias ou Model ID complet : haiku est un alias dont la résolution dépend du fournisseur et de la version ; claude-haiku-5-5 est l’ID complet publié par Anthropic.
4. Remplacement d’un rôle ou forçage global : un agent personnalisé nommé Explore remplace seulement l’Explore intégré ; CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 touche presque tous les sous-agents.

La documentation officielle actuelle résout le modèle dans cet ordre : modèle de l’invocation, model de la définition de l’agent, CLAUDE_CODE_SUBAGENT_MODEL, puis modèle de la conversation principale. Ainsi, CLAUDE_CODE_SUBAGENT_MODEL seul n’est qu’une valeur par défaut ; il ne garantit pas de l’emporter sur le frontmatter ou l’invocation. Consultez la documentation des sous-agents Claude Code.

Pour ce workflow, commencez par un seul agent en lecture seule, clairement nommé. N’activez pas d’abord un forçage global : vous pourriez aussi déplacer Plan, general-purpose, teammates ou workflow agents vers le petit modèle.

Étape 1 : vérifier la version de Claude Code et les ID du fournisseur

Commencez par afficher la version :

claude --version

La version modifie l’interface et la méthode de vérification :

• À partir de Claude Code v2.1.198, /agents n’ouvre plus l’assistant de création. La commande invite à demander à Claude de créer le fichier ou à modifier directement .claude/agents/ et ~/.claude/agents/.
• En v2.1.197 et versions antérieures, /agents ouvre l’assistant interactif avec les onglets Running et Library.
• À partir de v2.1.242, /tasks affiche le modèle sur la ligne du sous-agent en cours. Sur une version plus ancienne, accordez davantage de poids au journal du fournisseur.
• N’utilisez CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 que si vous voulez délibérément imposer un modèle à tous les sous-agents. Cette fonction requiert v2.1.257 ou plus récent.

Vérifiez ensuite les ID exacts acceptés par votre fournisseur :

• Sur l’API Anthropic Claude, le Model ID officiel de Haiku 5.5 est claude-haiku-5-5. Consultez la page officielle du modèle.
• Sur une plateforme cloud ou une passerelle tierce, ne supposez pas que le même ID est déjà disponible. Le fournisseur peut utiliser un nom de déploiement, un alias propre ou un catalogue sélectionné.
• Lors de la vérification de ce guide, le 10 octobre 2026, le catalogue public BetterToken contenait claude-haiku-4-5-20251001, claude-sonnet-5-5 et claude-opus-5-5, mais pas claude-haiku-5-5. Avec BetterToken, choisissez un ID réellement présent dans le catalogue courant. Consultez le catalogue BetterToken actuel.

« Anthropic a publié le modèle » et « ma passerelle sert le modèle » sont deux faits distincts. Si l’ID n’apparaît pas dans le catalogue, une consigne verbale ou un alias de famille ne prouve pas la disponibilité.

Étape 2 : créer un sous-agent de projet en lecture seule

Les agents de projet résident dans .claude/agents/ et peuvent être maintenus avec le dépôt. Les agents utilisateur dans ~/.claude/agents/ sont disponibles dans tous vos projets.

Depuis la racine du dépôt, créez le répertoire :

mkdir -p .claude/agents

Créez .claude/agents/repo-researcher.md. Avec l’API Anthropic Claude, utilisez cette définition :

---
name: repo-researcher
description: Finds symbols, traces call paths, and summarizes selected files before code changes. Use only for bounded read-only repository research.
tools: Read, Grep, Glob
model: claude-haiku-5-5
---

You are a read-only repository researcher.

For each task:
1. Search only the scope named by the caller.
2. Do not edit, create, delete, or rename files.
3. Return file paths and line numbers for every important finding.
4. Separate direct evidence from inference.
5. Stop when the requested question is answered; do not propose unrelated refactors.

Return:
- Findings
- Evidence: file:line
- Uncertainties
- Suggested next check for the main agent

Trois détails comptent :

• tools n’autorise que Read, Grep et Glob, sans Write, Edit ni Bash.
• description précise quand déléguer et réduit le risque d’envoyer une modification au sous-agent.
• model utilise un ID complet accepté par le fournisseur, et non une simple phrase demandant Haiku.

Si Claude Code est connecté via BetterToken, le petit modèle Claude présent dans le catalogue vérifié était :

model: claude-haiku-4-5-20251001

Il s’agit d’un exemple du catalogue courant, pas d’une promesse permanente. Revérifiez le catalogue ou Model Plaza avant de changer le mapping. La documentation BetterToken pour Claude Code demande un Model ID exact et ANTHROPIC_BASE_URL défini sur https://bettertoken.ai, sans ajouter /v1. Consultez le guide Claude Code de BetterToken.

Si .claude/agents/ n’existait pas au démarrage de la session et que Claude Code ne voit pas le nouvel agent, redémarrez Claude Code une fois. La documentation officielle précise qu’un watcher déjà actif ne découvre pas le premier répertoire agents s’il était absent au lancement.

Étape 3 : garder l’agent principal sur Sonnet ou Opus

Choisissez séparément le modèle de la conversation principale, par exemple :

/model sonnet

ou :

/model opus

Avec une passerelle, le modèle final derrière un alias dépend de la passerelle et de son mapping. Utilisez un ID complet du fournisseur si vous devez fixer une version, puis vérifiez-le dans le journal de requêtes.

N’activez pas un forçage global uniquement pour placer un agent de recherche sur un petit modèle. La configuration suivante a une portée bien plus large :

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}

Utilisez-la seulement si vous voulez consciemment que Plan, les sous-agents general-purpose, teammates et workflow agents suivent le même modèle. Pour ne modifier que l’exploration automatique du code, définissez un agent de projet ou utilisateur nommé Explore avec son propre model. Il remplacera l’Explore intégré sans changer les autres.

Étape 4 : déclencher l’agent avec un test auditable

Ne commencez pas par « comprends tout le dépôt ». Choisissez une tâche étroite dont la réponse peut être contrôlée manuellement :

Use the repo-researcher agent to find every call site of PaymentService.createCharge.
Return file:line, the caller's purpose, and the path from the public entry point.
Do not edit files. Stop after covering this symbol and its direct callers.

Après l’exécution, vérifiez quatre points :

1. Le transcript principal contient une ligne de délégation vers repo-researcher ; l’agent principal n’a pas effectué la recherche silencieusement.
2. Le sous-agent a rendu des chemins et numéros de ligne, en séparant preuves et inférences.
3. L’arbre de travail n’a pas changé :

git status --short

4. Le jugement suivant et les éventuelles modifications restent sous la responsabilité de l’agent principal.

Si la recherche mérite d’être conservée, relisez-la d’abord dans la conversation principale. Demandez ensuite à l’agent principal d’enregistrer le résultat validé dans la documentation ou une issue. N’accordez pas l’écriture au sous-agent uniquement pour sauvegarder sa sortie.

Étape 5 : vérifier le modèle réellement exécuté

1. Contrôler la définition de l’agent sans s’y arrêter

Vérifiez que .claude/agents/repo-researcher.md contient l’ID complet voulu. Cela ne prouve que la configuration statique. Un modèle fourni à l’invocation, une politique d’organisation ou un mapping de passerelle peuvent encore modifier la requête.

2. Consulter /tasks pendant l’exécution

Exécutez :

/tasks

Claude Code v2.1.242 ou plus récent affiche le modèle sur la ligne du sous-agent. S’il diffère du fichier, vérifiez si :

• Claude a transmis un autre modèle pour cette invocation ;
• CLAUDE_CODE_SUBAGENT_MODEL_FORCE est activé ;
• une politique availableModels de l’organisation a substitué un modèle autorisé ;
• votre version utilise un ancien ordre de priorité.

3. Rapprocher l’enregistrement du fournisseur

Trouvez la requête dans la même fenêtre temporelle et contrôlez son Model ID réel. C’est particulièrement important avec une passerelle tierce, car l’alias affiché par le client peut être remappé côté passerelle.

BetterToken regroupe modèle, tokens, débit final et statut dans un même enregistrement. Pour ce workflow, utilisez uniquement les champs modèle et statut comme preuve ; n’en déduisez pas une économie non mesurée. Alignez d’abord l’horodatage de la requête avec la période d’exécution du sous-agent.

Utilisez une petite table d’acceptation :

Point de contrôle	Preuve attendue	Action en cas d’écart
Fichier agent	Model ID exact	Corriger l’ID, attendre le rechargement ou redémarrer si nécessaire
/tasks	Sous-agent visé et modèle en cours	Vérifier paramètres d’invocation, variables force et politique d’organisation
Journal fournisseur	Model ID réel et statut réussi dans la même fenêtre	Vérifier catalogue, mapping d’alias, routing et accès du compte
git status --short	Aucun changement inattendu	Restreindre tools, annuler les changements et relancer

N’inscrivez « changement de modèle vérifié » que lorsque les trois premiers points concordent. La mention de Haiku dans un prompt, le nom de l’agent dans l’interface ou une réponse terminée ne suffisent pas séparément.

Dépannage

L’agent n’est pas invoqué

Vérifiez que le fichier est dans .claude/agents/ ou ~/.claude/agents/, que le frontmatter contient name et description, et que le YAML est valide. Redémarrez Claude Code si le premier répertoire agents a été créé après le début de la session. S’il ne charge toujours pas, lancez Claude Code avec --debug et examinez l’erreur.

/agents n’affiche pas d’assistant

Ce n’est généralement pas une panne. À partir de v2.1.198, /agents recommande d’éditer directement les fichiers ; l’assistant interactif appartient à v2.1.197 et versions antérieures. Suivez la documentation de la version réellement installée, pas une ancienne capture.

model: haiku ne prouve pas Haiku 5.5

haiku est un alias, pas une version figée. Sa cible peut changer avec la version de Claude Code, le fournisseur ou le mapping de la passerelle. Pour un routing auditable, utilisez un ID complet du catalogue courant et vérifiez /tasks ainsi que l’enregistrement du fournisseur.

La passerelle renvoie model not found, 403 ou applique un fallback

Vérifiez d’abord que l’ID figure dans le catalogue actif et que le compte y a accès. Si claude-haiku-5-5 n’est pas listé, ne répétez pas indéfiniment la même valeur : choisissez un modèle adapté déjà publié ou attendez son ajout. Une allowlist d’organisation peut aussi substituer le modèle sans arrêter la tâche.

Tous les sous-agents sont passés au petit modèle

Recherchez et supprimez CLAUDE_CODE_SUBAGENT_MODEL_FORCE. Pour fixer un seul agent, placez l’ID complet dans son frontmatter. Pour ne changer que l’exploration automatique, remplacez Explore.

Le sous-agent a modifié des fichiers

Utilisez git status --short pour identifier la portée puis annulez les changements imprévus. Limitez ensuite tools à Read, Grep, Glob et répétez la contrainte de lecture seule dans le system prompt. Retirer les outils d’écriture est plus fiable qu’une simple consigne « ne modifie rien ».

Déploiement minimal

Commencez par cinq étapes :

1. Mettez Claude Code à jour et exécutez claude --version.
2. Copiez un Model ID complet réellement disponible dans le catalogue de votre fournisseur.
3. Créez un seul repo-researcher limité à Read, Grep et Glob.
4. Déclenchez-le avec une tâche limitée à un symbole ou un répertoire.
5. Comparez /tasks, le journal du fournisseur et git status --short.

Le but n’est pas d’envoyer toute la charge au plus petit modèle. Il s’agit d’établir une répartition auditable : le petit modèle rassemble des preuves en lecture seule et vérifiables, tandis que l’agent principal Sonnet ou Opus conserve les décisions et modifications à fort impact. Validez d’abord une tâche étroite, puis étendez le schéma seulement là où les mêmes critères d’acceptation restent applicables.