Usar Haiku 5.5 como subagente de solo lectura en Claude Code y verificar el modelo

El patrón más seguro no consiste en mover toda la sesión de Claude Code a un modelo pequeño. Conviene asignar a Haiku 5.5 únicamente tareas acotadas, de solo lectura y fáciles de comprobar: buscar referencias a símbolos, seguir importaciones, localizar configuración o resumir un conjunto definido de archivos. La conversación principal puede seguir en Sonnet u Opus para tomar decisiones, editar, ejecutar pruebas y aprobar el resultado final.

Una configuración no queda demostrada porque el prompt diga «usa Haiku» o porque un archivo contenga model: haiku. Necesitas tres niveles de evidencia: el modelo explícito en la definición del agent, el modelo que Claude Code muestra durante la ejecución y el Model ID real en el registro de solicitudes del proveedor. Considera verificado el cambio solo cuando los tres coincidan.

Decide qué trabajo se puede delegar

Anthropic presenta Haiku 5.5 para cargas rápidas y repetitivas como resúmenes, compaction, consultas de base de datos y clasificación. Su anuncio también lo sitúa como subagente de programación junto a Sonnet 5.5 u Opus 5.5, mientras que recomienda modelos mayores para el agentic coding complejo. Consulta el anuncio de Haiku 5.5.

Puedes empezar con esta división:

Tarea	Responsable recomendado	Motivo
Encontrar todas las referencias a una clase, función o ajuste	Subagente de solo lectura con modelo pequeño	La entrada, la salida y el criterio de parada están claros
Resumir la función de los archivos de un directorio	Subagente de solo lectura	Requiere leer y sintetizar, no modificar
Seguir una solicitud desde el punto de entrada hasta la base de datos	Subagente de solo lectura	Se valida con rutas y números de línea
Elegir arquitectura, estrategia de migración o límites de seguridad	Agente principal Sonnet/Opus	Exige ponderar contexto amplio y riesgo
Modificar código, ejecutar migraciones, actualizar dependencias o permisos	Agente principal Sonnet/Opus	Cambia el espacio de trabajo y requiere revisión estricta
Decidir e implementar la corrección final	Agente principal Sonnet/Opus	Debe integrar las pruebas y asumir el resultado

Una regla útil: ¿puedes expresar en una sola frase qué debe buscar, qué debe devolver y cuándo debe detenerse, sin escribir archivos? Si no, mantén la tarea en la conversación principal.

Entiende cuatro controles distintos del modelo

En Claude Code es fácil mezclar varios mecanismos:

1. Modelo de la conversación principal: se selecciona con /model, una opción de inicio o la configuración.
2. Campo model del frontmatter del subagente: se aplica a esa definición concreta.
3. Alias frente a Model ID completo: haiku es un alias cuya resolución puede cambiar según proveedor y versión; claude-haiku-5-5 es el ID completo publicado por Anthropic.
4. Sustitución de una sola función frente a imposición global: un agent personalizado llamado Explore reemplaza únicamente el Explore integrado; CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 afecta a casi todos los subagentes.

La documentación oficial actual resuelve el modelo en este orden: modelo indicado para la invocación, model de la definición del agent, CLAUDE_CODE_SUBAGENT_MODEL y, por último, el modelo de la conversación principal. Por eso CLAUDE_CODE_SUBAGENT_MODEL por sí solo es un valor predeterminado, no una garantía de que prevalezca sobre el frontmatter o la invocación. Consulta la documentación de subagentes de Claude Code.

Para este flujo, empieza con un agent de solo lectura, explícito y con nombre propio. No actives primero una imposición global: podrías mover también Plan, general-purpose, teammates o workflow agents al modelo pequeño.

Paso 1: comprueba la versión de Claude Code y los ID del proveedor

Primero consulta la versión:

claude --version

La versión cambia la interfaz y la forma de verificar:

• En Claude Code v2.1.198 o posterior, /agents ya no abre el asistente de creación; indica que pidas a Claude crear el archivo o edites directamente .claude/agents/ y ~/.claude/agents/.
• En v2.1.197 o anterior, /agents abre el asistente interactivo con las pestañas Running y Library.
• En v2.1.242 o posterior, /tasks muestra el modelo en la fila del subagente en ejecución. En versiones anteriores, concede más peso al registro del proveedor.
• Usa CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 solo si quieres imponer deliberadamente un modelo a todos los subagentes. Requiere v2.1.257 o posterior.

