Dos asistentes, un repoque Claude y otro agente trabajen el mismo proyecto sin pisarse

01 el punto de partida

Por qué se pisan

Cada agente de código llega con su propio sistema de memoria y ninguno sabe del otro. Claude Code carga CLAUDE.md (el de tu usuario, el del proyecto y los de las carpetas por arriba de donde lo lanzaste). Codex construye su cadena de instrucciones con AGENTS.md (el global en su carpeta de configuración y luego cada nivel desde la raíz del repo hasta tu directorio). Son mecanismos paralelos: si escribes una regla en uno, el otro nunca la ve.

A eso súmale la memoria de sesión. Si usas el sistema de STATE.md para retomar proyectos, ese archivo es la única fuente de 'qué hice ayer y por dónde sigo'. Un segundo agente que lo lee está bien. Uno que lo escribe con su propio formato lo deja inservible para el comando de inicio del otro, que espera una estructura fija.

02 dos archivos, no uno

CLAUDE.md y AGENTS.md: cada quien el suyo

La primera decisión es aceptar que vas a mantener dos archivos de instrucciones. Intentar unificarlos a la fuerza funciona a medias: la doc de Claude Code ofrece importar AGENTS.md desde CLAUDE.md con @AGENTS.md, y sirve cuando las reglas son idénticas para ambos. En la práctica no lo son: Claude tiene slash-commands propios, Codex tiene los suyos, y cada uno cierra en una bitácora distinta. Lo que sí conviene compartir son las reglas de código, y para eso el import es perfecto.

Este es el arreglo que uso en un proyecto donde trabajan los dos: las reglas de código viven en AGENTS.md porque es el formato que más herramientas leen, y CLAUDE.md lo importa y agrega debajo lo que solo aplica a Claude.

git clone https://github.com/davidiriza-lab/dos-asistentes-un-repo.git

@AGENTS.md

## Solo para Claude Code

- Tu bitácora es STATE.md. La de Codex es CODEX_STATE.md: léela como contexto, nunca la escribas.
- Los comandos /iniciar-sesion y /cerrar-sesion viven en ~/.claude/commands y son tuyos.
- Protocolo de convivencia: lee ../ASSISTANT_COLLABORATION.md antes de tocar archivos de memoria.

# Reglas del proyecto

## Código (aplican a cualquier agente)
- TypeScript estricto. Prohibido `any`; usa tipos explícitos o `unknown`.
- Next.js: la lógica de backend va en API routes (`app/api/...`), nunca en server actions.
- Escrituras a la base de datos solo desde el servidor con la clave de servicio.
- Commits pequeños, en imperativo, un tema por commit.

## Solo para Codex
- Tu bitácora es CODEX_STATE.md. La de Claude es STATE.md: léela como contexto, nunca la escribas.
- No modifiques CLAUDE.md ni nada dentro de .claude/.
- Protocolo de convivencia: ../ASSISTANT_COLLABORATION.md

03 no lo supongas, míralo

Comprobar qué instrucciones cargó cada asistente

La mitad de los 'no me hizo caso' son archivos que nunca entraron al contexto. Los dos asistentes traen una forma de ver exactamente qué leyeron, y conviene correrla la primera vez que montas el arreglo de dos archivos, y cada vez que muevas un AGENTS.md de carpeta.

/context

codex debug prompt-input "hola" | grep -n "AGENTS"

Lo probé con un repo de juguete: un AGENTS.md en la raíz, otro en una subcarpeta y un CLAUDE.md al lado con una frase marcada. Lanzando Codex desde la subcarpeta, el prompt trae primero la raíz y luego la subcarpeta, y el CLAUDE.md no aparece por ningún lado. Con la versión 0.150 del CLI, el comportamiento fue exactamente el que documenta OpenAI:

AGENTS.override.md merece su propia advertencia. Es útil para pruebas locales (lo dejas fuera del repo con .gitignore y sobreescribes reglas sin tocar el archivo compartido), pero si se te olvida, Codex deja de leer el AGENTS.md del proyecto sin avisar. Si un día Codex 'olvidó' las reglas, busca ese archivo antes que nada.

04 la tercera forma de convivir

Codex dentro de Claude Code: mismo repo, una sola terminal

Hasta aquí el escenario era dos terminales, dos sesiones. Hay una tercera: Codex corriendo como subagente dentro de tu sesión de Claude Code, con el plugin oficial de OpenAI. Claude piensa y coordina; Codex ejecuta o revisa, y su consumo se descuenta de tu cuenta de ChatGPT, no de la de Claude. Es una forma barata de repartir carga cuando el trabajo pesado no necesita al modelo más caro.

Instalar el plugin (dentro de Claude Code)

1. /plugin marketplace add openai/codex-plugin-cc
2. /plugin install codex@openai-codex
3. /reload-plugins
4. /codex:setup. Te dice si el CLI de Codex está instalado y con sesión iniciada; si falta, ofrece instalarlo con npm.

