🎚️ Modelo por tarea

Piensa en una taller mecánico. Para cambiar una llanta no llamas al ingeniero jefe: mandas al ayudante, es rápido y económico. Para reconstruir el motor, ahí sí entra el maestro. Los modelos de IA funcionan igual: existe un tier bajo (rápido, barato, excelente para trabajo pesado), un tier medio (el operario competente que construye y revisa) y un tier alto (el maestro al que solo recurres cuando el problema exige un razonamiento de verdad). En Claude Code estos tres son Haiku, Sonnet e Opus — y cada subagente puede ejecutar el suyo.

↑ La escalera de tiers: cada peldaño hacia arriba aporta más razonamiento, pero cuesta más y aumenta la latencia. Sube solo hasta donde lo exija la tarea.

Haiku es el nivel barato y rápido. Destaca en el trabajo mecánico de alto volumen: escanear una carpeta entera, buscar una cadena en cientos de archivos, resumir un registro enorme, leer documentación y devuelve los 5 puntos que importan. Tareas en las que la respuesta es «encuentra e informa», no «piensa a fondo».

Sonnet es el nivel medio — el caballo de batalla del día a día. Él construye (escribe código, crea archivos, implementa un paso de un plan) y revisa (lee un diff y señala errores). Es lo bastante inteligente para la mayoría de las tareas reales y aun así mucho más barato que el tier alto. Cuando tienes dudas, Sonnet suele ser la opción segura por defecto.

Opus es el nivel caro y más lento, reservado para lo que realmente requiere razonamiento profundo: decisiones de arquitectura, análisis de seguridad, planificación delicada, depuración de un problema que nadie entiende. Aquí el costo extra vale la pena: un error de arquitectura cuesta mucho más que unos cuantos tokens adicionales.

Subir de tier no es solo «ser más inteligente». Son tres diales que se mueven juntos: más razonamiento viene con más costo y más latencia (tarda más en responder). Elegir un modelo es decidir de cuánto de cada uno la tarea precisa — y dejar de pagar por lo que no usa.

Este es el detalle que atrapa a mucha gente. El subagente no hereda tu conversación — él empieza desde cero, con la ventana vacía. Antes de producir cualquier cosa, necesita reunir el contexto por sí solo: leer los archivos y entender el terreno. Eso cambia el cálculo: parte de su trabajo consiste solo en «ubicarse», y ese trabajo de lectura es justo lo que un nivel barato hace bien.

# o maestro já conversou com você por 1h.
# o subagente NÃO sabe nada disso. ele nasce assim:

contexto: (vazio)
tarefa:   "ache onde o login quebra nos 40 arquivos de /auth"

# 1º ele GASTA tokens só pra se situar:
#   - lista a pasta /auth
#   - abre os 40 arquivos
#   - mapeia o fluxo de login
# SÓ DEPOIS ele começa a raciocinar sobre o bug.

# lição: essa fase de "reunir contexto" é leitura bruta
# → é trabalho de Haiku, não de Opus.

Hay un costo fijo al lanzar un subagente: nace en blanco, reúne contexto y después trabaja. Para una tarea grande, ese costo se diluye: vale la pena. Para una microtarea de 30 segundos, la sobrecarga de "ubicarse" supera el trabajo en sí: es un desperdicio. Y para el caso común, existe el atajo honesto: heredar el modelo del padre.

Esta es la tabla canónica del curso para elegir un modelo. Lee de izquierda a derecha: cada nivel tiene un grado de razonamiento, un costo relativo, una latencia y un conjunto de tareas para las que es la opción adecuada. Consérvala; volverá en la Ruta 4 cuando comparemos modelos de otros proveedores.

La elección del modelo está en el campo model del frontmatter. Mira tres subagentes de un mismo proyecto, cada uno en el nivel justificado para tu tarea — y lee el comentario que lo explica por qué cada uno está donde está.

# ── 1) file-scout.md ── varre o repo atrás de um padrão
---
name: file-scout
description: Varre o repositório atrás de onde um símbolo
  ou string aparece e devolve só os caminhos + linhas.
tools: Read, Grep, Glob       # só leitura
model: haiku                  # ← é "ache e relate": tier barato basta
---
You are a fast code scout. Liste apenas os arquivos e linhas
onde o alvo aparece. Não explique, não opine. Só o mapa.


# ── 2) feature-builder.md ── implementa um passo do plano
---
name: feature-builder
description: Implementa um passo bem-definido de um plano
  (uma função, uma validação, um endpoint) e roda os testes.
tools: Read, Edit, Write, Bash
model: sonnet                 # ← constrói código: o operário competente
---
You are a focused implementer. Implemente exatamente o passo
pedido, siga o padrão do projeto e rode os testes ao final.


# ── 3) security-reviewer.md ── caça falha de segurança
---
name: security-reviewer
description: Revisa o diff em busca de falhas de segurança
  (injeção, vazamento, authz). Use após mexer em auth/pagamentos.
tools: Read, Grep, Glob       # read-only: revisor não edita
model: opus                   # ← raciocínio de segurança: o erro é caro
---
You are a senior security reviewer. Pense como atacante.
Aponte cada risco com arquivo:linha e a gravidade. Não conserte.

Tres prompts para indicarle al maestro adaptar el modelo a la tarea. Fíjate en el patrón: dices el tier e a razón — y deja el trabajo barato en Haiku, el costoso en Opus.

Use um subagente em Haiku pra escanear /auth e me
trazer só os trechos que tocam o login. Depois,
com esse resumo, use Opus só pra decidir onde está
o bug. Não rode o Opus na varredura.

Crie um subagente "doc-summarizer" read-only com
model: haiku — a tarefa é só ler docs e resumir,
então quero o tier mais barato e rápido.

Esse é um revisor de segurança: coloque model: opus.
O erro aqui é caro, então quero o raciocínio máximo,
mesmo custando mais. Mantenha o agente read-only.

Así es como aparece la elección en la terminal. El maestro lanzó tres subagentes y la línea de estado muestra, para cada uno, qué modelo está en ejecución. Observa el diseño: la flota de exploración en Haiku, el builder en Sonnet, y solo el revisor de seguridad en Opus — jefe costoso, trabajadores baratos.

↑ Recreación ilustrativa del terminal (no es una captura de pantalla real). La línea de estado revela el modelo de cada subagente, y la flota económica carga con la mayor parte del trabajo.