4. Output Parsing y Comunicación Entre Agentes

Descripción

Ya sabes crear subagents con identidad propia (cápsula 02) y restringir lo que pueden hacer (cápsula 03). Pero un subagent aislado no resuelve flujos complejos. El valor real aparece cuando el output de un agente se convierte en el input del siguiente — cuando el reviewer encuentra problemas, el implementer los corrige, y el tester verifica. Esa cadena requiere comunicación estructurada, y la comunicación depende de un detalle que define todo: solo el mensaje final del subagent regresa a la conversación principal.

Las llamadas a herramientas intermedias, el razonamiento interno, los archivos leídos — todo se queda en el contexto del subagent y desaparece cuando termina. Si esa respuesta final es un párrafo narrativo, no podrás extraer datos confiablemente. Si es un reporte con headers consistentes o un JSON estructurado, puedes construir pipelines donde Claude procesa el output y delega al siguiente agente con exactamente la información que necesita.

Esta cápsula te enseña a diseñar system prompts que producen outputs parseables, a encadenar subagents secuencialmente, a elegir entre ejecución foreground y background, y a manejar errores cuando un agente devuelve algo inesperado. Todo conecta directamente con la cápsula 05, donde construirás el pipeline reviewer → implementer → tester usando estos patrones.

Cómo Fluye el Output de un Subagent

El modelo mental correcto

Cuando Claude delega a un subagent, se crea una sesión separada. El subagent ejecuta herramientas, razona, lee archivos — pero nada de eso regresa al padre. Solo el mensaje final cruza la frontera:

Conversación principal
│
├── Tú: "Usa el reviewer para analizar los cambios recientes"
│
├── Claude: [delega al subagent reviewer]
│   │
│   │   ┌── Contexto del subagent (invisible al padre) ──┐
│   │   │ - Lee git diff, analiza 5 archivos              │
│   │   │ - Ejecuta grep, razona sobre hallazgos          │
│   │   │ - MENSAJE FINAL: reporte estructurado ←─────────┤
│   │   └─────────────────────────────────────────────────┘
│   │
│   ↓ [Solo el mensaje final regresa]
│
├── Claude recibe: "### Code Review Report\n#### CRITICAL..."
│
└── Claude te muestra el resultado (o lo pasa a otro subagent)

Implicaciones prácticas

• 📦 El mensaje final es todo lo que tienes. Si el subagent encontró 3 issues pero solo mencionó 2 en su reporte, el tercero no existe para el resto del flujo.
• 📏 El tamaño consume contexto principal. Un reporte de 200 líneas ocupa 200 líneas de tu ventana de contexto. Ejecutar 5 subagents con reportes detallados puede llenar el contexto rápidamente.
• 🔗 Claude procesa antes de delegar. No hay conexión directa entre subagents — Claude actúa como intermediario, interpretando el output de uno y construyendo el prompt del siguiente.

Lo que NO regresa: tool calls intermedios, razonamiento interno, archivos leídos, errores que el subagent resolvió solo. Lo que SÍ regresa: el mensaje final de texto.

Esto es una feature. El aislamiento mantiene limpio el contexto principal. Pero significa que tu system prompt debe instruir al subagent a incluir todo lo relevante en su mensaje final.

El System Prompt Define el Output

La regla de oro

Si quieres output parseable, especifícalo en el system prompt. Un subagent sin instrucciones de formato produce prosa libre. Uno con formato definido produce datos estructurados.

Antes vs después: el impacto del formato

System prompt sin formato definido:

---
name: reviewer
description: Reviews code for issues
tools: Read, Grep, Glob
---

You are a code reviewer. Analyze the code and report any problems you find.

Output típico (impredecible):

I looked at the recent changes and found some issues. In auth.py,
there's a potential SQL injection on line 45 where user input is
directly interpolated. Also, the products endpoint doesn't have
pagination. The error handling looks good overall, though I'd
suggest adding retry logic for external API calls.

La estructura cambia con cada ejecución — a veces menciona líneas, a veces no. A veces organiza por severidad, a veces no.

System prompt con formato explícito:

---
name: reviewer
description: Reviews code changes and produces structured severity reports
tools: Read, Grep, Glob
---

## Role
Code reviewer. Analyze recent changes. Produce structured report.

## Output Format (follow EXACTLY)

### Code Review Report
**Files reviewed:** [list]

#### CRITICAL (must fix)
- **[file:line]** — Description
  - Evidence: `code snippet`
  - Fix: Specific recommendation

#### WARNING (should fix)
- **[file:line]** — Description

