Primeros Pasos con Codex — Instalación, Primera Tarea y Checkpoints

Referencias Oficiales: Quickstart · CLI Slash Commands · Best Practices · Review

Ruta del currículo

1. Primeros Pasos con Codex — Instalación, Primera Tarea y Checkpoints — primeros loops seguros ← Estás aquí
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
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

• Flujo inicial con app / CLI / IDE — Quickstart
• Comandos clave como /init, /review, /mcp y /status — CLI Slash Commands
• Por qué conviene usar checkpoints desde el inicio — Quickstart

Empieza con un loop exitoso, no con todas las funciones

La forma más rápida de entender Codex no es aprender cada setting de memoria. Es completar un loop pequeño, visible y reversible.

En la práctica, tu onboarding mejora muchísimo si respondes estas cuatro preguntas antes de escribir el primer prompt:

• ¿Qué cliente vas a usar primero: app, CLI, IDE o cloud?
• ¿Qué repo vas a abrir?
• ¿Cuál es la tarea más pequeña que todavía vale la pena hacer?
• ¿Cómo vas a revisar y revertir el resultado?

Ese marco evita el error clásico del primer día: intentar aprender producto, permisos, cloud, slash commands y prompting al mismo tiempo.

Elige tu puerta de entrada con intención

Codex puede usarse desde la app, el CLI, la extensión de IDE y flujos cloud, pero no todas las puertas sirven igual para el primer contacto.

La recomendación práctica sigue siendo simple: empieza local con la app o el CLI; sube a cloud cuando el loop básico ya no te sorprenda.

Los primeros 10 minutos correctos

El Quickstart resume un arranque bastante directo:

1. instalar la app de Codex o el CLI
2. iniciar sesión con tu cuenta de ChatGPT o con una OpenAI API key
3. elegir la carpeta del proyecto
4. enviar la primera tarea

La documentación también aclara algo importante para onboarding: si inicias sesión con una API key, algunas capacidades —sobre todo algunas funciones cloud— pueden no ser la ruta más simple para empezar. Para la mayoría de la gente que empieza, el camino más simple es:

• repo local
• inicio de sesión normal con cuenta
• primera tarea pequeña

Eso no significa que la API key sea “mala”. Solo significa que no es el punto de menor fricción para aprender el producto.

Mantén separados el aprendizaje del producto y el riesgo del trabajo

El primer objetivo no es “ser muy productivo”. El primer objetivo es construir confianza en el loop:

1. pedir algo entendible
2. revisar lo que cambió
3. verificarlo
4. deshacerlo si hace falta

Si tu primera sesión mezcla una tarea ambiciosa con permisos amplios, sin checkpoints y sin review, casi cualquier resultado se siente confuso aunque técnicamente funcione.

Cómo elegir bien la primera tarea

La primera tarea ideal tiene tres propiedades:

• es pequeña
• se inspecciona fácil
• se revierte fácil

Buenas primeras tareas

• “Explícame este repo en cinco bullets.”
• “Encuentra los archivos más relevantes para este error.”
• “Identifica candidatos de dead code en esta carpeta.”
• “Haz un refactor pequeño sin cambiar comportamiento.”
• “Agrega documentación breve en esta página sin tocar la lógica.”

Tareas malas para empezar

• “Mejora toda la app.”
• “Reorganiza la arquitectura.”
• “Haz la migración completa.”
• “Arregla todo lo roto y optimiza de paso.”

Si no sabes si una tarea es demasiado grande, pregúntate esto: ¿podría revisar cómodamente el diff y el resultado en 5–10 minutos? Si la respuesta es no, todavía es demasiado para el primer loop.

Sizing rápido para la primera semana

La progresión sana no es “más difícil cada día”. Es más completa cada día: primero leer, luego editar, luego verificar, luego repetir con menos fricción.

Usa prompts con forma de trabajo, no de deseo

Las best practices de Codex favorecen prompts estructurados. Aunque aquí todavía estés en onboarding, conviene empezar con una plantilla mínima:

Goal:
¿Qué quieres conseguir?
 
Context:
¿Dónde debería mirar primero Codex?
 
Constraints:
¿Qué no debe cambiar o ampliar?
 
