Claude Code como Orquestador: Usar Modelos mas Baratos para Sacar Proyectos Adelante

La mayoría de la gente usa Claude Code igual que usaba una ventana de chat: un modelo potente, una conversación larga, haciéndolo todo, desde leer el código hasta escribirlo y ejecutar las pruebas. Funciona, pero es lento, gasta tokens del modelo caro en tareas que uno más barato podría resolver, y la ventana de contexto se llena de ruido de cada archivo que el agente revisó por el camino.

Hay una forma mejor de pensarlo. Pensá en Claude Code como un pequeño equipo de ingeniería. Un modelo potente actúa como orquestador: entiende el objetivo, lo divide en partes y delega. Modelos más baratos y rápidos actúan como los trabajadores: exploran el código, hacen ediciones mecánicas y ejecutan las pruebas, y luego devuelven un resumen corto. El orquestador nunca ve las 4.000 líneas que leyó el trabajador, solo los dos párrafos que importan.

Este artículo muestra cómo armar eso para un proyecto real, con archivos .md listos para copiar, y un flujo que cubre el diseño, la implementación, la revisión y las pruebas.

El Modelo Mental: Orquestador y Trabajadores

La idea central se apoya en dos funciones de Claude Code: los subagentes y la selección de modelo por agente.

Un subagente es una instancia de Claude separada, con su propia ventana de contexto, su propio prompt de sistema, sus propios permisos de herramientas y su propio modelo. Cuando tu sesión principal delega una tarea a un subagente, ese subagente hace el trabajo de forma aislada y devuelve solo su respuesta final. Tu conversación principal se mantiene limpia.

Ese aislamiento es lo que hace posible el ahorro. Si una tarea de investigación va a leer veinte archivos, no querés esos veinte archivos ocupando el contexto de tu orquestador caro durante el resto de la sesión. Querés que un modelo barato los lea, los destile y te devuelva un resumen.

Este es el reparto de trabajo que uso:

Rol	Modelo	Qué hace
Orquestador (sesión principal)	Opus 4.8	Entiende el objetivo, planifica, delega, sintetiza, toma las decisiones de criterio
Explorador	Haiku 4.5	Busca en el código, encuentra archivos y patrones, reporta ubicaciones
Implementador	Sonnet 5	Escribe y edita código a partir de una especificación clara
Revisor	Sonnet 5	Lee un diff, señala bugs y problemas de estilo
Ejecutor de pruebas	Haiku 4.5	Ejecuta la suite de pruebas y el build, reporta si pasa o falla con la salida relevante

La regla práctica: usá el modelo más barato que pueda hacer el trabajo de forma fiable. Buscar y ejecutar comandos son tareas baratas. Escribir código con matices y revisarlo bien vale un modelo intermedio. Solo la coordinación y las decisiones de criterio difíciles necesitan el modelo más potente.

Paso 1: Dale una Memoria al Proyecto

Antes de definir ningún agente, escribí un CLAUDE.md en la raíz de tu proyecto. Este archivo se carga automáticamente en cada sesión y en cada subagente, así que es el lugar adecuado para los hechos que todo el “equipo” necesita conocer.

# Proyecto: taskflow-api

API REST para una app de gestión de tareas.

## Stack
- Node.js con TypeScript
- Fastify para la capa HTTP
- PostgreSQL vía Prisma
- npm como gestor de paquetes

## Convenciones
- Las rutas viven en `src/routes/`, un archivo por recurso
- La lógica de negocio va en `src/services/`, nunca en los handlers de ruta
- Toda la entrada de las peticiones se valida con esquemas de zod en `src/schemas/`
- Los errores se lanzan como `AppError` y los captura el handler de errores global

## Comandos
- `npm run dev` arranca el servidor de desarrollo con recarga en caliente
- `npm test` ejecuta la suite de vitest
- `npm run build` hace el chequeo de tipos y compila a `dist/`

Mantenelo corto. Un CLAUDE.md que pasa de doscientas líneas empieza a costarte contexto real en cada turno. Poné acá los hechos duraderos (stack, convenciones, comandos) y dejá los detalles pasajeros para la conversación.

