Codex AGENTS.md
AGENTS.md es el archivo de instrucciones personalizadas de Codex que te permite establecer pautas globales y normas de flujo de trabajo para Codex.
Esta sección explica en detalle cómo crear y usar AGENTS.md.
¿Qué es AGENTS.md?
Al iniciarse, Codex lee automáticamenteAGENTS.mdel archivo. Mediante el mecanismo jerárquico de «configuración global + anulación a nivel de proyecto», cada tarea hereda convenciones de trabajo coherentes, sin importar qué repositorio de código abras.
AGENTS.md es el archivo de instrucciones que Codex lee antes de realizar cualquier trabajo y te permite:
- Establecer estándares globales de codificación
- Definir flujos de trabajo específicos del proyecto
- Proporcionar diferentes pautas para distintos directorios
- Estandarizar las prácticas de desarrollo del equipo

Con AGENTS.md, puedes asegurarte de que Codex siga normas coherentes en todo el repositorio de código.
Cómo descubre Codex las guías
Codex construye la cadena de instrucciones según la siguiente prioridad.
Mecanismo de carga de tres niveles
| Nivel | Regla de carga | Descripción |
|---|---|---|
| Capa global | Lee~/.codex/AGENTS.override.md |
Si no existe, lee~/.codex/AGENTS.mdy solo toma el primer archivo no vacío |
| Capa de proyecto | Escanea desde la raíz de Git hasta el directorio actual, nivel por nivel | En cada nivel comprueba en ordenAGENTS.override.md → AGENTS.md → project_doc_fallback_filenameslos nombres de archivo alternativos en |
| Capa de fusión | Se concatenan de la raíz a las hojas en orden | Cuanto más cerca del directorio actual esté el archivo, más tarde aparece y mayor prioridad tiene |
El límite superior del tamaño total tras la fusión es de 32 KiB por defecto (controlado por
project_doc_max_bytes); el exceso se truncará.
Primer paso: crear la configuración global
La configuración global se aplica a todos los proyectos y es adecuada para convenciones de trabajo generales.
Crear el directorio de configuración
mkdir -p ~/.codex
Asegúrate de que exista el directorio principal de Codex; toda la configuración global debe colocarse en este directorio.
Escribir las convenciones globales
Crea~/.codex/AGENTS.mdel archivo y escribe las convenciones comunes a todos los proyectos:
# ~/.codex/AGENTS.md ## 全局工作约定 - 修改 JavaScript 文件后,始终运行 npm test - 安装依赖时优先使用 pnpm - 新增生产依赖前先请求确认
Verificar si la configuración surte efecto
Ejecuta el siguiente comando; Codex debería mostrar las entradas que escribiste:
codex --ask-for-approval never "Summarize the current instructions."
Si necesitas una anulación global temporal, puedes crear
AGENTS.override.md; elimina ese archivo para restaurar la configuración original.
Segundo paso: configuración por capas según el repositorio
Los archivos a nivel de proyecto hacen que Codex cumpla las normas específicas del repositorio, a la vez que sigue heredando la configuración global.
Añadir convenciones a nivel de repositorio
Crear en el directorio raíz del proyectoAGENTS.md:
# AGENTS.md ## 仓库约定 - 提 PR 前运行 npm run lint - 修改公共工具行为时,同步更新 docs/ 中的文档
Añadir anulaciones para subdirectorios
Para subdirectorios con necesidades especiales (comoservices/payments/), creaAGENTS.override.mdpara realizar anulaciones locales:
# services/payments/AGENTS.override.md ## 支付服务规则 - 使用 make test-payments 替代 npm test - 轮换 API Key 前必须通知安全频道
Estructura completa de directorios
A continuación se muestra un repositorio típico después de cargarAGENTS.mdel diseño del directorio resultante:
repo/
├── AGENTS.md # 仓库级约定(加载)
└── services/
├── payments/
│ ├── AGENTS.md # 被跳过(override 优先)
│ └── AGENTS.override.md # 支付服务覆写(加载)
└── search/
└── AGENTS.md # 搜索服务约定(加载)
En el mismo directorio, si
AGENTS.override.mdexiste, elAGENTS.mddel mismo nivel se omite.
Verificar el orden de carga
Inicia Codex desde un subdirectorio y observa el origen de las instrucciones cargadas:
codex --cd services/payments --ask-for-approval never \ "List the instruction sources you loaded."
Resultado esperado: se enumeran sucesivamente el archivo global, el archivo de la raíz del repositorio y el archivo de anulación del servicio de pagos.
Opciones avanzadas
Las dos funciones siguientes son adecuadas para escenarios en los que se necesita personalizar aún más el comportamiento de carga de instrucciones.
Personalizar el nombre de archivo
Si el proyecto ya tiene un nombre de archivo convencionalTEAM_GUIDE.md, puedes añadirlo a la lista de respaldo en el archivo de configuración; Codex lo tratará como un archivo de instrucciones:
# ~/.codex/config.toml # 追加回退文件名并提高合并上限 project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"] project_doc_max_bytes = 65536
Tras la modificación, el orden de comprobación en cada directorio pasa a ser:AGENTS.override.md → AGENTS.md → TEAM_GUIDE.md → .agents.md; se toma el primer archivo que exista.
Después de modificar la configuración, reinicia Codex para que
config.tomllos cambios surtan efecto.
Cambiar el directorio de configuración
Mediante laCODEX_HOMEvariable de entorno, puedes utilizar perfiles de configuración independientes para diferentes proyectos o flujos automatizados:
CODEX_HOME=$(pwd)/.codex codex exec "List active instruction sources"
En este caso, Codex leerá la configuración global desde el.codexsubdirectorio del directorio actual, en lugar del predeterminado~/.codex。
Verificación y depuración
Los siguientes comandos permiten comprobar rápidamente el origen de las instrucciones actualmente en vigor.
Comprobación rápida
# 从仓库根目录检查全局 + 项目指令 codex --ask-for-approval never "Summarize the current instructions." # 从子目录检查嵌套覆写 codex --cd subdir --ask-for-approval never "Show which instruction files are active."
Activar el registro detallado
Si necesitas auditar en detalle el proceso de carga de instrucciones, puedes activar el registro TUI:
# 输出 TUI 日志到本地目录 codex -c log_dir=./.codex-log # 日志文件位于 ./.codex-log/codex-tui.log
Solución de problemas comunes
La siguiente tabla resume los problemas que pueden surgir durante la configuración y las direcciones de solución.
| Síntoma | Dirección de solución |
|---|---|
| No se carga nada | Confirma que el archivo no esté vacío; ejecutacodex statuspara comprobar si el directorio raíz del área de trabajo es correcto |
| Aparecen instrucciones incorrectas | Comprueba si hay archivos residuales en los directorios superioresAGENTS.override.md |
| El nombre de archivo de respaldo no surte efecto | Confirma que la ortografía enconfig.tomlsea correcta y reinicia Codex para que surta efecto |
| El contenido de las instrucciones se trunca | Aumentaproject_doc_max_bytes, o divide los archivos grandes en varios niveles de directorios |
| Confusión de perfiles | Ejecutaecho $CODEX_HOMEy confirma que apunta al directorio esperado |