#### Summary
- Critical: [n] | Warning: [n] | Suggestion: [n]
- Verdict: PASS | PASS_WITH_WARNINGS | NEEDS_REVISION

If no issues in a category: "None found."

Output resultante (predecible):

### Code Review Report
**Files reviewed:** src/auth.py, src/routes/products.py

#### CRITICAL (must fix)
- **src/auth.py:45** — SQL injection via string interpolation
  - Evidence: `query = f"SELECT * FROM users WHERE id = '{user_id}'"`
  - Fix: Use parameterized query with SQLAlchemy

#### WARNING (should fix)
- **src/routes/products.py:62** — No pagination on GET /products

#### Summary
- Critical: 1 | Warning: 1 | Suggestion: 0
- Verdict: NEEDS_REVISION

Ahora Claude puede extraer los findings CRITICAL y pasárselos al implementer.

Tres formatos para tres situaciones

Para el flujo reviewer → implementer → tester, Markdown con headers es el mejor balance. Claude lo parsea confiablemente y los humanos pueden inspeccionar pasos intermedios.

Encadenando Subagents: El Patrón Chain

Cómo funciona el encadenamiento

No hay conexión directa entre subagents. Claude actúa como intermediario:

Tú: "Revisa el código, corrige los problemas, y verifica con tests"

Claude (internamente):
│
├── 1. Delega al reviewer
│      → Recibe: reporte con 2 critical, 1 warning
│
├── 2. Procesa el reporte — extrae findings
│
├── 3. Delega al implementer con contexto:
│      "Fix these issues: SQL injection in auth.py:45,
│       missing validation in api.py:23, no pagination in products.py:62"
│      → Recibe: reporte de cambios realizados
│
├── 4. Procesa los cambios — extrae archivos modificados
│
├── 5. Delega al tester con contexto:
│      "Run tests. Modified files: src/auth.py, src/api.py,
│       src/routes/products.py"
│      → Recibe: reporte de tests
│
└── 6. Te presenta el resumen consolidado

La instrucción que activa el chain

Un prompt natural activa el patrón:

Usa el reviewer para analizar los cambios recientes.
Después, usa el implementer para corregir los problemas encontrados.
Finalmente, usa el tester para verificar que todo funcione.

Claude entiende la secuencia implícita: el output del reviewer informa al implementer, y el resultado del implementer define lo que el tester verifica.

Esto es exactamente lo que construirás en la cápsula 05. El pipeline reviewer → implementer → tester es este patrón chain con los subagents que ya diseñaste en las cápsulas anteriores.

Foreground vs Background: Cuándo Usar Cada Modo

Foreground (blocking)

El modo por defecto. Claude espera a que el subagent termine antes de continuar:

Tú: "Usa el reviewer para analizar el módulo de auth"
Claude: [delegando al reviewer...] ← Esperas aquí
Claude: "El reviewer encontró 2 issues críticos..."

Background (concurrent)

Los subagents en background corren mientras tú continúas trabajando. Claude solicita los permisos antes de lanzar, porque no podrá preguntarte durante la ejecución:

Tú: "Usa el reviewer en background para analizar todo el proyecto"
Claude: "¿Permito que el reviewer ejecute shell commands? [Sí/No]"
Tú: "Sí"
Claude: [lanza reviewer en background]
Tú: "Mientras tanto, explícame el módulo de pagos"
Claude: [responde mientras el reviewer trabaja en paralelo]
...
Claude: "El reviewer terminó. Encontró 3 issues..."

Para ejecutar en background: indicarlo en el prompt, configurar background: true en el frontmatter, o presionar Ctrl+B para enviar un subagent en ejecución al background.

Comparación: Foreground vs Background

Regla práctica

¿El output es input del siguiente agente?  → Foreground
¿La tarea es independiente y larga?         → Background
¿Necesitas 3 análisis independientes?       → Background × 3

Para desactivar background tasks globalmente:

export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1

Resumir Subagents: Continuidad de Contexto

Un subagent termina, pero necesitas que continúe con contexto adicional. Sin resume, empezaría de cero:

Tú: "Usa el reviewer para revisar el módulo de autenticación"
[El reviewer analiza auth.py, middleware.py, tokens.py — devuelve reporte]

Tú: "Continúa esa revisión y ahora analiza también la autorización"
[Claude resume el MISMO subagent — conserva contexto, no re-lee auth.py]
[Analiza authorization.py, permissions.py — devuelve reporte complementario]

Los agent IDs se almacenan en ~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl.

Si un subagent en background se detiene por permisos, puedes resumirlo en foreground:

Resúmelo en foreground para que pueda pedir los permisos necesarios

Gestión del Context Window