También podés poner un CLAUDE.md dentro de un subdirectorio. Se carga solo cuando el agente empieza a trabajar con archivos de ese directorio, lo que mantiene la guía específica de un paquete fuera del contexto principal hasta que hace falta.

Paso 2: Define a los Trabajadores

Los subagentes viven en .claude/agents/ como archivos Markdown. El frontmatter en YAML configura el agente, y el cuerpo se convierte en su prompt de sistema. Los campos que más vas a usar son name, description, model y tools.

La description importa más de lo que parece. Claude la lee para decidir cuándo delegar en ese agente de forma automática, así que escribila como un disparador, no como un título.

El explorador (barato y de solo lectura)

---
name: explorer
description: Buscá en el código para localizar archivos, funciones y patrones. Usalo antes de cualquier cambio que toque código desconocido. Devuelve ubicaciones y resúmenes cortos, nunca edita.
model: haiku
tools: Read, Glob, Grep, Bash
---

Sos un agente rápido de investigación de código. Tu trabajo es encontrar
cosas y reportarlas de forma concisa.

- Localizá los archivos, funciones y puntos de llamada relevantes para la tarea dada.
- Reportá rutas de archivo con números de línea para que sean fáciles de abrir.
- Resumí en pocas frases cómo funciona el código existente.
- No propongas cambios y no edites nada. Encontrar y explicar es todo tu trabajo.

Correr esto en Haiku es deliberado. Buscar y leer es justo el tipo de trabajo de alto volumen y bajo criterio donde el modelo más barato se gana su lugar.

El implementador (intermedio, puede editar)

---
name: implementer
description: Escribí y editá código a partir de una instrucción clara y específica. Usalo cuando el diseño ya está decidido y sabés exactamente qué archivos cambian.
model: sonnet
tools: Read, Edit, Write, Bash
---

Implementás un cambio bien definido. Recibís una especificación: qué archivos
cambiar y cuál debe ser el resultado.

- Seguí al pie de la letra las convenciones de CLAUDE.md.
- Imitá el estilo del código de alrededor: nombres, imports, manejo de errores.
- Hacé el cambio y nada más. No refactorices código no relacionado.
- Después de editar, ejecutá el build o el comando correspondiente para confirmar que compila.
- Reportá qué cambiaste y cualquier decisión que hayas tenido que tomar.

El revisor (intermedio, de solo lectura)

---
name: reviewer
description: Revisá un diff o un conjunto de cambios recientes en busca de bugs de corrección y violaciones de convenciones. Usalo después de implementar, antes de dar una tarea por terminada.
model: sonnet
tools: Read, Grep, Bash
---

Revisás el código como un ingeniero senior cuidadoso revisa un pull request.

- Leé el diff y el código de alrededor para tener contexto.
- Señalá primero los bugs de corrección: errores de índice, awaits que faltan,
  errores no manejados, casos límite rotos.
- Después señalá las violaciones de convenciones frente a CLAUDE.md.
- Sé específico: citá el archivo y la línea, explicá la falla, sugerí el arreglo.
- No reescribas el código vos mismo. Reportá los hallazgos y dejá que el orquestador decida.

El ejecutor de pruebas (barato, mecánico)

---
name: test-runner
description: Ejecutá el build y la suite de pruebas, luego reportá si pasa o falla con la salida relevante. Usalo para verificar que un cambio funciona antes de seguir.
model: haiku
tools: Bash, Read
---

Ejecutás comandos de verificación y reportás resultados con claridad.

- Ejecutá los comandos de build y pruebas del proyecto (ver CLAUDE.md).
- Si todo pasa, decilo en una línea.
- Si algo falla, citá el error exacto y nombrá el archivo al que apunta.
- No intentes arreglar nada. Reportar con precisión es el trabajo.

Fijate en el patrón de los cuatro: cada trabajador es acotado, cada uno tiene un modelo acorde a la dificultad de su tarea, y a cada uno se le pide que reporte de vuelta en lugar de dispersarse. El orquestador (tu sesión principal, corriendo Opus) es lo que los conecta a todos.

Fijás el modelo de la sesión principal con /model opus dentro de una sesión, o lanzando con claude --model opus. Todo lo que sigue asume que la sesión principal es tu orquestador.

