Codex Worktrees — Ejecución Paralela Aislada Sin Caos de Branches

Referencias Oficiales: Codex Worktrees · Subagents · Best Practices

Ruta del currículo

1. Primeros Pasos con Codex — Instalación, Primera Tarea y Checkpoints — primeros loops seguros
2. Instrucciones de Codex — Cómo Hacer que AGENTS.md Sirva de Verdad — reglas del repo y defaults
3. Sandboxing en Codex — Permisos, Approvals y Entornos Cloud — permisos y límites
4. Diseño de Tareas en Codex — Escribe Prompts Como Issues, No Como Deseos — dar buena forma al trabajo
5. Skills de Codex — Convierte Prompts Repetidos en Workflows Reutilizables — convertir trabajo repetido en activos reutilizables
6. Subagentes de Codex — Ejecución Paralela y Patrones de Delegación — ejecución paralela y delegación
7. MCP en Codex — Conecta Contexto Externo en Vez de Copiarlo y Pegar — conectar sistemas externos
8. Reviews y Automatizaciones con Codex — /review, Worktrees e Ingeniería Repetible — ejecutar workflows estables una y otra vez
9. Codex Worktrees — Ejecución Paralela Aislada Sin Caos de Branches ← Estás aquí
10. Handoffs en Codex — Convertir Lanes Paralelos en Resultados Listos para Merge
11. Loops de Verificación en Codex — Demostrar que Funciona Antes del Merge
12. Release Readiness en Codex — Gates Finales Antes de Producción
13. Codex Loop Seguro del Primer Día — Flujo Inicial para Evitar Errores Tempranos
14. Playbook de Entrega de Equipo en Codex — Operación Intermedia por Lanes
15. Gobernanza de Cambios de Alto Riesgo en Codex — Controles Avanzados para Releases Críticas
16. Manual Operativo de Codex — Ritmo Diario, Semanal y de Release para Equipos
17. Playbook de Recuperación de Incidentes en Codex — Respuesta Determinista Bajo Presión
18. Bucle de Hardening Post-Incidente en Codex — De la Recuperación a Controles Duraderos
19. Simulacros de Resiliencia Caótica en Codex — Ensayar Fallos Antes de Recibirlos
20. Métricas de Resiliencia y SLO en Codex — Medir Confiabilidad Antes del Fallo
21. Loops de Persistencia Ralph en Codex — Llevar Tareas Largas a Cierre Verificado

Documentación oficial usada en esta guía

• Comportamiento de worktrees en Codex y repos Git — Codex Worktrees
• Diferencias frente a la paralelización con subagentes — Subagents
• Descomposición de tareas y tamaño de workflow — Best Practices

Por qué importan los worktrees para usuarios de Codex

Cuando usas Codex intensivamente, el cuello de botella suele ser el contexto de branch, no la velocidad de escritura.

Necesitas:

• mantener estable la tarea actual
• ejecutar otra tarea en paralelo
• evitar el ciclo constante de stash/pop

Un git worktree te da un segundo (o tercer) checkout del mismo repositorio, cada uno con su branch y directorio de trabajo.

Piensa así:

• subagentes = pensar en paralelo
• worktrees = ejecutar en paralelo con aislamiento

Cuándo elegir worktrees vs subagentes

En práctica, muchos equipos combinan ambos:

1. Exploran con subagentes.
2. Mueven el enfoque elegido a un worktree dedicado.
3. Ejecutan y verifican con Codex ahí.

Patrón práctico de setup

1) Crear un worktree con nombre de tarea

git fetch origin
git worktree add ../wt-auth-retry -b feat/auth-retry origin/main

Tip de naming:

• Directorio: wt-{tema}
• Branch: feat/{tema} o fix/{tema}

Con una convención consistente, limpiar y revisar se vuelve mucho más fácil.

2) Abrir Codex dentro de ese worktree

Inicia Codex desde el directorio del worktree para que ediciones, pruebas y commits queden dentro del scope correcto.

cd ../wt-auth-retry
codex

3) Verificar antes de merge

Dentro del worktree:

• ejecutar lint/typecheck/tests
• revisar que el diff solo toque archivos de esa tarea
• hacer commit, push y abrir PR

Comandos mínimos que conviene memorizar

# Ver worktrees activos
git worktree list
 
# Eliminar un worktree terminado
git worktree remove ../wt-auth-retry
 
# Borrar branch después del merge
git branch -d feat/auth-retry

Si Git dice que el branch sigue "checked out", primero revisa git worktree list y elimina el worktree asociado.

Guardrails operativos

Un worktree por objetivo

No mezcles cambios sin relación. Un worktree debe corresponder a una sola tarea revisable.

Validar alcance de AGENTS.md

Codex sigue instrucciones por alcance de directorio. Si tu repo usa AGENTS.md anidados, confirma que la ruta del worktree siga heredando las reglas correctas.

Evitar worktrees viejos

Los worktrees largos y olvidados generan drift de branches y fricción de merge. Mejor ciclos cortos y orientados a una meta.

Ejemplo de playbook de equipo

• repo principal: hotfixes y preparación de release
• wt-feature-a: implementación de nueva feature
• wt-migration-b: migración + validación
• wt-docs-c: documentación y notas de release

Cada lane queda aislado, pero todos convergen al mismo repositorio remoto y pipeline de revisión.

Errores comunes

Reusar un worktree para múltiples tareas

