Subagentes en paralelo en Codex y Claude Code: prompts y configuración

La idea extendida de que «Claude Code trabaja en paralelo por su cuenta, pero Codex no lo hace a menos que se lo pidas» es cierta, con matices. La app, la CLI y la extensión para IDE de Codex lanzan trabajadores en paralelo (subagentes) cuando se lo pides, o cuando AGENTS.md o una skill le indican que reparta el trabajo entre subagentes. Claude Code, además, delega por iniciativa propia, según el contenido de tu petición y la descripción de cada subagente.

Este artículo compara cómo conseguir trabajo en paralelo con ambas herramientas, a partir de la documentación oficial de OpenAI y Anthropic (consultada el 26 de octubre de 2026), en este orden: disparadores, cómo redactar las instrucciones, configuración, comandos y coste. En cada sección las dos herramientas aparecen en el mismo orden y con los mismos colores: Codex → Claude Code. Al final resumo las lecciones que este sitio ha aprendido ejecutando subagentes en paralelo con Claude Code.

1. Qué activa el trabajo en paralelo y qué pasa si no dices nada

Un subagente es un trabajador independiente que se encarga de una parte del trabajo de la conversación principal. Cada uno investiga o ejecuta pruebas en su propio contexto y devuelve a la conversación principal solo un resumen de sus resultados. Ejecutarlos en paralelo reduce la espera y evita que la conversación principal se llene de registros intermedios. Las dos herramientas comparten esta idea.

Lo que cambia es quién lo inicia. Veamos cuatro situaciones.

Fuentes: OpenAI «Subagents»; Anthropic «Create custom subagents». Consultado el 26 de octubre de 2026.

Según la documentación oficial de Codex, las versiones locales de Codex (app, CLI, extensión para IDE) delegan «cuando se les pide directamente o cuando las instrucciones pertinentes de AGENTS.md o de una skill requieren delegar». La función no está desactivada: el sistema de subagentes viene activado por defecto en las versiones actuales. Lanzarlos o no depende de tus instrucciones. En ChatGPT Work (web), la mayoría de los niveles de inteligencia requieren una petición explícita, y solo si eliges Ultra (Ultra está limitado a cuentas que cumplan los requisitos y a modelos compatibles) puede delegar por su cuenta cuando trabajar en paralelo mejoraría sustancialmente la velocidad o la calidad.

La descripción oficial de Claude Code es que «delega automáticamente según la tarea de tu petición, la description de la definición del subagente y el contexto actual». Para los subagentes que quieras que se usen de forma más proactiva, recomienda poner frases como «use proactively» en la descripción. Los subagentes que heredan la conversación tal cual (forks) también los lanza Claude a su criterio por defecto.

Un detalle: el registro de cambios de Codex incluye un cambio que permite a quienes integran Codex en sus propios productos (clientes de app-server) elegir la delegación entre «desactivada, solo peticiones explícitas o proactiva» (Codex CLI 0.142.0, 22 de junio de 2026). Para quienes usan la app, la CLI y el IDE, el comportamiento es el de la tabla anterior.

2. Cómo funcionan ambas, lado a lado

Aquí se compara cómo se escriben las definiciones de subagentes, cuántos pueden ejecutarse a la vez, cómo se separan los directorios de trabajo y más. Cuando solo la documentación oficial de una de las dos cubre un punto, se marca como «No documentado».

Fuentes: OpenAI «Subagents», «Configuration Reference», «Worktrees»; Anthropic «Create custom subagents», «Run parallel sessions with worktrees». Consultado el 26 de octubre de 2026.

Hay dos grandes diferencias. La primera es si puedes impedir que un subagente escriba. Codex usa los permisos del padre tal cual, así que decirle a un subagente «no edites» es solo una petición. Claude Code puede quitarle por completo a un subagente las herramientas de edición (Write, Edit). Para bloquear también la escritura desde la shell, quita además Bash. La segunda es una copia de trabajo por subagente: Claude Code puede crear un git worktree (una copia de trabajo separada del mismo repositorio) para cada subagente, mientras que en Codex los worktrees son por chat.

