Subagentes y orquestación en paralelo

Módulo 5 · Extensibilidad · Lección 7 de 8

Al terminar esta lección podrás diseñar un patrón de subagentes para una tarea de varios pasos de un proyecto, explicar el modelo de aislamiento de contexto y aconsejar al equipo del cliente sobre cuándo los subagentes son la herramienta adecuada frente a varias instancias paralelas de Claude.

La tarea es demasiado grande para un solo contexto. Los subagentes reparten el trabajo.

Dos patrones de orquestación: elige según la necesidad

El equipo de seguridad del cliente pregunta: «¿Puede Claude Code ejecutar una auditoría de seguridad mientras un desarrollador sigue programando, sin que una contamine el contexto de la otra?». Sí. Para eso existen los subagentes.

Una pregunta frecuente pero distinta es: «¿Podemos ejecutar dos funcionalidades independientes al mismo tiempo?». Eso no son subagentes: son instancias paralelas de Claude, un patrón aparte.

Ambos se confunden porque en los dos hay varios procesos de Claude ejecutándose a la vez. La diferencia está en cómo se relacionan: en un patrón hay un padre que coordina a sus hijos y reúne su salida; en el otro hay instancias independientes que nunca se comunican.

La distinción clave

Los subagentes devuelven resultados al agente principal. Las instancias paralelas de Claude entregan trabajo de forma independiente. Equivocarse en esto es el error de diseño de subagentes más común en los equipos de proyecto.

	Subagentes	Instancias paralelas de Claude
Qué es	Mini-agentes especializados generados dentro de tu sesión	Instancias independientes de Claude Code en terminales separadas
Contexto	Subcontexto aislado; devuelve resultados al agente principal	Contexto completo e independiente por instancia
Cuándo usarlo	Delegar trabajo especializado sin contaminar el contexto principal	Varias tareas que podrían entregarse como PR separados; horas de trabajo independiente
Coordinación	Automática: el agente principal espera los resultados	Manual: tú gestionas entre terminales; TMUX para tener visibilidad

Si has llevado proyectos con flujos de trabajo paralelos que reportan a un único líder de proyecto, ya conoces este modelo: el agente principal es el PM, los subagentes son los flujos de trabajo, y solo vuelven los entregables.

Anatomía de un subagente: un archivo de especificación en el directorio agents

Cada subagente es un archivo de especificación en Markdown. Claude lee la descripción para decidir qué subagente generar para una tarea concreta.

Estructura de directorios

flowchart TD
    A["my-project/"] --> B["CLAUDE.md"]
    A --> C["agents/"]
    C --> D["code-reviewer.md ← cada archivo es una especificación de subagente"]
    C --> E["security-auditor.md"]
    C --> F["researcher.md"]
    A --> G["src/"]

security-auditor.md (especificación de ejemplo)

name: security-auditor
description: Scans for SQL injection, XSS, CSRF, and OWASP
Top 10 vulnerabilities in modified code. Returns
a structured findings report.
tools: Read, Grep, Bash

Dos campos determinan el patrón de subagentes. description es la forma en que el agente principal decide qué subagente generar para una tarea concreta: escríbela igual que escribirías la descripción de una skill, explícita sobre la condición de activación. La lista tools acota el subagente a exactamente lo que necesita. Un auditor de seguridad no necesita acceso de Edit ni de Write.

La auditoría de seguridad con tres agentes: el patrón de proyecto que conviene proponer primero

Es el patrón de subagentes más concreto del material del curso, y el más probable que resuene con el equipo de seguridad de un cliente.

flowchart TD
    M1["Agente principal: escribe la funcionalidad"] --> A1["Subagente de auditoría: escanea OWASP Top 10"]
    A1 -->|"hallazgos"| R1["Subagente de remediación: corrige las vulnerabilidades"]
    R1 --> M2["Agente principal: funcionalidad segura completa"]

