PARA INGENIEROSDescargar .md
GUÍA PRÁCTICA · CODEX

Haz que tu agente
trabaje mejor.

Instrucciones, herramientas y flujos para desarrollar con IA. Qué resuelve cada mecanismo, cómo aplicarlo en Codex y dos ejemplos para empezar.

18 mecanismos36 ejemplos adaptablesFuentes oficiales enlazadasRevisado 20 oct 2026
TU PRIMER SETUP

Empieza por lo que más se repite.

4 pasos · un repositorio
COPIAR, ADAPTAR, VERSIONAR

Un AGENTS.md mínimo.

Empieza con reglas concretas. Añade instrucciones cuando resuelvan un problema recurrente del equipo.

Ver alcance y ejemplos ↗
AGENTS.md · adapta rutas y comandos
# 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.

Manual de campo para ingeniería de software.
Alcance: personalización y uso de agentes, con aplicación práctica en Codex.

Los ejemplos presuponen las herramientas indicadas en cada ficha.
Funciones y disponibilidad pueden variar por cliente y workspace.

← Todos los mecanismos
01 / Instrucciones y contexto

Prompts y steering

Nativo

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

  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.

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.
DOCUMENTACIÓN PRIMARIA

Consulta: 20 oct 2026
Ejemplos propios y adaptables.

← Todos los mecanismos
02 / Instrucciones y contexto

Steering files · AGENTS.md

Nativo

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

  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.

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.
← Todos los mecanismos
03 / Instrucciones y contexto

Skills

Nativo

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

  1. Guarda cada skill de equipo en .agents/skills/<nombre>/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.

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
← Todos los mecanismos
04 / Instrucciones y contexto

Contexto y RAG

Integración

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

  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.

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.
← Todos los mecanismos
05 / Instrucciones y contexto

Planes de ejecución

Convención

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

  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.

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.
← Todos los mecanismos
06 / Instrucciones y contexto

Memoria persistente

Nativo

Reutiliza contexto útil de sesiones anteriores.

PARA QUÉ SIRVE

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

  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.

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é.
← Todos los mecanismos
07 / Herramientas y ejecución

MCP

Integración

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

  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.

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.
← Todos los mecanismos
08 / Herramientas y ejecución

Plugins y conectores

Integración

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

  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.

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.
← Todos los mecanismos
09 / Herramientas y ejecución

Hooks de ciclo de vida

Nativo

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

  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.

Dos ejemplos, listos para adaptar

01 — 02
EJEMPLO 1

Comprobar el estado inicial

Obtiene el estado Git al iniciar o reanudar.

.codex/hooks.json · ejemplo independiente
{
  "hooks": {
    "SessionStart": [{
      "matcher": "startup|resume",
      "hooks": [{"type": "command", "command": "git status --short"}]
    }]
  }
}
EJEMPLO 2

Validar tras editar

Ejecuta la suite después de una escritura o edición.

.codex/hooks.json · ejemplo independiente
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "npm test",
        "timeout": 120
      }]
    }]
  }
}
← Todos los mecanismos
10 / Herramientas y ejecución

Subagentes

Nativo

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

  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.

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.
← Todos los mecanismos
11 / Herramientas y ejecución

Worktrees

Nativo

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

  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.

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.
← Todos los mecanismos
12 / Calidad y control

Sandbox y reglas

Nativo

Controla acceso a archivos, red y ejecución de comandos.

PARA QUÉ SIRVE

El sandbox delimita acceso; la política de aprobación regula escaladas. Las reglas de comandos permiten, preguntan o prohíben prefijos concretos.

Cómo aplicarlo 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.

Dos ejemplos, listos para adaptar

01 — 02
EJEMPLO 1

Edición dentro del workspace

Permite trabajo local con aprobación para salir del ámbito.

~/.codex/config.toml · claves de nivel raíz
sandbox_mode = "workspace-write"
approval_policy = "on-request"
EJEMPLO 2

Pedir aprobación para push

Reserva la publicación de commits a una decisión explícita.

~/.codex/rules/default.rules
prefix_rule(
    pattern = ["git", "push"],
    decision = "prompt",
    match = ["git push origin feature/parser"],
)
← Todos los mecanismos
13 / Calidad y control

Tests, reviews y evals

Flujo de trabajo

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

  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.

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.
← Todos los mecanismos
14 / Calidad y control

Modelos y fine-tuning

API / criterio

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

  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.

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.
← Todos los mecanismos
15 / Resultados y automatización

Artefactos

Resultado

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

  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.

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.
← Todos los mecanismos
16 / Resultados y automatización

Visión, navegador y medios

Según herramientas

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

  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.

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.
← Todos los mecanismos
17 / Resultados y automatización

Automatizaciones

Según cliente

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

  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.

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.
← Todos los mecanismos
18 / Resultados y automatización

CLI, CI y salidas estructuradas

Nativo · CLI

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

  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.

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