Guía de handoff entre Codex y Claude Code: implementación, revisión y recuperación de tareas largas

El error más común al combinar Codex y Claude Code es pensar que se trata de “dos IA escribiendo código a la vez”. El flujo estable es casi lo contrario: en cada fase, una herramienta escribe y la otra revisa, resume, reconstruye contexto o toma la siguiente etapa.

Si Claude Code y Codex editan los mismos archivos al mismo tiempo, al principio parece rápido, pero luego aparecen conflictos: no queda claro quién cambió qué, qué modificación rompió una prueba, o si un Agent sobrescribió el diseño del otro. El objetivo del handoff no es programar en paralelo, sino dividir una tarea compleja en fases.

Quick Answer

Empieza con esta división:

Tres reglas:

1. Solo un Agent escribe código a la vez.
2. Antes de cada traspaso se crea un paquete de handoff.
3. El receptor revisa el estado antes de editar.

Cuándo merece la pena hacer handoff

El handoff es útil cuando:

• Claude Code ya implementó algo y Codex debe revisarlo de forma independiente;
• Codex produjo un plan o findings y Claude Code debe aplicarlos;
• una tarea larga se interrumpió y otro Agent debe continuar desde un checkpoint;
• el entorno local y el entorno cloud tienen roles distintos;
• una herramienta conoce el contexto y la otra es mejor para revisar antes del PR;
• quieres una segunda perspectiva que cuestione el diseño.

Para un cambio de una línea, un typo o una prueba pequeña, el coste del handoff suele ser mayor que su beneficio.

No permitas que dos Agents escriban los mismos archivos

Regla de seguridad principal.

No recomendado:

1
2

Claude Code continues the login refactor.
Codex optimizes the same login files at the same time.

Recomendado:

1
2
3

Claude Code implements the login refactor. When done, it stops and outputs a handoff packet.
Codex reviews the diff in read-only mode and does not modify files.
Claude Code fixes the Codex findings.

Así la responsabilidad queda clara. Si algo falla, puedes ubicar la fase que introdujo el problema.

Qué debe contener un paquete de handoff

Cada traspaso debería incluir algo como:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

## Agent Handoff

### Original Goal
-

### Current Phase
- Plan / Implementation / Test / Review / Fix / Pre-release check

### Done
-

### Pending
-

### Changed Files
-

### Verification Run
-

### Current Risks
-

### Do Not Repeat
-

### Suggested Next Step
-

No es un resumen bonito. Es un registro para que el siguiente Agent reconstruya el estado. Debe incluir archivos, verificación y límites.

Se complementa con cómo reanudar tareas largas de AI Agent. El handoff es una forma deliberada de recuperación.

De Claude Code a Codex: revisión después de implementar

Flujo recomendado:

1. Claude Code termina la implementación.
2. Claude Code ejecuta las pruebas mínimas relevantes.
3. Claude Code genera el paquete de handoff.
4. Codex lee el diff y revisa en modo read-only.
5. Claude Code corrige los findings.
6. Codex vuelve a revisar.

Prompt para Claude Code:

1
2
3

Please implement this feature, but do not commit.
Before stopping, output a handoff packet with changed files, tests run, pending items, and risks.
Do not expand the scope before another Agent reviews it.

Prompt para Codex:

1
2
3

Please review the current uncommitted changes in read-only mode. Do not modify files.
Focus on bugs, regression risk, security issues, edge cases, and missing tests.
List findings by severity and reference exact file locations.

La documentación de Codex CLI también trata review como una capacidad separada: puede revisar cambios sin commit, un commit concreto o un diff contra una rama base. En esta fase conviene mantenerlo read-only.

De Codex a Claude Code: corregir findings

Después de que Codex entregue findings, no hace falta dejar que Codex reescriba todo. Es más seguro pasar los findings a Claude Code si este ya domina el contexto de implementación.

1
2
3
4
5
6
7

Below are Codex review findings. Handle them one by one.

Constraints:
1. Fix only the issues referenced by the findings.
2. Do not do extra refactoring.
3. Run the smallest relevant test after each class of fix.
4. When done, report handled / not handled / needs human judgment.

Así evitas que una revisión termine convertida en una reescritura completa.

Handoff de planificación

Codex puede ser útil primero para leer el repositorio, evaluar riesgos y producir un plan, mientras Claude Code ejecuta.

1
2
3
4
5
6
7
8

Please only plan; do not modify files.
After reading the relevant code, output:
1. goal understanding;
2. impact area;
3. suggested files to change;
4. phased implementation plan;
5. verification for each phase;
6. risks and rollback strategy.

Luego Claude Code ejecuta solo la primera fase:

1
2
3

Please execute only phase 1 from this plan.
Do not start phase 2 early.
Run the matching verification and output a handoff packet when done.

Cuanto mayor es el trabajo, más importante es avanzar por fases.

Transferir una tarea larga

Si una sesión de Claude Code acumuló mucho contexto, no copies todo el chat. Comprime el estado.

1
2
3
4
5
6