Paso 3: El Flujo de Trabajo

Con los trabajadores definidos, una funcionalidad real pasa por cuatro fases. El orquestador dirige todas y delega el trabajo pesado.

Diseño

Empezá en modo plan. Apretá Shift+Tab hasta que Claude Code esté en modo plan, lo que deja la sesión en solo lectura, así que el modelo explora y propone sin tocar nada.

En esta fase el orquestador delega la exploración al barato explorer para mapear el terreno, y luego hace el razonamiento él mismo, porque el diseño es una decisión de criterio que vale el modelo potente.

Vos: Quiero agregar paginación por cursor al endpoint GET /tasks.
     Planificalo. Usá el explorer para ver cómo funciona hoy ese endpoint.

Orquestador (Opus): [delega en explorer sobre Haiku]
Explorer (Haiku): GET /tasks se maneja en src/routes/tasks.ts, que llama a
     listTasks() en src/services/taskService.ts. Ese servicio ejecuta un
     findMany de Prisma sin límite ni cursor. La entrada de la query se valida
     con un esquema de zod en src/schemas/tasks.ts.

Orquestador: Este es el plan:
  1. Agregar los parámetros `limit` y `cursor` al esquema de tasks.
  2. Pasarlos a listTasks() y usar la paginación por cursor de Prisma.
  3. Devolver un `nextCursor` junto con los resultados.
  No hace falta migración de base de datos. ¿Lo aprobás?

Revisás el plan como humano. Este es el momento de mayor palanca de todo el ciclo, porque aprobar un buen plan es barato y detectar uno malo acá te ahorra una hora de implementación equivocada.

Implementación

Una vez que aprobás, el orquestador le entrega la especificación al implementer sobre Sonnet. La especificación es concreta porque la fase de diseño la hizo concreta.

Orquestador: [delega en implementer sobre Sonnet]
  "En src/schemas/tasks.ts, agregá los campos opcionales `limit` y `cursor` al
   esquema de la query de listado. En src/services/taskService.ts, actualizá
   listTasks() para que los acepte y use `take` y `cursor` de Prisma, devolviendo
   las filas y un `nextCursor`. Actualizá la ruta en src/routes/tasks.ts para
   pasarlos. Seguí las convenciones de CLAUDE.md."

Implementer (Sonnet): Actualizados el esquema, el servicio y la ruta. El
   chequeo de tipos pasa.

El orquestador no gastó tokens de Opus escribiendo un bucle for. Los gastó decidiendo qué debía hacer ese bucle.

Revisión

Nunca dejes que el modelo que escribió el código sea el único en juzgarlo. Delegá una revisión fresca en el reviewer, que lee el diff sin apego a la implementación.

Orquestador: [delega en reviewer sobre Sonnet]
Reviewer (Sonnet): Un problema. El campo `limit` no tiene tope superior, así
   que un cliente puede pedir toda la tabla con ?limit=1000000 y agotar la
   base de datos. src/schemas/tasks.ts:12. Ponele un tope, por ejemplo `.max(100)`.

Ese es un bug real que el implementador habría enviado tan tranquilo. Un revisor separado con contexto fresco detecta cosas ante las que el autor está ciego. Para una revisión más pesada podés usar el /review integrado para un pull request o el skill de code-review para el diff de trabajo.

Pruebas

Por último, el orquestador le pide al barato test-runner que verifique.

Orquestador: [delega en test-runner sobre Haiku]
Test runner (Haiku): npm test pasó, 47 pruebas en verde. npm run build hace el
   chequeo de tipos sin errores. GET /tasks?limit=20 devuelve 20 filas y un
   nextCursor.

Cuatro fases, cuatro modelos distintos aportando lo suyo, y el caro solo tocó las partes que necesitaban criterio.

Codifica el Flujo con un Comando

Cuando este ciclo te resulte natural, capturalo como un comando propio para no reescribirlo. Los comandos son archivos Markdown en .claude/commands/. El nombre del archivo se convierte en el comando, y $ARGUMENTS se reemplaza por lo que le pases.

