Introduction to Subagents — Resumen de estudio

Paths: Developer · Architect · 4 lecciones, 4 videos

Usar y crear subagents en Claude Code para tener el contexto limpio y delegar bien.

1. Qué son

• Asistentes especializados a los que Claude Code delega tareas. Cada uno corre en su propia ventana de contexto, hace el trabajo y devuelve solo un resumen. Lo intermedio (lecturas, búsquedas, tool calls) queda aislado y se descarta.
• Reciben dos cosas: el system prompt de su configuración (el rol) y una descripción de la tarea que escribe el agente principal.
• El tradeoff: pierdes visibilidad de cómo llegó a su conclusión.
• Ejemplo: "¿qué servicio maneja los reembolsos?" → Explore lee 15 archivos en su contexto y tu hilo principal solo guarda la pregunta y el resumen.
• Built-in:
  • General purpose: tareas de varios pasos que exploran y actúan.
  • Explore: buscar y navegar el código rápido.
  • Plan: investigación durante plan mode.
• Custom: con su propio system prompt y tools (revisor, generador de tests, documentación…).

2. Crear uno

• /agents → Create new agent → alcance (project o user) → recomendado: deja que Claude lo genere a partir de tu descripción.
• Tools por categoría: solo lectura, edición, ejecución, MCP, otras. Un revisor no necesita edición, pero conviene darle ejecución para ver el diff.
• Modelo: Haiku (ligero) · Sonnet (equilibrado) · Opus (análisis complejo) · Inherit (el mismo del hilo principal). Más un color para identificarlo en la UI.
• Se guarda en .claude/agents/<nombre>.md:

---
name: code-quality-reviewer
description: Use this agent when you need to review recently written or modified code...
tools: Bash, Glob, Grep, Read, WebFetch, WebSearch
model: sonnet
color: purple
---
(System prompt: rol, en qué fijarse, cómo reportar)

• name: invócalo pidiéndoselo a Claude o con @agent nombre.
• description: una sola línea (usa \n para saltos); puede incluir conversaciones de ejemplo.
• El cuerpo es el system prompt: sé específico sobre qué buscar y cómo estructurar la salida.
• Para que Claude lo use solo, incluye "proactively" en la descripción y añade escenarios concretos. Si no se activa, revisa la descripción.

3. Diseñar subagents efectivos (4 claves)

1. Descripciones específicas: el nombre y la descripción de todos los subagents van en el system prompt del agente principal. La descripción decide cuándo se lanza y además moldea el prompt de entrada que escribe el principal.
   • Ejemplo: "You must tell the agent precisely which files you want it to review" → el principal lista los archivos concretos.
   • "Return sources that can be cited" → lo pide en la delegación.
2. Formato de salida definido (la mejora más importante): crea puntos naturales de parada y evita que corra de más.
   • Revisor: Summary · Critical · Major · Minor · Recommendations · Approval Status.
3. Reportar obstáculos: una sección "Obstacles Encountered" (problemas de setup, workarounds, flags especiales, dependencias problemáticas), para que el hilo principal no tenga que redescubrirlos.
4. Limitar tools:
   • Investigación → solo Glob, Grep y Read.
   • Revisor → + Bash (git diff), sin Edit ni Write.
   • Modificador de estilo o código → Edit y Write.

4. Cuándo ayudan y cuándo estorban

La regla de decisión: ¿importa el trabajo intermedio? Si no, delega; si sí, déjalo en el hilo principal.

Funcionan bien en:

• Investigación ("la validación del JWT está en middleware/auth.js línea 42").
• Code reviews: Claude revisa mejor código que "escribió otro"; el subagent no tiene el historial de cómo se construyó, y se puede codificar el estándar del equipo en su prompt.
• System prompts personalizados: el prompt por defecto de Claude Code es conciso y técnico.
  • Copywriting: tono, audiencia, estilo.
  • Estilos: cargar los archivos del design system.

Anti-patrones:

• "Eres experto en Python o Kubernetes": no añade capacidad; Claude ya sabe eso.
• Pipelines secuenciales (reproducir → depurar → arreglar): se pierde información en cada traspaso cuando cada paso depende del anterior.
• Subagents que corren tests: esconden la salida completa que necesitas para depurar. En las pruebas fue el peor patrón.