Cada output de subagent consume espacio en la ventana de contexto principal. Con 3 subagents el impacto es manejable. Con 10 subagents detallados, el contexto se compacta frecuentemente.

Estrategias para controlar el tamaño

1. Límites explícitos en el system prompt:

## Output Constraints
- Maximum 10 findings (prioritize by severity)
- Code snippets: max 3 lines each
- No explanations longer than 2 sentences
- Total response: under 80 lines

2. Aislar operaciones pesadas en subagents:

MALO: En la conversación principal, leer 50 archivos y analizarlos
→ Todo ocupa contexto principal

BUENO: Subagent lee 50 archivos, devuelve resumen de 20 líneas
→ Solo 20 líneas ocupan contexto principal

Esta es una ventaja clave de los subagents: aíslan operaciones voluminosas. El subagent lee 50 archivos dentro de su propio contexto pero solo devuelve el resumen.

3. Auto-compaction: Al ~95% de capacidad, Claude Code compacta automáticamente. Ajusta el umbral:

export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=80

Patrones de Comunicación

Patrón 1: Chain secuencial (A → B → C)

Cada agente produce un output que informa al siguiente. El implementer necesita saber qué corregir antes de empezar.

reviewer → findings → implementer → changes → tester → results

Patrón 2: Investigación paralela

Múltiples subagents analizan aspectos diferentes simultáneamente:

                ┌→ security-reviewer → findings ─┐
Tu prompt ──────┼→ perf-reviewer → findings ─────┼→ Claude consolida
                └→ style-reviewer → findings ────┘

Patrón 3: Aislamiento de operaciones pesadas

Delegar operaciones voluminosas para que solo regrese un resumen:

Tu prompt → subagent lee 200 archivos → devuelve resumen de 30 líneas

Patrón 4: Chain con validación

Si el tester encuentra fallos, re-ejecutar parte del chain:

reviewer → implementer → tester
                              ├── ALL_PASS → fin
                              └── FAILURES → implementer → tester (retry)

Limitación clave

Un subagent no puede spawnar otros subagents. Solo la conversación principal puede delegar. Para orquestación multinivel, el módulo 4 (Agent Teams) es la solución. En este módulo, Claude en la conversación principal actúa como coordinator.

Error Handling: Output Inesperado

Qué puede salir mal

Defensa en el system prompt

Manejar "nada encontrado":

- If no issues found: respond with EXACT text:
  "### Review: CLEAN — No issues found in [n] files reviewed"
- NEVER return an empty response
- NEVER skip the Summary section

Forzar consistencia:

## Critical Output Rules
1. ALWAYS include the Summary section, even if empty
2. ALWAYS use the EXACT headers specified
3. If a category has no items, write "None found."
4. NEVER wrap output in markdown code fences

Manejar errores de herramientas:

- If git diff fails: report "ERROR: Could not read git history"
- If a file cannot be read: skip it, note in "Files Skipped" section
- If tests fail to RUN (not test failures, execution errors):
  report under "### EXECUTION ERROR" with the error message

Conexión con el Proyecto (Cápsula 05)

El pipeline que construirás en la cápsula 05 es este patrón chain en acción:

Paso 1: reviewer analiza → devuelve findings estructurados
Paso 2: Claude extrae CRITICAL y WARNING del reporte
Paso 3: implementer recibe findings como contexto → devuelve cambios
Paso 4: Claude extrae archivos modificados
Paso 5: tester ejecuta tests → devuelve pass/fail
Paso 6: Si hay fallos, Claude pasa detalles al implementer (iteración)

Todo lo que practicaste aquí — system prompts con formato explícito, chains secuenciales, manejo de output, control de contexto — se materializa en ese proyecto.

Troubleshooting

"El output del subagent no tiene la estructura que define"

Causa: El system prompt describe el formato pero no lo muestra con un ejemplo literal.

Solución: Incluye un ejemplo completo con datos ficticios y agrega "follow this EXACT structure." Un ejemplo literal es más efectivo que una descripción del formato.

"El subagent devuelve demasiada información"

Causa: Sin límites explícitos, reporta todo con máximo detalle.

Solución: Agrega constraints numéricos: "Maximum 10 findings. Code snippets: 3 lines max. Total response: under 80 lines."

"Claude no pasa el contexto correcto al siguiente subagent"

Causa: El output del primer subagent no tiene la información que el segundo necesita.

Solución: Sé explícito: "Del reporte, extrae SOLO los items CRITICAL. Pasa al implementer: archivo, línea, y descripción de cada uno."

"El subagent en background falló silenciosamente"

Causa: Necesitó un permiso que no fue concedido antes de lanzar.

