¿Las respuestas de Claude son demasiado largas? Crea tu equipo de IA con Subagents

Cuando pides a Claude una revisión de seguridad del código, a menudo te devuelve también sugerencias de refactorización, análisis de rendimiento y casos de prueba — 3000 líneas de golpe. El problema no es que la IA dé demasiado, sino que no hay forma de decirle que se centre solo en una cosa.

Subagent es el mecanismo que resuelve esto. Cada Subagent tiene un alcance de tarea, permisos de herramientas y selección de modelo independientes, y vive en el directorio .claude/agents/ del proyecto. ¿Necesitas revisión de código? Invoca el Subagent de revisión. ¿Necesitas documentación? Invoca el de documentación. Los límites de la tarea quedan fijados en el archivo de configuración: no se salta de rol ni se desvía.

Este artículo explica cómo configurar Subagents, su mecanismo de invocación y los modos de colaboración Multi-Agent, con un caso práctico de sistema de escritura de blogs.

Qué es exactamente un Subagent

En pocas palabras, un Subagent es un asistente personalizado que creas para Claude. Cada asistente tiene su propio alcance de tarea, permisos de herramientas e incluso puede usar un modelo distinto.
Viven en el directorio .claude/agents/ de tu proyecto; cada archivo es un asistente. La estructura es sencilla: arriba va la configuración YAML y debajo el prompt detallado en Markdown.

---

name: code-reviewer
description: Asistente especializado en revisar calidad de código y riesgos de seguridad
tools: [Read, Grep, Glob]
model: haiku

---

Eres un experto en revisión de código, enfocado en detectar:
- Vulnerabilidades de seguridad (inyección SQL, XSS, etc.)
- Cuellos de botella de rendimiento
- Problemas de estilo y convenciones
Solo señala problemas; no modifiques el código.

Frente a una conversación normal con Claude, un Subagent tiene tres diferencias claras:
Enfoque — solo hace lo que defines, sin desviarse. Si le pides revisar código, solo revisa; no te refactoriza el proyecto de paso.
Restricción — los permisos de herramientas los das tú; no puede usar lo que no autorizaste. Un asistente de solo lectura no puede tocar tus archivos.
Reutilización — el archivo de configuración vive en el proyecto y todo el equipo puede usarlo. Un recién llegado puede empezar con @code-reviewer directamente.

Por qué necesitas Subagents

Siendo honesto, al principio pensé que era redundante — ¿no basta con hablar con Claude?
Después de usarlo un tiempo, sí que compensa.

Enfoque

Claude es demasiado versátil: si le preguntas por código, puede colarte mejores prácticas, recomendarte frameworks o incluso escribir documentación. A veces ayuda, pero la mayoría del tiempo es ruido.
Un Subagent lo limita a una sola tarea. Un asistente de revisión de código no te redacta un plan de refactorización; uno de tests no cuestiona tu arquitectura.

Optimización de costes

Mucha gente no lo nota: no todas las tareas necesitan el modelo más caro.
Búsqueda, conversión de formato o análisis simple bastan con Haiku, que cuesta aproximadamente un tercio de Sonnet. En un equipo, el ahorro mensual es notable.

Procesamiento en paralelo

Aquí es donde más me gusta.
Puedes lanzar varias tareas a la vez en paralelo. Tras terminar una función, un asistente puede escribir tests unitarios, otro revisar código y otro documentar. En la práctica, el salto de eficiencia es muy claro.

Reutilización

Los archivos de configuración se suben al repositorio Git y todo el equipo los usa. La experiencia acumulada del proyecto se convierte en configuración ejecutable.

"El valor central de Subagent es el enfoque y la reutilización. Un generalista se convierte en un equipo de especialistas, cada uno en lo suyo."

Configuración YAML en detalle

Dicho esto, ¿cómo se escribe el archivo de configuración?
Un Subagent completo tiene varios campos, pero solo dos son obligatorios:

---

name: blog-writer          # Obligatorio: identificador único del asistente
description: Experto en redactar borradores de blog  # Obligatorio: descripción breve; afecta al disparo automático
tools: [Read, Write, Grep]  # Opcional: permisos de herramientas; por defecto, todas
model: sonnet              # Opcional: modelo; por defecto hereda el de la conversación principal

---

# El prompt va debajo del YAML
Eres un redactor profesional de blogs...

name — ID del asistente para invocarlo. Mejor un nombre legible de un vistazo, como code-reviewer o test-writer.
description — muy importante. Claude usa la descripción para decidir cuándo dispararlo automáticamente. Si pones «asistente genérico para todo», casi nunca se activará solo.
Mal:

Alibaba Cloud - Opción preferida para desarrolladores, 15 % de descuento exclusivo en Lighthouse

Obtener 15% dto. →Anuncio

description: Un ayudante

Bien:

description: Investigar a fondo temas de blog y generar documentos de planificación estructurados

tools — lista de permisos. Sin configurar, puede usar todas las herramientas, lo cual no suele ser buena idea (más adelante).
model — qué modelo usar. haiku es barato y rápido; sonnet es el equilibrio por defecto; opus da la máxima calidad pero cuesta más.