Lo importante para esta guía: por debajo sigue siendo el CLI de Codex, así que el subagente lee AGENTS.md (no CLAUDE.md) y Claude sigue leyendo solo CLAUDE.md. La tabla de propiedad no cambia. Lo que sí cambia es que ahora es Claude quien le pasa el encargo a Codex, y ese encargo hereda las reglas de convivencia que Claude tiene en contexto solo si se las repite. Yo agrego una línea al CLAUDE.md del proyecto: 'Si delegas a Codex, incluye en la tarea: escribe solo en CODEX_STATE.md y nunca en STATE.md'.

codex exec -s workspace-write -o /tmp/ultimo.md "Lee CODEX_STATE.md y agrega la sesión de hoy"

05 la regla que lo sostiene

Un archivo, un dueño

Toda la convivencia se reduce a una tabla de propiedad. Cada archivo de memoria, instrucciones o comandos tiene exactamente un dueño que puede escribirlo. El otro asistente puede leerlo cuando quiera, y no lo toca salvo que tú se lo pidas explícitamente en ese mensaje. Los archivos de trabajo (código, docs, config) son compartidos: cualquiera los edita cuando se lo pides.

La consecuencia práctica está en los comandos de sesión. Mi /iniciar-sesion de Claude lee STATE.md como memoria principal y, si existen CODEX_STATE.md o CODEX_SESIONES.md, los hojea como contexto secundario y agrega una línea al resumen: 'Última sesión de Codex: fecha y título'. Mi /cerrar-sesion escribe solo en STATE.md. El comando equivalente de Codex hace el espejo. Ninguno de los dos necesita saber cómo está escrito el comando del otro; solo el comportamiento es compartido.

### Paso 2 — Cargar contexto

1. Lee STATE.md (memoria principal de Claude). Extrae la sección "Última sesión".

2. Hojea la bitácora del otro asistente como contexto secundario: si existen
   CODEX_STATE.md o CODEX_SESIONES.md, léelos para saber si trabajó algo en
   paralelo. NUNCA los escribas ni modifiques (ver ASSISTANT_COLLABORATION.md).

[...]

6. En el resumen, agrega esta línea solo si el archivo existe:
   **Última sesión de Codex:** [fecha + título de la última sesión en CODEX_STATE.md]

> Regla de coordinación (ASSISTANT_COLLABORATION.md): Claude solo escribe en su
> propia bitácora (STATE.md / SESIONES.md / CLAUDE.md). NUNCA tocar CODEX_STATE.md,
> CODEX_SESIONES.md ni AGENTS.md salvo instrucción explícita del usuario en este mensaje.

06 donde de verdad se pierde trabajo

El protocolo git

Las bitácoras separadas evitan el choque de memoria. El choque de git es otro: dos sesiones, dos terminales, una rama. Cada agente commitea y sube por su cuenta al cerrar, y el que llega segundo encuentra que el remoto avanzó. Lo que hace en ese momento decide si pierdes trabajo o no. Cuatro reglas, en orden de importancia:

1. Nunca --force. Ni --force-with-lease. Si el push no entra, se reporta y se resuelve en la siguiente sesión con un humano mirando. Un agente que fuerza un push borra los commits del otro sin que nadie lo note hasta días después.
2. Fetch al abrir. Antes de cargar contexto, git fetch y leer git status -sb. Si estás atrás y tu copia está limpia, pull --ff-only y resumir qué llegó. Si estás atrás pero tienes cambios propios, no hacer pull automático: avisar y que tú decidas.
3. Rebase al cerrar. Después del commit de cierre, fetch otra vez. Si el remoto avanzó, git pull --rebase. Sin conflictos: push y una línea diciendo qué llegó de fuera. Con conflictos: git rebase --abort, reportar los archivos y dejarlo para la siguiente sesión. El cierre continúa igual; el estado ya está en el archivo.
4. Commits pequeños. Un tema por commit, mensaje en imperativo. Cuando dos agentes tocan el mismo repo, un commit gigante es garantía de conflicto en el rebase; diez pequeños casi siempre se aplican limpios.

# 1. Commit de la bitácora propia (solo la propia)
git add STATE.md
git commit -m "chore: cerrar sesión 2026-08-28"

# 2. Ver si el remoto avanzó mientras trabajabas
git fetch origin --quiet
git status -sb
#   "## main...origin/main"             -> al día, push directo
#   "## main...origin/main [behind 2]"  -> alguien publicó, rebase

# 3a. Al día
git push

# 3b. Atrás: rebase, nunca force
git pull --rebase && git push
# Si el rebase se detiene por conflicto:
git rebase --abort
# -> reportar archivos en conflicto y dejar la conciliación para la próxima sesión

El caso que más veces se presentó en la práctica fue el de 'ahead 1, behind 1': la sesión anterior cerró sin poder subir y desde entonces el otro asistente publicó. Mi comando de inicio lo detecta y no hace nada automático: reporta ambos números en 'Antes de empezar' y espera. Cinco segundos tuyos valen más que un rebase a ciegas sobre el trabajo de otro.

07 para copiar

El archivo de colaboración completo