Done when:
¿Qué evidencia muestra que terminó?

Un mal primer prompt

mejora esta parte

Un mejor primer prompt

Goal:
Encontrar utilidades sin uso dentro de src/lib/.
 
Context:
- Empieza por src/lib/
- Solo necesito investigación inicial
 
Constraints:
- No modificar archivos
- Mostrar evidencia de import o uso por candidato
 
Done when:
- Listar tres candidatos principales con su razón

La diferencia es enorme: el segundo prompt ya trae límite, forma de salida y criterio de cierre. Eso hace que la primera experiencia sea mucho más estable.

Slash commands: aprende primero un núcleo pequeño

La guía oficial lista muchos slash commands. Al principio no necesitas todos. Necesitas un kit corto que te ayude a mantener control.

/status

Muestra modelo activo, approval policy, writable roots y estado de sesión. Si Codex se comporta distinto de lo que esperabas, empieza aquí antes de culpar al prompt.

/init

Genera un scaffold de AGENTS.md en el directorio actual. Úsalo cuando notes que repites las mismas reglas del repo en varios turnos.

/review

Hace una revisión de tu working tree. Piensa en él como el segundo pase natural después de implementar o antes de hacer commit.

/mcp

Lista las herramientas MCP disponibles en la sesión. Útil cuando ya no basta el contexto local y necesitas docs o sistemas externos.

/plan

Pide a Codex un plan antes de implementar. No hace falta usarlo siempre, pero es excelente cuando la tarea ya dejó de ser trivial.

/compact

Resume la conversación visible para liberar contexto. Muy útil después de sesiones largas para no arrastrar ruido innecesario.

Otros comandos como /diff, /mention o /fork pueden venir después. Para la primera semana, este núcleo suele ser suficiente.

Review no es un paso final opcional

La documentación de Review aclara que el panel se enfoca por defecto en uncommitted changes, y puede cambiar a:

• diff contra la base branch
• cambios del último turno
• staged vs unstaged en trabajo local

Eso te da un patrón muy sólido para empezar:

1. pedir el cambio
2. ver el diff con /diff
3. pasar /review
4. decidir qué conservar

Ese loop te entrena a usar Codex como compañero de trabajo, no como caja negra.

Checkpoints: el hábito que más tranquilidad compra

Quickstart recomienda checkpoints de Git antes y después de cada tarea. Ese consejo parece básico, pero cambia mucho la experiencia de onboarding.

Un loop simple:

git status
git add -A && git commit -m "checkpoint: before codex task"

Luego:

• ejecutas la tarea
• revisas el diff
• corres checks relevantes
• haces otro checkpoint si el resultado quedó bien

Qué te compra este hábito

• rollback barato
• menos miedo a probar
• comparación clara entre “antes” y “después”
• mejor disciplina de revisión

Si el resultado sale raro, el checkpoint convierte “esto da miedo” en “esto se puede deshacer”.

Un loop de onboarding que sí funciona

Día 1

• usar app o CLI en un repo local
• hacer una tarea de solo lectura
• mirar /status
• revisar el resultado sin editar nada más

Días 2–3

• elegir un cambio pequeño y reversible
• crear checkpoint antes
• pedir el cambio con Goal / Context / Constraints / Done when
• revisar con /diff y /review

Días 4–7

• repetir el loop con una tarea ligeramente más completa
• probar /init para capturar reglas del repo
• empezar a usar /mention y /plan cuando hagan falta
• dejar cloud, automations o permisos más amplios para después del primer loop estable

Esa progresión crea confianza sin forzar complejidad artificial.

Fallos de onboarding muy comunes

Mini checklist para cada primer task

• ¿La tarea cabe en un diff pequeño y revisable?
• ¿Tengo un checkpoint antes de empezar?
• ¿El prompt tiene Goal, Context, Constraints y Done when?
• ¿Voy a mirar /diff y /review antes de aceptar el cambio?
• ¿Sé qué comando usaría para verificar o deshacer?

Resumen rápido

Empieza local, pequeño y reversible. Aprende pronto /status, /diff, /review, /init y /mention. Usa checkpoints desde el día uno. Y deja cloud, permisos amplios y automatización para después de dominar ese primer loop.