Después confirma los ID exactos que acepta tu proveedor:

• En la API de Anthropic Claude, el Model ID oficial de Haiku 5.5 es claude-haiku-5-5. Consulta la página oficial del modelo.
• En una plataforma cloud o un gateway de terceros, no des por hecho que ese mismo ID ya está disponible. Puede existir un nombre de despliegue, un alias propio o un catálogo limitado.
• Cuando se revisó esta guía, el 10 de octubre de 2026, el catálogo público de BetterToken incluía claude-haiku-4-5-20251001, claude-sonnet-5-5 y claude-opus-5-5, pero no claude-haiku-5-5. Si usas BetterToken, elige un ID que aparezca realmente en el catálogo actual. Consulta el catálogo actual de BetterToken.

«Anthropic ha publicado el modelo» y «mi gateway sirve el modelo» son hechos distintos. Si el ID no figura en el catálogo del proveedor, una instrucción verbal o un alias de familia no demuestran compatibilidad.

Paso 2: crea un subagente de proyecto de solo lectura

Los agents de proyecto viven en .claude/agents/ y se pueden mantener junto al repositorio. Los agents de usuario en ~/.claude/agents/ están disponibles en todos tus proyectos.

Desde la raíz del repositorio, crea el directorio:

mkdir -p .claude/agents

Crea .claude/agents/repo-researcher.md. Con la API de Anthropic Claude, usa esta definición:

---
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

Hay tres detalles importantes:

• tools permite solo Read, Grep y Glob; no concede Write, Edit ni Bash.
• description define cuándo procede la delegación, reduciendo el riesgo de enviar una modificación al subagente.
• model contiene un ID completo aceptado por el proveedor, no solo una frase que pide Haiku.

Si Claude Code está conectado mediante BetterToken, el modelo Claude pequeño que figuraba en el catálogo revisado era:

model: claude-haiku-4-5-20251001

Es un ejemplo del catálogo actual, no una promesa permanente. Vuelve a consultar el catálogo o Model Plaza antes de cambiar el mapping. La documentación de BetterToken para Claude Code indica que debes usar un Model ID exacto y configurar ANTHROPIC_BASE_URL como https://bettertoken.ai, sin añadir /v1. Consulta la guía de Claude Code de BetterToken.

Si .claude/agents/ no existía cuando empezó la sesión y Claude Code no encuentra el nuevo agent, reinicia Claude Code una vez. La documentación oficial explica que el watcher de una sesión en curso no detecta el primer directorio agents si no existía al arrancar.

Paso 3: mantén el agente principal en Sonnet u Opus

El modelo de la conversación principal se elige por separado. Por ejemplo:

/model sonnet

o:

/model opus

Con un gateway, el modelo final al que apunta un alias depende del gateway y de su mapping. Si necesitas fijar una versión, utiliza un ID completo del catálogo del proveedor y confírmalo después en el registro.

No actives una imposición global solo para colocar un agent de investigación en un modelo pequeño. Esta configuración tiene un alcance mucho mayor:

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

Úsala únicamente cuando quieras que Plan, los subagentes general-purpose, teammates y workflow agents sigan el mismo modelo. Si solo quieres cambiar la exploración automática del código, define un agent de proyecto o de usuario llamado Explore y asígnale su propio model. Sustituirá al Explore integrado sin cambiar los demás.

Paso 4: activa el agent con una prueba auditable

No empieces con «comprende todo el repositorio». Elige una tarea estrecha cuya respuesta puedas revisar manualmente:

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.

Después de la ejecución, comprueba cuatro cosas:

1. El transcript principal contiene una fila de delegación a repo-researcher; el agente principal no hizo la búsqueda silenciosamente.
2. El subagente devolvió rutas y números de línea, y separó evidencia de inferencias.
3. El árbol de trabajo no cambió:

git status --short

4. La decisión posterior y cualquier modificación siguen a cargo del agente principal.

Si merece la pena guardar la investigación, revísala primero en la conversación principal. Después deja que el agente principal escriba el resultado aceptado en la documentación o en un issue. No concedas escritura al subagente únicamente para persistir su salida.

Paso 5: verifica el modelo que se ejecutó de verdad

1. Revisa la definición del agent, pero no te detengas ahí

Comprueba que .claude/agents/repo-researcher.md contiene el ID completo previsto. Esto demuestra solo la configuración estática. Un modelo indicado para esa invocación, una política de organización o un mapping del gateway pueden cambiar la solicitud.

