Modelo, costo y orquestación

Haiku es el modelo más rápido y económico de la familia Claude. Ideal para tareas repetitivas que requieren poco razonamiento: leer archivos, buscar patrones, resumir fragmentos cortos y ejecutar comandos.

La mayoría de los subagentes de una flota no necesita un razonamiento profundo. Usar Haiku con ellos reduce el costo total hasta 10×. Elegir Opus para hacer un barrido es un error de presupuesto, no de calidad.

Costo por token muy bajo; menor latencia; contexto propio (empieza desde cero); no hereda el razonamiento del maestro: recibe instrucciones explícitas.

Sonnet equilibra la capacidad de razonamiento y el costo. Es excelente para escribir código, revisar PRs, sintetizar resultados de otros subagentes y tomar decisiones intermedias.

Es el modelo predeterminado de Claude Code. En la mayoría de los workflows, Sonnet se ocupa del «medio»: recibe datos sin procesar de Haiku y entrega material refinado para que Opus lo evalúe.

Excelente para generar código y sintetizar; costo medio; se usa como maestro en pipelines medianos; sustituye a Opus en el 80% de los casos sin una pérdida perceptible.

Opus tiene el razonamiento más profundo. Reservado para: decisiones arquitectónicas, evaluación de seguridad, síntesis de larga duración y situaciones donde equivocarse cuesta caro.

Usar Opus en toda la flota multiplica el costo por 5–20×. Saber identificar los momentos en que solo Opus sirve (y aquellos en que no hace falta) es la habilidad central de esta ruta.

Costo alto; mayor latencia; mejor para razonamiento de varias etapas; úsalo como jefe de una flotaHaiku/Sonnet; nunca en el bucle interno de subagentes baratos.

Todo subagente empieza con el contexto limpio. No sabe lo que acabas de discutir — necesita recibir instrucciones completas en su descripción y en los mensajes del maestro.

Un Haiku bien instruido supera a un Opus mal instruido. El modelo elegido solo importa después de que las instrucciones son correctas. La "trampa" es pagar más esperando que el modelo adivine el contexto.

Sin heredar el historial; el maestro pasa el contexto necesario mediante mensajes; CLAUDE_CODE_SUBAGENT_MODEL reemplaza el modelo predeterminado de la flota.

Una heurística simple: Haiku para «leer e informar», Sonnet para «construir y revisar», Opus para «decidir y diseñar la arquitectura». Aplícala a las tareas antes de codificar el subagente.

Los errores al asignar modelos son invisibles: el resultado parece igual, pero el costo es 5–10× mayor. Tener la tabla interiorizada evita decisiones automáticas de «usar el modelo más capaz».

Haiku: búsqueda, lectura, extracción y resumen. Sonnet: escritura, código, síntesis y revisión. Opus: arquitectura, seguridad, evaluación final y razonamiento profundo.

Dado un pipeline hipotético con 6 tareas (revisar logs, escribir pruebas, revisar un PR, proponer una arquitectura, buscar documentación, evaluar la seguridad), asigna el modelo adecuado a cada una.

La práctica de asignación consolida la heurística. Equivocarse en el ejercicio cuesta poco; equivocarse en un sistema real con 100 subagentes cuesta mucho.

Criterio de evaluación: costo estimado × calidad esperada. Hay una guía comentada en el módulo completo.

Cada subagente tiene su propio contexto, prompt de sistema y comunicación de ida y vuelta con la API. Con 10 subagentes ejecutándose en paralelo, la cantidad de tokens consumidos se multiplica rápidamente.

Sin esta conciencia, es fácil crear workflows que cuestan decenas de dólares por ejecución. Conocer el multiplicador permite planificar con anticipación y saber cuándo el enfoque multiagente vale el precio.

Costo por ejecución = (tokens de entrada + salida) × precio × nº de subagentes; el prompt del sistema se repite por agente; el contexto que pasa el maestro también cuenta.

El jefe (Opus o Sonnet) orquesta el trabajo: decide la estrategia, descompone las tareas y evalúa los resultados. La flota (Haiku) ejecuta en paralelo: lee, busca, extrae e informa.

