Documentación de ChatGPT
Español
Contacto goolvyouyou@gmail.com

Instrucciones personalizadas con AGENTS.md

Proporciona a Codex instrucciones adicionales y contexto para tu proyecto

Codex lee los archivos AGENTS.md antes de realizar cualquier trabajo. Al combinar directrices globales con excepciones específicas del proyecto, puedes comenzar cada tarea con expectativas coherentes, independientemente del repositorio que abras.

Cómo descubre Codex las directrices

Codex crea una cadena de instrucciones cuando se inicia (una vez por ejecución; en la TUI, esto suele significar una vez por cada sesión iniciada). El descubrimiento sigue este orden de prioridad:

  1. Ámbito global: En tu directorio principal de Codex (de forma predeterminada, ~/.codex, a menos que establezcas CODEX_HOME), Codex lee AGENTS.override.md si existe. De lo contrario, Codex lee AGENTS.md. Codex solo utiliza el primer archivo que no esté vacío en este nivel.
  2. Ámbito del proyecto: Codex comienza en la raíz del proyecto (normalmente, la raíz de Git) y recorre los directorios hasta llegar a tu directorio de trabajo actual. Si Codex no puede encontrar una raíz de proyecto, solo comprueba el directorio actual. En cada directorio de la ruta, busca AGENTS.override.md, luego AGENTS.md y, después, cualquier nombre alternativo definido en project_doc_fallback_filenames. Codex incluye como máximo un archivo por directorio.
  3. Orden de combinación: Codex concatena los archivos desde la raíz hacia abajo y los separa con líneas en blanco. Los archivos más cercanos a tu directorio actual prevalecen sobre las directrices anteriores porque aparecen más adelante en el prompt combinado.

Codex omite los archivos vacíos y deja de añadir archivos cuando el tamaño combinado alcanza el límite definido por project_doc_max_bytes (32 KiB de forma predeterminada). Para obtener detalles sobre estas opciones, consulta Descubrimiento de instrucciones del proyecto. Aumenta el límite o divide las instrucciones entre directorios anidados cuando alcances el máximo.

Crear directrices globales

Crea valores predeterminados persistentes en tu directorio principal de Codex para que todos los repositorios hereden tus acuerdos de trabajo.

  1. Asegúrate de que el directorio exista:

    mkdir -p ~/.codex

  2. Crea ~/.codex/AGENTS.md con preferencias reutilizables:

    # ~/.codex/AGENTS.md

## Working agreements

- Always run `npm test` after modifying JavaScript files.
- Prefer `pnpm` when installing dependencies.
- Ask for confirmation before adding new production dependencies.

  3. Ejecuta Codex en cualquier ubicación para confirmar que carga el archivo:

    codex --ask-for-approval never "Summarize the current instructions."

    Resultado esperado: Codex cita los elementos de ~/.codex/AGENTS.md antes de proponer trabajo.

Utiliza ~/.codex/AGENTS.override.md cuando necesites una excepción global temporal sin eliminar el archivo base. Elimina la excepción para restaurar las directrices compartidas.

Organizar las instrucciones del proyecto por niveles

Los archivos del repositorio mantienen a Codex al tanto de las normas del proyecto sin dejar de heredar tus valores predeterminados globales.

  1. En la raíz de tu repositorio, añade un AGENTS.md que describa la configuración básica:

    # AGENTS.md

## Repository expectations

- Run `npm run lint` before opening a pull request.
- Document public utilities in `docs/` when you change behavior.

  2. Añade excepciones en directorios anidados cuando determinados equipos necesiten reglas diferentes. Por ejemplo, crea AGENTS.override.md dentro de services/payments/:

    # services/payments/AGENTS.override.md

## Payments service rules

- Use `make test-payments` instead of `npm test`.
- Never rotate API keys without notifying the security channel.

  3. Inicia Codex desde el directorio de pagos:

    codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."

    Resultado esperado: Codex muestra primero el archivo global, después el AGENTS.md de la raíz del repositorio y, por último, la excepción de pagos.

Codex deja de buscar cuando llega a tu directorio actual, así que coloca las excepciones lo más cerca posible del trabajo especializado.

Este es un repositorio de ejemplo después de añadir un archivo global y una excepción específica para pagos:

<FileTree class="mt-4" tree={[ { name: "AGENTS.md", comment: "Expectativas del repositorio", highlight: true, }, { name: "services/", open: true, children: [ { name: "payments/", open: true, children: [ { name: "AGENTS.md", comment: "Se ignora porque existe una excepción", }, { name: "AGENTS.override.md", comment: "Reglas del servicio de pagos", highlight: true, }, { name: "README.md" }, ], }, { name: "search/", children: [{ name: "AGENTS.md" }, { name: "…", placeholder: true }], }, ], }, ]} />