• Agente principal · escribiendo la funcionalidad. Ventana de contexto completa. Es responsable de la tarea de programación. Genera el subagente de auditoría cuando la funcionalidad está lista para revisión.
• Subagente de auditoría · escanea OWASP Top 10. Contexto aislado. Solo ve el código que se le dio y sus propios resultados de herramientas. Devuelve un informe estructurado de hallazgos, no su proceso de razonamiento completo.
• Subagente de remediación · corrige las vulnerabilidades. Recibe el informe de hallazgos. Aplica correcciones dirigidas. Devuelve el código corregido al agente principal.
• Agente principal · funcionalidad segura completa. El contexto principal se mantuvo limpio durante todo el proceso. Recibe el resultado final corregido. El detalle de la auditoría nunca entró en la ventana de contexto principal.

Aplicación en el proyecto: propón este patrón a clientes que necesiten demostrar gobernanza de seguridad sobre código generado con IA. El pipeline produce una pista auditable (la tarea y la salida de cada subagente pueden registrarse) sin frenar el flujo principal de desarrollo.

Qué ve el subagente y qué pasa cuando falla

El aislamiento de contexto es la principal ventaja de los subagentes. También es la restricción que hay que diseñar alrededor.

sequenceDiagram
    participant P as Agente principal
    participant S as Subagente
    P->>S: Especificación y tarea (sin el historial de la conversación)
    Note over S: Ve su system prompt, la tarea y sus propios resultados de herramientas
    S-->>P: Resultado o error

Qué ve el subagente: su propio system prompt (del archivo de especificación), la tarea que le asignó el agente principal y sus propios resultados de herramientas. No ve el historial completo de la conversación del agente principal. Es el mecanismo que mantiene limpio el contexto principal: el subagente de auditoría puede hacer un análisis extenso sin que los hallazgos inunden el contexto de trabajo del desarrollador.

Lo que no ve: mensajes anteriores, conexiones MCP establecidas en la sesión principal (salvo que se pasen explícitamente) ni el estado actual de archivos del agente principal más allá de lo incluido en la descripción de la tarea. Diseña las tareas de los subagentes para que sean autocontenidas.

Red y credenciales: los subagentes operan dentro de la misma sesión de Claude Code y usan ventanas de contexto separadas. Esto no es lo mismo que el aislamiento a nivel de proceso o de red. Antes de delegar tareas sensibles, verifica que la política de red del cliente, las reglas del proxy y las credenciales se aplican como se espera a las operaciones de los subagentes. No des por hecho un aislamiento que no se haya confirmado explícitamente.

Manejo de fallos: diseñarlo desde el principio

Cuando un subagente falla, el agente principal recibe un resultado de error en lugar de un resultado de éxito. El agente principal es responsable de gestionarlo: reintentar, omitir o escalar. No construyas pipelines en los que el fallo de un subagente corrompa en silencio al siguiente. El caso más habitual es que el subagente de remediación reciba la salida de una auditoría fallida. Haz que el resultado de la auditoría sea explícito y valídalo antes de pasarlo a la siguiente etapa.

En el patrón de auditoría de seguridad: si el subagente de auditoría no logra parsear un archivo minificado, el agente principal recibe un resultado de error. No una respuesta nula. No un salto silencioso. Tiene este aspecto: { status: 'error', message: 'Parse failed: minified file at /dist/app.min.js' }. Después, el agente principal decide: reintentar con otro enfoque, marcar el archivo para revisión manual o continuar con los demás resultados de la auditoría. Nada de eso ocurre automáticamente. Hay que escribirlo en las instrucciones del agente principal.

Comprueba tu comprensión

Subagentes: dos afirmaciones

Marca cada afirmación como verdadera o falsa.

Afirmación 1: las instrucciones del agente principal determinan cómo se gestiona el fallo de un subagente; Claude Code no incluye ninguna recuperación automática.

Verdadero / Falso

Ver respuesta

Verdadero. Claude Code devuelve un resultado de error al agente principal; lo que ocurre después lo determinan por completo las instrucciones del agente principal. Si quieres lógica de reintento, de marcar y continuar o de escalado, escríbela. Los fallos de subagentes no gestionados detienen el pipeline.

Afirmación 2: si un subagente falla, Claude Code lo reintenta automáticamente hasta que tiene éxito.

Verdadero / Falso

Ver respuesta