Es el patrón con la mejor relación costo-beneficio: un solo agente costoso toma las decisiones inteligentes mientras muchos agentes económicos hacen el trabajo mecánico. La calidad aumenta y el costo promedio por resultado disminuye.

1 jefe, N trabajadores; el jefe evalúa y consolida; los trabajadores informan; la decisión de "qué hacer" queda en el jefe, y el "cómo hacerlo" en la flota.

Variable de entorno que obliga a todos los subagentes a usar un modelo específico, independientemente del valor predeterminado del sistema. Útil para controlar el costo en lotes grandes.

Sin esta variable, los subagentes usan el modelo predeterminado, que puede ser Sonnet u Opus. Con ella, te aseguras de que toda la flota use Haiku sin cambiar el código de cada agente.

`CLAUDE_CODE_SUBAGENT_MODEL=claude-haiku-4-5` en el entorno; sobrescribe solo los subagentes (el agente principal mantiene el modelo original); útil en workflows de alta escala.

Parámetro que limita cuántas rondas de ida y vuelta puede hacer un subagente. Cada turno consume tokens. Sin límite, un agente atrapado en un bucle puede gastar indefinidamente.

Los subagentes a veces entran en ciclos de ensayo y error. Con `maxTurns` definido, el costo máximo por ejecución es predecible, y el agente falla de forma controlada en vez de gastar recursos silenciosamente.

Configurado en el CLAUDE.md del subagente o mediante SDK; valor típico: 10–20 turnos; después del límite, el agente devuelve lo que tiene hasta ese momento.

Criterios objetivos para decidir: tareas paralelas que llevarían 10+ min cada una si se hicieran secuencialmente; jobs con una "pared de output" que causarían truncamiento en un solo contexto; codebase con 10+ archivos interdependientes.

Usar varios agentes para tareas pequeñas es pagar 15× por un 0% de ganancia real. Un criterio claro evita ese desperdicio y justifica el costo cuando la tarea realmente lo requiere.

Señal positiva: paralelismo genuino, separación de contexto, mucho contenido de salida. Señal negativa: tarea secuencial breve, necesidad de contexto compartido, resultado simple.

Dado un trabajo de análisis de repositorio (identificar code smells en 50 archivos), diseña la división: quién es el agente jefe, cuántos trabajadores hay, qué modelo usar para cada rol y cómo se consolida el resultado.

Diseñar antes de implementar evita rediseños costosos. El ejercicio obliga a pensar en la granularidad de las tareas, el costo estimado y los puntos de falla.

Entregable: diagrama sencillo (puede ser texto estructurado) con roles, modelos, flujo de datos y estimación del costo por ejecución.

El maestro es el agente principal que recibe la tarea del usuario, la divide en subtareas y asigna cada una a un subagente. Espera los resultados, los consolida y entrega la respuesta final.

Sin un maestro explícito, no hay coordinación: los subagentes no "conversan" entre sí. Reconocer al maestro como punto único de orquestación es la pieza central del diseño de workflows.

Topología en estrella: el maestro en el centro, los subagentes en los extremos; el maestro pasa contexto explícitamente a cada subagente; los resultados vuelven al maestro, nunca circulan entre subagentes.

Un agente (CLAUDE.md) no puede invocar directamente a otro agente. La invocación ocurre mediante una skill (que puede llamar a agents) o a través del propio Claude Code cuando ejecuta un workflow de nivel superior.

Diseñar un agent que intenta llamar a otro agent provoca un error de ejecución o un comportamiento indefinido. Conocer este límite evita arquitecturas imposibles y sugiere el camino correcto (mediante una skill).

El agent llama a una skill; la skill llama a un agent; el agent no llama a otro agent. El ciclo de control siempre queda en el Claude Code principal o en una skill orquestadora.

Una skill (archivo de instrucciones `.md`) puede contener lógica que activa varios agents en secuencia o en paralelo. Es el patrón correcto para crear pipelines complejos sin incumplir la regla de que los agents no llaman a otros agents.

Las skills son el «pegamento» del ecosistema. Entender cómo una skill activa agentes te permite construir workflows de N etapas sin necesitar un agente especial de orquestación.

