Instrucciones de Codex — Cómo Hacer que AGENTS.md Sirva de Verdad

Referencias Oficiales: Guía de AGENTS.md · Config Basics · CLI Slash Commands · Best Practices

Ruta del currículo

1. Primeros Pasos con Codex — Instalación, Primera Tarea y Checkpoints — primeros loops seguros
2. Instrucciones de Codex — Cómo Hacer que AGENTS.md Sirva de Verdad — reglas del repo y defaults ← Estás aquí
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

• Cómo Codex combina guía global y reglas del proyecto — Custom instructions with AGENTS.md
• Defaults comunes de modelo / approval / sandbox — Config basics
• /init para crear un AGENTS.md base en el directorio actual — CLI Slash Commands

Por qué esta superficie importa tanto

Si todo vive en el prompt, terminas repitiendo el mismo contexto del proyecto una y otra vez. Codex funciona mejor cuando separas responsabilidades:

• la tarea de hoy en el prompt
• las reglas duraderas del repo en AGENTS.md
• los defaults de ejecución en config

Esa es la idea real detrás de la instruction chain.

Cómo descubre instrucciones Codex

La guía de AGENTS explica que Codex arma una cadena de instrucciones antes de empezar a trabajar.

En la práctica eso significa:

1. ~/.codex/AGENTS.override.md o ~/.codex/AGENTS.md
2. archivos del proyecto desde la raíz del repo hasta el directorio actual
3. los archivos más cercanos se aplican después y por eso overridean reglas anteriores

Una buena forma de pensarlo:

• archivo en home = defaults personales
• archivo en raíz = estándares del equipo
• archivo anidado = excepción local de una zona del repo

/init da un punto de partida, no un documento terminado

La guía de slash commands describe /init como una forma de generar un scaffold de AGENTS.md en el directorio actual. Es útil, pero el scaffold es genérico por diseño.

Después de /init, casi siempre conviene agregar:

• comandos de verificación reales
• rutas protegidas
• la fuente de verdad del proyecto
• reglas sobre dependencias, migraciones y archivos generados

Qué va en cada superficie

Cuando separas bien esas tres cosas, los prompts se acortan y Codex se vuelve más predecible.

Estructura mínima útil para un AGENTS.md

En proyectos reales, cuatro secciones suelen dar la mayor parte del valor.

1. Contexto del proyecto

## Contexto del proyecto
- App Next.js 16 con App Router
- Los documentos viven en content/{locale}/{tool}/*.mdx
- Los componentes UI viven bajo src/components/

2. Acuerdos de trabajo

## Acuerdos de trabajo
- Preferir diffs pequeños
- No agregar dependencias sin aprobación
- Reutilizar patrones existentes primero

3. Verificación

## Verificación
- npm run lint
- npm run build
- No declarar terminado si fallan los checks

4. No hacer

## No hacer
- No editar archivos generados directamente
- No commitear secretos
- No cambiar APIs públicas a la ligera

Usa AGENTS anidados solo cuando las reglas realmente cambian

Los AGENTS.md anidados son potentes, pero demasiados generan confusión. La pregunta correcta es simple:

¿Esta carpeta necesita de verdad reglas distintas?

Buenos ejemplos:

• apps/web/AGENTS.md para reglas de UI y renderizado
• infra/AGENTS.md para límites de despliegue

Mal ejemplo:

• repetir casi igual el archivo raíz en cada subdirectorio

Config knobs que vale la pena tocar primero

Config basics destaca defaults muy comunes:

model = "gpt-5.4"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

El punto importante no es ese nombre de modelo para siempre. Lo importante es que el equipo elija defaults explícitos.

Usa prompts como issues, no como pedidos vagos

Incluso con buenas instrucciones, una tarea vaga produce resultados inestables. Por eso las best practices de Codex recomiendan prompts con forma de issue.

La estructura mínima es:

• Goal
• Context
• Constraints
• Done when

Eso ya elimina bastante adivinanza.

Errores comunes

1. Poner todas las reglas en el prompt

Genera repetición e inconsistencia.

2. Escribir AGENTS.md como si fuera una historia larga del proyecto

Importan más las reglas de ejecución que el contexto narrativo.

3. Listar comandos de verificación que no funcionan de verdad

Eso engaña a Codex y también a humanos.

4. Crear demasiados AGENTS anidados

Más overrides implica más sorpresas.

Versión corta

• usa /init para crear el borrador
• guarda reglas duraderas en AGENTS.md
• define defaults de ejecución en config
• deja la tarea del día en el prompt

Esa separación es una de las mejoras más grandes que puedes hacer en la calidad de Codex.