Claude Code tiene otras formas de trabajar en paralelo además de los subagentes (la vista de agentes, que ejecuta sesiones separadas en una sola pantalla, y los equipos de agentes, en los que los trabajadores se comunican entre sí). Las diferencias se explican en «Subagentes vs equipos de agentes en Claude Code» y «La vista de agentes de Claude Code».

3. Cómo redactar las instrucciones, con prompts listos para usar

La documentación oficial de Codex recomienda que un buen prompt indique cómo repartir el trabajo, si hay que esperar a todos los agentes antes de continuar y qué debe devolverse. Por nuestra experiencia ejecutando subagentes en paralelo en este sitio, añadir dos puntos más reduce los accidentes.

1. Cómo repartir el trabajoPor tema (seguridad, pruebas, mantenibilidad), por ubicación (directorio, módulo), etc. Reparte de forma que dos subagentes no miren lo mismo
2. Qué pueden tocar«Solo lectura» o «solo puedes editar este directorio». Nunca dejes que dos subagentes toquen el mismo archivo
3. Si hay que esperar a todosCombinar solo cuando estén todos los resultados, o permitir avanzar a mitad de camino
4. Qué devolverFormato y extensión («menos de 10 líneas con nombres de archivo», etc.). Las respuestas largas llenan rápido el contexto principal
5. Qué no hacerHacer commit, hacer push, que los subagentes lancen más subagentes, etc. Si no se les dice qué está prohibido, los subagentes lo harán con la mejor intención

Investigación y revisiones de solo lectura (empieza por aquí)

Revisa esta rama frente a main. Lanza tres subagentes en paralelo:
uno para problemas de seguridad, otro para pruebas que faltan y otro para la mantenibilidad.
Ninguno debe editar ningún archivo.
Espera a que terminen los tres y luego resume por tema, con nombres de archivo y números de línea.

Investiga en paralelo los módulos de autenticación, base de datos y API usando subagentes separados.
Todos los subagentes deben limitarse a leer, sin cambiar ningún archivo.
Que cada uno devuelva «archivos de entrada, flujo principal de procesamiento, puntos de atención» en menos de 10 líneas,
y combínalos en uno solo cuando estén todos los resultados.

Repartir trabajo que edita archivos

La documentación oficial de ambas trata con cautela el trabajo en paralelo con muchas escrituras. Asigna a cada subagente su propia zona editable y, en Claude Code, separa también las copias de trabajo.

Averigua por qué falla el guardado en la página de ajustes y corrígelo.
Que browser_debugger lo reproduzca en el navegador y anote los pasos,
y que code_mapper localice el código responsable (estos dos no deben editar nada).
Cuando se conozca la causa, que ui_fixer haga la corrección mínima. No toques archivos no relacionados.

/batch migra el JavaScript de src/ a TypeScript

Para no tener que decirlo cada vez

Si pedir trabajo en paralelo cada vez en Codex te resulta pesado, escribe reglas de delegación en el AGENTS.md del proyecto. La documentación oficial dice que delega cuando hay instrucciones pertinentes en AGENTS.md o en una skill. No dice qué redacción lo activa de forma fiable, así que, después de escribir las reglas, comprueba una vez si se lanzan subagentes con tus peticiones habituales.

## Uso de subagentes
- Para investigaciones que abarquen tres o más directorios, lanza un subagente por directorio e investiga en paralelo
- No dejes que los subagentes editen archivos. Haz toda la edición en el hilo principal
- Espera a tener todos los resultados y luego informa solo de lo esencial

En Claude Code, si quieres que se use más un subagente concreto, escribe en su description cuándo usarlo, además de «use proactively» (en la siguiente sección hay un ejemplo de definición). Al contrario, si delega demasiado, añadir Agent a permissions.deny impide que lance subagentes.

4. Configuración y archivos de definición de subagentes

Codex config.toml y .codex/agents/

