# IA / Codex — Manual de campo Revisado: 20 de octubre de 2026. Ejemplos propios; confirmar disponibilidad por cliente y workspace. ## 01. Prompts y steering Un buen prompt fija objetivo, contexto, restricciones y una comprobación observable. El steering es la corrección que envías mientras el agente trabaja. ### Aplicar en Codex 1. Abre el proyecto y señala archivos o errores concretos. 2. Define qué significa terminado; añade una corrección si cambia el alcance. ### Corregir un bug Acota la modificación y exige evidencia. Prompt · app / CLI / IDE ```text Corrige el 500 de POST /orders cuando items está vacío. Revisa src/orders.ts y tests/orders.test.ts. Devuelve 400 sin cambiar el contrato de los casos válidos. Añade un test de regresión y ejecuta esa suite. ``` ### Redirigir un refactor Evita que una decisión intermedia amplíe la tarea. Mensaje durante la ejecución ```text Mantén la API pública actual. Limita el refactor al parser y conserva los mensajes de error existentes. Comprueba la compatibilidad con los fixtures de v1. ``` Nota: Los ejemplos son instrucciones en lenguaje natural, no comandos que activen una función oculta. Fuentes: [Prompting](https://learn.chatgpt.com/docs/prompting) ## 02. Steering files · AGENTS.md AGENTS.md contiene instrucciones persistentes. Codex combina la guía global con la del proyecto y la del directorio de trabajo; las instrucciones más específicas resuelven conflictos. ### Aplicar en Codex 1. Crea AGENTS.md en la raíz; usa otro en un subdirectorio para reglas específicas. 2. Inicia una sesión desde el ámbito adecuado. Pide a Codex que confirme la guía cargada. ### Reglas del repositorio Evita repetir comandos y restricciones en cada chat. AGENTS.md · raíz del repo ```text # Convenciones - Usa TypeScript estricto. - Para cambios de lógica, ejecuta npm test. - No edites archivos generados en src/generated/. - Consulta docs/api.md cuando cambies endpoints. ``` ### Reglas de un servicio Especializa el comportamiento en un monorepo. services/billing/AGENTS.md ```text # Billing - Mantén las operaciones de cobro idempotentes. - Usa importes en céntimos enteros. - Prueba reintentos y eventos duplicados. - Conserva compatibilidad con los webhooks publicados. ``` Nota: Guía global: ~/.codex/AGENTS.md. AGENTS.override.md tiene prioridad en su nivel. Un archivo steering.md arbitrario necesita una referencia explícita; el Markdown no impone permisos. Fuentes: [AGENTS.md: alcance y precedencia](https://learn.chatgpt.com/docs/agent-configuration/agents-md) ## 03. Skills Una skill reúne SKILL.md, referencias y scripts opcionales. El agente carga sus instrucciones cuando la selecciona; la descripción determina cuándo encaja. ### Aplicar en Codex 1. Guarda cada skill de equipo en .agents/skills//SKILL.md. Para uso personal: ~/.agents/skills/. 2. Invócala por nombre; en CLI/IDE puedes usar $nombre o /skills. También puedes pedir $skill-creator para crearla. ### Revisar migraciones Reutiliza una revisión de base de datos. .agents/skills/revisar-sql/SKILL.md ```text --- name: revisar-sql description: Revisa migraciones SQL para detectar bloqueos y pérdida de datos. --- 1. Lee la migración y el esquema afectado. 2. Detecta locks, backfills y cambios incompatibles. 3. Propón validación y estrategia de recuperación. 4. Informa hallazgos; no ejecutes la migración. # Uso: $revisar-sql revisa migrations/042.sql ``` ### Preparar una release Estandariza una entrega sin publicar automáticamente. .agents/skills/preparar-release/SKILL.md ```text --- name: preparar-release description: Prepara notas de versión a partir de un rango de commits. --- 1. Solicita el rango si falta. 2. Agrupa cambios en funcionalidades, fixes y rupturas. 3. Guarda RELEASE_NOTES.md y señala pasos manuales. # Uso: $preparar-release desde v1.4.0 hasta HEAD ``` Nota: Mantén la skill específica. Pasa documentación extensa a references/ y lógica determinista a scripts/. Fuentes: [Crear e invocar skills](https://learn.chatgpt.com/docs/build-skills) ## 04. Contexto y RAG RAG recupera fragmentos de una fuente para fundamentar la respuesta. En un repo puedes empezar con búsquedas de código; una base documental necesita un índice o una herramienta conectada. ### Aplicar en Codex 1. Para código local, identifica rutas y pide búsquedas concretas. 2. Para documentación externa, conecta un MCP o implementa recuperación y devuelve fragmentos con su procedencia. ### Entender código existente Reduce contexto innecesario y respuestas inventadas. Prompt · contexto del repo ```text Busca dónde se valida el token y sus tests. Lee solo esos archivos y el contrato de autenticación. Explica el flujo citando rutas y líneas antes de cambiarlo. ``` ### Consultar una base interna Aplica decisiones y contratos vigentes. Prompt · requiere herramienta de búsqueda conectada ```text Busca en la documentación interna el contrato de facturación v2. Devuelve la fuente y versión de cada regla utilizada. Compara esos requisitos con services/billing/. Si no encuentras evidencia, señala la laguna. ``` Nota: Buscar archivos no equivale a configurar un vector store. Un RAG propio vive fuera de Codex y se expone mediante herramientas; no cambia los pesos del modelo. Fuentes: [Recuperación semántica](https://developers.openai.com/api/docs/guides/retrieval) ## 05. Planes de ejecución Un plan versionado registra objetivo, hitos, decisiones y verificación. PLANS.md es una convención de workflow; debes indicar a Codex cuándo leerlo y actualizarlo. ### Aplicar en Codex 1. Define en AGENTS.md cuándo exige el equipo un plan. 2. Crea un plan por cambio grande, con progreso y criterios de aceptación. ### Migración por fases Divide una tarea grande en entregas verificables. docs/plans/cache.md · convención propia ```text # Migrar caché Objetivo: conservar contrato y reducir lecturas a BD. - [ ] Medir comportamiento actual. - [ ] Añadir adaptador detrás de flag. - [ ] Probar fallos y expiración. Aceptación: misma respuesta en los fixtures de contrato. Decisiones: registrar cambios de enfoque y su motivo. ``` ### Continuar tras una pausa Recupera estado sin depender del historial del chat. Prompt ```text Lee docs/plans/cache.md y comprueba el estado real del repo. Continúa por el primer hito pendiente. Actualiza progreso, decisiones y resultados de pruebas. No marques como hecho lo que no has verificado. ``` Nota: Un plan ayuda con trabajos largos; para un cambio pequeño suele bastar un prompt con aceptación clara. Fuentes: [Patrón ExecPlans](https://developers.openai.com/cookbook/articles/codex_exec_plans) ## 06. Memoria persistente Las memorias locales de Codex extraen contexto de chats elegibles y lo reutilizan. Son distintas de las reglas versionadas que compartes con el equipo. ### Aplicar en Codex 1. En la app: Settings → Personalization → Enable Codex memories. Están desactivadas por defecto. 2. Usa /memories para controlar lectura y generación en el chat; en CLI también puedes habilitar la función con config.toml. ### Habilitar memoria local Conserva contexto entre tareas del mismo entorno. ~/.codex/config.toml · combinar con tu configuración ```text [features] memories = true # En una sesión interactiva: # /memories ``` ### Promover una decisión a regla Convierte conocimiento útil en documentación revisable. Prompt · persistencia explícita en el repo ```text Documenta en docs/decisions/007-cache.md por qué usamos Redis. Incluye límites y fecha de la decisión. Enlaza ese documento desde AGENTS.md para cambios de caché. ``` Nota: Las memorias se actualizan en segundo plano y pueden tardar. No sustituyen contratos ni documentación versionada; no guardes secretos. Fuentes: [Memorias locales y configuración](https://learn.chatgpt.com/docs/customization/memories) ## 07. MCP Model Context Protocol permite que un servidor exponga herramientas. Codex puede consultar documentación o actuar sobre un sistema si ese servidor y sus permisos lo permiten. ### Aplicar en Codex 1. Configura el servidor en Codex o en ~/.codex/config.toml. Usa OAuth cuando el servidor lo requiera. 2. Comprueba herramientas y conexión con codex mcp list y /mcp en CLI. ### Documentación oficial Consulta una API actual en lugar de depender de memoria. ~/.codex/config.toml · añadir bloque ```text [mcp_servers.openai_docs] url = "https://developers.openai.com/mcp" # Después, en Codex: # Consulta la documentación oficial de Responses con openai_docs. ``` ### Herramientas internas Expone una consulta controlada a tu sistema de tickets. CLI · requiere implementar el servidor indicado ```text codex mcp add tickets -- node /ruta/absoluta/tickets-mcp.mjs codex mcp list # Prompt: consulta ENG-42 y contrasta su aceptación con el diff. ``` Nota: MCP aporta acceso; una skill puede describir el procedimiento. El servidor tickets es un ejemplo propio, no viene instalado con Codex. Fuentes: [Conectar servidores MCP](https://learn.chatgpt.com/docs/extend/mcp?surface=cli) ## 08. Plugins y conectores Un plugin distribuye skills y, opcionalmente, conexiones MCP. Un conector aporta acceso a un servicio con la identidad y los permisos que hayas autorizado. ### Aplicar en Codex 1. Busca el plugin en el catálogo disponible en tu cliente. Instálalo y conecta la cuenta si lo necesita. 2. Selecciona o menciona el plugin y pide una operación con alcance explícito. ### Analizar una PR Combina contexto remoto y análisis del cambio. Prompt · requiere plugin de GitHub conectado ```text Con GitHub, lee la PR 123 de mi-org/mi-repo. Resume cambios de contrato y riesgos con referencias al diff. Deja los hallazgos en este chat. ``` ### Convertir requisitos en tareas Reutiliza información del gestor de trabajo. Prompt · requiere plugin de Linear conectado ```text Consulta el issue ENG-42 en Linear. Propón tareas de implementación y pruebas de aceptación. Señala dependencias y guarda el plan en docs/plans/ENG-42.md. ``` Nota: La disponibilidad depende del cliente, cuenta y políticas del workspace. Instalar un plugin y conectar una cuenta son pasos distintos. Fuentes: [Plugins: instalación y conexiones](https://learn.chatgpt.com/docs/plugins), [Skills dentro de un plugin](https://developers.openai.com/plugins/concepts/skills) ## 09. Hooks de ciclo de vida Los hooks nativos lanzan comandos o herramientas MCP en eventos como SessionStart, PostToolUse y Stop. Sirven para contexto, auditoría o validaciones automáticas. ### Aplicar en Codex 1. Crea .codex/hooks.json en el repo o ~/.codex/hooks.json para tu usuario. 2. En CLI usa /hooks para revisar y confiar en la definición exacta. Los cambios necesitan nueva revisión. La capa .codex/ del proyecto debe ser de confianza. ### Comprobar el estado inicial Obtiene el estado Git al iniciar o reanudar. .codex/hooks.json · ejemplo independiente ```text { "hooks": { "SessionStart": [{ "matcher": "startup|resume", "hooks": [{"type": "command", "command": "git status --short"}] }] } } ``` ### Validar tras editar Ejecuta la suite después de una escritura o edición. .codex/hooks.json · ejemplo independiente ```text { "hooks": { "PostToolUse": [{ "matcher": "Write|Edit", "hooks": [{ "type": "command", "command": "npm test", "timeout": 120 }] }] } } ``` Nota: Combina eventos en un único objeto hooks. npm test requiere un script test y arrancar en la raíz del proyecto. PostToolUse ignora stdout en texto: para devolver contexto o decisiones usa su contrato JSON. Mantén CI como control de merge. Fuentes: [Hooks: eventos, confianza y contrato](https://learn.chatgpt.com/docs/hooks) ## 10. Subagentes Un agente principal puede asignar trabajos a subagentes con contexto y objetivos delimitados. Es útil para exploración paralela, revisiones o dominios diferentes. ### Aplicar en Codex 1. Pide explícitamente delegación e indica entregables y propiedad de archivos. 2. En CLI la configuración de agentes usa la tabla [agents]. Las políticas de tu instalación pueden restringir su uso. ### Exploración en paralelo Reduce tiempo de investigación sin editar archivos. Prompt · requiere soporte de subagentes ```text Usa dos subagentes en paralelo: uno analiza autenticación y otro cobertura de tests. Que no editen archivos. Cada uno debe devolver rutas, hallazgos y evidencia. Integra los resultados en un único plan. ``` ### Implementación separada Evita que dos agentes escriban en los mismos archivos. Prompt ```text Delega a un subagente la documentación de docs/api.md y a otro los tests de tests/parser.test.ts. Tú implementa src/parser.ts. Fija primero el contrato común. Integra y ejecuta la suite al terminar. ``` Nota: Delegar consume más contexto y cuota. Los subagentes no implican aislamiento Git; usa worktrees si necesitas separar checkouts. Fuentes: [Subagentes y configuración](https://learn.chatgpt.com/docs/agent-configuration/subagents) ## 11. Worktrees Un worktree proporciona archivos de trabajo independientes y comparte el historial Git. Permite aislar una tarea del código que estás editando en el checkout principal. ### Aplicar en Codex 1. En un proyecto Git de la app, inicia o mueve la tarea a un worktree mediante los controles de entorno. 2. Verifica dependencias y pruebas en ese checkout; integra después mediante rama y PR. ### Probar otra solución Experimenta sin alterar tu checkout actual. Git CLI · ejecutar desde un repositorio ```text git worktree add ../mi-proyecto-cache -b experimento/cache # Abre esa carpeta como proyecto en Codex. # Prompt: implementa una caché detrás de un feature flag. ``` ### Mantenimiento aislado Separa una actualización de la funcionalidad en curso. Prompt · app con proyecto Git ```text Realiza esta tarea en un worktree: actualiza las dependencias compatibles y ejecuta las pruebas. Prepara un diff con las versiones y los fallos encontrados. Conserva mi trabajo del checkout actual. ``` Nota: Cada checkout necesita su entorno. Los archivos ignorados, secretos y procesos locales requieren preparación propia. Fuentes: [Worktrees en Codex](https://learn.chatgpt.com/docs/environments/git-worktrees) ## 12. Sandbox y reglas El sandbox delimita acceso; la política de aprobación regula escaladas. Las reglas de comandos permiten, preguntan o prohíben prefijos concretos. ### Aplicar en Codex 1. Ajusta permisos en el cliente; en CLI usa /permissions o config.toml. 2. Pon reglas .rules junto a una capa de configuración activa. Las restricciones administradas siguen aplicándose. ### Edición dentro del workspace Permite trabajo local con aprobación para salir del ámbito. ~/.codex/config.toml · claves de nivel raíz ```text sandbox_mode = "workspace-write" approval_policy = "on-request" ``` ### Pedir aprobación para push Reserva la publicación de commits a una decisión explícita. ~/.codex/rules/default.rules ```text prefix_rule( pattern = ["git", "push"], decision = "prompt", match = ["git push origin feature/parser"], ) ``` Nota: Una regla de comandos no amplía el sandbox. Una instrucción en AGENTS.md tampoco es un control de acceso. Las políticas del administrador tienen prioridad. Fuentes: [Sandbox y aprobaciones](https://learn.chatgpt.com/docs/sandboxing), [Reglas de ejecución](https://learn.chatgpt.com/docs/agent-configuration/rules) ## 13. Tests, reviews y evals Los tests validan el producto; una review busca defectos del diff; las evals comprueban si prompts y skills funcionan en un conjunto representativo de tareas. ### Aplicar en Codex 1. Define aceptación comprobable y ejecuta las pruebas relevantes del proyecto. 2. Usa /review en un repo Git. Para evaluar una skill, prepara tareas positivas, negativas y casos límite. ### Revisión con evidencia Obtiene hallazgos accionables antes del merge. Codex · /review + instrucciones de revisión ```text /review # Elige cambios sin commit o comparación con la rama base. # Prioriza regresiones, pérdida de datos y casos límite. # Para cada hallazgo: archivo, entrada que falla y prueba. ``` ### Evaluar una skill Detecta activaciones incorrectas y resultados incompletos. Prompt · diseño de eval propia ```text Evalúa revisar-sql en 8 migraciones y 4 tareas ajenas a SQL. Mide: activación correcta, riesgos detectados y falsos positivos. Guarda casos, resultados y coste observado en evals/results.md. Compara con el mismo conjunto antes de cambiar la skill. ``` Nota: Un texto convincente no demuestra que las pruebas hayan pasado. Pide comandos, resultados y limitaciones verificadas. Fuentes: [Code review](https://learn.chatgpt.com/docs/code-review), [Evaluar skills sistemáticamente](https://developers.openai.com/blog/eval-skills) ## 14. Modelos y fine-tuning El modelo y el esfuerzo de razonamiento afectan calidad, latencia y coste. El fine-tuning adapta pesos en modelos compatibles; es un proceso de API distinto de personalizar Codex con instrucciones. ### Aplicar en Codex 1. En Codex, elige entre los modelos y esfuerzos que ofrezca tu cliente. Compara con tareas reales. 2. Para un producto por API, evalúa prompting y recuperación antes de entrenar; comprueba modelos y métodos compatibles. ### Escoger por resultados Evita usar máxima capacidad en todas las tareas. Procedimiento de equipo ```text Compara dos configuraciones disponibles en 10 tareas: 5 cambios sencillos y 5 bugs complejos. Registra aceptación, duración y consumo. Usa la configuración más económica que cumpla tu umbral. ``` ### Adaptar un clasificador Ajusta un comportamiento repetitivo de una app propia. Prompt · preparación de un proyecto API ```text Prepara un dataset revisado de tickets y etiquetas. Separa entrenamiento y evaluación sin duplicados. Compara un prompt base con un modelo ajustado compatible. Mide macro-F1 y coste; no incluyas secretos en el dataset. ``` Nota: Crear AGENTS.md o una skill no entrena el modelo. No asumas que un modelo afinado por API puede seleccionarse en Codex. Fuentes: [Optimización de modelos](https://developers.openai.com/api/docs/guides/model-optimization) ## 15. Artefactos Un artefacto es un resultado persistente: HTML, informe, CSV, diagrama o documento. Indica formato, ubicación y validación. Las vistas previas dependen del cliente y las herramientas disponibles. ### Aplicar en Codex 1. Pide el archivo final y su ruta, además de explicar el resultado en el chat. 2. Para PDF, hojas o presentaciones, usa una skill o herramienta capaz de generarlos y verificar su formato. ### Informe de arquitectura Entrega una referencia versionable y revisable. Prompt · archivo Markdown ```text Analiza los módulos de src/. Genera docs/architecture.md con responsabilidades, dependencias y un diagrama Mermaid. Cita rutas reales y marca las inferencias. ``` ### Panel estático Hace explorables unos datos sin backend. Prompt · HTML + CSS + JS ```text Con metrics.csv, crea outputs/metrics.html autocontenido. Incluye tabla filtrable, unidades y origen de los datos. Comprueba que totales y filas coinciden con el CSV. Abre una vista previa si el entorno lo permite. ``` Nota: No hay que crear un artefacto por cada respuesta. No asumas un formato universal artifacts.json ni una API de artefactos común a todos los clientes. Fuentes: [Archivos y vistas previas](https://learn.chatgpt.com/docs/artifacts-viewer) ## 16. Visión, navegador y medios La visión permite analizar imágenes; las herramientas de navegador interactúan con páginas; las de generación crean medios. Cada capacidad requiere soporte en el cliente, no basta con pedirla. ### Aplicar en Codex 1. Adjunta una captura o proporciona la página y los criterios de comprobación. 2. Para interactuar con una web o generar imágenes, comprueba que la sesión tenga la herramienta correspondiente. ### Detectar un fallo visual Convierte una captura en una corrección comprobable. Prompt · adjuntar captura ```text En esta captura el menú tapa el formulario a 390 px. Localiza la regla CSS responsable y corrígela. Verifica a 390 y 1280 px, con teclado y zoom al 200 %. ``` ### Verificar una interfaz Comprueba comportamiento real, además de leer código. Prompt · requiere navegador controlable ```text Abre la vista previa local. Busca "hooks", abre la ficha y comprueba el enlace directo y el botón de copiar. Repite en viewport móvil. Informa fallos observados. ``` Nota: Generar imágenes, vídeo o audio puede necesitar un plugin o una API adicional. Codex puede integrar esos archivos; no todos los clientes generan todos los formatos. Fuentes: [Entradas de imagen](https://learn.chatgpt.com/docs/image-inputs), [Navegador](https://learn.chatgpt.com/docs/browser) ## 17. Automatizaciones Una tarea programada vuelve a ejecutar una instrucción. Es adecuada para mantenimiento, seguimiento y análisis recurrente; un hook responde a un evento, no a un horario. ### Aplicar en Codex 1. Crea la tarea desde las funciones de programación de la app e indica proyecto, frecuencia y resultado esperado. 2. Para archivos locales, mantén encendidos el equipo y la app. Usa un worktree si el trabajo modifica un repo Git. ### Revisar dependencias Detecta cambios que merecen una tarea de mantenimiento. Solicitud en la app · propuesta de automatización ```text Cada lunes a las 09:00, Europe/Madrid, revisa dependencias de este proyecto en un worktree. Informa actualizaciones relevantes y pruebas necesarias. Notifica solo si hay cambios accionables. ``` ### Seguir una incidencia Evita comprobar repetidamente un estado a mano. Solicitud · requiere acceso al sistema de CI ```text Comprueba cada hora el estado del pipeline de la rama main. Consulta el CI conectado. Avisa si pasa de correcto a fallido o vuelve a estar correcto. Incluye ejecución y causa probable. ``` Nota: Estos textos son ejemplos; leerlos no crea tareas. Revisa las ejecuciones y el acceso del entorno programado. Fuentes: [Tareas programadas y entornos](https://learn.chatgpt.com/docs/automations) ## 18. CLI, CI y salidas estructuradas codex exec ejecuta una tarea sin interfaz interactiva. Puede guardar la respuesta final, emitir eventos JSONL o producir datos conforme a un JSON Schema. ### Aplicar en Codex 1. Instala y autentica Codex CLI en el entorno; en CI configura credenciales mediante secretos. 2. Ejecuta dentro del repo y fija permisos. Valida la salida antes de usarla en otro paso. ### Preparar notas de cambios Automatiza una salida de texto sin publicar nada. Terminal · Codex CLI autenticado ```text codex exec --sandbox read-only "Resume los últimos 10 commits para una release" -o release-notes.md ``` ### Generar JSON con contrato Entrega campos estables a otro proceso. schema.json + comando de terminal ```text { "type": "object", "properties": {"summary": {"type": "string"}}, "required": ["summary"], "additionalProperties": false } # Guarda el JSON anterior en schema.json. Después ejecuta: codex exec "Resume este repositorio" --output-schema schema.json -o report.json ``` Nota: --json emite eventos JSONL; no equivale al JSON final del esquema. El SDK permite integrar ejecuciones desde código. Mantén tests y comprobaciones deterministas como gates de CI. Fuentes: [Modo no interactivo](https://learn.chatgpt.com/docs/non-interactive-mode), [Codex SDK](https://learn.chatgpt.com/docs/codex-sdk)