Master 97% de Codex en 1 hora

Si venís dominando Claude Code y querés probar Codex (el equivalente de OpenAI con GPT-5.5 debajo), buenas noticias: el 97% de lo que sabés se traslada con cambios mínimos. Esta guía cubre los 5 movimientos clave para llegar al nivel "user avanzado" en una hora, con 7 prompts copy-paste y los 3 gotchas que matan 40 minutos a los nuevos.

Por qué Codex (sin religión)

No te vendo que migres de Claude Code. La realidad es:

• Claude Code todavía gana en razonamiento largo, planificación, manejo de codebases enormes.
• Codex gana en velocidad pura para tareas simples-medias, y tiene browser use built-in (ventaja real).

La estrategia que más rinde hoy: Claude Code planea, Codex ejecuta. Eso lo cubre la nota "Claude + Codex Hack" en otro post. Acá nos enfocamos en dominar Codex solo.

Movimiento 1: AGENTS.md (no CLAUDE.md)

Lo primero que tenés que cambiar mentalmente. Codex no lee CLAUDE.md. Lee AGENTS.md.

AGENTS.md es el archivo propuesto por OpenAI/comunidad como estándar agnóstico de agentes. Codex lo respeta. Cursor también. Codex y Claude pueden coexistir en el mismo repo si tenés ambos archivos.

Estrategia: mantené los dos.

mi-repo/
  CLAUDE.md     ← reglas específicas que solo Claude usa
  AGENTS.md     ← reglas universales (todos los agentes leen)

En AGENTS.md van las decisiones de proyecto (tech stack, convenciones, comandos de build/test/deploy). En CLAUDE.md van las específicas (slash commands de Claude, skills que asume cargadas).

Movimiento 2: Plan mode con Shift+Tab

Codex tiene plan mode similar al de Claude Code, pero el atajo es Shift+Tab dentro de una sesión activa (en Claude Code es la misma combinación, sí — está estandarizándose en el ecosistema).

Cuándo entrar en plan mode:

• Antes de cualquier cambio que toque más de 3 archivos.
• Antes de refactors.
• Antes de touchear configuración de infraestructura.

En plan mode, Codex te propone qué va a hacer. No toca nada hasta que le decís "go". Salir de plan mode es Shift+Tab otra vez.

Gotcha: si abrís plan mode y aceptás "go", Codex ejecuta todo lo planeado seguido sin permiso por archivo. Es más rápido que Claude Code pero también más fácil que se "vaya de mambo". Para repos con commits importantes, mejor combinar con git stash antes.

Movimiento 3: Skills reutilizables en .codex/skills

Codex implementó skills muy parecido a Claude Code, pero el directorio es .codex/skills/ (no .claude/skills/). El formato del SKILL.md es casi idéntico, salvo dos diferencias:

1. El frontmatter acepta un campo agent_compatibility (lista de agentes para los que la skill está validada).
2. Las skills pueden ejecutar npm scripts directo (un binding que Claude Code no tiene nativo, pero suple con scripts custom).

La mayoría de skills publicadas para Claude Code funcionan en Codex sin modificación. Probalas tal cual primero, y si algo falla, mirá si necesita el agent_compatibility field.

Instalación es la misma:

npx skills@latest add usuario/skill --agent codex

El flag --agent codex mete la skill en .codex/skills/ en lugar de .claude/skills/.

Movimiento 4: Browser use built-in

Acá Codex tiene una ventaja real sobre Claude Code stock. Codex puede abrir un browser headless por sí solo, sin instalar Playwright, Firecrawl ni nada.

Para usarlo:

> Andá a https://example.com/dashboard y decime qué métricas
  aparecen en el primer panel.

Codex abre Chromium headless, navega, te devuelve el contenido del primer panel. Pesa más en RAM que las soluciones API-based pero ahorra setup.

Casos de uso reales:

• Verificar que tu deploy funciona (entra a la URL y mira).
• Scrapear data simple que no requiere login.
• Llenar formularios automatizados.
• Tomar screenshots para reports.

Limitación: no maneja bien login complejo con 2FA. Para eso, seguís necesitando Playwright con sesión persistente.

Movimiento 5: Deploy con GitHub + Vercel

Codex tiene integración nativa con GitHub (login OAuth, no necesitás configurar token) y con Vercel. Esto simplifica el flow "código → repo → deploy" a tres comandos:

> commit con mensaje "feat: nueva landing"
> push a la rama main
> deploy a vercel

Cada uno es una operación atómica. Codex pregunta confirmación si está en plan mode, o las ejecuta direct si no.

El "deploy a vercel" usa el Vercel CLI por debajo, que tiene que estar instalado. Una vez que lo configurás la primera vez, los siguientes deploys son automáticos.

7 prompts copy-paste

1. Bootstrap de proyecto