Eso recrea la misma colisión de contexto que los worktrees buscan evitar.

Olvidar la limpieza

Los worktrees no usados se acumulan rápido y confunden ownership de branches.

Mezclar exploración y ejecución

Si aún estás comparando enfoques, usa subagentes primero. Crea el worktree cuando ya elegiste una ruta.

Plantillas de prompt listas para usar

Plantilla A — lane de implementación

Trabaja solo dentro de este worktree de tarea: ../wt-{tema}
 
Goal:
- Implementar <feature/fix> con el diff más pequeño y revisable.
 
Constraints:
- No editar archivos fuera de <directorios>.
- Ejecutar lint + tests antes de proponer commit.
- Resumir riesgos y ruta de rollback.

Plantilla B — lane de verificación

Usa este worktree de verificación para auditar el branch <branch-name>.
 
Check:
- tests fallando
- regresiones de type/lint
- segmentos de diff sensibles en seguridad
 
Return:
- PASS/FAIL
- hallazgos concretos (archivo/línea)
- plan mínimo de corrección

Plantilla C — lane de docs/release

En este worktree de docs, modifica solo documentación y release notes.
 
Do:
- leer PRs mergeados desde <date>
- agrupar por impacto para usuario
- producir borrador conciso de release notes
 
No modificar archivos fuente de la aplicación.

Playbook de recuperación de fallos

Cuando falla un worktree, normalmente el problema es operativo, no de código.

Caso 1: worktree sucio bloquea el remove

git -C ../wt-auth-retry status
git -C ../wt-auth-retry stash -u   # o commit
git worktree remove ../wt-auth-retry

Caso 2: drift de branch demasiado grande

git -C ../wt-auth-retry fetch origin
git -C ../wt-auth-retry rebase origin/main

Si el conflicto es grande, abre un worktree nuevo y reaplica solo los commits aún válidos.

Caso 3: se creó desde una base equivocada

Cierra ese worktree pronto. Recrearlo desde la base correcta suele ser más seguro que forzar una cadena riesgosa de rebases.

Métricas para demostrar que esto funciona

Mide adopción de worktrees con indicadores ligeros:

• lead time de review por PR (¿el aislamiento acelera la review?)
• tasa de retrabajo tras review (¿baja el ida y vuelta?)
• incidentes de colisión de contexto (stash churn, ediciones cruzadas accidentales)
• edad media de worktrees abiertos (worktrees viejos suelen anticipar fricción de merge)

Si mejoran en 2–4 semanas, la práctica de worktrees está dando retorno.

Matriz de naming que escala

Cuando un equipo supera 3–4 worktrees simultáneos, el naming ad-hoc deja de ser legible. Conviene fijar una matriz corta:

Si el propósito se entiende solo con ver la ruta, mejora tanto el enrutado de review como la limpieza.

Contrato de handoff entre lanes

Muchos fallos de paralelización vienen de handoffs inconsistentes, no de código difícil. Define un contrato mínimo para cada entrega entre lanes:

• Estado de objetivo: done / partial / blocked
• Evidencia: salida de lint/test/build (o motivo de omisión)
• Alcance del diff: directorios tocados y por qué
• Nota de riesgo: plan de rollback y edge cases abiertos
• Siguiente owner: reviewer, verifier o lane de release

Trátalo como un API interno entre worktrees: mejor contrato, menos fricción de coordinación.

Ejemplo de cadencia semanal

Una cadencia simple y repetible:

• Lun: abrir worktrees de implementación y migración
• Mar–Mié: ejecución de lanes + checks diarios del lane de verificación
• Jue: revisión pre-merge centrada en diff branch-vs-base
• Vie: actualización de docs/release + limpieza de worktrees viejos

Más importante que el día exacto es mantener el ritmo. La repetición reduce el desgaste de contexto.

Tabla de decisión: lane único vs subagentes vs worktrees

Cuando hay debate sobre cómo ejecutar, usa esta tabla rápida:

Regla de secuencia:

1. Explora con subagentes si la incertidumbre es alta.
2. Ejecuta en worktree cuando ya elegiste una ruta.
3. Verifica en lane separado si riesgo o alcance es medio/alto.

Plantilla de política de equipo

Puedes pegar esto en el handbook de ingeniería o en docs complementarios de AGENTS.md:

### Política de Worktrees
 
- Un worktree debe corresponder a un único objetivo revisable.
- Los nombres de worktree deben seguir la matriz de naming aprobada.
- Todo handoff debe incluir estado, evidencia, alcance de diff y nota de riesgo.
- Todo handoff debe nombrar al siguiente owner (reviewer, verifier o lane de release).
- Worktrees con más de 14 días deben revisarse para merge/limpieza.
- El lane de verificación es obligatorio para migraciones, auth, billing o cambios sensibles de seguridad.

Con esto, el uso de worktrees deja de ser preferencia personal y pasa a ser contrato operativo del equipo.

Checklist rápido

Antes de abrir un worktree:

• ¿La tarea durará más de una sesión corta?
• ¿Necesita aislamiento de branch respecto al trabajo actual?
• ¿Tiene nombre de tarea y condición de cierre claras?

Antes de eliminar un worktree:

• ¿El branch ya fue mergeado o está push de forma segura?
• ¿Lint/tests están verificados con evidencia?
• ¿PR o issue relacionado está enlazado?

Los worktrees son uno de los hábitos de mayor impacto para ejecutar trabajo paralelo en Codex con límites claros.