2. Revisa /tasks mientras se ejecuta

Ejecuta:

/tasks

Claude Code v2.1.242 o posterior muestra el modelo en la fila del subagente. Si difiere del archivo, comprueba si:

• Claude pasó otro modelo en esta invocación;
• está habilitado CLAUDE_CODE_SUBAGENT_MODEL_FORCE;
• una política availableModels de la organización sustituyó el modelo;
• tu versión usa una regla de prioridad anterior.

3. Relaciona el registro de solicitud del proveedor

Busca la solicitud dentro del mismo intervalo temporal y revisa su Model ID real. Es especialmente importante con un gateway de terceros, porque el alias visible en el cliente puede volver a mapearse en el gateway.

BetterToken presenta el modelo, los tokens, el cargo final y el estado en una misma solicitud. Para este flujo utiliza únicamente los campos de modelo y estado como evidencia; no conviertas ese registro en una afirmación de ahorro no demostrada. Relaciona primero la hora de la solicitud con la ventana de ejecución del subagente.

Puedes usar esta tabla de aceptación:

Punto de control	Evidencia esperada	Qué hacer si no coincide
Archivo del agent	Model ID exacto	Corrige el ID y espera la recarga o reinicia si es necesario
/tasks	Subagente objetivo y modelo en ejecución	Revisa parámetros de invocación, variables force y política de organización
Registro del proveedor	Model ID real y estado correcto en la misma ventana	Revisa catálogo, mapping de alias, routing y acceso de la cuenta
git status --short	Ningún cambio inesperado	Restringe tools, revierte cambios y repite la prueba

Registra «cambio de modelo verificado» solo cuando coincidan los tres primeros niveles. Que el prompt mencione Haiku, que aparezca el nombre del agent o que haya una respuesta no es suficiente por separado.

Solución de problemas

El agent no se invoca

Confirma que el archivo está en .claude/agents/ o ~/.claude/agents/, que el frontmatter contiene name y description, y que el YAML es válido. Reinicia Claude Code si el primer directorio agents se creó tras iniciar la sesión. Si sigue sin cargarse, ejecuta Claude Code con --debug y revisa el error.

/agents no muestra el asistente

Normalmente no es un fallo. En v2.1.198 o posterior, /agents indica que edites los archivos directamente. El asistente interactivo pertenece a v2.1.197 o anterior. Sigue la documentación de la versión que ejecutas, no una captura antigua.

model: haiku no demuestra Haiku 5.5

haiku es un alias, no una versión fijada. Su destino puede cambiar con la versión de Claude Code, el proveedor o el mapping del gateway. Para un routing auditable, usa un ID completo del catálogo actual y comprueba /tasks y el registro del proveedor.

El gateway devuelve model not found, 403 o aplica fallback

Primero verifica que el ID figura en el catálogo vivo y que la cuenta tiene acceso. Si no aparece claude-haiku-5-5, no repitas indefinidamente ese valor: elige un modelo adecuado que sí esté listado o espera a que el gateway lo incorpore. Una allowlist de organización también puede sustituir el modelo sin detener la tarea.

Todos los subagentes cambiaron al modelo pequeño

Busca y elimina CLAUDE_CODE_SUBAGENT_MODEL_FORCE. Para fijar solo un agent, coloca el ID completo en su frontmatter. Para cambiar únicamente la exploración automática, sustituye Explore.

El subagente modificó archivos

Usa git status --short para identificar el alcance y revierte los cambios no deseados. Después limita tools a Read, Grep, Glob y repite la frontera de solo lectura en el system prompt. Quitar herramientas de escritura es más fiable que limitarse a decir «no edites».

Despliegue mínimo recomendado

Empieza con cinco pasos:

1. Actualiza Claude Code y ejecuta claude --version.
2. Copia un Model ID completo y disponible desde el catálogo actual de tu proveedor.
3. Crea un solo repo-researcher limitado a Read, Grep y Glob.
4. Actívalo con una tarea limitada a un símbolo o directorio.
5. Compara /tasks, el registro del proveedor y git status --short.

El objetivo no es enviar todo al modelo más pequeño, sino establecer una división de trabajo auditable: el modelo pequeño reúne evidencia de solo lectura que se puede comprobar; el agente principal Sonnet u Opus conserva las decisiones y cambios de mayor impacto. Verifica primero una tarea estrecha y amplía el patrón solo cuando puedas mantener los mismos criterios de aceptación.