Los ajustes globales van en [agents] de config.toml (personal: ~/.codex/config.toml, proyecto: .codex/config.toml).

# .codex/config.toml
[agents]
max_concurrent_threads_per_session = 4     # Máximo de hilos de subagentes abiertos a la vez (sin contar el hilo principal)
default_subagent_model = "gpt-6-luna"      # Modelo por defecto para los subagentes
default_subagent_reasoning_effort = "high" # Esfuerzo de razonamiento por defecto para los subagentes

Fuente: OpenAI «Configuration Reference». Consultado el 26 de octubre de 2026. El «multi agent v2» que aparece a menudo en los resultados de búsqueda es la versión actual de este sistema; según el registro de cambios, pasó a ser estable en Codex CLI 0.145.0 (21 de julio de 2026) (registro de cambios). En las versiones actuales está activado sin que tengas que escribir multi_agent = true.

Los agentes personalizados van en .codex/agents/, un archivo TOML por agente. El nombre del agente sale de name, no del nombre del archivo.

# .codex/agents/reviewer.toml
name = "reviewer"
description = "Revisor centrado en la corrección, la seguridad y las pruebas que faltan"
model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
developer_instructions = """
No edites archivos.
Prioriza la corrección, la seguridad, las regresiones de comportamiento y las pruebas que faltan.
Haz comentarios solo de estilo únicamente cuando oculten un error real.
"""

Adaptado del ejemplo oficial. Los nombres de modelo proceden del ejemplo oficial; los modelos disponibles varían según la cuenta y el espacio de trabajo. La recomendación oficial es gpt-6.1-sol para agentes que toman muchas decisiones de criterio y gpt-6-luna para agentes ligeros con un alcance bien acotado. Ajustes como sandbox_mode, approval_policy y mcp_servers quedan sustituidos por los del padre aunque los escribas en el archivo del agente.

Claude Code .claude/agents/ y settings.json

Los subagentes se guardan en .claude/agents/ como Markdown. También puedes pedirle a Claude que «cree un subagente que haga X» y dejar que escriba el archivo.

---
name: test-runner
description: Runs the test suite and reports only failing tests with their errors. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: haiku
---

Ejecuta las pruebas y devuelve solo los nombres de las que fallan y lo esencial de sus errores.
No corrijas código. No devuelvas la lista de pruebas que pasan.

Como tools no incluye Write ni Edit, según la documentación oficial este subagente no puede editar ni escribir archivos. Sin embargo, se mantiene Bash para que pueda ejecutar las pruebas, lo que deja margen para escribir mediante comandos de shell. El «No corrijas código» del cuerpo sirve de recordatorio para eso. model acepta sonnet, opus, haiku, fable, un ID de modelo o inherit (el mismo que la conversación principal). Cómo elegir modelo por subagente se explica en «Cómo ejecutar los subagentes de Claude Code con otro modelo».

El límite de concurrencia y la profundidad de anidamiento se configuran con variables de entorno, que puedes poner en env de settings.json.

{
  "env": {
    "CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS": "5",
    "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "1"
  }
}

Fuentes: Anthropic «Create custom subagents», «Orchestrate teams of Claude Code sessions». Consultado el 26 de octubre de 2026.

5. Referencia de comandos

Estos son los comandos para vigilar los subagentes en ejecución, separar copias de trabajo, ramificar una conversación, etc. Algunos comparten nombre pero hacen cosas distintas, así que ten cuidado.

Fuentes: OpenAI «Command line options, Slash commands», «Subagents»; Anthropic «Commands», «Run agents in parallel», «Create custom subagents» (probar varios enfoques con forks). Consultado el 26 de octubre de 2026.

El que confunde es /agents, porque el nombre coincide. En Codex, /agents es la lista de chats en el servidor (el centro de mando). En Claude Code, /agents te indica dónde se guardan las definiciones de subagentes, y la lista de sesiones es claude agents (se lanza desde la shell).

6. Tareas que encajan con el trabajo en paralelo y tareas que no

