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 porproject_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 crearAGENTS.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, siAGENTS.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 queconfig.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
Otras extensiones