Añadir reglas de revisión de código

Para la revisión de código de Codex en GitHub, añade una sección ## Code Review Rules al AGENTS.md más cercano al código que rigen las reglas. Coloca las comprobaciones de todo el repositorio en la raíz y las comprobaciones específicas del servicio en un archivo anidado.

## Code Review Rules

### Experiment cohorts

- Do not filter treatment comparisons on post-exposure behavior, including conversion or retention.
  Safe path: build cohorts from assignment or exposure; report conversion as an outcome.

Mantén las reglas concisas, explica el comportamiento que se debe señalar y cualquier alternativa segura o excepción, y reserva para CI las comprobaciones de formato y lint. Consulta Personalizar lo que revisa Codex para obtener orientación sobre la configuración y la redacción de reglas.

Personalizar los nombres de archivo alternativos

Si tu repositorio ya utiliza otro nombre de archivo (por ejemplo, TEAM_GUIDE.md), añádelo a la lista de nombres alternativos para que Codex lo trate como un archivo de instrucciones.

  1. Edita tu configuración de Codex:

    # ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

  2. Reinicia Codex o ejecuta un comando nuevo para que se cargue la configuración actualizada.

Ahora Codex comprueba cada directorio en este orden: AGENTS.override.md, AGENTS.md, TEAM_GUIDE.md, .agents.md. Los nombres de archivo que no estén en esta lista se ignoran durante el descubrimiento de instrucciones. El límite de bytes más alto permite combinar más directrices antes de truncarlas.

Una vez configurada la lista de nombres alternativos, Codex trata los archivos alternativos como instrucciones:

<FileTree class="mt-4" tree={[ { name: "TEAM_GUIDE.md", comment: "Detectado mediante la lista de nombres alternativos", highlight: true, }, { name: ".agents.md", comment: "Archivo alternativo en la raíz", }, { name: "support/", open: true, children: [ { name: "AGENTS.override.md", comment: "Prevalece sobre las directrices alternativas", highlight: true, }, { name: "playbooks/", children: [{ name: "…", placeholder: true }], }, ], }, ]} />

Establece la variable de entorno CODEX_HOME cuando quieras usar un perfil diferente, como un usuario de automatización específico del proyecto:

CODEX_HOME=$(pwd)/.codex codex exec "List active instruction sources"

Resultado esperado: La salida muestra los archivos relativos al directorio personalizado .codex.

Verificar la configuración

  • Ejecuta codex --ask-for-approval never "Summarize the current instructions." desde la raíz de un repositorio. Codex debería repetir las directrices de los archivos globales y del proyecto en orden de prioridad.
  • Utiliza codex --cd subdir --ask-for-approval never "Show which instruction files are active." para confirmar que las excepciones anidadas reemplazan las reglas más generales.
  • Para auditar qué archivos de instrucciones cargó Codex, habilita un registro de texto sin formato de la TUI con codex -c log_dir=./.codex-log y comprueba ./.codex-log/codex-tui.log, o inspecciona el archivo session-*.jsonl más reciente si habilitaste el registro de sesiones.
  • Si las instrucciones parecen obsoletas, reinicia Codex en el directorio de destino. Codex vuelve a crear la cadena de instrucciones en cada ejecución (y al inicio de cada sesión de la TUI), por lo que no hay ninguna caché que debas borrar manualmente.

Solucionar problemas de descubrimiento

  • No se carga nada: Verifica que te encuentres en el repositorio previsto y que codex status muestre la raíz del espacio de trabajo esperada. Asegúrate de que los archivos de instrucciones tengan contenido; Codex ignora los archivos vacíos.
  • Aparecen directrices incorrectas: Busca un AGENTS.override.md en un nivel superior del árbol de directorios o en tu directorio principal de Codex. Cambia el nombre de la excepción o elimínala para volver a utilizar el archivo normal.
  • Codex ignora los nombres alternativos: Confirma que incluiste los nombres en project_doc_fallback_filenames sin errores tipográficos y, después, reinicia Codex para que la configuración actualizada surta efecto.
  • Instrucciones truncadas: Aumenta project_doc_max_bytes o divide los archivos grandes entre directorios anidados para conservar intactas las directrices esenciales.
  • Confusión con el perfil: Ejecuta echo $CODEX_HOME antes de iniciar Codex. Un valor que no sea el predeterminado dirige Codex a un directorio principal diferente del que editaste.

Próximos pasos