Please turn the current task into a handoff packet for Codex.
Requirements:
1. Under 800 words.
2. Include goal, done, pending, changed files, verification, and risks.
3. State Codex's first step after receiving it.
4. Mark commands that should not be repeated.

Y en Codex:

1
2
3

Below is a Claude Code handoff packet. First review it; do not modify files yet.
Check current git status and diff, verify the packet matches the workspace,
then execute only the stated first step.

Es mucho más fiable que decir “continúa lo que hacía Claude Code”.

Si usas un puente como codex-plugin-cc, consulta codex-plugin-cc: conectar Codex al workflow de Claude Code. Sin plugin, un paquete manual suele bastar.

Cuidado con resume

Codex CLI tiene codex resume; Claude Code ofrece --resume, --continue o recuperación de sesión. Pero resume no es un seguro absoluto.

Antes de continuar, pregunta:

1. ¿La sesión pertenece a este repositorio?
2. ¿El workspace coincide con la memoria de la sesión?
3. ¿La ejecución anterior ya lanzó comandos con efectos secundarios?

Prompt inicial:

1
2
3

We are resuming an old session. Do not edit files yet.
Please inspect the current workspace state and compare it with your remembered task state.
If they differ, trust the current workspace and output a recovery summary first.

Así evitas aplicar planes antiguos a archivos nuevos.

Usa Git como límite

Git es la mejor línea de handoff:

1
2
3

git status --short
git diff --stat
git diff

Si una fase terminó, puedes crear un commit pequeño:

1
2

git add <files>
git commit -m "feat: implement login validation"

O guardar un patch:

1

git diff > handoff-login-validation.diff

No hagas handoff con un workspace caótico. Separa cambios del usuario, cambios de Claude Code, cambios de Codex y archivos que el siguiente Agent no debe tocar.

Hooks y Skills

Si haces handoff a menudo, convierte “generar paquete antes de parar” en una regla o hook.

1
2
3
4
5

If this turn changed files, output:
- changed files;
- verification run;
- pending items;
- suggested next step for Codex.

En Codex, el mismo proceso puede convertirse en un skill. Consulta cómo escribir tu propio workflow con Codex Skills y separa revisión read-only, análisis del paquete y recuperación de tareas largas.

Roles locales, IDE y cloud

No fuerces todo en una sola ventana.

La clave no es quién sustituye a quién, sino mantener claro el contexto y la responsabilidad.

Ejemplo completo

Tarea: refactorizar importación de usuarios y añadir pruebas.

1
2
3

Refactor the user import flow. Only handle CSV parsing and field validation.
Do not change UI or database schema.
Run the relevant unit tests and output a handoff packet.

Revisión read-only en Codex:

1
2
3
4
5
6

Review the current uncommitted diff. Do not modify files.
Focus on:
1. CSV edge cases;
2. error handling;
3. types and null values;
4. whether tests cover failure paths.

Corrección en Claude Code:

1
2
3

Fix only the P1/P2 issues from the Codex findings.
Do not do extra refactoring.
Run the related test after each fix.

Después Codex re-revisa y la persona decide commit, merge y release.

Errores comunes

Dos Agents editan el código del otro

Usa la regla de un solo escritor: uno escribe y otro revisa.

Paquete demasiado largo

El handoff no es el historial del chat. Debe ser corto, estructurado y accionable.

Sin verificación

“Está terminado” no basta. Indica qué se ejecutó, qué no se ejecutó y qué falló.

El revisor también corrige todo

Separa revisión y corrección.

Contexto obsoleto

Después de resume, alinea la sesión con el workspace actual antes de editar.

Convertirlo en automatización total desde el primer día

Primero estabiliza paquete, revisión read-only y corrección por findings. Luego añade hooks o skills.

Checklist de handoff

Si no puedes completar esta tabla, no hagas handoff todavía.

Referencias

• OpenAI Developers: Codex CLI features: https://developers.openai.com/codex/cli/features
• OpenAI Developers: Codex workflows: https://developers.openai.com/codex/workflows
• OpenAI Developers: Codex IDE extension features: https://developers.openai.com/codex/ide/features
• Anthropic Docs: Claude Code common workflows: https://docs.anthropic.com/en/docs/claude-code/common-workflows
• Anthropic Docs: Claude Code hooks guide: https://docs.anthropic.com/en/docs/claude-code/hooks-guide

Resumen

El handoff entre Codex y Claude Code no consiste en hacer que dos Agents trabajen al mismo tiempo. Consiste en colaborar por fases.

Claude Code puede encargarse de implementación, corrección y avance local continuo. Codex puede encargarse de revisión independiente, revisión de planes, chequeo antes de PR y continuación de tareas largas. Cada traspaso debe incluir objetivo, archivos cambiados, verificación, riesgos y siguiente paso. Git, resume, review, hooks, skills y checkpoints dan los límites.

Cuando “uno escribe, otro revisa y el receptor primero revisa el estado” se vuelve hábito, el handoff deja de ser un caos de doble IA y se convierte en un flujo de ingeniería controlado.