Flujo de trabajo multi-agente — colaboración entre Claude Code y Codex CLI

Lo primero que falla cuando un usuario de un solo agente empieza a combinar dos o más es el supuesto de que comparten contexto. Las personas cubren los vacíos con Slack, reuniones y trabajo conjunto. Los agentes no pueden. La delegación debe expresarse no como una promesa, sino como una puerta impuesta en código.

Esta guía recopila patrones de una semana o más ejecutando Claude Code (agente principal) + Codex CLI (subagente). Los mismos patrones aplican a otras combinaciones (Cursor + Claude Code, Aider + Claude Code, etc.).

TL;DR

1. División de roles: análisis / planificación / instrucciones van al agente principal (Opus); la ejecución va al secundario (Sonnet / Codex). La misma tarea en ambos produce resultados divergentes.
2. Escribir un documento de traspaso: no un mensaje de Slack. Un documento autónomo que otro agente puede leer y con el que puede terminar el trabajo.
3. Empaquetar puertas de verificación como código: scripts npm run verify:{fase} + verificaciones de CI. Sin puertas, los vacíos se acumulan.
4. Una tarea por agente: no confiar ciegamente en los resultados del secundario. El principal re-ejecuta antes del merge.

Por qué usar varios agentes

Un agente es suficiente para muchas tareas: ediciones en un solo archivo, refactorizaciones cortas, revisiones de código. El flujo multi-agente gana en estos casos:

• Trabajo independiente paralelizable: frontend + backend + migración concurrentemente
• División alineada al modelo: razonamiento (Opus) y ejecución (Sonnet/GPT) divididos por coste y velocidad
• Aislamiento de contexto: proteger el contexto del agente principal en codebases grandes
• Verificación independiente: la separación de autor y verificador aporta objetividad

Es una pérdida cuando:

• El trabajo converge en un solo archivo: los conflictos de merge anulan la ganancia de colaboración
• El contexto es muy pequeño: el documento de traspaso tarda más que el trabajo
• La especificación es ambigua: dos agentes divergirán en interpretaciones diferentes

1. División de roles: quién hace qué

El error habitual es "hacer que ambos hagan el mismo trabajo". Los resultados divergen y nadie es responsable del resultado final.

División recomendada:

Incluso si una sola persona ejecuta ambos, dividir las sesiones. Si el agente principal verifica sus propios resultados con su propio contexto, se pierde la objetividad.

Qué solo hace el principal

• Plan + evaluación de tradeoffs + comparación de alternativas
• Documentar el "por qué" detrás de las decisiones
• Escribir el documento de traspaso
• Verificar los resultados del secundario antes del merge (re-ejecutar, inspeccionar el output raw de la puerta)

Qué solo hace el secundario

• Tareas claramente definidas — entrada/salida/aceptación fijados en el traspaso
• Trabajo CLI repetitivo (build, test, ejecuciones de migración)
• Grep/find en codebases grandes — protege el contexto del principal

Nunca hacer que ambos hagan

• "Descubrir cómo hacer esto y contarme" — dos respuestas diferentes que reconciliar
• "Escribir el código y también verificarlo" — la auto-revisión pasa por alto los puntos ciegos

2. Patrón de documento de traspaso

Un traspaso es un documento autónomo que otro agente puede usar para terminar el trabajo desde ese punto. No es un mensaje de Slack ni un prompt corto.

Secciones requeridas

# Fase X — {Título}
 
## Objetivo
{Una frase: qué se termina}
 
## Contexto
- Archivos relacionados: `src/foo.ts:42`, `tests/foo.test.ts`
- Trabajo previo: PR #123 mergeado, RFC-005 adoptado
- Dep externa: especificación API `docs/api.md` v2
 
## Ámbito
1. Cambiar firma de {función B} en {archivo A}
2. Añadir nueva función D en {archivo C}
3. Actualizar cuatro tests en {archivo E}
 
## Fuera del ámbito
- No {extensión tentadora} (trabajo de la siguiente fase)
- No {tentación de refactorización} (PR separado)
 
