Subagentes

Claude Code puede delegar tareas a subagentes autónomos. Cada subagente se ejecuta en su propio contexto aislado, lo que protege el hilo principal y permite lanzar varias tareas en paralelo.

¿Qué es un subagente?

Un subagente es una instancia secundaria de Claude Code, invocada por el hilo principal para gestionar una tarea concreta. Tiene su propio contexto: no ve el historial de la conversación padre, y sus acciones (leer archivos, ejecutar comandos) no contaminan el contexto principal.

Dos ventajas concretas:

• Aislamiento: una tarea exploratoria (leer 50 archivos para entender una arquitectura) consume ventana de contexto. Delegarla a un subagente protege el contexto del hilo principal para lo que viene después.
• Especialización: cada subagente puede tener un rol definido: explorar, refactorizar, escribir pruebas, redactar documentación. El hilo principal orquesta, los subagentes ejecutan.

Lanzar un subagente ad hoc

No necesitas ninguna configuración previa para usar un subagente. Simplemente pídelo en tu prompt:

Lanza un subagente para explorar la carpeta src/ y dame un resumen de la arquitectura. No modifiques nada.

Claude Code creará un subagente, le pasará la tarea y te devolverá el resultado en tu hilo. El subagente desaparece una vez terminada la tarea.

También puedes paralelizar varias tareas en una sola solicitud:

Lanza dos subagentes en paralelo: el primero lista todas las dependencias directas de package.json con sus versiones, el segundo busca los archivos TODO en el proyecto.

El menú /agents

El slash command /agents lista todos los subagentes disponibles en tu sesión, incluidos los que hayas configurado (ver la sección siguiente).

$/agents

Este menú te muestra los agentes disponibles, sus descripciones y las herramientas a las que tienen acceso. Úsalo para verificar que un agente personalizado se ha cargado correctamente al iniciar la sesión.

Configurar un subagente personalizado

Para tareas recurrentes (escribir pruebas, validar SQL, revisar documentación), puedes definir un subagente persistente. La configuración se hace mediante un archivo Markdown en .claude/agents/.

Estructura de un archivo de agente

Crea un archivo .claude/agents/test-writer.md con este formato:

---
name: test-writer
description: Escribe pruebas unitarias para las funciones TypeScript pasadas como entrada. Úsalo cuando el usuario pida probar una función o módulo.
tools:
  - Read
  - Write
  - Bash
model: sonnet
---

Eres un experto en pruebas unitarias TypeScript con Vitest.
Para cada función recibida:
1. Identifica los casos nominales y los casos límite.
2. Escribe las pruebas en un archivo `*.test.ts` adyacente al fuente.
3. Ejecuta `pnpm test --run` para verificar que las pruebas pasan.

Los campos del frontmatter:

• name: identificador en kebab-case. Es lo que usas para invocar al agente (usa test-writer para esta función).
• description: describe cuándo usar este agente. Claude lee esta descripción para decidir si invocar al agente automáticamente cuando sea relevante.
• tools: lista de herramientas permitidas. Restringir las herramientas reduce la superficie de riesgo.
• model (opcional): modelo a usar. sonnet es la opción adecuada para la mayoría de agentes secundarios.

Cuerpo del archivo

Todo lo que sigue al frontmatter es el system prompt del agente. Aquí defines su comportamiento, sus restricciones y su estilo de respuesta.