La documentación oficial de ambas dice casi lo mismo: empieza por el trabajo de solo lectura y ten cuidado con el que implica muchas escrituras.

Fuentes: OpenAI «Subagents» (Why subagent workflows help); Anthropic «Create custom subagents» (Choose between subagents and main conversation) y «agent teams» (Avoid file conflicts). Consultado el 26 de octubre de 2026.

7. Impacto en el coste (límites de uso)

Trabajar en paralelo es más rápido, pero consume más de tu cuota de uso, porque cada subagente hace sus propias llamadas al modelo y usa sus propias herramientas.

Fuentes: OpenAI «Subagents», «Changelog»; Anthropic «Manage costs effectively», «Create custom subagents». Consultado el 26 de octubre de 2026.

Otra cosa fácil de pasar por alto es que las respuestas de los subagentes también acaban en el contexto principal. La documentación de Claude Code advierte que ejecutar muchos subagentes que devuelven resultados detallados puede consumir mucho contexto principal. Fijar un formato de respuesta como «menos de 10 líneas» también ayuda con el coste. El ahorro de tokens en general con Claude Code se explica en «Trucos para ahorrar tokens en Claude Code».

8. Lecciones de la práctica (ejemplos de este sitio)

Este sitio (AI Arte) funciona encargando la traducción y las comprobaciones de artículos a subagentes de Claude Code en paralelo. La investigación y el borrador de este artículo también los escribió uno de los subagentes enviados por la sesión principal. A continuación, cosas que ocurrieron de verdad y cómo evitarlas. Todas son registros de Claude Code; ninguna se reprodujo en Codex. Aun así, los conflictos por el mismo archivo y los informes inexactos sobre lo que queda fuera del alcance de un subagente merecen vigilarse también en Codex, ya que su mecanismo es parecido.

1. Julio de 2026Ajusta cuántos se ejecutan a la vez según tus propios límites

   Qué pasó

   Al ejecutar seis o más a la vez, los subagentes fallaban por límites de tasa

   Cómo evitarlo

   Limítalo a 5 a la vez y ejecuta los trabajos grandes en tandas de 5. Fija un límite acorde a tus propios límites, por debajo del límite por defecto de Claude Code (20)

2. 22 de septiembre de 2026No dejes que los subagentes lancen más subagentes

   Qué pasó

   Un subagente al que se encargó un trabajo en 10 idiomas lanzó por su cuenta 5 subagentes de traducción. Sumados a los 5 del padre, eran 10 ejecutándose a la vez, se alcanzó el límite de uso y todos se detuvieron a medias

   Cómo evitarlo

   En el apartado «qué no hacer» de las instrucciones, escribe «No lances subagentes. El padre asigna el trabajo». Claude Code permite por defecto que los subagentes lancen subagentes (hasta 3 niveles), así que también puedes impedir el anidamiento con CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1

3. 22 de agosto de 2026Nunca dejes que dos subagentes toquen el mismo archivo

   Qué pasó

   Una frase que el padre había añadido al final de un capítulo de un curso la borraba otro subagente por «no estar en las instrucciones», luego se volvía a añadir, una y otra vez

   Cómo evitarlo

   Asigna a cada subagente los archivos que puede tocar. Para lo que el padre vaya a añadir en bloque más tarde, menciónalo también en las instrucciones de los subagentes o añádelo cuando todos hayan terminado

4. 22 de septiembre de 2026Separa también dónde van los archivos temporales

   Qué pasó

   Un script temporal que un subagente había dejado directamente en la carpeta temporal fue sobrescrito por un archivo con el mismo nombre de otro subagente. Los subagentes lanzados desde la misma conversación ven la misma carpeta temporal

   Cómo evitarlo

   En las instrucciones, asigna a cada subagente su propia subcarpeta

5. 5 de septiembre de 2026No hagas commit de todo de golpe mientras haya subagentes en marcha

   Qué pasó

   Con 5 en marcha, se hizo commit de un cambio no relacionado con git add -A (todos los cambios), y arrastró a ese commit ajeno 100 archivos que los subagentes habían terminado

   Cómo evitarlo

   Haz commit indicando los archivos. Diles también a los subagentes que están prohibidas las operaciones que agrupan todos los cambios o que revierten cambios