Creá un proyecto Next.js 15 con TypeScript, Tailwind v4, shadcn/ui, y
Drizzle ORM apuntando a Postgres. Configurá biome para lint+format.
AGENTS.md con las convenciones que asumas.

2. Plan antes de feature

Tengo que agregar autenticación con OAuth (Google + GitHub). Antes de
tocar nada, entrá en plan mode y mostrame qué archivos vas a crear,
qué libs vas a instalar, y dónde van las env vars.

3. Refactor sin romper

El archivo X tiene 800 líneas. Refactorizá en 4-6 archivos manteniendo
la API pública intacta. Corré los tests después y mostrame que todos
pasan. Si alguno falla, no commitees.

4. Browser para verificar

Acabás de deployar. Andá a https://mi-app.vercel.app y verificá que:
1. La home cargue sin errores en console.
2. El login funciona con OAuth Google.
3. El dashboard muestra datos.
Sacame screenshot de cada uno.

5. Skill nueva

Quiero una skill para Codex que automatice el changelog. Cuando le
pase un commit hash, debería leer los cambios, generar entrada
formato Keep-a-Changelog, y agregarla a CHANGELOG.md. Hacé el SKILL.md
con triggers claros.

6. Migración de Claude Code

Este repo viene de Claude Code. Tiene CLAUDE.md con 200 líneas. Leé
CLAUDE.md, separá: (a) reglas universales que copiamos a AGENTS.md
y (b) reglas Claude-específicas que se quedan en CLAUDE.md. Mostrame
el plan.

7. Deploy con preview

Deployá a Vercel pero como preview (no production). Una vez que
preview esté arriba, abrí el URL en browser headless, hacé smoke
test, y si todo pasa, promoteá a production.

3 gotchas que matan 40 minutos

Gotcha 1: La sesión de Codex no persiste contexto entre Shift+Tab

En Claude Code, salir y entrar de plan mode mantiene contexto. En Codex (al menos en la versión current), salir de plan mode resetea parte del contexto interno. Si planeaste algo grande, ejecutá inmediato después de aceptar. No te vayas a hacer otra cosa y vuelvas.

Gotcha 2: Browser use consume tokens del modelo, no es "gratis"

El browser use built-in es práctico pero no es free — cada página que carga, su HTML pasa al contexto del modelo. Una página de 500KB de HTML te puede gastar 50k tokens fácil. Si vas a hacer mucho browsing, considerá:

• Filtrar el HTML antes (Codex permite extraer solo selectores específicos).
• Usar playwright puro con extracción server-side, y solo pasarle a Codex el resultado parseado.

Gotcha 3: AGENTS.md con secciones contradictorias = caos

Como AGENTS.md es propuesta abierta, distintas tools le entienden cosas levemente distintas. Si copiás AGENTS.md de un repo public sin revisar, puede traer secciones que tu agente actual no soporta (ej: directivas específicas de Aider). Codex en general las ignora pero a veces se enroscan.

Recomendación: arrancá tu AGENTS.md desde cero, sin copiar otros. Va a ser corto, claro, y específico a tu proyecto.

Cuándo NO usar Codex

Para que sea honesto:

• Repos muy grandes (>500k LOC). Codex tiene context window grande pero Claude Code maneja mejor codebases monstruosas con su sub-agentes.
• Razonamiento prolongado sin acción. Si necesitás que un agente piense 20 minutos sobre arquitectura sin tocar archivos, Claude Code con extended thinking gana.
• Sin presupuesto para suscripción extra. Codex es suscripción aparte (OpenAI Plus o ChatGPT Pro). Si ya pagás Claude Max, sumar Codex es +$20-$200/mes adicional.

Cuándo SÍ usar Codex (recomendaciones específicas)

• Tareas medias y rápidas (CRUD, scripts, configuración).
• Cuando necesitás browser sin armar Playwright setup.
• Cuando trabajás con stack OpenAI (Realtime API, Whisper, etc.) — Codex sabe esos modelos sin que se lo expliques.
• Cuando querés segunda opinión sobre un problema. Lo planeás con Claude, lo ejecutás con Codex, comparás resultados.

Conclusión

Codex no es reemplazo de Claude Code — es complemento. Los 5 movimientos (AGENTS.md, plan mode, skills en .codex, browser built-in, deploy GitHub+Vercel) cubren el 97% del uso diario. Los 7 prompts son tu primer set para arrancar. Los 3 gotchas son las trampas que más tiempo te queman si no las conocés.

Una hora con esto y operás Codex con confianza. La especialización viene con uso — qué tipos de tareas le encajan mejor a cuál agente lo vas a aprender en 2-3 semanas de tener ambos abiertos.

Tags: master-codex, codex, openai-codex, agents-md, plan-mode, skills, browser-use, github, vercel