Solución: Resume en foreground. Alternativa preventiva: usa permissionMode: bypassPermissions para subagents de background si confías en sus restricciones de tools.

"Resultados inconsistentes entre ejecuciones"

Causa: Criterios subjetivos en el system prompt.

Solución: Reemplaza subjetividad con medibles: "functions with cyclomatic complexity > 8" en vez de "important issues."

Ejercicios

Ejercicio 1: Diseñar output para encadenamiento (Fácil)

Tienes un dependency-checker cuyo output será consumido por un dependency-updater. Diseña el system prompt del checker con un formato que el updater pueda consumir directamente. Debe incluir: paquete, versión actual, versión nueva, y nivel de riesgo (major/minor/patch).

---
name: dependency-checker
description: Checks for outdated dependencies with risk classification
tools: Read, Glob, Bash
disallowedTools: Write, Edit
model: haiku
maxTurns: 10
---

## Role
Dependency auditor. Check for outdated packages. Report for updater agent.

## Process
1. Identify package manager (requirements.txt, pyproject.toml, package.json)
2. Run check: pip list --outdated --format=json OR npm outdated --json
3. Classify by semver risk

## Output Format (EXACT structure)

### Dependency Audit
**Package manager:** [pip|npm]
**Config file:** [path to config file]

#### MAJOR (breaking changes possible)
- **[package]** current=[version] → latest=[version]

#### MINOR (backward compatible)
- **[package]** current=[version] → latest=[version]

#### PATCH (bug fixes only)
- **[package]** current=[version] → latest=[version]

#### Summary
- Major: [n] | Minor: [n] | Patch: [n]
- Recommendation: UPDATE_ALL | UPDATE_MINOR_PATCH | REVIEW_MAJOR_FIRST

Ejercicio 2: Prompt de chain de 3 agentes (Fácil)

Escribe el prompt que le darías a Claude para: lint-checker analiza, lint-fixer corrige errores, lint-verifier verifica que no queden errores. Incluye instrucciones de qué transferir entre cada paso.

Ejecuta este flujo en secuencia:

1. Usa el lint-checker para analizar todos los archivos Python en src/.
   Espera su reporte completo.

2. Del reporte del lint-checker, extrae todos los errores (no warnings).
   Pasa al lint-fixer: la lista de archivos con errores, el código
   de error (E501, W291, etc.), y la línea específica.

3. Usa el lint-verifier para correr el linter sobre los archivos
   que fueron modificados. Si reporta 0 errores, el flujo termina.
   Si reporta errores restantes, muéstramelos sin intentar corregir.

Ejercicio 3: Foreground vs background — Decidir el modo (Medio)

Para cada escenario, decide foreground o background y justifica:

1. Reviewer analiza auth, su output va al implementer
2. Tres reviewers independientes analizan security, performance y style
3. Un tester ejecuta una suite que tarda 5 minutos
4. Un implementer necesita permisos para instalar un package

Ejercicio 4: System prompt antes y después (Medio)

Este system prompt produce output impredecible. Reescríbelo para output consistente y parseable:

---
name: test-analyzer
description: Analyzes test results
tools: Bash, Read
---

Run the tests and tell me what happened. Include any failures
with details about why they failed.

---
name: test-analyzer
description: Runs tests and produces structured pass/fail report
tools: Bash, Read, Glob
disallowedTools: Write, Edit
model: haiku
maxTurns: 10
---

## Role
Test executor and reporter. NEVER modify source code or tests.

## Process
1. Detect framework (pytest.ini, pyproject.toml, package.json)
2. Run with verbose: `python -m pytest -v --tb=short 2>&1`
3. Parse and report

## Output Format (EXACTLY)

### Test Report
**Framework:** [pytest|jest|vitest]
**Command:** [exact command]

#### Results
- Passed: [n] | Failed: [n] | Skipped: [n]

#### Failures
- **[test_file::test_name]**
  - Expected: [assertion]
  - Actual: [what happened]
  - Root cause: [one sentence]

If no failures: "None"

#### Verdict: [ALL_PASS | HAS_FAILURES | EXECUTION_ERROR]

## Rules
- ALWAYS include all sections
- NEVER include full stack traces
- NEVER suggest fixes — only report

Ejercicio 5: Controlar tamaño del output (Medio)

Tu codebase-auditor analiza 100+ archivos y produce reportes de 500+ líneas. Rediseña el system prompt para máximo 50 líneas sin perder información crítica.

---
name: codebase-auditor
description: Audits codebase and produces compact summary
tools: Read, Grep, Glob
model: haiku
maxTurns: 20
---

## Role
Codebase auditor. COMPACT output — will be consumed by other agents.