Skill = instrucción para Claude Code; Claude Code ejecuta el agente invocado; la skill define la secuencia lógica; el estado intermedio se puede pasar mediante archivos o mensajes.

Cuando el resultado de A es necesario para que B empiece, y el resultado de B es necesario para que C empiece, tenemos una canalización secuencial. El maestro espera cada etapa antes de iniciar la siguiente.

Mezclar lo secuencial con lo paralelo sin darte cuenta genera condiciones de carrera o resultados incorrectos. Identificar las dependencias entre tareas es el primer paso para diseñar cualquier pipeline.

Dependencia de datos = secuencial; independencia = paralelo; el maestro decide el orden según las dependencias; pasar el output de A como input de B mediante un mensaje o un archivo.

Cada subagente se comunica solo con el maestro que lo invocó. No hay un canal lateral entre el subagente A y el subagente B. Para que A «le pase algo» a B, el maestro debe intervenir.

Los proyectos que suponen una comunicación directa entre subagentes no funcionan. Conocer este límite antes de diseñar evita arquitecturas que parecen elegantes en teoría, pero son imposibles en la práctica.

Maestro es el único punto de unión; las «conversaciones» entre subagentes son una ilusión: el maestro hace de intermediario; usa archivos compartidos cuando dos agentes necesitan el mismo dato.

Diseña (en texto o en un diagrama) un pipeline de 3 etapas para el trabajo: «buscar issues abiertas → priorizar por impacto → redactar comentarios de clasificación». Identifica qué etapas son secuenciales y cuáles pueden ejecutarse en paralelo.

La habilidad de descomponer un job en etapas con dependencias claras es la base de cualquier orquestación. Equivocarse aquí es el error más común de quienes empiezan con multiagentes.

Entregable: diagrama con flechas dirigidas, modelos elegidos, puntos de handoff y mecanismo para pasar datos (mensaje o archivo).

El agente que construyó un artefacto lleva en su contexto todo el historial de decisiones que lo condujeron a ese resultado. Ese contexto induce un sesgo de confirmación: tiende a validar lo que ya decidió.

Un revisor con contexto limpio no tiene acceso al «porqué» de las decisiones: solo ve el resultado. Ese aislamiento genera críticas más objetivas e identifica problemas que el builder ignoró.

Contexto limpio = empieza desde cero; no hereda la "lógica interna" del builder; recibe solo el artefacto + los criterios de evaluación; produce comentarios sin anclarse en las decisiones originales.

El builder recibe la tarea y produce el artefacto (código, plan, investigación). El reviewer recibe el artefacto + los criterios y produce un informe de calidad. Son dos subagentes distintos, convocados en secuencia por el maestro.

La separación de roles aumenta la calidad sin aumentar la complejidad de cada agente: cada uno hace una cosa y la hace bien. El maestro decide si los comentarios requieren una nueva iteración del builder.

Flujo: maestro → builder (produce) → maestro → reviewer (critica) → maestro (decide si iterar o publicar); el reviewer no tiene acceso al proceso interno del builder.

El patrón builder-reviewer funciona con cualquier tipo de artefacto: código (el revisor verifica errores y estilo), plan (el revisor verifica la viabilidad y los riesgos), investigación (el revisor verifica las fuentes y la coherencia).

Reconocer que el mismo patrón se aplica en distintos dominios permite reutilizar la misma arquitectura de orquestación: solo cambia el criterio que se le pasa al revisor, no el pipeline.

Criterios explícitos en el prompt del reviewer; específicos del dominio (código: corrección, estilo; plan: viabilidad, riesgo; investigación: fuentes, coherencia); el revisor entrega un informe estructurado.

`plan-roaster` y `code-reviewer` son subagentes disponibles en el ecosistema Claude Code que implementan el patrón de revisor. Son ejemplos concretos para estudiar y adaptar.

Estudiar un revisor existente revela cómo se transmite el criterio, cómo se estructura el output, qué modelo usar para la revisión y cómo el maestro utiliza el resultado. Es más rápido que diseñarlo desde cero.