Este es el protocolo, genérico, tal como lo uso. Va en la carpeta que contiene tus proyectos (un nivel arriba de los repos), para que ambos asistentes lo encuentren con la misma ruta relativa desde cualquier proyecto. Es neutral a propósito: no vive dentro de ~/.claude ni de ~/.codex, porque entonces sería propiedad de uno de los dos.

touch ~/proyectos/ASSISTANT_COLLABORATION.md

# Protocolo de colaboración entre asistentes

Este archivo es neutral. Claude Code y Codex lo leen para coordinarse en los
proyectos de esta carpeta. Ninguno de los dos lo escribe.

## Objetivo

Que ambos asistentes trabajen sobre los mismos proyectos y retomen contexto
entre sesiones sin pisar las memorias, comandos ni bitácoras del otro.

## Propiedad de archivos

### Codex escribe
- ~/.codex/** (configuración, comandos, memoria global)
- AGENTS.md dentro de cada proyecto
- CODEX_STATE.md dentro de cada proyecto
- CODEX_SESIONES.md dentro de cada proyecto

Claude puede leerlos, pero no los escribe salvo instrucción explícita del
usuario en el mensaje, nombrando el archivo.

### Claude escribe
- ~/.claude/** (configuración, comandos, memoria global)
- CLAUDE.md dentro de cada proyecto
- STATE.md dentro de cada proyecto
- SESIONES.md dentro de cada proyecto

Codex puede leerlos, pero no los escribe salvo instrucción explícita del
usuario en el mensaje, nombrando el archivo.

### Compartidos
Ambos leen y, cuando el usuario lo pide, editan código fuente, docs y
configuración del proyecto activo.

## Bitácoras

Cada asistente cierra sesión en su propia bitácora:
- Codex cierra en CODEX_STATE.md.
- Claude cierra en STATE.md.

Cada asistente hojea la bitácora del otro como contexto secundario al iniciar
sesión y la menciona en una línea de su resumen (fecha y título de la última
sesión del otro). No la modifica.

## Comandos

Cada asistente mantiene sus propios comandos internos (~/.claude/commands para
Claude; ~/.codex/skills, o ~/.codex/prompts en instalaciones viejas, para
Codex). Ninguno modifica ni necesita conocer los del otro.

La única convención compartida es el comportamiento:
- iniciar sesión = cargar la memoria propia y hojear la del otro como contexto.
- cerrar sesión = escribir solo en la bitácora propia del asistente activo.

## Git

- Commits pequeños: un tema por commit, mensaje en imperativo.
- Al abrir: git fetch. Si la copia local está limpia y atrás, pull --ff-only y
  resumir qué llegó. Si hay cambios propios, avisar y no hacer pull automático.
- Al cerrar: commit de la bitácora propia, fetch, y si el remoto avanzó,
  pull --rebase. Con conflicto: rebase --abort, reportar archivos, no forzar.
- Prohibido git push --force y --force-with-lease. Sin excepción.
- Si el push falla por cualquier razón, avisar en una línea y continuar el
  cierre. El estado ya quedó en el archivo.

## Regla de oro

Leer al otro está bien. Escribir en el espacio del otro, no, salvo que el
usuario lo pida explícitamente.

Después de crearlo, agrega en tu CLAUDE.md global y en tu AGENTS.md global una sola línea: 'Antes de escribir cualquier archivo de memoria o bitácora, lee ~/proyectos/ASSISTANT_COLLABORATION.md'. Con eso ambos lo cargan en cada sesión sin que tengas que repetirlo.

08 paso a paso

Ponerlo en marcha en un proyecto existente

1. Crea el protocolo en la carpeta padre de tus proyectos con el contenido de arriba.
2. En el proyecto, deja las reglas de código en AGENTS.md y haz que CLAUDE.md lo importe con @AGENTS.md más su sección propia. Si el proyecto ya tenía todo en CLAUDE.md, mueve las reglas de código a AGENTS.md; no las dupliques.
3. Agrega a tus comandos de sesión de Claude las dos reglas: hojear CODEX_STATE.md sin escribirlo al iniciar, y el candado de 'solo STATE.md' al cerrar. Haz lo simétrico en los comandos de Codex.
4. Pon los archivos de memoria del otro asistente en tu radar de git: STATE.md y CODEX_STATE.md se commitean ambos. Son parte del repo, no archivos locales.
5. Prueba el choque a propósito: abre una sesión con cada asistente, haz un commit en cada una y cierra las dos. La segunda en cerrar debe hacer rebase y push limpio, y su resumen debe mencionar qué llegó de fuera.
6. Verifica que cada uno cargó lo suyo: en Claude Code, /context lista los archivos de memoria cargados; en Codex, pídele que resuma sus instrucciones actuales y revisa que aparezca AGENTS.md y no CLAUDE.md.

ls -1 STATE.md CODEX_STATE.md CLAUDE.md AGENTS.md 2>/dev/null

09 lo que probé y descarté

Decisiones y sus razones

Un dato de contexto: el proyecto donde más se usó esto es un CRM con más de 800 mil contactos y despliegues a producción varias veces por semana. Ahí un push forzado no es una molestia, es un incidente. Por eso la regla de nunca forzar va primero y sin excepciones.