Handoffs en Codex — Convertir Lanes Paralelos en Resultados Listos para Merge

Referencias Oficiales: Best Practices · Subagents · Review · Worktrees

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
10. Handoffs en Codex — Convertir Lanes Paralelos en Resultados Listos para Merge ← Estás aquí
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

• Descomposición de tareas y restricciones explícitas — Best Practices
• Lanes paralelos con workers delegados — Subagents
• Checkpoints de review por alcance de diff — Review
• Modelo de aislamiento branch/archivos — Worktrees

Por qué los handoffs son donde se fuga la calidad

Muchos equipos ya generan código rápido con Codex. Muchos menos pueden transferir trabajo entre lanes sin fricción.

Los handoffs suelen fallar cuando falta uno de estos campos:

• estado actual del objetivo
• evidencia de verificación
• alcance exacto del diff
• nota de riesgo y plan de rollback
• siguiente owner explícito

Si falta uno, el siguiente lane debe redescubrir contexto. Ahí se pierde tiempo y calidad.

Contrato mínimo de handoff

Trata cada handoff lane-a-lane como un API pequeño. Exige siempre estos cinco campos:

1. Estado de objetivo — done / partial / blocked
2. Evidencia — salida de lint/tests/build (o motivo de omisión)
3. Alcance del diff — qué cambió y dónde
4. Nota de riesgo — rollback y edge cases abiertos
5. Siguiente owner — quién toma exactamente la siguiente acción

Un contrato compacto es más fuerte que un resumen largo.

Profundidad de evidencia por tipo de cambio

Cuanto mayor el blast radius, más robusta debe ser la evidencia del handoff.

Plantilla copy-ready de handoff

### Handoff: <lane-name> -> <lane-name>
 
- Estado de objetivo: done | partial | blocked
- Evidencia:
  - lint: <pass/fail + command>
  - tests: <pass/fail + command>
  - build: <pass/fail + command>
- Alcance del diff:
  - directorios cambiados: <list>
  - archivos clave: <list>
- Nota de riesgo:
  - rollback: <short>
  - edge cases abiertos: <list or none>
- Siguiente owner: <person/role/lane>
- Próxima acción antes de: <date/time or trigger>

Usa la misma plantilla en issues, comentarios de PR o runbooks internos. La consistencia importa más que la herramienta.

Patrones de routing de lanes que funcionan

Patrón A — Explorar y luego ejecutar

1. El lane de subagentes explora 2–3 opciones.
2. El lane principal elige una.
3. El lane en worktree ejecuta.
4. El lane de verificación valida antes del PR.

Patrón B — Ejecutar + verificar independiente

1. Worktree de implementación crea candidato.
2. Worktree de verificación independiente repite checks y audita diff.
3. Lane de review decide merge o retrabajo.

Patrón C — Flujo docs/release seguro

1. Implementación mergeada.
2. Lane docs/release actualiza solo docs y release notes.
3. Reviewer valida consistencia user-facing.

Importa menos el nombre del patrón que la claridad del ownership en cada paso.

Anti-patrones comunes de handoff

“Se ve bien” sin salida de comandos

Sin evidencia, el siguiente lane repite validación desde cero.

“Alguien revíselo” sin owner

El trabajo se estanca por vacío de ownership.

Entregar diff gigante y mezclado al verifier

No puede aislar riesgo rápido. Divide lanes antes.

Riesgo conocido sin rollback definido

El plan de rollback se inventa durante el incidente.

Auditoría rápida pre-merge (15 minutos)

Antes de merge, pregunta:

• ¿Están los cinco campos del contrato?
• ¿La evidencia es fresca (no reciclada)?
• ¿El alcance del diff coincide con el objetivo declarado?
• ¿Cada acción pendiente tiene siguiente owner nombrado?
• ¿El rollback es realista para el cambio?

Si una respuesta es no, haz una vuelta más de handoff.

Protocolo de escalación para lanes bloqueados

Si un lane queda bloqueado más de un ciclo:

1. marca estado como blocked
2. adjunta evidencia concreta del bloqueo
3. propone una ruta alternativa
4. asigna siguiente owner explícito
5. define próximo check-in con timebox

Los bloqueos son normales. Los bloqueos sin owner son caros.

Versión para desarrollador individual

Incluso trabajando solo, mantén el contrato entre tus propias fases:

• tú como builder
• tú como verifier
• tú como reviewer

Parece redundante al inicio, pero reduce puntos ciegos por exceso de confianza.

Checklist rápido

Antes del handoff:

• cinco campos del contrato completos
• evidencia adjunta
• siguiente owner nombrado

Antes del merge:

• feedback del lane de verificación resuelto
• review scope limpio
• rollback documentado

Buen output de Codex no alcanza por sí solo. Son los buenos handoffs los que vuelven confiable el workflow paralelo a escala de equipo. Luego continúa con Loops de Verificación en Codex para estandarizar la calidad de prueba antes del merge.