Falso. No hay reintento automático. El agente principal recibe un resultado de error y decide cómo responder: reintentar, omitir, escalar o continuar con resultados parciales. Escribe esta gestión en las instrucciones del agente principal. Un fallo de subagente no gestionado detendrá el pipeline.

Las dos restricciones de diseño que debes llevar a todo patrón de subagentes que propongas son el aislamiento de contexto y la gestión explícita de fallos.

Subagentes frente a la política de proxy: ¿cuál es tu siguiente paso?

La arquitectura correcta está clara, pero la restricción es organizativa. Hay tres respuestas: una investiga antes de ceder.

Decisión · Orquestación

El equipo de TI de un cliente dice que su política de proxy bloqueará la generación de subagentes. El desarrollador quiere subagentes paralelos de lint, seguridad y tests después de cada cambio de código. ¿Cuál es tu primera respuesta?

• A. Cambiar a tres terminales de Claude en paralelo, cada una ejecutando una comprobación de forma independiente.
• B. Aceptar la restricción y rediseñar como un flujo secuencial de un solo agente.
• C. Preguntar a TI qué se está bloqueando concretamente. Los subagentes se ejecutan dentro de la misma sesión de Claude Code y no hacen conexiones salientes separadas. La restricción puede no aplicarse.

Ver respuesta

C es correcta. Los subagentes se generan dentro del proceso de la sesión y no hacen llamadas salientes de API para arrancar. Las restricciones de proxy suelen aplicarse a las llamadas HTTP/S, no a la generación en proceso. Es probable que el equipo de TI esté confundiendo los subagentes con llamadas a APIs externas. Aclara antes de rediseñar nada.

A: cambiar a terminales paralelas resuelve el problema equivocado. La preocupación por el proxy aún no se ha validado, y las instancias paralelas pierden la coordinación y la recogida de resultados que el desarrollador necesita.

B: aceptar la restricción sin cuestionarla es la opción más costosa. Una sola pregunta aclaratoria puede disolver la preocupación por completo.

Mismo proyecto, semana dos. El subagente de auditoría de seguridad está en marcha.

Decisión · Manejo de fallos

El subagente de auditoría de seguridad falla con un error de parseo en un archivo minificado. Los subagentes de lint y tests ya han devuelto resultados limpios. ¿Qué hace el agente principal?

• A. Marca el pipeline completo como fallido y se detiene, porque el resultado de la auditoría está incompleto.
• B. Reintenta automáticamente el subagente de auditoría hasta que el parseo tenga éxito.
• C. Recibe el resultado de error, registra el fallo concreto, marca el archivo para revisión manual y continúa con los resultados de lint y tests.

Ver respuesta

C es correcta. Esto es lo que significa «diseñar las tareas de los subagentes para que sean atómicas» en la práctica. Cada subagente devuelve un resultado o un error. El agente principal los gestiona de forma independiente, continúa con lo que tiene y registra lo que falló. Incorpora esa lógica de manejo de fallos en las instrucciones del agente principal desde el principio.

A: detener el pipeline descarta dos resultados limpios porque un subagente encontró un archivo que no pudo parsear. El diseño atómico de tareas existe precisamente para que un solo fallo no invalide trabajo no relacionado.

B: no hay reintento automático. El agente principal recibe el resultado de error y actúa según lo que digan sus instrucciones; si no contemplan el fallo, el pipeline se detiene.

Ideas clave

• Los subagentes devuelven resultados al agente principal; las instancias paralelas de Claude entregan trabajo de forma independiente.
• Cada subagente tiene contexto aislado: solo ve su especificación, la tarea asignada y sus propios resultados de herramientas.
• El patrón de auditoría de seguridad con tres agentes es la primera propuesta cuando un cliente necesita gobernanza sobre código generado con IA, y no exige cambios en el flujo de desarrollo.
• No hay reintento automático: las instrucciones del agente principal deben definir qué hacer con cada fallo.
• Las dos restricciones de diseño que debes llevar a cualquier patrón son el aislamiento de contexto y la gestión explícita de fallos.

Siguiente: Marketplaces de plugins y versionado de dependencias