Control de permisos de herramientas

Aquí tropecé; merece un apartado.
Al principio, por comodidad, dejé permisos totales en todos los Subagents. Una vez, un asistente que solo debía analizar código modificó varios archivos — y lo hizo mal.
Desde entonces trato los permisos en serio. El principio es simple: solo lo imprescindible, nada de más.
Combinaciones habituales:

---

name: code-reviewer
tools: []  # array vacío = todos los permisos; poco seguro

---

Buena configuración: solo lectura

---

name: code-reviewer
tools: [Read, Grep, Glob]

---

Un revisor de solo lectura no puede alterar tu código por error. Esa restricción es una protección.

Tres formas de invocación

Configuración lista: ¿cómo invocarlo? Hay tres vías:

Disparo automático

Si la description es clara, Claude decide cuándo llamarlo. Por ejemplo, «gestionar todas las peticiones de revisión de código»: al decir «revísame este PR», debería activarse solo.

@-mention

La forma más directa: @agent-name:

@code-reviewer ¿Puedes revisar si esta función tiene problemas?

Herramienta Task

Invocación programática, para escenarios más complejos:

Task(subagent_type="code-reviewer", prompt="Revisar todos los archivos del directorio src/")

Colaboración Multi-Agent

Hasta aquí, un solo asistente. La fuerza real de Subagent es la colaboración entre varios.

Modo secuencial

Uso mucho el modo secuencial, ideal para flujos de creación de contenido:

Entrada del usuario (tema)
    |
@blog-planner investiga y redacta el esquema
    | salida: documento de planificación
@blog-writer lee el esquema y escribe el borrador
    | salida: borrador
@blog-editor lee el borrador y pulsa para publicar
    | salida: versión final

Cada asistente cubre una fase; la salida de uno alimenta al siguiente. Claro, controlable y fácil de depurar.

Modo paralelo

Aún mejor en paralelo. Tras una función nueva, lanzas a la vez:

• @test-writer tests unitarios
• @code-reviewer revisión de código
• @doc-writer documentación
  Tres tareas en paralelo, sin interferencias. Lo que antes llevaba 30 minutos en serie, en 10 minutos.

Modo HITL (Human In The Loop)

También hay un modo con confirmación humana:

@planner genera el plan
    |
El usuario confirma o ajusta
    |
@executor ejecuta el plan

Las decisiones críticas las controlas tú; no se descontrola del todo.

Siete técnicas de redacción

Tras meses con Subagents, resumo 7 trucos para configuraciones más útiles:

KiloClaw - OpenClaw gestionado para empresas: orquestación de agentes IA y enrutamiento inteligente

Empezar →Anuncio

Técnica 1: descripción precisa

La description afecta directamente al disparo automático.
Demasiado vaga — casi nunca se activa:

description: Un asistente genérico

Precisa — alcance claro:

description: Revisar vulnerabilidades de seguridad y rendimiento en código Python

Técnica 2: prompt concreto

No basta con «eres experto en revisión de código»; indica cómo revisar.
Demasiado general:

Eres experto en revisión de código; ayuda al usuario a revisar.

Guía concreta:

Eres experto en seguridad de código Python.
## Focos de revisión
1. Riesgo de inyección SQL — revisar todas las operaciones de base de datos
2. Vulnerabilidades XSS — revisar el tratamiento de entrada de usuario
3. Fuga de información sensible — revisar logs y manejo de errores
## Formato de salida
Reporta cada problema así:
- Archivo: xxx
- Línea: xxx
- Nivel de riesgo: alto/medio/bajo
- Descripción: xxx
- Sugerencia de corrección: xxx

Técnica 3: herramientas al mínimo

Ya comentado: solo permisos necesarios. Menos permisos no empeora al asistente; limita lo que puede hacer.

Técnica 4: el modelo adecuado

Tareas simples con Haiku; complejas con Sonnet. En concreto:

• Haiku: búsqueda y resumen, conversión de formato, análisis simple, organización de datos
• Sonnet: lógica compleja, contenido creativo, generación de código, análisis con razonamiento

Técnica 5: probar bien

Tras escribir la configuración, prueba varias formas de invocación. ¿Funciona el disparo automático? ¿@-mention responde bien? ¿Qué pasa en casos límite?

Técnica 6: documentación clara

El prompt es documentación. Si está claro, el equipo entiende al instante qué hace el asistente y cómo usarlo.

Técnica 7: iterar a menudo

No busques la perfección a la primera. Escribe una versión usable, úsala un tiempo y ajusta según feedback.

Errores comunes que conviene evitar

Tras las técnicas, los fallos que yo cometí:

Error 1: descripción demasiado vaga

«Asistente genérico» no le dice a Claude cuándo invocarlo. Especifica la responsabilidad.
Mal:

description: Asistente que ayuda al usuario

Mejor:

description: Cuando el usuario mencione tests o pruebas unitarias, generar casos de prueba automáticamente