El revisor recibe: artefacto + criterios + alcance; produce: informe con hallazgos categorizados por severidad; el maestro decide qué hacer según el informe.

Después de que el revisor entregue el informe, el director decide: ¿los hallazgos son críticos (nueva iteración del builder) o aceptables (publicar)? Este ciclo puede repetirse 2–3 veces antes de llegar a un criterio de parada.

Sin un criterio de detención, el ciclo puede ejecutarse indefinidamente. Definir "cuándo es suficientemente bueno" antes de ejecutar es tan importante como diseñar los agentes.

Criterio de parada: cero hallazgos críticos, o alcanzar N iteraciones, o llegar al límite de costo; el maestro codifica el criterio; el revisor informa la severidad para facilitar la decisión.

Usa como artefacto el diagrama de pipeline que creaste en M3.3. Dáselo a un revisor (puedes ser tú mismo con «contexto limpio» o un subagente code-reviewer) con estos criterios: viabilidad, eficiencia y puntos de falla.

Revisar el propio trabajo con una mirada externa (aunque sea simulada) es la habilidad de metacalidad. El ejercicio cierra el ciclo M3.3 → M3.4: ya construiste y ahora evalúas.

Entregable: informe con hallazgos (al menos 1 mejora identificada); reflexiona sobre qué cambiarías en el diagrama de M3.3 después de la revisión.

`ultracode` (anteriormente llamado "workflow") es el disparador que instruye a Claude Code para operar en modo de alta escala: descompone el job en decenas de tareas paralelas y activa subagentes para cada una.

Activar `ultracode` para trabajos pequeños desperdicia presupuesto. Saber qué hace el disparador internamente permite usarlo con precisión — solo cuando la escala lo justifica.

Modo de planificación automática + paralelización agresiva; Claude Code estima el número de subagentes antes de ejecutar; puedes confirmar o cancelar; costo estimado visible antes del commit.

Caso real documentado en el que un solo job lanzó 41 subagentes en paralelo para refactorizar un repositorio grande. El resultado se entregó en una fracción del tiempo que habría tomado hacerlo de forma secuencial.

El caso concreto sirve de ancla para el concepto: no es teoría. Muestra qué es posible, cuál fue el costo real y qué aciertos y problemas se encontraron en la ejecución a gran escala.

41 subagentes Haiku; maestro Sonnet; tarea: refactorizar más de 80 archivos; costo estimado: ~$8 en la ejecución; tiempo total: ~6 min frente a ~2h secuenciales; cobertura de pruebas mantenida.

Las sesiones con decenas de subagentes consumen tokens rápidamente. Los límites de tasa de la API (rate limits) y los límites de sesión de Claude Code pueden interrumpir un workflow a la mitad.

No planificar el presupuesto antes de un ultracode lleva a trabajos incompletos y a un costo desperdiciado. Entender los límites permite dimensionar correctamente el trabajo o dividirlo en lotes más pequeños.

Límites de solicitudes por minuto y por día; límite de sesión de Claude Code (tokens por ventana); estrategia de batching: dividir en grupos de 10–20 subagentes para respetar los límites.

Lista de verificación práctica: más de 10 archivos por modificar, tareas genuinamente paralelas (sin dependencias entre sí), resultado esperado que causaría truncamiento en un único contexto, refactorización a gran escala, análisis en paralelo de varios módulos.

La checklist evita decidir por intuición. Con ella, llegas a «sí/no para workflow» en 30 segundos, antes de ejecutar cualquier cosa.

Cualquier «sí» rotundo en la checklist apunta a workflow; señales de alerta: tarea pequeña, necesidad de compartir contexto, resultados interdependientes; si tienes dudas, no uses workflow.

En workflows de más de 40 subagentes, se esperan fallas parciales. El maestro debe detectar qué subtareas fallaron y decidir: volver a intentarlo, ignorarlas o abortar todo el job.

Los jobs sin una estrategia de recuperación fallan por completo cuando falla cualquier subagente. Diseñar el manejo de fallas antes de la ejecución reduce el costo de retrabajo y aumenta la robustez.

Registro de resultados por subagente; identificar los fallidos por id; estrategia «retry once, then skip»; el maestro consolida e indica incomplete donde sea necesario.