---
description: Diseñá, implementá, revisá y probá una funcionalidad de principio a fin
argument-hint: <descripción de la funcionalidad>
---

Entregá esta funcionalidad usando el flujo completo: $ARGUMENTS

1. Usá el agente explorer para mapear el código relevante. No te lo saltees.
2. Proponé un plan corto y esperá mi aprobación antes de editar.
3. Una vez aprobado, delegá el cambio en el agente implementer.
4. Delegá una revisión en el agente reviewer y atendé los hallazgos reales.
5. Delegá la verificación en el agente test-runner.
6. Resumí qué cambió en tres líneas.

Guardá eso como .claude/commands/feature.md y vas a poder correr /feature agregá paginación por cursor al endpoint de tasks. El orquestador sigue la receta cada vez, lo que significa que la delegación a los trabajadores baratos ocurre por defecto en lugar de solo cuando te acordás de pedirla.

Automatiza lo Aburrido con Hooks

Los hooks te dejan ejecutar un comando de shell automáticamente cuando ocurren ciertos eventos, configurados en .claude/settings.json. El más útil para este flujo es correr tu chequeo de tipos o tu linter después de cada edición de archivo, para que los errores salgan a la luz de inmediato en lugar de en la revisión.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx tsc --noEmit 2>&1 | tail -10"
          }
        ]
      }
    ]
  }
}

Ahora, cada vez que cualquier agente edita un archivo, el chequeo de tipos se ejecuta y su salida vuelve al agente. Si un cambio introduce un error de tipos, el implementador lo ve y lo arregla en el acto, sin esperar a la fase de pruebas. Los hooks son deterministas, así que esto pasa se acuerde o no el modelo de chequear.

Una advertencia: un hook que corre un comando lento en cada edición hace que toda la sesión se arrastre. Mantené rápidos los comandos de los hooks, o acotá el matcher para que solo se disparen en los archivos que importan.

Por Qué Esto Sale mas Barato y Mejor

La ventaja obvia es el costo. Haiku cuesta una fracción del precio de Opus, así que empujar la búsqueda y la ejecución de pruebas hacia él suma rápido en una sesión larga. Pero la ventaja más importante es la calidad, y viene de la higiene del contexto.

Cuando un solo modelo lo hace todo, su contexto se llena de la salida cruda de cada búsqueda, cada lectura de archivo y cada comando fallido. Al final de una tarea larga termina razonando sobre una montaña de ruido. Cuando los trabajadores absorben ese volumen y devuelven resúmenes, el orquestador razona sobre una vista limpia y curada del proyecto. Toma mejores decisiones porque no está distraído.

La separación también crea puntos de control naturales. Un revisor dedicado con ojos nuevos detecta lo que el autor pasó por alto. Un planificador dedicado que aprobás antes de escribir una sola línea detecta direcciones equivocadas a tiempo. Son las mismas prácticas que hacen efectivos a los equipos humanos, aplicadas a un equipo de modelos.

Consejos Prácticos

Algunas cosas que aprendí a los golpes:

Escribí las descripciones como disparadores. Claude decide cuándo delegar según la description del agente. “Usalo antes de cualquier cambio que toque código desconocido” delega de forma fiable. “Agente de código” no.
Dale a los trabajadores las herramientas más acotadas que necesiten. Un explorador que no puede escribir no puede editar por accidente. La restricción es una ventaja, no una limitación.
No sobre-delegues. Arreglar un typo de una línea no necesita un pipeline de cinco agentes. El orquestador debería arreglarlo y listo. Reservá el ciclo completo para funcionalidades de verdad.
Mantené CLAUDE.md honesto. Cada agente confía en él. Un comando desactualizado o una convención equivocada en ese archivo se propaga a todos los trabajadores a la vez.
Aprobá planes, no solo diffs. El lugar más barato para arreglar un error es el plan, antes de escribir una sola línea.

Armar esto lleva una tarde. A partir de ahí, cada proyecto que toques recibe un pequeño equipo de especialistas en lugar de un generalista sobrecargado, y gastás tu propia atención en las decisiones que de verdad necesitan a un humano.

Si esto te resultó útil, compartilo con alguien que siga pasando cada tarea por un solo modelo.