Error 2: demasiados permisos

Dar todo por comodidad y que el asistente haga lo que no quieres. Sobre todo Write: piénsalo antes de concederlo.
Mal:

name: format-converter
tools: []  # array vacío = todos los permisos

Mejor:

name: format-converter
tools: [Read, Write]

Error 3: prompt demasiado largo

El prompt de Subagent también consume tokens. Miles de palabras en cada invocación. Mantén lo esencial.

Vultr - Servidor cloud NVMe de alto rendimiento, 32 ubicaciones globales, despliegue Docker con un clic

Ver precios →Anuncio

Error 4: olvidar el model

Sin model, hereda el de la conversación principal (suele ser Sonnet). Tareas simples y dinero de más.
Olvidado:

name: text-extractor
tools: [Read]

Con model:

name: text-extractor
tools: [Read]
model: haiku

Error 5: llamadas en bucle

El agente A llama al B y el B vuelve al A. El bucle corre hasta timeout o hasta que lo pares.
Correcto: A -> B -> C
Incorrecto: A -> B -> A

Error 6: sin manejo de errores

Los Subagents también fallan. Añade lógica de error en el flujo para detectarlo a tiempo.

Error 7: configuración sin control de versiones

Sube los archivos a Git. Si un cambio rompe algo, puedes volver atrás.

Caso práctico: sistema de escritura de blogs

Tras la teoría, un ejemplo real.
Mi sistema de blogs usa tres Subagents:

Arquitectura del sistema

El usuario aporta el tema
    |
blog-planner: investigación + planificación (20 min)
    | salida: docs/[tema]-planificacion-contenido.md
blog-writer: borrador (40 min)
    | salida: docs/[tema]-borrador.md
blog-editor: pulido (20 min)
    | salida: docs/[tema]-version-final.md

blog-planner (planificador)

---

name: blog-planner
description: Investigar a fondo el tema y crear documento de planificación de contenido
tools: [Read, Write, Grep, WebSearch, WebFetch]
model: sonnet

---

Eres planificador de contenido. Te encargas de:
1. Investigar tendencias del tema con WebSearch
2. Analizar audiencia objetivo y puntos de dolor
3. Diseñar estructura del artículo y estrategia SEO
4. Guardar el documento de planificación en docs/

blog-writer (autor)

---

name: blog-writer
description: Redactar borrador de blog según el documento de planificación
tools: [Read, Write, Grep]
model: sonnet

---

Eres autor de contenido. Te encargas de:
1. Leer el documento de planificación
2. Redactar el borrador completo según el esquema
3. Asegurar tono humano y sin olor a IA
4. Guardar el borrador en docs/

blog-editor (editor)

---

name: blog-editor
description: Editar borrador y optimizar expresión natural
tools: [Read, Edit]
model: haiku

---

Eres editor de contenido. Te encargas de:
1. Leer el borrador
2. Detectar y eliminar expresiones con olor a IA
3. Mejorar naturalidad y legibilidad
4. Guardar la versión final en docs/

El flujo es sencillo:

# Paso 1: planificación
@blog-planner Consejos de uso de Claude Code Subagent
# Paso 2: redacción
@blog-writer
# Paso 3: edición
@blog-editor

Cada fase tiene entrada y salida claras; si algo falla, localizas rápido.

Consejos de optimización de costes

Por último, el coste.
Haiku y Sonnet difieren unas 3 veces en precio (consulta la web de Anthropic). En una tarea típica de blog, repartir modelos con criterio ahorra bastante.

Estrategia de selección de modelo

Mi recomendación:
Usar Haiku

• Búsqueda y resumen de información
• Conversión de formato simple
• Organización y clasificación de datos
• Revisión de código (análisis de solo lectura)
  Usar Sonnet
• Creación de contenido (blogs, documentación)
• Generación de código compleja
• Análisis que requiere razonamiento
• Escenarios con exigencia alta de calidad

Referencia comparativa de modelos

Reglas para ahorrar

Recuerda:

• Si puedes usar Haiku, no uses Sonnet
• Si puedes limitar herramientas, no des All tools
• Si puedes acortar el prompt, no lo alargues
• Si puedes acotar la salida, no dejes que improvise

Para cerrar

En resumen, Subagent no es magia negra: es dividir las capacidades de Claude según necesidad. Un generalista se convierte en un equipo de especialistas.
Si sigues con «un solo Claude para todo», te recomiendo probar Subagents. Media hora escribiendo configuraciones puede ahorrarte innumerables «Claude se ha ido por las ramas otra vez».
Los principios clave:

1. Un agente, una tarea
2. Solo permisos de herramientas imprescindibles
3. Haiku para tareas simples
4. Prompts concretos y claros
5. En colaboración multi-agente, pasar contexto con documentos
   Si algo falla, suele ser la configuración. Con las 7 técnicas y los 7 errores de este artículo, la mayoría se resuelve.
   Y por último: no persigas la configuración perfecta; empieza a usarla e itera.
   ¡Que montes pronto tu propio equipo de IA!