Dados 3 escenarios (A: refactorizar 1 archivo; B: analizar 100 PRs cerrados; C: escribir pruebas para 15 módulos), aplica la checklist y responde: ¿workflow o no? Justifica cada decisión.

La práctica de tomar una decisión binaria con justificación es la habilidad clave del módulo. Las respuestas sin justificación no cuentan: el razonamiento es el entregable, no el sí o no.

Respuestas: A = no (un único archivo); B = sí (100 tareas paralelas independientes); C = sí (15 módulos separables); el módulo completo incluye un análisis detallado de cada caso.

N subagentes que se ejecutan al mismo tiempo, cada uno con su propia tarea aislada, sin dependencias entre sí. El maestro los inicia a todos y espera a que terminen para consolidar.

Es el patrón más eficiente para tareas uniformes a gran escala: analizar N archivos, buscar N documentos, generar N borradores. Identificar cuándo las tareas son realmente independientes es un requisito previo.

Independencia total: ningún subagente necesita el resultado de otro; el maestro sincroniza al final; costo = N × costo individual; speedup = N× (limitado por el rate limit).

Etapas A → B → C, donde el output de cada etapa es el input de la siguiente. El maestro ejecuta una a la vez, espera cada resultado antes de continuar.

Para tareas con dependencias de datos, el pipeline es el único patrón correcto. Forzar el paralelismo cuando hay dependencias genera errores o resultados inconsistentes: reconocer las dependencias es esencial.

Latencia total = suma de las latencias individuales; no hay aceleración por paralelismo; cada etapa puede usar un modelo diferente (ej.: Haiku recopila, Sonnet sintetiza, Opus decide).

1 entrada → N subagentes en paralelo → 1 resultado agregado. El maestro inicia N workers con distintas partes del problema, espera a todos y pasa los N resultados a un agregador que sintetiza el resultado final.

Fan-out es el patrón de ultracode. Entender la estructura "dispatcher → workers → aggregator" te permite diseñar cualquier workflow de alta escala y entender lo que hace Claude Code por debajo cuando usas ultracode.

Dispatcher: maestro que divide la entrada; workers: Haiku/Sonnet en paralelo; aggregator: agente separado (Sonnet/Opus) que consolida; resultado final: único, coherente y completo.

Los agent teams son configuraciones en las que varios agentes comparten contexto y se comunican directamente — a diferencia de los subagentes clásicos con topología de estrella. Cuestan más porque mantienen abiertos varios contextos.

Saber la diferencia evita confundir las dos arquitecturas. Los equipos de agentes son poco comunes en Claude Code y, por lo general, más costosos y complejos. Para la mayoría de los casos, los subagentes con un maestro central son más eficientes.

Subagentes: topología en estrella, maestro central, contextos aislados, menor costo. Agent teams: grafo de comunicación, contextos parcialmente compartidos, mayor costo, menos común.

Heurística práctica: si el trabajo implica más de 10 archivos separables O produciría un resultado que se truncaría en un solo contexto, usa fan-out o ejecución en paralelo. De lo contrario, usa un pipeline secuencial o un solo agente.

Tener una heurística numérica evita el análisis detallado para cada job. "10 archivos" es el threshold práctico derivado de la experiencia real: por debajo de eso, el overhead del multiagente generalmente no compensa.

10 archivos = ~umbral de overhead; «pared de output» = resultado que causaría > 50% del contexto; ambos son indicadores, no reglas absolutas; el juicio final es del operador.

Dados 3 problemas (A: traducir 30 archivos Markdown; B: generar notas de la versión a partir de 50 commits analizados en orden; C: revisar código + proponer una refactorización + implementarla), elige la topología y justifica tu elección.

El ejercicio cierra el recorrido: aplicas el vocabulario de topologías a problemas reales. Respuestas: A = paralelo independiente; B = fan-out + pipeline (recopilación en paralelo, síntesis secuencial); C = pipeline (3 etapas dependientes).

Entregable: tabla problema × topología × justificación × modelos elegidos. El módulo completo incluye una implementación de referencia para cada caso.