6. 22 de agosto de 2026Vuelve a medir lo que los subagentes informen fuera de su propio alcance

   Qué pasó

   Dos subagentes informaron de que «24 elementos no pasan la comprobación» y «28», pero la cifra real era 16. Habían supuesto el estado de archivos que no habían tocado

   Cómo evitarlo

   El padre verifica cifras y objetivos ejecutando él mismo las comprobaciones. Lo que un subagente encuentra dentro de su propio alcance es muy preciso, así que eso sí es fiable

Tomado de los registros de funcionamiento de este sitio (de julio a septiembre de 2026). Solo se incluyen cifras que constan en esos registros.

Si juntamos estas lecciones, las instrucciones que se reparten quedan así. Los subagentes no conocen el resto de la conversación, así que redáctalas de forma que las instrucciones basten por sí solas para terminar el trabajo.

[Tarea] Investigar el artículo 273 y escribir el borrador ja
[Qué no hacer]
- operaciones git (add, commit, checkout, restore, stash, push)
- No lances subagentes (el padre asigna el trabajo)
- No edites otros artículos
- Pon los archivos temporales en carpeta-temporal/a273/
[Cómo investigar] A partir del texto original de la documentación oficial (anota URL y fechas de consulta)
[Qué devolver] Archivos creados, título, lo que no se haya podido verificar

El esqueleto (resumido) de las instrucciones que recibió el subagente que escribió este artículo, más dos de las lecciones anteriores (no lanzar subagentes, dónde poner los archivos temporales). El mismo formato sirve para dar instrucciones a subagentes tanto en Codex como en Claude Code.

Resumen

Para las diferencias generales entre ambas herramientas (precios, límites, dónde se ejecutan), consulta «Claude Code vs Codex: ¿cuál elegir?», y para los ajustes que acercan los subagentes a la solo lectura, consulta «Cómo usar Codex y Claude Code en modo de solo lectura».

Preguntas frecuentes

P. ¿Cuántos subagentes de Codex pueden ejecutarse a la vez?

R. El límite se fija con agents.max_concurrent_threads_per_session en config.toml (el hilo principal no cuenta). Si lo omites, decide Codex, y ese valor por defecto no se publica. Los ejemplos oficiales de configuración usan 6 u 8. En Claude Code el valor por defecto es 20 a la vez, y se cambia con CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS. Con cualquiera de las dos, cuantos más ejecutes, más rápido se agotan los límites de uso.

P. ¿Puedo usar un modelo más barato solo para los subagentes?

R. Sí. En Codex, configúralo con default_subagent_model en [agents], o con model y model_reasoning_effort en el archivo del agente. Si no se indica, se hereda el modelo del padre. En Claude Code, define model en la definición del subagente (haiku, etc.) o usa la variable de entorno CLAUDE_CODE_SUBAGENT_MODEL.

P. ¿Tengo que escribir «multi_agent = true» en mi configuración?

R. No en el Codex actual. En la referencia de configuración, features.multi_agent es estable y está activado por defecto, y agents.enabled también es true por defecto. Según el registro de cambios, multi-agent V2 llegó como un sistema opcional y pasó a ser estable en Codex CLI 0.145.0 (21 de julio de 2026). Los pasos para «activarlo» de las guías antiguas ahora producen el mismo estado que no escribir nada. Para desactivarlo, escribe enabled = false en [agents].

P. ¿Cómo impido que Claude Code lance subagentes por su cuenta?

R. Para bloquear los subagentes por completo, añade Agent a permissions.deny en tus ajustes de permisos. Para impedir solo los subagentes que heredan la conversación (forks), usa Agent(fork) o la variable de entorno CLAUDE_CODE_FORK_SUBAGENT=0. Si los equipos de agentes están activados, un subagente con nombre puede arrancar como miembro del equipo, así que déjalos desactivados si no los usas.