# Proyecto
- Usa los patrones existentes y limita el alcance.
- Ejecuta las pruebas relevantes y reporta el resultado.
- Consulta docs/architecture.md para cambios entre módulos.
- No edites código generado.
- Entrega archivos, verificación y limitaciones.
Define el resultado y corrige el rumbo durante la tarea.
PARA QUÉ SIRVE
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.
Cómo aplicarlo en Codex
Abre el proyecto y señala archivos o errores concretos.
Define qué significa terminado; añade una corrección si cambia el alcance.
Dos ejemplos, listos para adaptar
01 — 02
EJEMPLO 1
Corregir un bug
Acota la modificación y exige evidencia.
Prompt · app / CLI / IDE
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.
EJEMPLO 2
Redirigir un refactor
Evita que una decisión intermedia amplíe la tarea.
Mensaje durante la ejecución
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.
Versiona las reglas que Codex debe conocer en tu repositorio.
PARA QUÉ SIRVE
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.
Cómo aplicarlo en Codex
Crea AGENTS.md en la raíz; usa otro en un subdirectorio para reglas específicas.
Inicia una sesión desde el ámbito adecuado. Pide a Codex que confirme la guía cargada.
Dos ejemplos, listos para adaptar
01 — 02
EJEMPLO 1
Reglas del repositorio
Evita repetir comandos y restricciones en cada chat.
AGENTS.md · raíz del repo
# 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.
EJEMPLO 2
Reglas de un servicio
Especializa el comportamiento en un monorepo.
services/billing/AGENTS.md
# 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.
Encapsula un procedimiento reutilizable con sus recursos.
PARA QUÉ SIRVE
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.
Cómo aplicarlo en Codex
Guarda cada skill de equipo en .agents/skills/<nombre>/SKILL.md. Para uso personal: ~/.agents/skills/.
Invócala por nombre; en CLI/IDE puedes usar $nombre o /skills. También puedes pedir $skill-creator para crearla.
Dos ejemplos, listos para adaptar
01 — 02
EJEMPLO 1
Revisar migraciones
Reutiliza una revisión de base de datos.
.agents/skills/revisar-sql/SKILL.md
---
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
EJEMPLO 2
Preparar una release
Estandariza una entrega sin publicar automáticamente.
.agents/skills/preparar-release/SKILL.md
---
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
Recupera información relevante antes de generar una respuesta.
PARA QUÉ SIRVE
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.
Cómo aplicarlo en Codex
Para código local, identifica rutas y pide búsquedas concretas.
Para documentación externa, conecta un MCP o implementa recuperación y devuelve fragmentos con su procedencia.
Dos ejemplos, listos para adaptar
01 — 02
EJEMPLO 1
Entender código existente
Reduce contexto innecesario y respuestas inventadas.
Prompt · contexto del repo
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.
EJEMPLO 2
Consultar una base interna
Aplica decisiones y contratos vigentes.
Prompt · requiere herramienta de búsqueda conectada
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.
Mantén el estado de cambios que duran varias sesiones.
PARA QUÉ SIRVE
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.
Cómo aplicarlo en Codex
Define en AGENTS.md cuándo exige el equipo un plan.
Crea un plan por cambio grande, con progreso y criterios de aceptación.
Dos ejemplos, listos para adaptar
01 — 02
EJEMPLO 1
Migración por fases
Divide una tarea grande en entregas verificables.
docs/plans/cache.md · convención propia
# 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.
EJEMPLO 2
Continuar tras una pausa
Recupera estado sin depender del historial del chat.
Prompt
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.
Las memorias locales de Codex extraen contexto de chats elegibles y lo reutilizan. Son distintas de las reglas versionadas que compartes con el equipo.
Cómo aplicarlo en Codex
En la app: Settings → Personalization → Enable Codex memories. Están desactivadas por defecto.
Usa /memories para controlar lectura y generación en el chat; en CLI también puedes habilitar la función con config.toml.
Dos ejemplos, listos para adaptar
01 — 02
EJEMPLO 1
Habilitar memoria local
Conserva contexto entre tareas del mismo entorno.
~/.codex/config.toml · combinar con tu configuración
[features]
memories = true
# En una sesión interactiva:
# /memories
EJEMPLO 2
Promover una decisión a regla
Convierte conocimiento útil en documentación revisable.
Prompt · persistencia explícita en el repo
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é.
Conecta el agente con datos y acciones de otros sistemas.
PARA QUÉ SIRVE
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.
Cómo aplicarlo en Codex
Configura el servidor en Codex o en ~/.codex/config.toml. Usa OAuth cuando el servidor lo requiera.
Comprueba herramientas y conexión con codex mcp list y /mcp en CLI.
Dos ejemplos, listos para adaptar
01 — 02
EJEMPLO 1
Documentación oficial
Consulta una API actual en lugar de depender de memoria.
~/.codex/config.toml · añadir bloque
[mcp_servers.openai_docs]
url = "https://developers.openai.com/mcp"
# Después, en Codex:
# Consulta la documentación oficial de Responses con openai_docs.
EJEMPLO 2
Herramientas internas
Expone una consulta controlada a tu sistema de tickets.
CLI · requiere implementar el servidor indicado
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.
Instala paquetes de capacidades y conecta cuentas.
PARA QUÉ SIRVE
Un plugin distribuye skills y, opcionalmente, conexiones MCP. Un conector aporta acceso a un servicio con la identidad y los permisos que hayas autorizado.
Cómo aplicarlo en Codex
Busca el plugin en el catálogo disponible en tu cliente. Instálalo y conecta la cuenta si lo necesita.
Selecciona o menciona el plugin y pide una operación con alcance explícito.
Dos ejemplos, listos para adaptar
01 — 02
EJEMPLO 1
Analizar una PR
Combina contexto remoto y análisis del cambio.
Prompt · requiere plugin de GitHub conectado
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.
EJEMPLO 2
Convertir requisitos en tareas
Reutiliza información del gestor de trabajo.
Prompt · requiere plugin de Linear conectado
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.
Ejecuta código cuando ocurre un evento del agente.
PARA QUÉ SIRVE
Los hooks nativos lanzan comandos o herramientas MCP en eventos como SessionStart, PostToolUse y Stop. Sirven para contexto, auditoría o validaciones automáticas.
Cómo aplicarlo en Codex
Crea .codex/hooks.json en el repo o ~/.codex/hooks.json para tu usuario.
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.
Delega subtareas independientes y reúne sus resultados.
PARA QUÉ SIRVE
Un agente principal puede asignar trabajos a subagentes con contexto y objetivos delimitados. Es útil para exploración paralela, revisiones o dominios diferentes.
Cómo aplicarlo en Codex
Pide explícitamente delegación e indica entregables y propiedad de archivos.
En CLI la configuración de agentes usa la tabla [agents]. Las políticas de tu instalación pueden restringir su uso.
Dos ejemplos, listos para adaptar
01 — 02
EJEMPLO 1
Exploración en paralelo
Reduce tiempo de investigación sin editar archivos.
Prompt · requiere soporte de subagentes
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.
EJEMPLO 2
Implementación separada
Evita que dos agentes escriban en los mismos archivos.
Prompt
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.
Trabaja en paralelo con checkouts separados del mismo repo.
PARA QUÉ SIRVE
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.
Cómo aplicarlo en Codex
En un proyecto Git de la app, inicia o mueve la tarea a un worktree mediante los controles de entorno.
Verifica dependencias y pruebas en ese checkout; integra después mediante rama y PR.
Dos ejemplos, listos para adaptar
01 — 02
EJEMPLO 1
Probar otra solución
Experimenta sin alterar tu checkout actual.
Git CLI · ejecutar desde un repositorio
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.
EJEMPLO 2
Mantenimiento aislado
Separa una actualización de la funcionalidad en curso.
Prompt · app con proyecto Git
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.
Comprueba el software y mide la calidad del agente.
PARA QUÉ SIRVE
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.
Cómo aplicarlo en Codex
Define aceptación comprobable y ejecuta las pruebas relevantes del proyecto.
Usa /review en un repo Git. Para evaluar una skill, prepara tareas positivas, negativas y casos límite.
Dos ejemplos, listos para adaptar
01 — 02
EJEMPLO 1
Revisión con evidencia
Obtiene hallazgos accionables antes del merge.
Codex · /review + instrucciones de revisión
/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.
EJEMPLO 2
Evaluar una skill
Detecta activaciones incorrectas y resultados incompletos.
Prompt · diseño de eval propia
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.
Elige capacidad y adapta comportamiento con medidas.
PARA QUÉ SIRVE
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.
Cómo aplicarlo en Codex
En Codex, elige entre los modelos y esfuerzos que ofrezca tu cliente. Compara con tareas reales.
Para un producto por API, evalúa prompting y recuperación antes de entrenar; comprueba modelos y métodos compatibles.
Dos ejemplos, listos para adaptar
01 — 02
EJEMPLO 1
Escoger por resultados
Evita usar máxima capacidad en todas las tareas.
Procedimiento de equipo
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.
EJEMPLO 2
Adaptar un clasificador
Ajusta un comportamiento repetitivo de una app propia.
Prompt · preparación de un proyecto API
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.
Convierte una tarea en un entregable que se pueda usar.
PARA QUÉ SIRVE
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.
Cómo aplicarlo en Codex
Pide el archivo final y su ruta, además de explicar el resultado en el chat.
Para PDF, hojas o presentaciones, usa una skill o herramienta capaz de generarlos y verificar su formato.
Dos ejemplos, listos para adaptar
01 — 02
EJEMPLO 1
Informe de arquitectura
Entrega una referencia versionable y revisable.
Prompt · archivo Markdown
Analiza los módulos de src/. Genera docs/architecture.md
con responsabilidades, dependencias y un diagrama Mermaid.
Cita rutas reales y marca las inferencias.
EJEMPLO 2
Panel estático
Hace explorables unos datos sin backend.
Prompt · HTML + CSS + JS
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.
Trabaja con capturas, interfaces y recursos visuales.
PARA QUÉ SIRVE
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.
Cómo aplicarlo en Codex
Adjunta una captura o proporciona la página y los criterios de comprobación.
Para interactuar con una web o generar imágenes, comprueba que la sesión tenga la herramienta correspondiente.
Dos ejemplos, listos para adaptar
01 — 02
EJEMPLO 1
Detectar un fallo visual
Convierte una captura en una corrección comprobable.
Prompt · adjuntar captura
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 %.
EJEMPLO 2
Verificar una interfaz
Comprueba comportamiento real, además de leer código.
Prompt · requiere navegador controlable
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.
Ejecuta trabajo recurrente con un horario y un objetivo.
PARA QUÉ SIRVE
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.
Cómo aplicarlo en Codex
Crea la tarea desde las funciones de programación de la app e indica proyecto, frecuencia y resultado esperado.
Para archivos locales, mantén encendidos el equipo y la app. Usa un worktree si el trabajo modifica un repo Git.
Dos ejemplos, listos para adaptar
01 — 02
EJEMPLO 1
Revisar dependencias
Detecta cambios que merecen una tarea de mantenimiento.
Solicitud en la app · propuesta de automatización
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.
EJEMPLO 2
Seguir una incidencia
Evita comprobar repetidamente un estado a mano.
Solicitud · requiere acceso al sistema de CI
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.
Integra Codex en scripts y pipelines reproducibles.
PARA QUÉ SIRVE
codex exec ejecuta una tarea sin interfaz interactiva. Puede guardar la respuesta final, emitir eventos JSONL o producir datos conforme a un JSON Schema.
Cómo aplicarlo en Codex
Instala y autentica Codex CLI en el entorno; en CI configura credenciales mediante secretos.
Ejecuta dentro del repo y fija permisos. Valida la salida antes de usarla en otro paso.
Dos ejemplos, listos para adaptar
01 — 02
EJEMPLO 1
Preparar notas de cambios
Automatiza una salida de texto sin publicar nada.
Terminal · Codex CLI autenticado
codex exec --sandbox read-only "Resume los últimos 10 commits para una release" -o release-notes.md
EJEMPLO 2
Generar JSON con contrato
Entrega campos estables a otro proceso.
schema.json + comando de terminal
{
"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