## Output Constraints (MANDATORY)
- MAXIMUM 50 lines total
- Top 5 findings only (by severity)
- One line per finding: **[file:line]** severity — description
- No code snippets longer than 1 line
- Aggregate similar issues: "N+1 queries in 4 files" not 4 entries

## Output Format

### Audit Summary
**Files:** [n] | **Issues:** [n] | **Severity:** [highest]

#### Top Findings (max 5)
1. **[file:line]** CRITICAL — [description]
2. **[file:line]** WARNING — [description]

#### Patterns
- [pattern]: [n] files ([abbreviated list])

#### Health: [0-100] — [one sentence]

## Aggregation
- Same issue in 3+ files: aggregate into one finding
- Group by pattern, not by file
- Priority: security > correctness > performance > style

Ejercicio 6: Chain con manejo de errores (Difícil)

Diseña un chain scanner → fixer → verifier con manejo de: scanner no encuentra nada, fixer no puede corregir un issue, verifier detecta regresiones. Escribe el prompt completo.

Ejecuta este flujo con manejo de errores:

## Paso 1: Scanner
Usa el security-scanner para analizar src/.
- Si devuelve "CLEAN — No issues": para aquí, repórtame que está limpio.
- Si devuelve findings: continúa al paso 2.
- Si devuelve error de ejecución: repórtame el error y para.

## Paso 2: Fixer
Pasa al security-fixer SOLO los CRITICAL del scanner.
Incluye: archivo, línea, descripción, recomendación.
- Si reporta items "Not addressed": anota cuáles y por qué. Continúa.
- Si no pudo corregir NINGUNO: para, repórtame que requiere fix manual.

## Paso 3: Verifier
Usa el security-verifier para testear archivos modificados por el fixer.
- Si ALL_PASS: reporta éxito con resumen.
- Si HAS_FAILURES: pasa fallos al fixer para un segundo intento.
  Máximo 1 re-intento. Si sigue fallando: para y repórtame
  qué tests fallan y qué correcciones los causaron.

## Reporte Final (siempre)
- Issues encontrados: [n]
- Corregidos: [n]
- No corregidos: [n] (con razón)
- Tests: PASS / FAIL
- Estado: RESOLVED | PARTIALLY_RESOLVED | NEEDS_MANUAL_FIX

Resumen

• Solo el mensaje final del subagent regresa a la conversación principal — tool calls intermedios y razonamiento se quedan en el contexto del subagent
• El system prompt es la clave para output parseable — sin formato definido, obtienes prosa libre impredecible
• Un ejemplo literal del output esperado es más efectivo que una descripción del formato
• El patrón chain (A → B → C) funciona porque Claude procesa el output de un subagent y construye el contexto del siguiente
• Foreground para chains donde cada paso depende del anterior; background para tareas independientes en paralelo
• Resume preserva el contexto de un subagent para continuar sin empezar de cero
• Cada output consume contexto principal — usa constraints de tamaño y aísla operaciones pesadas en subagents
• Los subagents no pueden spawnar otros subagents — delegación multinivel requiere Agent Teams (módulo 4)
• Auto-compaction al ~95% protege contra overflow; ajústalo con CLAUDE_AUTOCOMPACT_PCT_OVERRIDE
• El pipeline reviewer → implementer → tester de la cápsula 05 es este patrón chain con formato estructurado

Recursos Adicionales

1. Create Custom Subagents (Anthropic Docs) — Documentación oficial de subagents incluyendo output handling y chaining
2. Claude Code Sub-Agents — Referencia de foreground/background y resume
3. Claude Code Best Practices — Buenas prácticas de delegación y manejo de contexto
4. Prompt Engineering: Be Clear and Direct — Técnicas de claridad transferibles a system prompts
5. Claude Code CLI Reference — Flags de background tasks y compaction
6. Claude Code Settings — Variables de entorno: CLAUDE_AUTOCOMPACT_PCT_OVERRIDE, CLAUDE_CODE_DISABLE_BACKGROUND_TASKS
7. Prompt Engineering: Give Claude a Role — Cómo definir roles que producen outputs consistentes
8. Claude Code Tips and Tricks — Tips sobre manejo de contexto y delegación

Siguiente cápsula: En la cápsula 05 construirás el proyecto del módulo: un pipeline funcional de 3 subagents (reviewer → implementer → tester) que analiza código real, corrige problemas, y verifica que los tests pasen. Todo lo que aprendiste en las cápsulas 02-04 — subagent files, restricciones de herramientas, y comunicación estructurada — se integra en un flujo de desarrollo que puedes usar mañana en tu proyecto.