## Aceptación
- [ ] `npm run verify:fase-X` pasa
- [ ] `npm run typecheck` limpio
- [ ] Diff del PR < 300 líneas (dividir en más pequeños si es mayor)
 
## Comandos de verificación
\`\`\`bash
npm run verify:fase-X  # puerta específica de la fase
npm test src/foo        # tests unitarios
\`\`\`
 
## Cuando estés bloqueado
- Si encuentras el mismo error 3 veces, reportar de vuelta (sin bucle infinito propio)
- Si la API externa devuelve algo diferente a lo esperado, reportar (no falsificar respuestas)
 
## Autor / Fecha
csmarch · 2026-05-12

Principios fundamentales

1. Autónomo: el trabajo debe ser posible solo con el traspaso. "Lo hablamos en Slack" no es válido.
2. Declarar el ámbito Y lo que está fuera: bloquea la expansión de alcance bienintencionada.
3. Aceptación como código: reemplazar "si funciona, OK" con puertas concretas npm run verify:fase-X.
4. Regla de bloqueo: límite explícito en el tiempo de auto-depuración.

La longitud del traspaso escala con el tamaño de la tarea. Un traspaso de 100 líneas para una tarea de una línea es un desperdicio. 5+ archivos o un nuevo módulo → traspaso obligatorio; corrección de bug en 1–2 archivos → una línea de chat está bien.

3. Puertas de verificación: promesas convertidas en código

El error más común y más costoso: "Verificaremos después del merge."

Cuando el secundario reporta que terminó, el principal confía y pasa a la siguiente fase. Si la siguiente fase rompe algo, hay que rastrear hacia atrás. Los vacíos se acumulan y eventualmente explotan en una costosa puesta al día.

Principio: empaquetar el script de verificación y la puerta de merge en el mismo PR que el traspaso.

Tres puertas

1. Script de verificación local: npm run verify:fase-X o npm run verify:auth, una por tarea
2. Puerta CI: GitHub Actions / GitLab CI ejecuta verify:fase-X automáticamente. Merge bloqueado en caso de fallo
3. Re-ejecución del principal: el principal reproduce el resultado del secundario en su propio entorno. Mismo resultado → merge

Ejemplo — script verify:fase-X

// package.json
{
  "scripts": {
    "verify:fase-A": "tsc --noEmit && eslint src/fase-a && jest src/fase-a --coverage",
    "verify:fase-B": "...",
    "verify:assets": "node scripts/check-asset-sha256.mjs"
  }
}

Ejemplo de puerta GitHub Actions

# .github/workflows/ci.yml
name: CI
on: [pull_request]
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v3
      - run: pnpm install --frozen-lockfile
      - run: pnpm lint
      - run: pnpm build
      - run: pnpm verify:assets   # la verificación de fase sigue el mismo patrón

Formato de informe de finalización del secundario

Cuando el secundario reporta una fase completada, adjuntar:

[Fase X completada]
- Archivos modificados: 5 (src/foo.ts, ...)
- Output raw de verify:
  $ npm run verify:fase-X
  ✓ tsc limpio
  ✓ eslint limpio
  ✓ jest 23 pasados
- PR: #234

Informes sin output raw de verify → pedir de nuevo. No confiar en el texto "funciona".

4. Una tarea por agente: no confiar ciegamente en los resultados

No continuar en cuanto el secundario reporte que terminó. El principal hace tres cosas:

1. Re-ejecutar: no confiar en el output raw de verify del secundario; el principal ejecuta los mismos comandos localmente. Si difiere, investigar (¿diferencia de entorno? ¿condición de carrera? ¿caché?).
2. Revisión del diff: revisar el diff del PR con la misma profundidad que una revisión humana. Vigilar cambios fuera de ámbito, comentarios ausentes y tests faltantes.
3. Probar casos contrarios: más allá de la aceptación, ejecutar 1–2 casos de "esto no debe romperse" por cuenta propia.

Esto no es dudar de la capacidad del secundario: los agentes fundamentalmente no pueden ver los puntos ciegos de su propio contexto. Las personas tampoco pueden revisar su propio código con objetividad.

5. Lecciones de fallos reales

Caso: el traspaso existía, la puerta no

Situación: fase D de rediseño de UI delegada. El traspaso listaba 8 elementos de aceptación. El secundario reportó "todo listo". El principal hizo merge. Comenzó la fase E.

Problema: La aceptación #4 de la fase D en realidad no pasaba (el secundario juzgó una implementación parcial como OK). La fase E usó la función de la fase D y se rompió. Depurar la fase E requirió volver a la fase D. El mismo patrón se repitió en F.

Recuperación: una fase separada para poner al día D~F, con scripts verify:fase-D escritos retroactivamente. Si la puerta hubiera existido desde el principio, habría fallado antes.

Lección: La aceptación sin un script de verificación se desvanece. Empaquetar traspaso + script verify + puerta CI en el mismo PR.

Caso: bucle infinito propio del secundario

Situación: Al secundario se le pidió "arreglar los tests que fallan". El secundario probó 5 cosas diferentes en su propio código, cada una produciendo un nuevo error. Después de una hora: "Probé varias cosas, no funciona."

Problema: Sin regla de bloqueo. El secundario no tenía criterio para cuándo pedir ayuda.

Recuperación: Se añadió "reportar inmediatamente después de 3 intentos con el mismo error" a la plantilla de traspaso. El principal proporcionó una hipótesis diferente con contexto más amplio.

Lección: Estipular reglas de bloqueo en el traspaso. "Seguir intentando" pasa a ser "Después de 3 fallos, reportar."

6. Lista de verificación para empezar con multi-agente

Primera semana al cambiar a flujo multi-agente:

1. Definir la persona y reglas del agente principal: CLAUDE.md o equivalente con rol, autonomía, prohibiciones y estilo de código.
2. Empezar con un solo secundario: Codex CLI o un subagente Sonnet. No 3–4 a la vez.
3. Mantener los primeros traspasos cortos: trabajo de 1–2 archivos, 2–3 elementos de aceptación, un script verify.
4. Registrar una puerta verify en GitHub Actions: añadir más a medida que las fases se multiplican.
5. Aplicar la regla de bloqueo: reportar después de 3 fallos y el principal revisa.
6. Retrospectiva después de cada fase: nota de una línea sobre qué faltó. La plantilla de traspaso evoluciona con el tiempo.

Solución de problemas

"El traspaso es tan largo que pierdo la motivación"

La tarea es demasiado grande. Dividir la fase en partes más pequeñas. Si el traspaso supera las 100 líneas, el trabajo probablemente dure más de una semana.

"El secundario sigue haciendo trabajo fuera del ámbito"

La sección "Fuera del ámbito" es vaga o está ausente. En lugar de "sin refactorización", escribir concretamente "no tocar src/legacy/".

"No tengo tiempo para escribir scripts verify"

Escribir el script verify al mismo tiempo que el traspaso, no después del código. Cada elemento de aceptación se mapea a una aserción en verify:fase-X.

"Dos agentes siguen generando conflictos"

El aislamiento de contexto falló: sus ámbitos se superponen. La "lista de archivos de ámbito" del traspaso debe ser claramente separable. Dos personas editando el mismo archivo también generarían conflictos.

"El principal se convierte en un cuello de botella"

La solución no es dar al secundario más autoridad. El principal conserva la verificación y las decisiones de merge. En cambio, invertir en la automatización del traspaso y las puertas, y reducir la cantidad de trabajo (ámbito más pequeño, plan más simple).

Referencias

• Configuración de Claude Code — configuración del agente principal primero
• Anthropic — Subagentes de Claude Code (mejores prácticas de subagentes)
• OpenAI Codex CLI — openai-codex GitHub

Registro de cambios

• 2026-05-12: Primer borrador. Una semana+ de experiencia de operación como seis secciones + cinco casos de solución de problemas.