Subagentes en coding agents: cuándo delegar (y cuándo no)

Un coding agent que lee 200 archivos para responder “¿dónde está el auth?” te deja la ventana principal llena de ruido. Un subagente hace esa exploración en su propia ventana de contexto y devuelve un resumen. Claude Code y Cursor lo documentan como delegación dentro de una sesión, no como un segundo servicio en producción.

Esta guía es operativa para quien programa con agentes. Si buscas varios agentes en backend, empieza por orquestación multi-agente. Aquí el foco es contexto y permisos en el IDE o la terminal.

Qué es un subagente (definición citable)

Un subagente es un asistente especializado que el agente principal invoca para una subtarea acotada: explorar el repo, investigar antes de un plan, o ejecutar un flujo con tools restringidas. Claude Code lo define con system prompt propio, acceso a tools configurable y permisos independientes. El principal delega según la description del subagente; el subagente trabaja y retorna resultados, no el volcado completo de lecturas.

Cursor sigue el mismo patrón para mantener el chat principal limpio.

Cuándo delegar (señales reales)

Delega a subagente cuando:

1. La subtarea inunda contexto — logs largos, búsqueda en monorepo, “lee estos 15 archivos y dime el patrón”.
2. Quieres tools distintas — solo lectura para explorar; escritura solo en el agente principal.
3. Repites el mismo worker — mismo prompt de “audita migraciones SQL” cada semana → subagente custom reutilizable.
4. Plan mode necesita investigación — Claude delega al subagente Plan (solo lectura) para no mezclar exploración con el plan final.

No delegues cuando:

• La tarea es un archivo y una respuesta corta.
• Necesitas trazabilidad entre sesiones en producción (ahí es cola + worker, no subagente de chat).
• El “subagente” sería solo un alias del mismo prompt sin ahorro de contexto.

Anthropic en Building effective agents insiste en la solución más simple: un subagente no arregla un mal prompt del agente principal.

Built-in en Claude Code (los que verás sin configurar)

Subagente	Tools	Para qué
Explore	Solo lectura (Write/Edit denegados)	Descubrir archivos, búsqueda, mapa del repo
Plan	Solo lectura	Investigación en plan mode
General-purpose	Conjunto completo	Pasos que mezclan leer y modificar

Explore y Plan no cargan CLAUDE.md ni el git status del padre (diseño para ir rápido y barato). El resto sí. Si defines un subagente custom llamado Explore, sobrescribes el built-in.

Claude elige thoroughness en Explore: quick / medium / very thorough. Para “¿dónde está X?” basta quick; para auditoría de módulo, very thorough.

Subagentes custom: el contrato mínimo

En Claude Code, un subagente custom necesita sobre todo una description clara: qué hace y cuándo debe dispararse. Las descriptions suman tokens al arranque; si superan ~15k tokens combinados (sin contar built-ins), Claude Code avisa — recorta descriptions y mueve detalle al system prompt del subagente (solo carga al ejecutarse).

Checklist al crear uno:

• Nombre y description con trigger (“Use when…”).
• Tools: ¿solo Read, Grep, Bash de lectura?
• Modelo: ¿Haiku para exploración barata o heredar del padre?
• Salida esperada: “devuelve lista de archivos + 5 bullets”, no “investiga todo”.

En Cursor, el flujo es equivalente: subagentes para tareas que no deben contaminar el hilo principal (docs).

Subagente ≠ multi-agente en producción

	Subagente (coding session)	Multi-agente (producción)
Vida	Una sesión IDE/CLI	Procesos, colas, APIs
Objetivo	Ahorrar contexto del chat	Paralelismo, dominios, aislamiento de fallos
Estado	Vuelve un resumen al padre	Persistencia, idempotencia, observabilidad
Doc relacionada	Esta guía	Orquestación multi-agente

Un subagente no reemplaza un worker en Redis ni un handoff entre servicios. Mezclarlos (“subagente que hace deploy a prod”) es cómo pierdes sandboxing.

Patrones que funcionan

Investigación → decisión humana → implementación. Subagente Explore (o equivalente) trae mapa; tú eliges; agente principal edita.

Plan con investigación aislada. Plan mode + subagente Plan: el plan no se mezcla con 80 cat de archivos.

Especialista de solo lectura en código legacy. Custom subagente sin Write: puede leer todo el monolito; el principal solo aplica parches acotados.

Anti-patrón: subagente “hazlo todo” sin description — duplica al general-purpose y gasta doble contexto.

Checklist

• ¿La subtarea llenaría el chat de lecturas que no volverás a usar? → subagente.
• ¿Description con “use when” explícito?
• ¿Tools mínimas (lectura vs escritura)?
• ¿Salida acotada (resumen, lista, tabla)?
• ¿No estás usando subagente para lo que es un pipeline en CI?
• ¿Permisos del padre siguen siendo la última barrera para acciones peligrosas?

FAQ

¿Los subagentes comparten el mismo modelo?
En Claude Code, Explore hereda el modelo del padre (con tope en Opus en API). Puedes forzar CLAUDE_CODE_SUBAGENT_MODEL o poner model: haiku en un custom Explore.

¿Cursor y Claude Code son intercambiables?
Mismo concepto; configuración distinta. AGENTS.md / CLAUDE.md no sustituyen definir subagentes cuando necesitas aislamiento de contexto.

¿Y background agents?
Sesiones paralelas largas, otro producto. Subagentes = delegación dentro de una sesión activa.

---

Siguiente paso: la próxima vez que pidas “explora todo el repo”, añade “usa un subagente y devuélveme solo hallazgos” y compara tokens y claridad del hilo principal.